Class SagaCorrelation
Derives a saga identifier from a business correlation key, so a publisher can address a saga instance without knowing the identifier the saga was created with.
public static class SagaCorrelation
- Inheritance
-
SagaCorrelation
- Inherited Members
Remarks
The problem this solves. SagaId is the only thing that locates a saga instance, so without this a publisher has to already hold the saga's identifier — which the first message in a conversation cannot, and a service in another bounded context generally never will. The business key is the thing every participant does share: an order number, a tenant's subscription id, a shipment reference.
Why derivation rather than a lookup table. The same key always derives the same identifier, so the existing load-by-id path finds the instance with no second query, no index to keep, and nothing extra for a provider to implement. Every store that can load a saga by id can therefore correlate, which is why this works on all of them rather than on whichever ones gained a lookup first.
The identifier is a function of the saga TYPE as well as the key, so two different sagas correlating on the same order number receive independently scoped hash inputs. Pass a stable type scope: a renamed saga derives different identifiers and stops finding its own in-flight instances, which is a migration hazard and is the reason the type name is an explicit argument rather than something read from the call site.
Collision bound. The result retains 122 SHA-256 digest bits after UUID version and variant encoding. Framing distinguishes input boundaries, but truncated hashes cannot prove uniqueness. A saga whose identity must be provably unique should carry an identifier assigned by a suitable authoritative identity service.
SHA-256 and RFC 9562 version 8, deliberately, and NOT the version 5 that a reader might expect. Name-based version 5 is specified over SHA-1, and this project does not use SHA-1. Version 8 is the RFC's provision for an application-defined derivation, which is exactly what this is, so the digest can be SHA-256 while the result is still a well-formed UUID with its version and variant bits set. The derivation is not a security boundary: it decides which saga an event belongs to, and an attacker who can choose the business key can already address that saga by sending the key.
Versioned framing. The v2 derivation hashes a domain tag and two big-endian UTF-8 byte-length frames. Changing this derivation changes existing IDs: publishers and coordinators must upgrade together, and retained in-flight state needs explicit migration rather than an ambiguous fallback.
Methods
ToSagaId(string, string)
Derives the saga identifier for correlationKey within sagaType.
public static Guid ToSagaId(string sagaType, string correlationKey)
Parameters
sagaTypestringA stable name for the saga type, scoping the key independently for unrelated sagas.
correlationKeystringThe business key shared by every participant in the conversation.
Returns
Exceptions
- ArgumentException
Thrown when either argument is null, empty, whitespace, or contains ill-formed UTF-16. Neither has a meaningful empty value: an empty key would route every message to one instance, and an empty type would let unrelated sagas share identifiers.
ToSagaId<TSaga>(string)
Derives an identifier using the same stable, fully scoped type identity as declarative saga correlation.
public static Guid ToSagaId<TSaga>(string correlationKey)
Parameters
correlationKeystringThe literal well-formed Unicode business key.
Returns
Type Parameters
TSagaThe closed saga type, including its assembly simple name, namespace and generic arguments.
Remarks
Assembly versions, strong-name keys and load contexts are excluded intentionally. Renaming or moving the type/assembly changes identifiers. Supplying the exact generated scope through the string overload reproduces this typed result; an ordinary short type-name scope does not.
Exceptions
- ArgumentException
The key is null, empty, whitespace or ill-formed UTF-16.