Interface IActivityGroupGrantReplacement
- Namespace
- Excalibur.A3.Authorization
- Assembly
- Excalibur.A3.Abstractions.dll
An optional capability of IActivityGroupGrantStore: replacing a set of grants in one atomic step instead of deleting and re-inserting them.
public interface IActivityGroupGrantReplacement
Remarks
Why it is a separate interface. Not every store can offer it. A replace has to remove a set of rows
and write another set so that no reader and no failure can observe the gap between them, which needs a
transaction and a lock the store can take across both statements. The relational and in-memory stores have
that; stores over document and key-value databases that do not offer a cross-document transaction cannot
provide it honestly, and declaring it on the base contract would have made them claim it. A consumer
composing one of those chooses explicitly, through
ActivityGroupSyncOptions.GrantSyncAtomicity, between refusing at start-up and accepting the
non-atomic sync with its window documented.
The guarantee, in falsifiable terms. Each member below either applies its whole snapshot or changes nothing. A concurrent reader observes the whole set before the replace or the whole set after it, never a partial or empty one. Two replaces of the same set are serialized, so the set that remains is the one whose replace committed last — never the union of both. Nothing outside the member's own scope is touched: an estate-wide replace leaves grants of other types alone, and a per-user replace leaves other users' grants alone.
Preconditions are carried by the snapshot. An ActivityGroupGrantSnapshot can only be constructed with every term present, free of leading and trailing whitespace and within the tenant width, so every store receives an input every other store would also accept. The scope preconditions — a snapshot that is entirely of this grant type, and for the per-user member entirely of this user — are checked BEFORE the transaction opens, so a snapshot that cannot be applied whole is refused without anything having been removed.
It runs in its own transaction. A database store refuses, with InvalidOperationException, to run inside an ambient transaction, because it would then commit or roll back with work it cannot see.
Methods
ReplaceActivityGroupGrantsAsync(string, ActivityGroupGrantSnapshot, CancellationToken)
Makes snapshot the whole set of grantType grants, for every user,
in one atomic step.
Task<IReadOnlyCollection<string>> ReplaceActivityGroupGrantsAsync(string grantType, ActivityGroupGrantSnapshot snapshot, CancellationToken cancellationToken)
Parameters
grantTypestringThe grant type to replace. Required; must be non-empty.
snapshotActivityGroupGrantSnapshotThe grants that are to be current afterwards. Every entry must carry
grantType, and there must be at least one.cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyCollection<string>>
The distinct users that held a grant of this type immediately before the replace, observed inside the same transaction, in no particular order. A caller invalidating state derived from the old grants needs these as well as UserIds: a user the replace revoked appears only here.
Remarks
This member is estate-wide by specification. Afterwards the store holds exactly the snapshot's grants of this type: a user absent from it holds none of them. To revoke one user's grants, call ReplaceActivityGroupGrantsForUserAsync(string, string, ActivityGroupGrantSnapshot, CancellationToken), which names the user; the estate-wide behaviour is never reached by omitting an argument.
An empty snapshot is refused, because it would revoke every user's grants of this type and an empty result from an authority cannot be told apart from a fetch that returned nothing.
Exceptions
- ArgumentNullException
Thrown when
snapshotis null.- ArgumentException
Thrown when
grantTypeis missing, whensnapshotis empty, or when any entry carries a different grant type. Nothing is changed.- InvalidOperationException
Thrown when a database store is called inside an ambient transaction, or cannot obtain the lock that orders replaces. Nothing is changed.
ReplaceActivityGroupGrantsForUserAsync(string, string, ActivityGroupGrantSnapshot, CancellationToken)
Makes snapshot the whole set of userId's
grantType grants, in one atomic step, leaving every other user's alone.
Task<IReadOnlyCollection<string>> ReplaceActivityGroupGrantsForUserAsync(string userId, string grantType, ActivityGroupGrantSnapshot snapshot, CancellationToken cancellationToken)
Parameters
userIdstringThe user whose grants to replace. Required; must be non-empty. Pass a BARE value.
grantTypestringThe grant type to replace. Required; must be non-empty.
snapshotActivityGroupGrantSnapshotThe grants that are to be current for this user afterwards. Every entry must carry
userIdandgrantType. May be empty.cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyCollection<string>>
The users that held a grant of this type immediately before the replace and had it removed — at most
userId— observed inside the same transaction.
Remarks
An empty snapshot is ACCEPTED here, unlike the estate-wide member: a user who now holds no grants of this type is an ordinary state and every grant they held is revoked. A caller must therefore never pass an empty snapshot to stand for a fetch that failed — a failure is raised, never handed on as an empty set.
Exceptions
- ArgumentNullException
Thrown when
snapshotis null.- ArgumentException
Thrown when
userIdorgrantTypeis missing, or when any entry carries a different user or grant type. Nothing is changed.- InvalidOperationException
Thrown when a database store is called inside an ambient transaction, or cannot obtain the lock that orders replaces. Nothing is changed.