Server API

createSnapshot

A callback that receives an object containing the snapshot structure sent by clients. The Snapshot should be persistet to a database. In case persisting fails an error should be thrown.

export type CreateSnapshotParams = {
  snapshot: SnapshotWithClientData;
};

createUpdate

A callback that receives an object containing the update structure sent by clients. The Update should be persistet to a database. In case persisting fails an error should be thrown.

export type CreateUpdateParams = {
  update: Update;
};

getDocument

A callback that should return the necessary document information. The simples implementation would just return the latest snapshot, the proofs for snapshot ancestor chain and all related updates.

A more advanced implementation should take into account if the full document or just a delta was requested and idenitfy if and if so which updates are necessary to send and only return those.

export type GetDocumentMode = "complete" | "delta";
 
export type GetDocumentParams = {
  documentId: string;
  knownSnapshotId?: string;
  knownSnapshotUpdateClocks?: SnapshotUpdateClocks;
  mode: GetDocumentMode;
};

Note: Depending on the application the getDocument can be a getOrCreateDocument and it creates a document if the ID has not seen before.

hasAccess

A callback to verify if the client has read or write access to the requested document. Should return true if the client has access and false in case not.

The callback is invoked with the following argument:

type HasAccessParams =
  | {
      action: "read";
      documentId: string;
      websocketSessionKey: string | undefined;
    }
  | {
      action: "write-snapshot" | "write-update" | "send-ephemeral-message";
      documentId: string;
      publicKey: string;
      websocketSessionKey: string | undefined;
    };

hasBroadcastAccess

A callback to verify if clients are allowed to receive a new message. Should an array of true or false values matching the index of the websocketSessionKeys to indicate which client has access.

The callback is invoked with the following argument:

export type HasBroadcastAccessParams = {
  documentId: string;
  websocketSessionKeys: string[];
};

additionalAuthenticationDataValidations

Must be identical to the supported additionalAuthenticationDataValidations on the client for data parsing to function correctly.

Documentation Example Backend

A fully functional backend can be found here https://github.com/serenity-kit/secsync/tree/main/examples/backend (opens in a new tab). Keep in mind that it accepts any client and does not verify the Websocket session key/token.