@evolu/nodejs 1.0.1-preview.1 → 1.0.1-preview.10

package/dist/Crypto.d.ts

@@ -0,0 +1,3 @@
+import type { TimingSafeEqual } from "@evolu/common";
+export declare const createTimingSafeEqual: () => TimingSafeEqual;
+//# sourceMappingURL=Crypto.d.ts.map

package/dist/Crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Crypto.d.ts","sourceRoot":"","sources":["../src/Crypto.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,eAAO,MAAM,qBAAqB,QAAO,eAAkC,CAAC"}

package/dist/Crypto.js

@@ -0,0 +1,2 @@
+import { timingSafeEqual } from "node:crypto";
+export const createTimingSafeEqual = () => timingSafeEqual;

package/dist/Evolu/Relay.d.ts

@@ -1,7 +1,22 @@
-import { ConsoleDep } from "@evolu/common";
+import { ConsoleDep, CreateSqliteDriverDep, Result, SqliteError } from "@evolu/common";
 import { Relay, RelayConfig } from "@evolu/common/evolu";
 export interface NodeJsRelayConfig extends RelayConfig {
+    /** The port number for the HTTP server. */
     readonly port?: number;
 }
-export declare const createNodeJsRelay: (deps: ConsoleDep) => (config: NodeJsRelayConfig) => Promise<Relay>;
+/**
+ * Creates an Evolu relay server.
+ *
+ * This implementation uses Node.js and better-sqlite3. Additional relay
+ * implementations will be provided for other platforms (Bun, Deno, Cloudflare
+ * Workers, Vercel Edge, etc.).
+ */
+export declare const createNodeJsRelay: (deps: ConsoleDep) => (config: NodeJsRelayConfig) => Promise<Result<Relay, SqliteError>>;
+/**
+ * Creates an Evolu relay server with a custom SQLite driver.
+ *
+ * Use this when you need to provide a different SQLite driver implementation
+ * (e.g., using alternative SQLite libraries).
+ */
+export declare const createNodeJsRelayWithSqliteDriver: (deps: ConsoleDep & CreateSqliteDriverDep) => (config: NodeJsRelayConfig) => Promise<Result<Relay, SqliteError>>;
 //# sourceMappingURL=Relay.d.ts.map

package/dist/Evolu/Relay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../src/Evolu/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAQX,MAAM,eAAe,CAAC;AACvB,OAAO,EAML,KAAK,EACL,WAAW,EAEZ,MAAM,qBAAqB,CAAC;AAI7B,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,iBAAiB,GAC3B,MAAM,UAAU,MACV,QAAQ,iBAAiB,KAAG,OAAO,CAAC,KAAK,CA0G/C,CAAC"}
+{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../src/Evolu/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAIV,qBAAqB,EAIrB,MAAM,EAEN,WAAW,EAGZ,MAAM,eAAe,CAAC;AACvB,OAAO,EASL,KAAK,EACL,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAO7B,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC3B,MAAM,UAAU,MAChB,QAAQ,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAInD,CAAC;AAEf;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,GAC3C,MAAM,UAAU,GAAG,qBAAqB,MACxC,QAAQ,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAKnD,CAAC"}

package/dist/Evolu/Relay.js

@@ -1,80 +1,164 @@
-import { createManyToManyMap, createRandom, createSqlite, getOrThrow, SimpleName, Uint8Array, } from "@evolu/common";
-import { applyProtocolMessageAsRelay, createRelayStorage, maxProtocolMessageSize, protocolVersion, } from "@evolu/common/evolu";
+import { createManyToManyMap, createRandom, createSqlite, ok, SimpleName, Uint8Array, } from "@evolu/common";
+import { applyProtocolMessageAsRelay, createBaseSqliteStorageTables, createRelayLogger, createRelaySqliteStorage, createRelayStorageTables, defaultProtocolMessageMaxSize, parseOwnerIdFromOwnerWebSocketTransportUrl, } from "@evolu/common/evolu";
+import { existsSync } from "fs";
+import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
 import { createBetterSqliteDriver } from "../BetterSqliteDriver.js";
-export const createNodeJsRelay = (deps) => async (config) => {
-    const { port = 443, name = getOrThrow(SimpleName.from("evolu-relay")), enableLogging = false, } = config;
-    deps.console.log(`Evolu Relay started on port ${port}`);
-    deps.console.enabled = enableLogging;
-    const versionedName = getOrThrow(SimpleName.from(`${name}-${protocolVersion}`));
-    const sqlite = getOrThrow(await createSqlite({
-        ...deps,
-        createSqliteDriver: createBetterSqliteDriver,
-    })(versionedName));
-    const sqliteStorageDeps = {
-        sqlite,
-        random: createRandom(),
-    };
-    const storage = getOrThrow(createRelayStorage(sqliteStorageDeps)({
-        onStorageError: (error) => {
-            deps.console.error("[relay]", "[storage]", error);
-        },
-    }));
+import { createTimingSafeEqual } from "../Crypto.js";
+/**
+ * Creates an Evolu relay server.
+ *
+ * This implementation uses Node.js and better-sqlite3. Additional relay
+ * implementations will be provided for other platforms (Bun, Deno, Cloudflare
+ * Workers, Vercel Edge, etc.).
+ */
+export const createNodeJsRelay = (deps) => (config) => createNodeJsRelayWithSqliteDriver({
+    ...deps,
+    createSqliteDriver: createBetterSqliteDriver,
+})(config);
+/**
+ * Creates an Evolu relay server with a custom SQLite driver.
+ *
+ * Use this when you need to provide a different SQLite driver implementation
+ * (e.g., using alternative SQLite libraries).
+ */
+export const createNodeJsRelayWithSqliteDriver = (deps) => (config) => createNodeJsRelayWithDeps({
+    ...deps,
+    random: createRandom(),
+    timingSafeEqual: createTimingSafeEqual(),
+})(config);
+const createNodeJsRelayWithDeps = (deps) => async ({ port = 443, name = SimpleName.orThrow("evolu-relay"), enableLogging = false, authenticateOwner, }) => {
+    const log = createRelayLogger(deps);
+    log.started(enableLogging, port);
+    const dbFileExists = existsSync(`${name}.db`);
+    const sqlite = await createSqlite(deps)(name);
+    if (!sqlite.ok)
+        return sqlite;
+    const depsWithSqlite = { ...deps, sqlite: sqlite.value };
+    if (!dbFileExists) {
+        const baseTables = createBaseSqliteStorageTables(depsWithSqlite);
+        if (!baseTables.ok)
+            return baseTables;
+        const relayTables = createRelayStorageTables(depsWithSqlite);
+        if (!relayTables.ok)
+            return relayTables;
+    }
+    const storage = createRelaySqliteStorage(depsWithSqlite)({
+        onStorageError: log.storageError,
+    });
+    const server = createServer();
     const wss = new WebSocketServer({
-        maxPayload: maxProtocolMessageSize,
-        port,
+        maxPayload: defaultProtocolMessageMaxSize,
+        noServer: true,
     });
     const ownerSocketsMap = createManyToManyMap();
+    server.on("upgrade", (request, socket, head) => {
+        socket.on("error", log.upgradeSocketError);
+        const completeUpgrade = () => {
+            socket.removeListener("error", log.upgradeSocketError);
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                wss.emit("connection", ws, request);
+            });
+        };
+        if (!authenticateOwner) {
+            completeUpgrade();
+            return;
+        }
+        const ownerId = parseOwnerIdFromOwnerWebSocketTransportUrl(request.url ?? "");
+        if (!ownerId) {
+            log.invalidOrMissingOwnerIdInUrl(request.url);
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        authenticateOwner(ownerId)
+            .then((isAuthenticated) => {
+            if (!isAuthenticated) {
+                log.unauthorizedOwner(ownerId);
+                socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+                socket.destroy();
+                return;
+            }
+            completeUpgrade();
+        })
+            .catch((error) => {
+            log.authenticateOwnerError(error);
+            socket.write("HTTP/1.1 500 Internal Server Error\r\n\r\n");
+            socket.destroy();
+        });
+    });
     wss.on("connection", (ws) => {
-        ws.on("error", deps.console.error);
+        log.connectionEstablished(wss.clients.size);
+        ws.on("error", (error) => {
+            log.connectionWebSocketError(error);
+        });
         const options = {
             subscribe: (ownerId) => {
                 ownerSocketsMap.add(ownerId, ws);
+                log.relayOptionSubscribe(ownerId, () => ownerSocketsMap.getValues(ownerId)?.size ?? 0);
+            },
+            unsubscribe: (ownerId) => {
+                ownerSocketsMap.remove(ownerId, ws);
+                log.relayOptionUnsubscribe(ownerId, () => ownerSocketsMap.getValues(ownerId)?.size ?? 0);
             },
             broadcast: (ownerId, message) => {
                 const sockets = ownerSocketsMap.getValues(ownerId);
+                if (!sockets)
+                    return;
+                let broadcastCount = 0;
                 for (const socket of sockets) {
                     if (socket !== ws && socket.readyState === WebSocket.OPEN) {
                         socket.send(message, { binary: true });
+                        broadcastCount++;
                     }
                 }
+                log.relayOptionBroadcast(ownerId, broadcastCount, sockets.size);
             },
         };
         ws.on("message", (message) => {
             if (!Uint8Array.is(message))
                 return;
-            const response = applyProtocolMessageAsRelay({ storage })(message, options);
-            if (!response.ok) {
-                deps.console.warn(response.error.type);
-                return;
-            }
-            if (response.value) {
-                ws.send(response.value, { binary: true });
-            }
+            log.messageLength(message.length);
+            applyProtocolMessageAsRelay({ storage })(message, options)
+                .then((response) => {
+                if (!response.ok) {
+                    log.applyProtocolMessageAsRelayError(response.error);
+                    return;
+                }
+                ws.send(response.value.message, { binary: true });
+                log.responseLength(response.value.message.length);
+            })
+                .catch(log.applyProtocolMessageAsRelayUnknownError);
         });
         ws.on("close", () => {
             ownerSocketsMap.deleteValue(ws);
+            log.connectionClosed(wss.clients.size);
         });
     });
-    const disposeWss = () => {
-        deps.console.log("Shutting down Evolu Relay...");
+    server.listen(port);
+    const dispose = () => {
+        log.shuttingDown();
         wss.clients.forEach((client) => {
             if (client.readyState === WebSocket.OPEN) {
                 client.close(1000, "Evolu Relay shutting down");
             }
         });
         wss.close(() => {
-            deps.console.log("Evolu Relay disposed");
+            log.webSocketServerDisposed();
+        });
+        server.close(() => {
+            log.httpServerDisposed();
         });
     };
     let isDisposed = false;
-    return {
+    const relay = {
         [Symbol.dispose]: () => {
             if (isDisposed)
                 return;
             isDisposed = true;
-            sqlite[Symbol.dispose]();
-            disposeWss();
+            sqlite.value[Symbol.dispose]();
+            dispose();
         },
     };
+    return ok(relay);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/nodejs",
-  "version": "1.0.1-preview.1",
+  "version": "1.0.1-preview.10",
   "description": "Evolu for Node.js",
   "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
   "license": "MIT",
@@ -20,19 +20,21 @@
     "README.md"
   ],
   "dependencies": {
-    "better-sqlite3": "^11.10.0",
+    "better-sqlite3": "^12.1.1",
     "ws": "^8.18.2"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^22.15.30",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.2",
-    "@evolu/common": "6.0.1-preview.2",
+    "@types/node": "^22.17.1",
+    "@types/ws": "^8.18.1",
+    "shx": "^0.4.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.4",
+    "@evolu/common": "6.0.1-preview.26",
     "@evolu/tsconfig": "0.0.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^6.0.1-preview.2"
+    "@evolu/common": "^6.0.1-preview.26"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/Crypto.ts

@@ -0,0 +1,4 @@
+import { timingSafeEqual } from "node:crypto";
+import type { TimingSafeEqual } from "@evolu/common";
+
+export const createTimingSafeEqual = (): TimingSafeEqual => timingSafeEqual;

package/src/Evolu/Relay.ts

@@ -3,114 +3,215 @@ import {
   createManyToManyMap,
   createRandom,
   createSqlite,
-  getOrThrow,
+  CreateSqliteDriverDep,
+  ok,
   OwnerId,
+  RandomDep,
+  Result,
   SimpleName,
+  SqliteError,
+  TimingSafeEqualDep,
   Uint8Array,
 } from "@evolu/common";
 import {
   applyProtocolMessageAsRelay,
   ApplyProtocolMessageAsRelayOptions,
-  createRelayStorage,
-  maxProtocolMessageSize,
-  protocolVersion,
+  createBaseSqliteStorageTables,
+  createRelayLogger,
+  createRelaySqliteStorage,
+  createRelayStorageTables,
+  defaultProtocolMessageMaxSize,
+  parseOwnerIdFromOwnerWebSocketTransportUrl,
   Relay,
   RelayConfig,
-  SqliteStorageDeps,
 } from "@evolu/common/evolu";
+import { existsSync } from "fs";
+import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
 import { createBetterSqliteDriver } from "../BetterSqliteDriver.js";
+import { createTimingSafeEqual } from "../Crypto.js";
 
 export interface NodeJsRelayConfig extends RelayConfig {
+  /** The port number for the HTTP server. */
   readonly port?: number;
 }
 
+/**
+ * Creates an Evolu relay server.
+ *
+ * This implementation uses Node.js and better-sqlite3. Additional relay
+ * implementations will be provided for other platforms (Bun, Deno, Cloudflare
+ * Workers, Vercel Edge, etc.).
+ */
 export const createNodeJsRelay =
   (deps: ConsoleDep) =>
-  async (config: NodeJsRelayConfig): Promise<Relay> => {
-    const {
-      port = 443,
-      name = getOrThrow(SimpleName.from("evolu-relay")),
-      enableLogging = false,
-    } = config;
-
-    deps.console.log(`Evolu Relay started on port ${port}`);
-
-    deps.console.enabled = enableLogging;
-
-    const versionedName = getOrThrow(
-      SimpleName.from(`${name}-${protocolVersion}`),
-    );
-
-    const sqlite = getOrThrow(
-      await createSqlite({
-        ...deps,
-        createSqliteDriver: createBetterSqliteDriver,
-      })(versionedName),
-    );
-
-    const sqliteStorageDeps: SqliteStorageDeps = {
-      sqlite,
+  (config: NodeJsRelayConfig): Promise<Result<Relay, SqliteError>> =>
+    createNodeJsRelayWithSqliteDriver({
+      ...deps,
+      createSqliteDriver: createBetterSqliteDriver,
+    })(config);
+
+/**
+ * Creates an Evolu relay server with a custom SQLite driver.
+ *
+ * Use this when you need to provide a different SQLite driver implementation
+ * (e.g., using alternative SQLite libraries).
+ */
+export const createNodeJsRelayWithSqliteDriver =
+  (deps: ConsoleDep & CreateSqliteDriverDep) =>
+  (config: NodeJsRelayConfig): Promise<Result<Relay, SqliteError>> =>
+    createNodeJsRelayWithDeps({
+      ...deps,
       random: createRandom(),
-    };
+      timingSafeEqual: createTimingSafeEqual(),
+    })(config);
 
-    const storage = getOrThrow(
-      createRelayStorage(sqliteStorageDeps)({
-        onStorageError: (error) => {
-          deps.console.error("[relay]", "[storage]", error);
-        },
-      }),
-    );
+const createNodeJsRelayWithDeps =
+  (deps: ConsoleDep & CreateSqliteDriverDep & RandomDep & TimingSafeEqualDep) =>
+  async ({
+    port = 443,
+    name = SimpleName.orThrow("evolu-relay"),
+    enableLogging = false,
+    authenticateOwner,
+  }: NodeJsRelayConfig): Promise<Result<Relay, SqliteError>> => {
+    const log = createRelayLogger(deps);
+    log.started(enableLogging, port);
+
+    const dbFileExists = existsSync(`${name}.db`);
+
+    const sqlite = await createSqlite(deps)(name);
+    if (!sqlite.ok) return sqlite;
+
+    const depsWithSqlite = { ...deps, sqlite: sqlite.value };
+
+    if (!dbFileExists) {
+      const baseTables = createBaseSqliteStorageTables(depsWithSqlite);
+      if (!baseTables.ok) return baseTables;
+
+      const relayTables = createRelayStorageTables(depsWithSqlite);
+      if (!relayTables.ok) return relayTables;
+    }
+
+    const storage = createRelaySqliteStorage(depsWithSqlite)({
+      onStorageError: log.storageError,
+    });
 
+    const server = createServer();
     const wss = new WebSocketServer({
-      maxPayload: maxProtocolMessageSize,
-      port,
+      maxPayload: defaultProtocolMessageMaxSize,
+      noServer: true,
     });
 
     const ownerSocketsMap = createManyToManyMap<OwnerId, WebSocket>();
 
+    server.on("upgrade", (request, socket, head) => {
+      socket.on("error", log.upgradeSocketError);
+
+      const completeUpgrade = () => {
+        socket.removeListener("error", log.upgradeSocketError);
+        wss.handleUpgrade(request, socket, head, (ws) => {
+          wss.emit("connection", ws, request);
+        });
+      };
+
+      if (!authenticateOwner) {
+        completeUpgrade();
+        return;
+      }
+
+      const ownerId = parseOwnerIdFromOwnerWebSocketTransportUrl(
+        request.url ?? "",
+      );
+      if (!ownerId) {
+        log.invalidOrMissingOwnerIdInUrl(request.url);
+        socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+        socket.destroy();
+        return;
+      }
+
+      authenticateOwner(ownerId)
+        .then((isAuthenticated) => {
+          if (!isAuthenticated) {
+            log.unauthorizedOwner(ownerId);
+            socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+            socket.destroy();
+            return;
+          }
+          completeUpgrade();
+        })
+        .catch((error: unknown) => {
+          log.authenticateOwnerError(error);
+          socket.write("HTTP/1.1 500 Internal Server Error\r\n\r\n");
+          socket.destroy();
+        });
+    });
+
     wss.on("connection", (ws) => {
-      ws.on("error", deps.console.error);
+      log.connectionEstablished(wss.clients.size);
+
+      ws.on("error", (error) => {
+        log.connectionWebSocketError(error);
+      });
 
       const options: ApplyProtocolMessageAsRelayOptions = {
         subscribe: (ownerId) => {
           ownerSocketsMap.add(ownerId, ws);
+          log.relayOptionSubscribe(
+            ownerId,
+            () => ownerSocketsMap.getValues(ownerId)?.size ?? 0,
+          );
+        },
+
+        unsubscribe: (ownerId) => {
+          ownerSocketsMap.remove(ownerId, ws);
+          log.relayOptionUnsubscribe(
+            ownerId,
+            () => ownerSocketsMap.getValues(ownerId)?.size ?? 0,
+          );
         },
+
         broadcast: (ownerId, message) => {
-          const sockets = ownerSocketsMap.getValues(ownerId)!;
+          const sockets = ownerSocketsMap.getValues(ownerId);
+          if (!sockets) return;
+
+          let broadcastCount = 0;
           for (const socket of sockets) {
             if (socket !== ws && socket.readyState === WebSocket.OPEN) {
               socket.send(message, { binary: true });
+              broadcastCount++;
             }
           }
+
+          log.relayOptionBroadcast(ownerId, broadcastCount, sockets.size);
         },
       };
 
       ws.on("message", (message) => {
         if (!Uint8Array.is(message)) return;
+        log.messageLength(message.length);
 
-        const response = applyProtocolMessageAsRelay({ storage })(
-          message,
-          options,
-        );
-
-        if (!response.ok) {
-          deps.console.warn(response.error.type);
-          return;
-        }
-
-        if (response.value) {
-          ws.send(response.value, { binary: true });
-        }
+        applyProtocolMessageAsRelay({ storage })(message, options)
+          .then((response) => {
+            if (!response.ok) {
+              log.applyProtocolMessageAsRelayError(response.error);
+              return;
+            }
+            ws.send(response.value.message, { binary: true });
+            log.responseLength(response.value.message.length);
+          })
+          .catch(log.applyProtocolMessageAsRelayUnknownError);
       });
 
       ws.on("close", () => {
         ownerSocketsMap.deleteValue(ws);
+        log.connectionClosed(wss.clients.size);
       });
     });
 
-    const disposeWss = () => {
-      deps.console.log("Shutting down Evolu Relay...");
+    server.listen(port);
+
+    const dispose = () => {
+      log.shuttingDown();
 
       wss.clients.forEach((client) => {
         if (client.readyState === WebSocket.OPEN) {
@@ -119,18 +220,24 @@ export const createNodeJsRelay =
       });
 
       wss.close(() => {
-        deps.console.log("Evolu Relay disposed");
+        log.webSocketServerDisposed();
+      });
+
+      server.close(() => {
+        log.httpServerDisposed();
       });
     };
 
     let isDisposed = false;
 
-    return {
+    const relay: Relay = {
       [Symbol.dispose]: () => {
         if (isDisposed) return;
         isDisposed = true;
-        sqlite[Symbol.dispose]();
-        disposeWss();
+        sqlite.value[Symbol.dispose]();
+        dispose();
       },
     };
+
+    return ok(relay);
   };