Interface IActivityGroupStore
- Namespace
- Excalibur.A3.Authorization
- Assembly
- Excalibur.A3.Abstractions.dll
Provider-neutral store for activity group persistence.
public interface IActivityGroupStore : IServiceProvider
- Inherited Members
Remarks
Follows the Microsoft ASP.NET Core Identity IRoleStore<TRole> pattern:
minimal CRUD surface (5 methods) with GetService(Type) for ISP extensions.
Replaces IActivityGroupRequestProvider (4-method, SQL-coupled interface).
TYPE INVARIANT — an activity group name is unique only WITHIN a tenant. Two tenants may each
hold a group called "Support", conferring different activities, and they are different groups.
Every member below is specified against that invariant; it is the property the whole surface turns on,
so it is stated here rather than left to each implementation to restate.
KEY COMPOSITION — how a returned key is formed, stated so a caller can construct one. Members
that return keyed results compose them with
Compose(string, string) — two segments, in the order
(tenant identifier, group name). That composer escapes each segment before joining, so a tenant
identifier or group name containing the separator cannot collide with a different pair. Do not build
such a key by string interpolation. A hand-built "tenant:name" is correct only until a term
contains the separator, at which point it silently addresses nothing — and the one thing a caller must
get right to stay inside its own tenant is exactly this. Use the composer, or
Split(string, int) to decompose one.
Arity is per member and is stated on each. An implementation may key its own internal storage with more segments than it returns; what is specified here is the shape a CALLER observes, which is the only shape a caller may rely on.
Methods
ActivityGroupExistsAsync(string, string, CancellationToken)
Checks whether tenantId has an activity group with the given name.
Task<bool> ActivityGroupExistsAsync(string tenantId, string activityGroupName, CancellationToken cancellationToken)
Parameters
tenantIdstringThe tenant identifier. Required; must be non-empty. Pass a BARE value.
activityGroupNamestringThe name of the activity group, BARE — not a composed key.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Answers only for the named tenant, and never observes another tenant's catalogue. Because a
group name is unique only within a tenant, a bare-name question has no single answer: two tenants
may each hold a group called "Support". The tenant term is therefore part of the question,
not a filter applied to it.
CreateActivityGroupAsync(string, string, string, CancellationToken)
Creates a new activity group entry.
Task<int> CreateActivityGroupAsync(string tenantId, string name, string activityName, CancellationToken cancellationToken)
Parameters
tenantIdstringThe tenant identifier. Required; must be non-empty. Pass it as a BARE value — the store composes any key it needs internally. No member of this interface accepts an already-composed key.
namestringThe activity group name, BARE — unique only within
tenantId.activityNamestringThe activity name to associate.
cancellationTokenCancellationTokenCancellation token.
Returns
DeleteActivityGroupsForTenantAsync(string, CancellationToken)
Deletes tenantId's activity groups, and no other tenant's.
Task<int> DeleteActivityGroupsForTenantAsync(string tenantId, CancellationToken cancellationToken)
Parameters
tenantIdstringThe tenant whose groups to remove. Required; must be non-empty. Pass a BARE value.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
This is the member a consumer reaches for to remove its own groups. Its sibling ReplaceAllActivityGroupsAsync(ActivityGroupCatalogue, CancellationToken) is estate-wide; the two are separate NAMED operations rather than one member with an optional tenant, deliberately.
Why not one member taking a nullable tenant. A string? whose null meant "every tenant"
would make the CATASTROPHIC case the value you get by FORGETTING — an omitted argument, a default, an
unassigned field all resolve to the widest possible blast radius. Two named operations make the wrong
one inexpressible by accident: a caller that wants one tenant cannot reach the estate-wide behaviour
without naming it.
And why the tenant is explicit rather than ambient. Resolving it from an ambient scope would make the SAME SOURCE LINE mean different things depending on whether a scope happened to be active, and it fails silently in both directions — scoped when you meant estate-wide leaves an incomplete refresh, estate-wide when you meant scoped destroys every other tenant's groups. For an operation whose radius can be "everything", the radius must be readable AT THE CALL SITE.
FindActivityGroupsAsync(string, CancellationToken)
Retrieves tenantId's activity groups.
Task<IReadOnlyDictionary<string, IReadOnlyCollection<string>>> FindActivityGroupsAsync(string tenantId, CancellationToken cancellationToken)
Parameters
tenantIdstringThe tenant identifier. Required; must be non-empty. Pass a BARE value.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyDictionary<string, IReadOnlyCollection<string>>>
tenantId's activity groups, each keyed by its composed (tenant, name) key and carrying the names of the activities in that group. Never another tenant's groups.
Remarks
Answers only for the named tenant. The tenant term SELECTS and the composed key still IDENTIFIES; both are needed and they do different jobs. Without the selection every caller receives the whole estate's catalogue and can read it, and without the composition two tenants' same-named groups fuse into one entry whose membership satisfies both.
The value is typed, and that is load-bearing. This returned object and was described
as a "provider-specific projection", so each implementation invented its own shape: the in-memory
store produced a List<string> while both database stores produced a private
record declared inside the store. The single consumer then had to guess with a runtime type test,
which only the in-memory shape satisfied, so on either database provider every activity group
resolved to nothing -- with no exception and no log, because a failed type test is silent.
A private type is not merely inconvenient to consume; it is impossible to consume. No caller could have written a correct test against it. Typing the value removes the question: a store that returns the wrong shape now fails to compile.
ReplaceAllActivityGroupsAsync(ActivityGroupCatalogue, CancellationToken)
Makes catalogue the whole activity-group catalogue, for every tenant, in one atomic step.
Task<IReadOnlyCollection<string>> ReplaceAllActivityGroupsAsync(ActivityGroupCatalogue catalogue, CancellationToken cancellationToken)
Parameters
catalogueActivityGroupCatalogueThe complete catalogue to make current.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyCollection<string>>
The distinct tenants that held groups immediately before the replace, observed under the same lock that orders the replace, in no particular order. A caller invalidating state derived from the old catalogue needs these as well as TenantIds: a tenant that the replace removed appears only here.
Remarks
This member is estate-wide by specification. Afterwards the store holds exactly the entries of
catalogue: a tenant that is absent from it has no groups at all. To remove one
tenant's groups, call DeleteActivityGroupsForTenantAsync(string, CancellationToken), which names the tenant; the
estate-wide behaviour is never reached by omitting an argument.
Atomic for readers and writers. A concurrent reader observes either the whole previous catalogue or the whole new one, never a partial one. Concurrent replaces are serialized, so the catalogue that remains is the one whose replace committed last. If the operation fails, the previous catalogue is unchanged.
Preconditions are carried by the type. An ActivityGroupCatalogue can only be constructed non-empty, as a set, with every term present, free of leading and trailing whitespace and within the shipped widths, so every store receives an input every other store would also accept.
One application per catalogue. The catalogue carries no application identifier, so two applications that replace the same store's catalogue replace each other's groups. Give each application its own store, for example its own schema on the database providers.
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.
Exceptions
- ArgumentNullException
Thrown when
catalogueis null.- InvalidOperationException
Thrown when a database store is called inside an ambient transaction, or cannot obtain the lock that orders replaces. Nothing is changed.