Weave.js
Server

WeaveWebsocketsServer

API reference for the WeaveWebsocketsServer class

Overview

The WeaveWebsocketsServer is a server-side class in Weave.js WebSockets store that provides a real-time backend for collaborative applications using WebSockets as the transport layer and and Express as the server framework. Built on top of the Yjs ecosystem, it acts as a store provider that manages the shared-document state and synchronizes it across all connected clients.

This class enables seamless collaboration by handling server-side:

  • Connection management via WebSocket clients
  • Document synchronization using CRDTs (through Yjs)
  • Broadcasting updates between users in real time
  • Support for awareness events
  • Support for persistence of the shared-state

Import

import { WeaveWebsocketsServer } from "@inditextech/weave-store-websockets/server";

Instantiation

const websocketsServer = new WeaveWebsocketsServer(params: WeaveWebsocketsServerParams);

Parameters

PropTypeDefault
initialState?
initialState
defaultInitialState
horizontalSyncHandlerConfig?
WeaveStoreHorizontalSyncConfig
-
fetchRoom?
FetchRoom
-
persistRoom?
PersistRoom
-
extractRoomId
ExtractRoomId
-
performUpgrade
PerformUpgrade
-

In production...

For production, we recommend deploying using the horizontalSyncHandlerConfig setup.

Methods

handleUpgrade

handleUpgrade(server: http.Server | https.Server)

This method needs the underlying server where request are made and need to apply the HTTP/1.1 protocol upgrade mechanism to switch from HTTP protocol to the WebSockets one.

TypeScript types

type PerformUpgrade = (req: IncomingMessage) => Promise<boolean>;

type ExtractRoomId = (req: IncomingMessage) => string | undefined;

type FetchInitialState = (doc: Y.Doc) => void;

type PersistRoom = (
  roomId: string,
  actualState: Uint8Array<ArrayBufferLike>
) => Promise<void>;

type FetchRoom = (roomId: string) => Promise<Uint8Array | null>;

type WeaveStoreHorizontalSyncRedisConfig = {
  host: string;
  port: number;
  keyPrefix: string;
  password?: string;
};

type WeaveStoreHorizontalSyncConfig = {
  type: "redis";
  config: WeaveStoreHorizontalSyncRedisConfig;
};

type WeaveWebsocketsServerParams = {
  initialState?: FetchInitialState;
  horizontalSyncHandlerConfig?: WeaveStoreHorizontalSyncConfig;
  performUpgrade: PerformUpgrade;
  extractRoomId: ExtractRoomId;
  persistRoom?: PersistRoom;
  fetchRoom?: FetchRoom;
};

Shared-state initial value

If not defined the defaultInitialState is used, which is nothing more than:

A Stage node with 5 children Layer nodes, in the specified order (bottom-to-top):

  • gridLayer: is the layer used by WeaveStageGridPlugin to render the reference grid elements.
  • mainLayer: is the main layer where all the nodes added by the users live.
  • selectionLayer: is the layer used by WeaveNodesSelectionPlugin to render the selection overlay elements.
  • usersPointersLayer: is the layer used by WeaveUsersPointersPlugin to render the users pointers overlay elements.
  • utilityLayer: is a wildcard layer defined that can be used by any plugin.

Check out here the code hat defines the defaultInitialState function.