Table of Contents

Class ColdStorageKey

Namespace
Excalibur.EventSourcing
Assembly
Excalibur.EventSourcing.Abstractions.dll

Composes the tenant-qualified segment of a cold-storage object key.

public static class ColdStorageKey
Inheritance
ColdStorageKey
Inherited Members

Remarks

Cold stores address objects by a flat string key, so a tenant and an aggregate identifier must be combined into one path. Naive concatenation with a delimiter makes distinct pairs collide whenever a component can contain the delimiter (or the character a provider substitutes for it): tenant "t/a" with aggregate "b" and tenant "t" with aggregate "a/b" both render as "t/a/b". A collision here is a cross-tenant read.

This helper encodes the tenant identifier with Base64Url, which is injective: distinct tenants always produce distinct segments, and the alphabet (A-Z a-z 0-9 - _) contains no path separator, so the segment cannot introduce structure into the key. Collisions become inexpressible rather than sanitized away, and each provider keeps its own idiom for the remainder of the key.

A lossy substitution (replacing path separators with a placeholder) is not sufficient and must not be reintroduced: it maps distinct tenants onto the same segment, and every tenant that collides shares one object. Length-prefixing does not repair that — equal-length inputs collide identically. Only a reversible encoding makes the guarantee.

This encoding is a persisted wire format, not an implementation detail. The value it produces becomes part of the object key under which events are durably stored, so changing it orphans every object already written: existing archives remain in cold storage under their old keys, and reads composed with the new encoding return nothing — indistinguishable, to a caller, from an aggregate that was never archived. Treat any change as a data migration requiring a re-key of existing objects, never as a refactor. Callers MUST NOT parse or construct these segments themselves.

Methods

AggregateSegment(string)

Builds the aggregate segment for a cold-storage key.

public static string AggregateSegment(string aggregateId)

Parameters

aggregateId string

The aggregate identifier the object holds events for.

Returns

string

A path segment uniquely determined by aggregateId, safe to concatenate with a tenant segment without ambiguity.

Remarks

Encoding the aggregate term is not redundant beside an injective tenant segment. A key is a function of both components, so it is injective only if both are: sanitizing the aggregate identifier by rewriting unsafe characters — Replace('/', '_'), Replace('\\', '_') — is many-to-one, and maps the distinct identifiers a/b, a\b and a_b onto the same object within a single tenant. Two aggregates then share one object: each read returns the other's events and each write silently overwrites them.

This is the same defect as the tenant-segment collision in a narrower form — one tenant's aggregates rather than several tenants — so it is closed the same way, by a reversible encoding rather than a sanitation map. The alphabet excludes / and \, so an aggregate identifier can neither alias a sibling nor inject a path boundary into the key.

Persisted wire format. The same migration constraint stated for TenantSegment(KeyedTenantPartition) applies here verbatim: changing this encoding orphans every object already written under it.

Exceptions

ArgumentNullException

aggregateId is null.

StreamPath(KeyedTenantPartition, string, string)

Builds a versioned path identifying one tenant, aggregate type, and aggregate identifier.

public static string StreamPath(KeyedTenantPartition tenant, string aggregateType, string aggregateId)

Parameters

tenant KeyedTenantPartition

The owning tenant partition.

aggregateType string

The nonempty, case-sensitive aggregate type.

aggregateId string

The nonempty, case-sensitive aggregate identifier.

Returns

string

The persisted v2/tenant/type/id path with independently encoded identity terms.

Remarks

This format is distinct from legacy tenant/aggregate keys. Switching an existing store to it requires migration of complete validated archives and a cutover that stops legacy writers. Calling this helper does not migrate data or certify that a legacy archive was copied. Identity terms are not normalized or trimmed; whitespace-only aggregate terms are preserved. Strict UTF-8 has no byte-order mark, Base64Url has no padding, and the path has no trailing slash. Invalid UTF-16 is rejected rather than replaced with bytes that could make distinct identities collide. Providers must validate the complete key length, including their configured prefix and suffix.

Exceptions

ArgumentNullException

tenant is null.

ArgumentException

An aggregate identity term is null or empty.

EncoderFallbackException

An identity term contains invalid UTF-16.

TenantSegment(KeyedTenantPartition)

Builds the tenant-qualified prefix segment for a cold-storage key.

public static string TenantSegment(KeyedTenantPartition tenant)

Parameters

tenant KeyedTenantPartition

The tenant partition that owns the object.

Returns

string

A path segment uniquely determined by tenant, safe to concatenate with an aggregate identifier without ambiguity.

Exceptions

ArgumentNullException

tenant is null.