Interface ILegalHoldStore
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Storage abstraction for legal holds.
public interface ILegalHoldStore
Remarks
Legal holds support GDPR Article 17(3) exceptions that block erasure when data must be retained for legal reasons.
Tenant confinement. Every member here is confined to the ambient tenant established for this
store instance: GetHoldAsync(Guid, CancellationToken) reports a hold stored under another tenant as not found
rather than resolving it — a real authorization boundary, since a hold identifier is exactly the kind
of caller-supplied value a foreign tenant could otherwise probe with — and UpdateHoldAsync(LegalHold, CancellationToken)
can neither read nor overwrite another tenant's hold for the same identifier. Which mechanism a given
provider uses to hold that boundary is declared by its capability marker —
ITenantScopingCapability<TContract> for a store that reads an ambient tenant — and the
package's own ARCHITECTURE.md states the falsifiable guarantee and how it is verified. A store
presenting no marker is not confined by the framework.
Methods
GetHoldAsync(Guid, CancellationToken)
Gets a legal hold by ID.
Task<LegalHold?> GetHoldAsync(Guid holdId, CancellationToken cancellationToken)
Parameters
holdIdGuidThe hold ID.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Confined to the ambient tenant established for this store instance: a hold stored under another
tenant is reported as not found, the same as a holdId that never existed.
GetService(Type)
Gets a sub-interface or related service from this store implementation.
object? GetService(Type serviceType)
Parameters
serviceTypeTypeThe type of service to retrieve (e.g. ILegalHoldQueryStore).
Returns
Remarks
This follows the IServiceProvider.GetService escape-hatch pattern from Microsoft design guidelines,
allowing callers to discover optional sub-interfaces without widening the core interface.
SaveHoldAsync(LegalHold, CancellationToken)
Saves a new legal hold. This is a save, never an upsert: a hold identifier already in use is rejected rather than overwritten.
Task SaveHoldAsync(LegalHold hold, CancellationToken cancellationToken)
Parameters
holdLegalHoldThe legal hold to save.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
The hold identifier namespace is estate-wide, unlike the reads on this interface. Every shipped relational provider declares the hold identifier as the sole primary key of its table, so an identifier is unique across the whole estate rather than within one tenant. That is deliberate, and it is stated here because it is the one place this interface is wider than its type-level confinement paragraph, and a caller who assumes otherwise misreads the result.
The consequence a caller must plan for: under multi-tenancy this operation can report a duplicate for a hold that GetHoldAsync(Guid, CancellationToken) reports as absent, because the colliding hold belongs to another tenant and is — correctly — not visible. Both answers are true. A caller that must not disclose whether an identifier is in use allocates hold identifiers randomly rather than deriving them from a case reference or any other value another tenant could guess.
Exceptions
- DuplicateLegalHoldException
A hold with the same HoldId is already stored — raised if and only if that is the reason, so a caller can tell it apart from the other conditions that surface as an InvalidOperationException here.
- TenantRequiredException
Multi-tenancy is active but no ambient tenant is established. The hold is not stored. This also derives from InvalidOperationException, which is why the duplicate condition has a type of its own: catching the base type here treats a hold that was never written as one already on file, and a legal hold silently dropped does not fail safe — the next erasure runs and succeeds.
UpdateHoldAsync(LegalHold, CancellationToken)
Updates a legal hold, but only while the stored record still carries the Version the caller read.
Task<bool> UpdateHoldAsync(LegalHold hold, CancellationToken cancellationToken)
Parameters
holdLegalHoldThe hold with updated values. Its Version is the version the caller read and is the value compared against storage — it is not written through. On success the stored version becomes that value plus one.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<bool>
true when the hold was updated; false when no hold with that identifier is visible to this store — absent, or owned by another tenant. A version mismatch is not reported here; it raises LegalHoldConcurrencyException.
Remarks
This is a compare-and-set, not a blind write, and the distinction is the difference between a legal hold that holds and one that silently does not. Every caller of this method is performing a read-modify-write: it reads a hold, decides from what it read, and writes the whole record back. Applied blindly, that decision lands over whatever the record became in the meantime — so a hold whose expiry an operator extended, in the window between an expiry sweep's read and its write, is released anyway, and the next erasure for that subject destroys the records the hold existed to preserve. Nothing reports the lost update: the released record is well-formed and carries a plausible reason, so an auditor reading it afterwards sees a legitimate release.
The comparison is therefore part of the same atomic statement as the write, never a check the caller performs first. A store that reads the version, compares it, and then writes has only moved the race.
On LegalHoldConcurrencyException, re-read and re-decide — never re-apply. The conflict means the caller's premise expired, so repeating the same write against a fresh version reinstates exactly the lost update this contract exists to prevent. Re-read the hold, evaluate the decision again against what it now says, and act on that; if the new state no longer warrants the change, the correct outcome is to make none.
Exceptions
- LegalHoldConcurrencyException
The hold exists and is visible, but carries a different Version. Nothing was written.