@fluidframework/protocol-definitions Package

Packages > @fluidframework/protocol-definitions

Core set of Fluid protocol interfaces shared between services and clients. These interfaces must always be back and forward compatible.

Interfaces

Interface Alerts Description
IActorClient DEPRECATED
IAttachment
IBlob Raw blob stored within the tree
IBranchOrigin Branch origin information
ICapabilities
IClient
IClientConfiguration Key value store of service configuration properties provided to the client as part of connection
IClientDetails
IClientJoin Contents sent with a ClientJoin message
IConnect Message sent to connect to the given document
IConnected Message sent to indicate a client has connected to the server
ICreateBlobResponse
IDocumentAttributes
IDocumentMessage Document specific message
IDocumentSystemMessage Document Message with optional system level data field.
IHelpMessage Represents a message containing tasks.
INack
INackContent Interface for nack content.
IProcessMessageResult
IProposal

Proposal to set the given key/value pair.

Consensus on the proposal is achieved if the MSN is >= the sequence number at which the proposal is made and no client within the collaboration window rejects the proposal.

IProtocolState
IQueueMessage Represents a message in task queue to be processed.
IQuorum Interface combining tracking of clients as well as proposals in the Quorum.
IQuorumClients Interface for tracking clients in the Quorum.
IQuorumClientsEvents Events fired by a Quorum in response to client tracking.
IQuorumProposals Interface for tracking proposals in the Quorum.
IQuorumProposalsEvents Events fired by a Quorum in response to proposal tracking.
ISequencedClient
ISequencedDocumentAugmentedMessage
ISequencedDocumentMessage Sequenced message for a distributed document
ISequencedDocumentSystemMessage
IServerError General errors returned from the server. May want to add error code or something similar in the future.
ISignalClient
ISignalMessage
ISnapshotTree
ISnapshotTreeEx
ISummaryAck Contents of summary ack expected from the server.
ISummaryAttachment Unique identifier for blobs uploaded outside of the summary. Attachment Blobs are uploaded and downloaded separately and do not take part of the snapshot payload. The id gets returned from the backend after the attachment has been uploaded. Additional information can be found here: https://github.com/microsoft/FluidFramework/issues/6374
ISummaryBlob String or Binary data to be uploaded to the server as part of the container's Summary. Note: Already uploaded blobs would be referenced by a ISummaryAttachment. Additional information can be found here: https://github.com/microsoft/FluidFramework/issues/6568
ISummaryContent
ISummaryHandle Path to a summary tree object from the last successful summary indicating the summary object hasn't changed since it was uploaded.
ISummaryNack Contents of summary nack expected from the server.
ISummaryProposal Data about the original proposed summary op.
ISummaryTokenClaims DEPRECATED
ISummaryTree Tree Node data structure with children that are nodes of SummaryObject type: Blob, Handle, Attachment or another Tree.
ITokenClaims

JSON Web Token (JWT) Claims

See https://datatracker.ietf.org/doc/html/rfc7519#section-4

ITokenProvider DEPRECATED
ITokenService DEPRECATED
ITrace Messages to track latency trace
ITree
IUploadedSummaryDetails
IUser Base user definition. It is valid to extend this interface when adding new details to the user object.
IVersion Represents a version of the snapshot of a data store

Enumerations

Enum Description
FileMode
MessageType
NackErrorType Type of the Nack. InvalidScopeError: Client's token is not valid for the intended op. ThrottlingError: Retryable after retryAfter number. BadRequestError: Clients op is invalid and should retry immediately with a valid op. LimitExceededError: Service is having issues. Client should not retry.
ScopeType Defines scope access for a Container/Document
SignalType
TreeEntry Type of entries that can be stored in a tree

Types

TypeAlias Description
ConnectionMode
IApprovedProposal Adds the sequence number at which the message was approved to an ISequencedProposal
ICommittedProposal Adds the sequence number at which the message was committed to an IApprovedProposal
IQuorumEvents All events fired by an IQuorum, both client tracking and proposal tracking.
ISequencedProposal Similar to IProposal except includes the sequence number when it was made in addition to the fields on IProposal
IsoDate ISO 8601 format date: YYYY-MM-DDTHH:MM:SSZ
ITreeEntry A tree entry wraps a path with a type of node
SummaryObject Object representing a node within a summary tree. If any particular node is an ISummaryTree, it can contain additional SummaryObjects as its children.
SummaryTree The root of the summary tree.
SummaryType Type tag used to distinguish different types of nodes in a ISummaryTree.
SummaryTypeNoHandle Summary type that ISummaryHandle points to.

Namespaces

Namespace Description
SummaryType Type tag used to distinguish different types of nodes in a ISummaryTree.

Enumeration Details

FileMode

Signature

export declare enum FileMode 

Flags

Flag Description
Directory
Executable
File
Symlink

FlagDetails

Directory
Signature
Directory = "040000"
Executable
Signature
Executable = "100755"
File
Signature
File = "100644"
Symlink = "120000"

MessageType

Signature

export declare enum MessageType 

Flags

Flag Description
ClientJoin System message sent to indicate a new client has joined the collaboration.
ClientLeave System message sent to indicate a client has left the collaboration.
Control Service specific control messages that are never sequenced.
NoClient Message to indicate that no active clients are present.
NoOp Empty operation message. Used to send an updated reference sequence number. Relay service is free to coalesce these messages or fully drop them, if another op was used to update MSN to a number equal or higher than referenced sequence number in Noop.
Operation Channel operation (op).
Propose Proposes a new consensus value.
Reject Message used to reject a pending proposal.
RemoteHelp Message to indicate the need of a remote agent for a document.
RoundTrip Message to indicate successful round trip.
Summarize Summary operation (op).
SummaryAck Summary operation (op) written.
SummaryNack Summary operation (op) write failure.

FlagDetails

ClientJoin

System message sent to indicate a new client has joined the collaboration.

Signature
ClientJoin = "join"
ClientLeave

System message sent to indicate a client has left the collaboration.

Signature
ClientLeave = "leave"
Control

Service specific control messages that are never sequenced.

Signature
Control = "control"
NoClient

Message to indicate that no active clients are present.

Signature
NoClient = "noClient"
NoOp

Empty operation message. Used to send an updated reference sequence number. Relay service is free to coalesce these messages or fully drop them, if another op was used to update MSN to a number equal or higher than referenced sequence number in Noop.

Signature
NoOp = "noop"
Operation

Channel operation (op).

Signature
Operation = "op"
Propose

Proposes a new consensus value.

Signature
Propose = "propose"
Reject

Message used to reject a pending proposal.

Signature
Reject = "reject"
RemoteHelp

Message to indicate the need of a remote agent for a document.

Signature
RemoteHelp = "remoteHelp"
RoundTrip

Message to indicate successful round trip.

Signature
RoundTrip = "tripComplete"
Summarize

Summary operation (op).

Signature
Summarize = "summarize"
SummaryAck

Summary operation (op) written.

Signature
SummaryAck = "summaryAck"
SummaryNack

Summary operation (op) write failure.

Signature
SummaryNack = "summaryNack"

NackErrorType

Type of the Nack. InvalidScopeError: Client’s token is not valid for the intended op. ThrottlingError: Retryable after retryAfter number. BadRequestError: Clients op is invalid and should retry immediately with a valid op. LimitExceededError: Service is having issues. Client should not retry.

Signature

export declare enum NackErrorType 

Flags

Flag Description
BadRequestError
InvalidScopeError
LimitExceededError
ThrottlingError

FlagDetails

BadRequestError
Signature
BadRequestError = "BadRequestError"
InvalidScopeError
Signature
InvalidScopeError = "InvalidScopeError"
LimitExceededError
Signature
LimitExceededError = "LimitExceededError"
ThrottlingError
Signature
ThrottlingError = "ThrottlingError"

ScopeType

Defines scope access for a Container/Document

Signature

export declare enum ScopeType 

Flags

Flag Description
DocRead Read access is supported on the Container/Document
DocWrite Write access is supported on the Container/Document
SummaryWrite User can generate new summaries operations

FlagDetails

DocRead

Read access is supported on the Container/Document

Signature
DocRead = "doc:read"
DocWrite

Write access is supported on the Container/Document

Signature
DocWrite = "doc:write"
SummaryWrite

User can generate new summaries operations

Signature
SummaryWrite = "summary:write"

SignalType

Signature

export declare enum SignalType 

Flags

Flag Description
ClientJoin System signal sent to indicate a new client has joined the collaboration.
ClientLeave System signal sent to indicate a client has left the collaboration.

FlagDetails

ClientJoin

System signal sent to indicate a new client has joined the collaboration.

Signature
ClientJoin = "join"
ClientLeave

System signal sent to indicate a client has left the collaboration.

Signature
ClientLeave = "leave"

TreeEntry

Type of entries that can be stored in a tree

Signature

export declare enum TreeEntry 

Flags

Flag Description
Attachment
Blob
Tree

FlagDetails

Attachment
Signature
Attachment = "Attachment"
Blob
Signature
Blob = "Blob"
Tree
Signature
Tree = "Tree"

Type Details

ConnectionMode

Signature

export declare type ConnectionMode = "write" | "read";

IApprovedProposal

Adds the sequence number at which the message was approved to an ISequencedProposal

Signature

export declare type IApprovedProposal = {
    approvalSequenceNumber: number;
} & ISequencedProposal;

ICommittedProposal

Adds the sequence number at which the message was committed to an IApprovedProposal

Signature

export declare type ICommittedProposal = {
    commitSequenceNumber: number;
} & IApprovedProposal;

IQuorumEvents

All events fired by an IQuorum, both client tracking and proposal tracking.

Signature

export declare type IQuorumEvents = IQuorumClientsEvents & IQuorumProposalsEvents;

ISequencedProposal

Similar to IProposal except includes the sequence number when it was made in addition to the fields on IProposal

Signature

export declare type ISequencedProposal = {
    sequenceNumber: number;
} & IProposal;

IsoDate

ISO 8601 format date: YYYY-MM-DDTHH:MM:SSZ

Signature

export declare type IsoDate = string;

ITreeEntry

A tree entry wraps a path with a type of node

Signature

export declare type ITreeEntry = {
    path: string;
    mode: FileMode;
} & ({
    type: TreeEntry.Blob;
    value: IBlob;
} | {
    type: TreeEntry.Tree;
    value: ITree;
} | {
    type: TreeEntry.Attachment;
    value: IAttachment;
});

SummaryObject

Object representing a node within a summary tree. If any particular node is an ISummaryTree, it can contain additional SummaryObjects as its children.

Signature

export declare type SummaryObject = ISummaryTree | ISummaryBlob | ISummaryHandle | ISummaryAttachment;

SummaryTree

The root of the summary tree.

Signature

export declare type SummaryTree = ISummaryTree | ISummaryHandle;

SummaryType

Type tag used to distinguish different types of nodes in a ISummaryTree.

Signature

export declare type SummaryType = SummaryType.Attachment | SummaryType.Blob | SummaryType.Handle | SummaryType.Tree;

SummaryTypeNoHandle

Summary type that ISummaryHandle points to.

Signature

export declare type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment;

Remarks

Summary handles are often used to point to summary tree objects contained within older summaries, thus avoiding the need to re-send the entire subtree if summary object has not changed.