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
Prop | Type | Default |
---|---|---|
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.