WeaveWebsocketsServer

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

Property Type Required Default Description

Property	Type	Required	Default	Description
`performUpgrade`	`PerformUpgrade`	Required		A function that receives as parameter the request and must return a boolean indicating if the request allows to perform the HTTP/1.1 protocol upgrade mechanism. When it returns false, the server replies with HTTP 401 Unauthorized and immediately destroys the socket.
`extractRoomId`	`ExtractRoomId`	Required		A function that receives as parameter the request and must return the room id to connect to
`persistRoom`	`PersistRoom`			Weave.js Store to use to handle the real-time communication
`fetchRoom`	`FetchRoom`			Child nodes to render
`horizontalSyncHandlerConfig`	`WeaveStoreHorizontalSyncConfig`			The configuration for a Redis instance that syncs horizontally several instances of the server. A must-be when scaling horizontally. If not defined no horizontal sync is performed.
`initialState`	`initialState`		`defaultInitialState`	Array of nodes to register and use by the instance

performUpgrade

PerformUpgrade

Required

A function that receives as parameter the request and must return a boolean indicating if the request allows to perform the HTTP/1.1 protocol upgrade mechanism. When it returns false, the server replies with HTTP 401 Unauthorized and immediately destroys the socket.

extractRoomId

ExtractRoomId

Required

A function that receives as parameter the request and must return the room id to connect to

persistRoom

PersistRoom

Weave.js Store to use to handle the real-time communication

fetchRoom

FetchRoom

Child nodes to render

horizontalSyncHandlerConfig

WeaveStoreHorizontalSyncConfig

The configuration for a Redis instance that syncs horizontally several instances of the server. A must-be when scaling horizontally. If not defined no horizontal sync is performed.

initialState

defaultInitialState

Array of nodes to register and use by the instance

In production…

For production, we recommend deploying using the horizontalSyncHandlerConfig setup.

Methods

handleUpgrade

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

This method attaches the upgrade handler to the underlying HTTP/HTTPS server. It applies the HTTP/1.1 protocol upgrade mechanism to switch from HTTP to WebSocket protocol.

If performUpgrade returns false, the server writes an HTTP 401 Unauthorized response and destroys the socket so denied connections do not remain open.

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.