IIdCompressor Interface
A distributed UUID generator and compressor. IdCompressor offers the ability to generate arbitrary non-colliding v4 UUIDs, called stable IDs, while compressing them into small integers for efficient storage and transmission. It also provides the ability to decompress these integers back into their original UUIDs.
The compressor is designed to be used in a distributed environment, where multiple clients may be generating IDs concurrently. IDs generated by a compressor, via calls to generateCompressedId, are created in the compressor's "local" session. These IDs are unique within the session, but may not be unique across sessions. In the context of Fluid, the scope of a session is the same as the scope of a container. This means that anytime IDs are transferred between sessions, they must be translated through a process called "normalization": - The scope of a local session (in which local IDs are unique) is called the "session space" of the client. - The context of persisted state (in Fluid, this is the context of ops and summaries) is called "op space". - SessionSpaceCompressedIds, generated via calls to generateCompressedId, should NEVER be serialized directly. In Fluid, this means they should not be included in ops or summaries. - Before serialization, IDs must be normalized to op space to ensure they are interpretable by other clients. - Upon receipt, IDs should be normalized back to session space before use.
Example Usage:
### Client A (Sender)
// Generate several local IDs
const localId1 = idCompressor.generateCompressedId();
const localId2 = idCompressor.generateCompressedId();
const localId3 = idCompressor.generateCompressedId();
// Normalize these IDs to op space for inclusion in a message
const opSpaceId1 = idCompressor.normalizeToOpSpace(localId1);
const opSpaceId2 = idCompressor.normalizeToOpSpace(localId2);
const opSpaceId3 = idCompressor.normalizeToOpSpace(localId3);
// Create and send a message containing these op space IDs along with the sender's session ID
// In Fluid, this would be an op or summary
const message = {
sessionID: idCompressor.localSessionId,
ids: [opSpaceId1, opSpaceId2, opSpaceId3]
};
### Client B (Receiver)
// Receive the message from Client A
const receivedMessage = ...; // In Fluid, this would be an op or summary
// Normalize the received IDs back to session space, utilizing the sender's session ID
const sessionSpaceId1 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[0], receivedMessage.sessionID);
const sessionSpaceId2 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[1], receivedMessage.sessionID);
const sessionSpaceId3 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[2], receivedMessage.sessionID);
This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.
Signature
/** @sealed */
export interface IIdCompressor
Properties
| Property | Type | Description |
|---|---|---|
| localSessionId | SessionId | The local session ID. |
Methods
| Method | Return Type | Description |
|---|---|---|
| decompress(id) | StableId | Decompresses a previously compressed ID into a UUID. |
| generateCompressedId() | SessionSpaceCompressedId | Generates a new compressed ID. The returned ID is in session space and should not be serialized directly. See IIdCompressor for more details. |
| generateDocumentUniqueId() | (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId | Generates a new ID that is guaranteed to be unique across all sessions known to this compressor without the need for any normalization. The returned ID is not guaranteed to be a compressed ID (small number); it may be a stable ID (UUID string). In Fluid, the likelihood of generating the bulkier stable ID is dictated by network conditions and is highly probable in scenarios such as offline. This is still useful for use cases where simplicity is more important than performance and this approach will often be superior to generating a UUID. If small numbers are a requirement, generateCompressedId and normalization should be used instead. See IIdCompressor for more details. |
| normalizeToOpSpace(id) | OpSpaceCompressedId | Normalizes a session space ID into op space. The returned ID is in op space and can be safely serialized. However, it should be normalized back to session space before use. |
| normalizeToSessionSpace(id, originSessionId) | SessionSpaceCompressedId | Normalizes an ID into session space. |
| recompress(uncompressed) | SessionSpaceCompressedId | Recompresses a UUID. |
| tryNormalizeToSessionSpaceWithoutSession(id) | SessionSpaceCompressedId | undefined | Attempts to normalize an op-space ID into session space without an originator session id. This mainly exists for data recovery purposes, when the originator session id was lost. When possible, use normalizeToSessionSpace(id, originSessionId) instead. |
| tryRecompress(uncompressed) | SessionSpaceCompressedId | undefined | Attempts to recompress a UUID. |
Property Details
localSessionId
The local session ID.
Signature
localSessionId: SessionId;
Type: SessionId
Method Details
decompress
Decompresses a previously compressed ID into a UUID.
Signature
decompress(id: SessionSpaceCompressedId): StableId;
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | SessionSpaceCompressedId | The compressed ID to be decompressed. |
Returns
The UUID associated with the compressed ID.
Return type: StableId
Error Handling
If the ID was not generated by any session known to this compressor.
generateCompressedId
Generates a new compressed ID. The returned ID is in session space and should not be serialized directly. See IIdCompressor for more details.
Signature
generateCompressedId(): SessionSpaceCompressedId;
Returns
A new local ID in session space.
Return type: SessionSpaceCompressedId
generateDocumentUniqueId
Generates a new ID that is guaranteed to be unique across all sessions known to this compressor without the need for any normalization. The returned ID is not guaranteed to be a compressed ID (small number); it may be a stable ID (UUID string). In Fluid, the likelihood of generating the bulkier stable ID is dictated by network conditions and is highly probable in scenarios such as offline. This is still useful for use cases where simplicity is more important than performance and this approach will often be superior to generating a UUID. If small numbers are a requirement, generateCompressedId and normalization should be used instead. See IIdCompressor for more details.
Signature
generateDocumentUniqueId(): (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId;
Returns
A new local ID in session space.
Return type: (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId
normalizeToOpSpace
Normalizes a session space ID into op space. The returned ID is in op space and can be safely serialized. However, it should be normalized back to session space before use.
Signature
normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | SessionSpaceCompressedId | The local ID to normalize. |
Returns
The ID in op space.
Return type: OpSpaceCompressedId
normalizeToSessionSpace
Normalizes an ID into session space.
Signature
normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;
Remarks
For this to be valid, originSessionId must be the localSessionId of the compressor that normalized id to op space. Additionally, this compressor must know about the relevant IdCreationRange from the encoding IIdCompressor. This can be accomplished using creating the compressor using deserializeIdCompressor(serialized, logger), or relying on something (like the Fluid runtime) to synchronize the range information using internal mechanisms.
The IIdCompressor provided by the Fluid Framework runtime will automatically track Id Creation Ranges (via its own ops) from other clients in the container. It is up to the user of the IIdCompressor to ensure the relevant session information is available, either by depending on the originating client's session ID for ops, or by explicitly storing it alongside the data containing the OpSpaceCompressedId.
Note that attachment summaries, while they are ops, are also interpreted as summaries without the context of their originating session, so they should explicitly include session IDs if required to decode them just like regular summaries and exported data.
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | OpSpaceCompressedId | The ID to normalize. |
| originSessionId | SessionId | The localSessionId of the compressor which encoded id. This might not be the client that created id in the first place, but rather the client that serialized it. This is an important distinction in the case of a reference, where a client might refer to an ID created by another client. |
Returns
The session-space ID in the local session corresponding to id.
Return type: SessionSpaceCompressedId
recompress
Recompresses a UUID.
Signature
recompress(uncompressed: StableId): SessionSpaceCompressedId;
Parameters
| Parameter | Type | Description |
|---|---|---|
| uncompressed | StableId | The UUID to recompress. |
Returns
The CompressedId associated with uncompressed.
Return type: SessionSpaceCompressedId
Error Handling
If the UUID was not generated by any session known to this compressor.
tryNormalizeToSessionSpaceWithoutSession
Attempts to normalize an op-space ID into session space without an originator session id. This mainly exists for data recovery purposes, when the originator session id was lost. When possible, use normalizeToSessionSpace(id, originSessionId) instead.
Signature
tryNormalizeToSessionSpaceWithoutSession(id: OpSpaceCompressedId): SessionSpaceCompressedId | undefined;
Remarks
When the id is a final ID, this will return the properly translated session-space ID, or throw if it detects that the final id is not valid in this compressor.
Returns undefined if id is a non-final op-space ID — those are local to the originating session and require its session id to resolve. Callers which have the originating session id should call normalizeToSessionSpace(id, originSessionId) instead.
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | OpSpaceCompressedId | The ID to normalize. |
Returns
The session-space ID corresponding to id, or undefined if id is non-final and therefore requires an originator session id to resolve.
Return type: SessionSpaceCompressedId | undefined
Error Handling
If id is final but is not known to this compressor (i.e. it refers to a final id that has never been observed as finalized). Note that it is possible (even likely) for a finalized id from another id compressor to pass this check, and return an incorrect session-space ID. This error is thrown only in cases where it is possible to detect the input is invalid, and intended to help with catching bugs where invalid identifiers are being provided. It cannot be relied upon for validation.
tryRecompress
Attempts to recompress a UUID.
Signature
tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
Parameters
| Parameter | Type | Description |
|---|---|---|
| uncompressed | StableId | The UUID to recompress. |
Returns
The CompressedId associated with uncompressed or undefined if the UUID was not generated by any session known to this compressor.
Return type: SessionSpaceCompressedId | undefined