IIdCompressorCore Interface
A distributed UUID generator and compressor.
Generates arbitrary non-colliding v4 UUIDs, called stable IDs, for multiple "sessions" (which can be distributed across the network), providing each session with the ability to map these UUIDs to numbers.
A session is a unique identifier that denotes a single compressor. New IDs are created through a single compressor API which should then sent in ranges to the server for total ordering (and are subsequently relayed to other clients). When a new ID is created it is said to be created by the compressor's "local" session.
For each stable ID created, two numeric IDs are provided by the compressor:
-
A session-local ID, which is stable for the lifetime of the session (which could be longer than that of the compressor object, as it may be serialized for offline usage). Available as soon as the stable ID is allocated. These IDs are session-unique and are thus only safely usable within the scope of the compressor that created it.
-
A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing the corresponding session-local ID is totally ordered (via consensus) with respect to other sessions' allocations. Final IDs are known to and publicly usable by any compressor that has received them.
Compressors will allocate UUIDs in non-random ways to reduce entropy allowing for optimized storage of the data needed to map the UUIDs to the numbers.
The following invariants are upheld by IdCompressor:
-
Session-local IDs will always decompress to the same UUIDs for the lifetime of the session.
-
Final IDs will always decompress to the same UUIDs.
-
After a server-processed range of session-local IDs (from any session) is received by a compressor, any of those session-local IDs may be translated by the compressor into the corresponding final ID. For any given session-local ID, this translation will always yield the same final ID.
-
A UUID will always compress into the same session-local ID for the lifetime of the session.
Session-local IDs are sent across the wire in efficiently-represented ranges. These ranges are created by querying the compressor, and *must* be ordered (i.e. sent to the server) in the order they are created in order to preserve the above invariants.
Session-local IDs can be used immediately after creation, but will eventually (after being sequenced) have a corresponding final ID. This could make reasoning about equality of those two forms difficult. For example, if a cache is keyed off of a session-local ID but is later queried using the final ID (which is semantically equal, as it decompresses to the same UUID/string) it will produce a cache miss. In order to make using collections of both remotely created and locally created IDs easy, regardless of whether the session-local IDs have been finalized, the compressor defines two "spaces" of IDs:
-
Session space: in this space, all IDs are normalized to their "most local form". This means that all IDs created by the local session will be in local form, regardless of if they have been finalized. Remotely created IDs, which could only have been received after finalizing and will never have a local form for the compressor, will of course be final IDs. This space should be used with consumer APIs and data structures, as the lifetime of the IDs is guaranteed to be the same as the compressor object. Care must be taken to not use these IDs across compressor objects, as the local IDs are specific to the compressor that created them.
-
Op space: in this space, all IDs are normalized to their "most final form". This means that all IDs except session-local IDs that have not yet been finalized will be in final ID form. This space is useful for serialization in ops (e.g. references), as other clients that receive them need not do any work to normalize them to *their* session-space in the common case. Note that IDs in op space may move out of Op space over time, namely, when a session-local ID in this space becomes finalized, and thereafter has a "more final form". Consequentially, it may be useful to restrict parameters of a persisted type to this space (to optimize perf), but it is potentially incorrect to use this type for a runtime variable. This is an asymmetry that does not affect session space, as local IDs are always as "local as possible".
These two spaces naturally define a rule: consumers of compressed IDs should use session-space IDs, but serialized forms such as ops should use op-space IDs.
To use, import via @fluidframework/id-compressor/legacy.
For more information about our API support guarantees, see here.
Signature
export interface IIdCompressorCore
Methods
| Method | Alerts | Return Type | Description |
|---|---|---|---|
| beginGhostSession(ghostSessionId, ghostSessionCallback) | Alpha |
void |
Run a callback that is performed from the perspective of a special "ghost" session. Any ids generated by this session will be immediately finalized on the local client as if they were created by a remote client with *WARNING:* This API requires an external consensus mechanism to safely use: In an attached container (i.e. multiple clients may have the document loaded), all clients must guarantee that: - They invoke this API starting from the same finalized creation ranges - This API is invoked with the same ghost session id - |
| finalizeCreationRange(range) | Alpha |
void | Finalizes the supplied range of IDs (which may be from either a remote or local session). |
| serialize(withSession) | Alpha |
SerializedIdCompressorWithOngoingSession | Returns a persistable form of the current state of this IdCompressor which can be rehydrated via IdCompressor.deserialize(). This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios. |
| serialize(withSession) | Alpha |
SerializedIdCompressorWithNoSession | Returns a persistable form of the current state of this IdCompressor which can be rehydrated via IdCompressor.deserialize(). This only includes finalized state and is therefore suitable for use in summaries. |
| takeNextCreationRange() | Alpha |
IdCreationRange | Returns a range of IDs created by this session in a format for sending to the server for finalizing. The range will include all IDs generated via calls to generateCompressedId since the last time a range was taken (via this method or takeUnfinalizedCreationRange). |
| takeUnfinalizedCreationRange() | Alpha |
IdCreationRange | Returns a range of IDs created by this session in a format for sending to the server for finalizing. The range will include all unfinalized IDs generated via calls to generateCompressedId. |
Method Details
beginGhostSession
Run a callback that is performed from the perspective of a special "ghost" session. Any ids generated by this session will be immediately finalized on the local client as if they were created by a remote client with ghostSessionId.
*WARNING:* This API requires an external consensus mechanism to safely use: In an attached container (i.e. multiple clients may have the document loaded), all clients must guarantee that: - They invoke this API starting from the same finalized creation ranges - This API is invoked with the same ghost session id - ghostSessionCallback deterministically mints the same number of ids on each client within the ghost session Failure to meet these requirement will result in divergence across clients and eventual consistency errors. While the ghost sesion callback is running, IdCompressor does not support serialization.
To use, import via @fluidframework/id-compressor/alpha.
For more information about our API support guarantees, see here.
Signature
beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): void;
Remarks
This API is primarily intended for data migration scenarios which are able to deterministically transform data in some format into data in a new format. The first requirement (that all clients must invoke the API with the same finalized creation ranges) is guaranteed for this scenario because the data transformation callback occurs at a specific ack within the op stream on all clients, and clients don't finalize creation ranges for local changes they might have at this point in time.
Parameters
| Parameter | Type | Description |
|---|---|---|
| ghostSessionId | SessionId | The session id that minted ids generated within ghostSessionCallback should be attributed to. |
| ghostSessionCallback | () => void | Callback which mints ids attributed to the ghost session. |
finalizeCreationRange
Finalizes the supplied range of IDs (which may be from either a remote or local session).
To use, import via @fluidframework/id-compressor/alpha.
For more information about our API support guarantees, see here.
Signature
finalizeCreationRange(range: IdCreationRange): void;
Parameters
| Parameter | Type | Description |
|---|---|---|
| range | IdCreationRange | the range of session-local IDs to finalize. |
serialize
Returns a persistable form of the current state of this IdCompressor which can be rehydrated via IdCompressor.deserialize(). This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios.
To use, import via @fluidframework/id-compressor/alpha.
For more information about our API support guarantees, see here.
Signature
serialize(withSession: true): SerializedIdCompressorWithOngoingSession;
Parameters
| Parameter | Type | Description |
|---|---|---|
| withSession | true |
Returns
Return type: SerializedIdCompressorWithOngoingSession
serialize
Returns a persistable form of the current state of this IdCompressor which can be rehydrated via IdCompressor.deserialize(). This only includes finalized state and is therefore suitable for use in summaries.
To use, import via @fluidframework/id-compressor/alpha.
For more information about our API support guarantees, see here.
Signature
serialize(withSession: false): SerializedIdCompressorWithNoSession;
Parameters
| Parameter | Type | Description |
|---|---|---|
| withSession | false |
Returns
Return type: SerializedIdCompressorWithNoSession
takeNextCreationRange
Returns a range of IDs created by this session in a format for sending to the server for finalizing. The range will include all IDs generated via calls to generateCompressedId since the last time a range was taken (via this method or takeUnfinalizedCreationRange).
To use, import via @fluidframework/id-compressor/alpha.
For more information about our API support guarantees, see here.
Signature
takeNextCreationRange(): IdCreationRange;
Returns
the range of IDs, which may be empty. This range must be sent to the server for ordering before it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.
Return type: IdCreationRange
takeUnfinalizedCreationRange
Returns a range of IDs created by this session in a format for sending to the server for finalizing. The range will include all unfinalized IDs generated via calls to generateCompressedId.
To use, import via @fluidframework/id-compressor/alpha.
For more information about our API support guarantees, see here.
Signature
takeUnfinalizedCreationRange(): IdCreationRange;
Returns
the range of IDs, which may be empty. This range must be sent to the server for ordering before it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method. Note: after finalizing the range returned by this method, finalizing any ranges that had been previously taken will result in an error.
Return type: IdCreationRange