Table of Contents

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

tenantId string

The tenant identifier. Required; must be non-empty. Pass a BARE value.

activityGroupName string

The name of the activity group, BARE — not a composed key.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

true if tenantId has a group so named; otherwise false. Modifies nothing.

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

tenantId string

The 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.

name string

The activity group name, BARE — unique only within tenantId.

activityName string

The activity name to associate.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<int>

Number of rows affected.

DeleteActivityGroupsForTenantAsync(string, CancellationToken)

Deletes tenantId's activity groups, and no other tenant's.

Task<int> DeleteActivityGroupsForTenantAsync(string tenantId, CancellationToken cancellationToken)

Parameters

tenantId string

The tenant whose groups to remove. Required; must be non-empty. Pass a BARE value.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<int>

Number of rows affected. Zero when the tenant had no groups.

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

tenantId string

The tenant identifier. Required; must be non-empty. Pass a BARE value.

cancellationToken CancellationToken

Cancellation 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

catalogue ActivityGroupCatalogue

The complete catalogue to make current.

cancellationToken CancellationToken

Cancellation 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 catalogue is null.

InvalidOperationException

Thrown when a database store is called inside an ambient transaction, or cannot obtain the lock that orders replaces. Nothing is changed.