Table of Contents

Class KeyedTenantPartition

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

The tenant partition of a request against a keyed store — one whose unique key includes the tenant column (inbox, saga, snapshot, and any event store that carries a tenant column). A keyed partition has exactly two inhabitants, Scoped(string?) and Untenanted, and always yields a concrete, non-null tenant term.

public sealed class KeyedTenantPartition : IEquatable<KeyedTenantPartition>
Inheritance
KeyedTenantPartition
Implements
Inherited Members
Extension Methods

Remarks

This type exists so that a keyed store whose emitted statement carries no tenant term is unconstructable. It has no absent inhabitant: the untenanted case is the explicit Untenanted sentinel, which still binds a value (__untenanted__). A destructive or identity-bearing keyed operation can therefore never resolve to an empty predicate that matches every tenant's rows.

It is a reference type on purpose: it has no public constructor and no default, so a null reference is a distinct, nullable-reference-flagged, throwing value rather than a silent empty term. Every factory is total and every inhabitant binds a non-empty tenant term, so an empty predicate is unconstructable. TenantScope reaches the same totality by a different route — its tenant term folds onto the sentinel for default — so a caller that resolves a scope from ambient context projects it through FromScope(TenantScope).

The partition owns the existence and value of the tenant term; the request owns provider-specific placement (for example Oracle positional bind order). The partition never exposes a mutable parameter bag a caller could strip, so the term cannot be removed after binding.

Properties

IsRealTenant

Gets a value indicating whether this partition names a real tenant (true) or the reserved untenanted sentinel (false). Both cases emit a tenant term; this only distinguishes a real tenant from the sentinel.

public bool IsRealTenant { get; }

Property Value

bool

TenantId

Gets the concrete, non-null tenant term to bind: a validated real tenant identifier for a Scoped(string?) partition, or the reserved untenanted sentinel for Untenanted. It is never null and never empty.

public string TenantId { get; }

Property Value

string

Untenanted

The reserved partition for a genuinely untenanted row inside a keyed multi-tenant store. It binds the reserved untenanted value, which Scoped(string?) rejects, so it can never collide with a real tenant. Because it still binds a concrete value, an untenanted keyed operation emits a real equality term (never an empty predicate).

public static KeyedTenantPartition Untenanted { get; }

Property Value

KeyedTenantPartition

Methods

Equals(KeyedTenantPartition?)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(KeyedTenantPartition? other)

Parameters

other KeyedTenantPartition

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

FromContext(ITenantContext)

Derives the keyed partition from an ambient tenant context, which is required: the resolved tenant yields Scoped(string?), and a context resolving the reserved sentinel yields Untenanted (the sentinel term — never an empty predicate).

public static KeyedTenantPartition FromContext(ITenantContext tenantContext)

Parameters

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

Returns

KeyedTenantPartition

Untenanted when tenantContext resolves the reserved sentinel; otherwise Scoped(string?).

Remarks

There is deliberately no null-accepting form of this conversion. A caller holding an optional context — because multi-tenancy may not be registered in that deployment — must state at its own call site what a missing context means for that store. It is not a decision this type can make on the caller's behalf, and a conversion that made it silently is how a store whose context was never wired came to report a well-formed untenanted partition: "no context was supplied" quietly acquired the meaning "this row has no tenant". Requiring the argument turns that substitution into a compile error instead of a plausible wrong answer at run time.

A store that has already encoded "no tenant" as the reserved sentinel hands that value back through the ambient context, so this conversion must accept it. Routing through the single sentinel-aware conversion keeps that decision in one place — a context resolving the sentinel yields the untenanted partition instead of throwing on a read path.

Exceptions

ArgumentNullException

tenantContext is null.

TenantRequiredException

tenantContext resolves a null/whitespace tenant.

FromScope(TenantScope)

Projects a column-agnostic TenantScope onto the keyed family: a scope naming a real tenant becomes Scoped(string?); a scope bound to the reserved sentinel becomes Untenanted. This is the bridge for callers that resolve a TenantScope from ambient context and need a keyed partition.

public static KeyedTenantPartition FromScope(TenantScope scope)

Parameters

scope TenantScope

The column-agnostic scope to project.

Returns

KeyedTenantPartition

Untenanted for a scope bound to the reserved sentinel; otherwise Scoped(string?) for a real identifier.

Remarks

This projection routes through the sentinel-aware conversion rather than calling Scoped(string?) directly, which rejects the sentinel outright. Without that, the one scope whose entire purpose is to name the untenanted partition is the one scope that cannot be projected onto it. Because TenantId is total, this conversion is total.

FromStoredValue(string?)

Rehydrates a partition from a tenant value read back from a store, mapping every value that cannot name a real tenant onto Untenanted.

public static KeyedTenantPartition FromStoredValue(string? storedValue)

Parameters

storedValue string

The tenant term as the store returned it.

Returns

KeyedTenantPartition

Untenanted when storedValue is the reserved sentinel, or is null, empty, or whitespace; otherwise a partition bound to that exact value.

Remarks

This is the read-back counterpart to Scoped(string?), and the two are deliberately not interchangeable. Scoped(string?) guards authoring a partition from caller input, so it rejects the reserved sentinel; a value coming back off disk already passed that guard on the way in, so re-applying it would turn a legitimately-stored sentinel into a throw — aborting a whole cross-tenant pass on the first legacy row. This factory is therefore total: it has no rejecting input, and callers reading persisted tenant columns must use it rather than hand-branching on the sentinel.

By the store's own contract, null, empty, whitespace and the sentinel are all untenanted — rows written before tenancy existed, or written by a non-multi-tenant host. A caller that must distinguish "the store holds no tenant for this row" from "the query never supplied the column" cannot get that distinction here, because both arrive as the same value: it must reject an absent column at the projection, before calling this.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

Scoped(string?)

Creates a keyed partition scoped to a real tenant. The tenant identifier is required: a null or whitespace value throws, so a keyed request can never be constructed without a tenant term.

public static KeyedTenantPartition Scoped(string? tenantId)

Parameters

tenantId string

The non-empty tenant identifier.

Returns

KeyedTenantPartition

A KeyedTenantPartition bound to tenantId.

Exceptions

TenantRequiredException

tenantId is null, empty, or whitespace.

ArgumentException

tenantId is the reserved framework sentinel and therefore cannot name a real tenant; or is longer than MaxLength characters, which no shipped provider can store whole — rejected here rather than truncated later by a store, where a truncated identifier could collide with another tenant's.

ToSignedTenantId(string?)

Maps a stored tenant term back to the identifier a caller supplied, with every spelling of untenanted collapsing to null.

public static string? ToSignedTenantId(string? storedValue)

Parameters

storedValue string

The tenant term as persisted.

Returns

string

The originating tenant identifier, or null when the row belongs to no tenant.

Remarks

This is the inverse of FromStoredValue(string?) and is deliberately written in terms of it, so there is exactly one predicate in the codebase deciding what counts as absent. Two hand-rolled copies of that decision is how the two spellings drift apart: one integrity tag computed over null while the sentinel was stored made every untouched audit trail verify as tampered.

Use it wherever a stored term must be turned back into the value a caller signed, compared, or re-entered as a scope — never a local == sentinel comparison, which silently disagrees with this one about empty and whitespace.