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
aggregateIdstringThe 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
aggregateIdis 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
tenantKeyedTenantPartitionThe owning tenant partition.
aggregateTypestringThe nonempty, case-sensitive aggregate type.
aggregateIdstringThe nonempty, case-sensitive aggregate identifier.
Returns
- string
The persisted
v2/tenant/type/idpath 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
tenantis 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
tenantKeyedTenantPartitionThe 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
tenantis null.