Table of Contents

Class SegmentedKey

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

The framework's single injective encoding for composing several identity terms into one string key.

public static class SegmentedKey
Inheritance
SegmentedKey
Inherited Members

Remarks

Joining terms with a bare separator — tenant + ":" + id — is not injective, because no term is validated against any charset. A term containing the separator shifts across the boundary and two distinct tuples render one key:

tenant "acme"     record "eu:order-42"   ->  acme:eu:order-42
tenant "acme:eu"  record "order-42"      ->  acme:eu:order-42     IDENTICAL

Two identities addressing one key is not a formatting problem. Depending on what the key addresses it is one tenant reading, overwriting or irreversibly erasing another's records; one tenant's cached response served to another; or one tenant's authorization grant answering for another's request.

'%' is escaped FIRST, and that is what makes the encoding reversible. Escaping only ':' would map the distinct terms a:b and a%3Ab onto one key — a collision introduced by the escaping itself.

The encoding is the IDENTITY on any term containing neither ':' nor '%', which is what makes it safe to adopt on already-persisted keys: an ordinary identifier encodes to itself, byte for byte, so no stored record is orphaned. The only keys whose bytes change are the ambiguous ones, which had no single correct owner to begin with.

Why not EscapeDataString(string). The framework's standing direction is to build on the BCL rather than hand-roll an equivalent, and EscapeDataString is injective, so it was the first candidate. It is rejected for one measured reason: it percent-encodes everything outside the RFC 3986 unreserved set A-Z a-z 0-9 - . _ ~, so it is not the identity on ordinary identifiers. A tenant term containing a space, '+', '@' or any non-ASCII character encodes to different bytes under EscapeDataString than the bytes already stored, which turns a free, migration-free consolidation into a rewrite of shipped keys. The identity property above is the whole reason this encoding can be adopted on persisted data, and no BCL escaper preserves it. That gap is asserted by a test rather than left as a claim here.

This type exists so the encoding has ONE implementation, reachable from both frameworks. It had grown three times independently — once per subsystem that needed it — because the existing copies sat in packages the other subsystems could not reference. It lives here because this package is the only one every affected subsystem already reaches, and it takes no dependency of its own: the file is pure BCL.

Fields

Separator

The separator placed between encoded segments. Segments are encoded so that none can contain it.

public const char Separator = ':'

Field Value

char

Methods

Compose(string, string)

Composes two terms into one key no other pair of terms can produce.

public static string Compose(string first, string second)

Parameters

first string

The first term.

second string

The second term.

Returns

string

The composed key.

Compose(string, string, string)

Composes three terms into one key no other triple of terms can produce.

public static string Compose(string first, string second, string third)

Parameters

first string

The first term.

second string

The second term.

third string

The third term.

Returns

string

The composed key.

Compose(params string[])

Composes four or more terms into one key no other sequence of terms can produce.

public static string Compose(params string[] segments)

Parameters

segments string[]

The terms, in order. At least two are required.

Returns

string

The composed key.

Exceptions

ArgumentException

segments holds fewer than two terms, or any term is null.

Escape(string)

Encodes one term so that no character in it can be mistaken for a segment boundary.

public static string Escape(string value)

Parameters

value string

The term to encode.

Returns

string

The term with '%' and ':' escaped — the same instance as value when it contains neither.

Remarks

Exposed because subsystems compose different shapes — some join a tenant with one identifier, others with a user, a grant type and a qualifier. Each shape stays injective as long as every term goes through here and the separator between them is a raw Separator.

Exceptions

ArgumentNullException

value is null.

Split(string, int)

Splits a key produced by Compose(string, string) back into its original terms.

public static string[] Split(string key, int count)

Parameters

key string

The composed key.

count int

The exact number of segments the key is expected to carry.

Returns

string[]

The decoded terms, in order.

Remarks

Empty segments are preserved, and that is the point of this method existing. The obvious form, key.Split(':', count, StringSplitOptions.RemoveEmptyEntries), silently SHIFTS the remaining segments left when any term is empty, so a key whose user term is empty promotes the tenant into the user position and addresses a different record entirely. That flag is a defect on its own, wholly independent of escaping, and it was found in two parsers that had each written it by hand.

A key carrying the wrong number of segments is rejected rather than padded or truncated: a caller that receives fewer terms than it asked for would otherwise read a shifted term as a real one.

Exceptions

ArgumentException

key does not carry exactly count segments.

TryCompose(Span<char>, out int, string, string, string)

Composes three terms into a caller-supplied buffer, producing the same key as Compose(string, string, string) without allocating a string.

public static bool TryCompose(Span<char> destination, out int charsWritten, string first, string second, string third)

Parameters

destination Span<char>

The buffer to write the composed key into.

charsWritten int

When this method returns true, the number of characters written to destination; otherwise, zero.

first string

The first term.

second string

The second term.

third string

The third term.

Returns

bool

true if the composed key fitted in destination; otherwise, false, with nothing written.

Remarks

Why this exists. The string-returning overload is the right shape when the key is going to be stored. It is the wrong shape when the key is composed only to probe a dictionary and then dropped, which is what an authorization check does on the dispatch path for every authorized message -- there the composed string is garbage before the call returns. Paired with Dictionary<string, T>.GetAlternateLookup<ReadOnlySpan<char>>() this turns a per-check allocation into a stack write.

It is the same encoding, not a second one, and that is the whole point of it living here. The escaping is identical to Escape(string) -- '%' and ':' encoded in ONE pass, so no ordering exists for a later edit to get wrong -- so a key composed through this method and one composed through Compose(string, string, string) are equal character for character. A caller that probed with one and stored with the other would still find its row. Composing the key a second way, in the caller, is what this method exists to prevent.

Returning false rather than throwing is deliberate: a buffer too small is an ordinary outcome for a stack buffer sized for the common case, and the caller's fallback is simply the allocating overload. It is not an error, so it is not an exception.

Exceptions

ArgumentNullException

first, second or third is null.

Unescape(string)

Reverses Escape(string).

public static string Unescape(string value)

Parameters

value string

The encoded term.

Returns

string

The original term.

Remarks

':' is unescaped BEFORE '%', mirroring the encode order. Doing it the other way round would turn an encoded %253A — a literal "%3A" in the original term — into a separator that was never there.

Exceptions

ArgumentNullException

value is null.