[ws] Simple server

Author: jamesgpearce

gulpfile.mjs

@@ -33,6 +33,7 @@ const TEST_MODULES = [
   'synchronizers/synchronizer-local',
   'synchronizers/synchronizer-ws-client',
   'synchronizers/synchronizer-ws-server',
+  'synchronizers/synchronizer-ws-server-simple',
   'synchronizers/synchronizer-broadcast-channel',
 ];
 const ALL_MODULES = [

site/build.ts

@@ -180,6 +180,9 @@ const addApi = (docs: Docs): Docs =>
     .addApiFile('dist/@types/synchronizers/synchronizer-local/index.d.ts')
     .addApiFile('dist/@types/synchronizers/synchronizer-ws-client/index.d.ts')
     .addApiFile('dist/@types/synchronizers/synchronizer-ws-server/index.d.ts')
+    .addApiFile(
+      'dist/@types/synchronizers/synchronizer-ws-server-simple/index.d.ts',
+    )
     .addApiFile(
       'dist/@types/synchronizers/synchronizer-broadcast-channel/index.d.ts',
     )

src/@types/synchronizers/synchronizer-ws-server-simple/docs.js

@@ -0,0 +1,142 @@
+/**
+ * The synchronizer-ws-server-simple module of the TinyBase project lets you
+ * create a server that facilitates synchronization between clients, without the
+ * complications of listeners, persistence, or statistics.
+ *
+ * This makes it more suitable to be used as a reference implementation for
+ * other server environments.
+ * @see Synchronization guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-server-simple
+ * @since v5.4.0
+ */
+/// synchronizer-ws-server-simple
+
+/**
+ * The WsServerSimple interface represents an object that facilitates
+ * synchronization between clients that are using WsSynchronizer instances.
+ *
+ * The core functionality is equivalent to the WsServer interface, but without
+ * the complications of listeners, persistence, or statistics.
+ *
+ * You should use the createWsServerSimple function to create a WsServerSimple
+ * object.
+ * @category Server
+ * @since v5.4.0
+ */
+/// WsServerSimple
+{
+  /**
+   * The getWebSocketServer method returns a reference to the WebSocketServer
+   * being used for this WsServerSimple.
+   * @returns The WebSocketServer reference.
+   * @example
+   * This example creates a WsServerSimple and then gets the WebSocketServer
+   * reference back out again.
+   *
+   * ```js
+   * import {WebSocketServer} from 'ws';
+   * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+   *
+   * const webSocketServer = new WebSocketServer({port: 8053});
+   * const server = createWsServerSimple(webSocketServer);
+   *
+   * console.log(server.getWebSocketServer() == webSocketServer);
+   * // -> true
+   *
+   * server.destroy();
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  /// WsServerSimple.getWebSocketServer
+  /**
+   * The destroy method provides a way to clean up the server at the end of its
+   * use.
+   *
+   * This closes the underlying WebSocketServer that was provided when the
+   * WsServerSimple was created.
+   * @example
+   * This example creates a WsServerSimple and then destroys it again, closing
+   * the underlying WebSocketServer.
+   *
+   * ```js
+   * import {WebSocketServer} from 'ws';
+   * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+   *
+   * const webSocketServer = new WebSocketServer({port: 8053});
+   * webSocketServer.on('close', () => {
+   *   console.log('WebSocketServer closed');
+   * });
+   * const server = createWsServerSimple(webSocketServer);
+   *
+   * server.destroy();
+   * // ...
+   * // -> 'WebSocketServer closed'
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  /// WsServerSimple.destroy
+}
+/**
+ * The createWsServerSimple function creates a WsServerSimple that facilitates
+ * synchronization between clients that are using WsSynchronizer instances.
+ *
+ * This should be run in a server environment, and you must pass in a configured
+ * WebSocketServer object in order to create it.
+ *
+ * The core functionality is equivalent to the WsServer interface, but without
+ * the complications of listeners, persistence, or statistics. This makes it
+ * more suitable to be used as a reference implementation for other server
+ * environments.
+ * @param webSocketServer A WebSocketServer object from your server environment.
+ * @returns A reference to the new WsServerSimple object.
+ * @example
+ * This example creates a WsServerSimple that synchronizes two clients on a
+ * shared path.
+ *
+ * ```js
+ * import {WebSocketServer} from 'ws';
+ * import {createMergeableStore} from 'tinybase';
+ * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+ * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+ *
+ * // Server
+ * const server = createWsServerSimple(new WebSocketServer({port: 8053}));
+ *
+ * // Client 1
+ * const clientStore1 = createMergeableStore();
+ * clientStore1.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer1 = await createWsSynchronizer(
+ *   clientStore1,
+ *   new WebSocket('ws://localhost:8053/petShop'),
+ * );
+ * await synchronizer1.startSync();
+ * // ...
+ *
+ * // Client 2
+ * const clientStore2 = createMergeableStore();
+ * clientStore2.setCell('pets', 'felix', 'species', 'cat');
+ * const synchronizer2 = await createWsSynchronizer(
+ *   clientStore2,
+ *   new WebSocket('ws://localhost:8053/petShop'),
+ * );
+ * await synchronizer2.startSync();
+ * // ...
+ *
+ * console.log(clientStore1.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * console.log(clientStore2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * server.destroy();
+ * ```
+ * @category Creation
+ * @since v5.4.0
+ */
+/// createWsServerSimple

src/@types/synchronizers/synchronizer-ws-server-simple/index.d.ts

@@ -0,0 +1,16 @@
+/// synchronizer-ws-server-simple
+
+import type {WebSocketServer} from 'ws';
+
+/// WsServerSimple
+export interface WsServerSimple {
+  /// WsServerSimple.getWebSocketServer
+  getWebSocketServer(): WebSocketServer;
+  /// WsServerSimple.destroy
+  destroy(): void;
+}
+
+/// createWsServerSimple
+export function createWsServerSimple(
+  webSocketServer: WebSocketServer,
+): WsServerSimple;

src/@types/synchronizers/synchronizer-ws-server-simple/with-schemas/index.d.ts

@@ -0,0 +1,16 @@
+/// synchronizer-ws-server-simple
+
+import type {WebSocketServer} from 'ws';
+
+/// WsServerSimple
+export interface WsServerSimple {
+  /// WsServerSimple.getWebSocketServer
+  getWebSocketServer(): WebSocketServer;
+  /// WsServerSimple.destroy
+  destroy(): void;
+}
+
+/// createWsServerSimple
+export function createWsServerSimple(
+  webSocketServer: WebSocketServer,
+): WsServerSimple;

src/synchronizers/synchronizer-ws-server-simple/index.ts

@@ -0,0 +1,71 @@
+import {EMPTY_STRING, UTF8, strMatch} from '../../common/strings.ts';
+import {
+  IdMap2,
+  mapEnsure,
+  mapForEach,
+  mapGet,
+  mapNew,
+  mapSet,
+} from '../../common/map.ts';
+import {WebSocket, WebSocketServer} from 'ws';
+import type {
+  WsServerSimple,
+  createWsServerSimple as createWsServerSimpleDecl,
+} from '../../@types/synchronizers/synchronizer-ws-server-simple/index.js';
+import {collClear, collDel, collIsEmpty} from '../../common/coll.ts';
+import {createRawPayload, ifPayloadValid} from '../common.ts';
+import type {Id} from '../../@types/common/index.js';
+import {ifNotUndefined} from '../../common/other.ts';
+import {objFreeze} from '../../common/obj.ts';
+
+const PATH_REGEX = /\/([^?]*)/;
+
+export const createWsServerSimple = ((webSocketServer: WebSocketServer) => {
+  const clientsByPath: IdMap2<WebSocket> = mapNew();
+
+  webSocketServer.on('connection', (webSocket, request) =>
+    ifNotUndefined(strMatch(request.url, PATH_REGEX), ([, pathId]) =>
+      ifNotUndefined(request.headers['sec-websocket-key'], async (clientId) => {
+        const clients = mapEnsure(clientsByPath, pathId, mapNew<Id, WebSocket>);
+        mapSet(clients, clientId, webSocket);
+
+        webSocket.on('message', (data) => {
+          const payload = data.toString(UTF8);
+          ifPayloadValid(payload, (toClientId, remainder) => {
+            const forwardedPayload = createRawPayload(clientId, remainder);
+            if (toClientId === EMPTY_STRING) {
+              mapForEach(clients, (otherClientId, otherWebSocket) =>
+                otherClientId !== clientId
+                  ? otherWebSocket.send(forwardedPayload)
+                  : 0,
+              );
+            } else {
+              mapGet(clients, toClientId)?.send(forwardedPayload);
+            }
+          });
+        });
+
+        webSocket.on('close', () => {
+          collDel(clients, clientId);
+          if (collIsEmpty(clients)) {
+            collDel(clientsByPath, pathId);
+          }
+        });
+      }),
+    ),
+  );
+
+  const getWebSocketServer = () => webSocketServer;
+
+  const destroy = () => {
+    collClear(clientsByPath);
+    webSocketServer.close();
+  };
+
+  const wsServerSimple = {
+    getWebSocketServer,
+    destroy,
+  };
+
+  return objFreeze(wsServerSimple as WsServerSimple);
+}) as typeof createWsServerSimpleDecl;

test/unit/core/documentation.test.ts

@@ -22,6 +22,7 @@ import * as TinyBaseSynchronizerBroadcastChannel from 'tinybase/synchronizers/sy
 import * as TinyBaseSynchronizerLocal from 'tinybase/synchronizers/synchronizer-local';
 import * as TinyBaseSynchronizerWsClient from 'tinybase/synchronizers/synchronizer-ws-client';
 import * as TinyBaseSynchronizerWsServer from 'tinybase/synchronizers/synchronizer-ws-server';
+import * as TinyBaseSynchronizerWsServerSimple from 'tinybase/synchronizers/synchronizer-ws-server-simple';
 import * as TinyBaseSynchronizers from 'tinybase/synchronizers';
 import * as TinyBaseTools from 'tinybase/tools';
 import * as TinyBaseUiReact from 'tinybase/ui-react';
@@ -86,6 +87,8 @@ import {transformSync} from 'esbuild';
   'tinybase/synchronizers/synchronizer-local': TinyBaseSynchronizerLocal,
   'tinybase/synchronizers/synchronizer-ws-client': TinyBaseSynchronizerWsClient,
   'tinybase/synchronizers/synchronizer-ws-server': TinyBaseSynchronizerWsServer,
+  'tinybase/synchronizers/synchronizer-ws-server-simple':
+    TinyBaseSynchronizerWsServerSimple,
   'tinybase/synchronizers/synchronizer-broadcast-channel':
     TinyBaseSynchronizerBroadcastChannel,
   'tinybase/tools': TinyBaseTools,

test/unit/synchronizers/synchronizer-ws-server-simple.test.ts

@@ -0,0 +1,54 @@
+/* eslint-disable jest/no-conditional-expect */
+
+import {WebSocket, WebSocketServer} from 'ws';
+import {createMergeableStore} from 'tinybase';
+import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+import {pause} from '../common/other.ts';
+import {resetHlc} from '../common/mergeable.ts';
+
+beforeEach(() => {
+  resetHlc();
+});
+
+test('Basics', async () => {
+  const wsServerSimple = createWsServerSimple(
+    new WebSocketServer({port: 8054}),
+  );
+
+  const s1 = createMergeableStore('s1');
+  const synchronizer1 = await createWsSynchronizer(
+    s1,
+    new WebSocket('ws://localhost:8054'),
+  );
+  await synchronizer1.startSync();
+  s1.setCell('t1', 'r1', 'c1', 4);
+
+  const s2 = createMergeableStore('s2');
+  const synchronizer2 = await createWsSynchronizer(
+    s2,
+    new WebSocket('ws://localhost:8054'),
+  );
+  await synchronizer2.startSync();
+  s2.setCell('t1', 'r2', 'price', 5);
+
+  await pause();
+
+  expect(s1.getTables()).toEqual({
+    t1: {r2: {price: 5}, r1: {c1: 4}},
+  });
+  expect(s2.getTables()).toEqual({
+    t1: {r2: {price: 5}, r1: {c1: 4}},
+  });
+
+  synchronizer1.destroy();
+  synchronizer2.destroy();
+  wsServerSimple.destroy();
+});
+
+test('Accessors', async () => {
+  const wssServer = new WebSocketServer({port: 8054});
+  const wsServerSimple = createWsServerSimple(wssServer);
+  expect(wsServerSimple.getWebSocketServer()).toEqual(wssServer);
+  wsServerSimple.destroy();
+});