Class SegmentedKey
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
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
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
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
segmentsstring[]The terms, in order. At least two are required.
Returns
- string
The composed key.
Exceptions
- ArgumentException
segmentsholds 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
valuestringThe term to encode.
Returns
- string
The term with '%' and ':' escaped — the same instance as
valuewhen 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
valueis 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
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
keydoes not carry exactlycountsegments.
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
destinationSpan<char>The buffer to write the composed key into.
charsWrittenintWhen this method returns true, the number of characters written to
destination; otherwise, zero.firststringThe first term.
secondstringThe second term.
thirdstringThe third term.
Returns
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,secondorthirdis null.
Unescape(string)
Reverses Escape(string).
public static string Unescape(string value)
Parameters
valuestringThe 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
valueis null.