@evolu/nodejs 1.0.1-preview.8 → 1.0.1-preview.9

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,EAKL,KAAK,EACL,WAAW,EAEZ,MAAM,qBAAqB,CAAC;AAK7B,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,CA+I/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,EAOL,KAAK,EACL,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAM7B,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,54 +1,98 @@
-import { createManyToManyMap, createRandom, createSqlite, getOrThrow, SimpleName, Uint8Array, } from "@evolu/common";
-import { applyProtocolMessageAsRelay, createRelayStorage, maxProtocolMessageSize, } from "@evolu/common/evolu";
+import { createManyToManyMap, createRandom, createSqlite, ok, SimpleName, Uint8Array, } from "@evolu/common";
+import { applyProtocolMessageAsRelay, createRelayLogger, createRelaySqliteStorage, defaultProtocolMessageMaxSize, parseOwnerIdFromUrl, } from "@evolu/common/evolu";
+import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
 import { createBetterSqliteDriver } from "../BetterSqliteDriver.js";
 import { createTimingSafeEqual } from "../Crypto.js";
-export const createNodeJsRelay = (deps) => async (config) => {
-    const { port = 443, name = SimpleName.orThrow("evolu-relay"), enableLogging = false, } = config;
-    deps.console.enabled = true;
-    deps.console.log(`Evolu Relay started on port ${port}`);
-    deps.console.enabled = enableLogging;
-    const sqlite = getOrThrow(await createSqlite({
-        ...deps,
-        createSqliteDriver: createBetterSqliteDriver,
-    })(name));
-    const relaySqliteStorageDeps = {
-        sqlite,
-        random: createRandom(),
-        timingSafeEqual: createTimingSafeEqual(),
-    };
-    const storage = getOrThrow(createRelayStorage(relaySqliteStorageDeps)({
-        onStorageError: (error) => {
-            deps.console.error("[relay]", "storage", error);
-        },
-    }));
+/**
+ * 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 sqliteResult = await createSqlite(deps)(name);
+    if (!sqliteResult.ok)
+        return sqliteResult;
+    const sqlite = sqliteResult.value;
+    const storageResult = createRelaySqliteStorage({ ...deps, sqlite })({
+        onStorageError: log.storageError,
+    });
+    if (!storageResult.ok)
+        return storageResult;
+    const storage = storageResult.value;
+    const server = createServer();
     const wss = new WebSocketServer({
-        maxPayload: maxProtocolMessageSize,
-        port,
+        maxPayload: defaultProtocolMessageMaxSize,
+        noServer: true,
     });
     const ownerSocketsMap = createManyToManyMap();
-    wss.on("connection", (ws) => {
-        deps.console.log("[relay]", "connection", {
-            clientCount: wss.clients.size,
+    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 = parseOwnerIdFromUrl(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) => {
+        log.connectionEstablished(wss.clients.size);
         ws.on("error", (error) => {
-            deps.console.warn("[relay]", "error", { error });
-            deps.console.error(error);
+            log.connectionWebSocketError(error);
         });
         const options = {
             subscribe: (ownerId) => {
                 ownerSocketsMap.add(ownerId, ws);
-                deps.console.log("[relay]", "subscribe", {
-                    ownerId,
-                    subscriberCount: ownerSocketsMap.getValues(ownerId)?.size ?? 0,
-                });
+                log.relayOptionSubscribe(ownerId, () => ownerSocketsMap.getValues(ownerId)?.size ?? 0);
             },
             unsubscribe: (ownerId) => {
                 ownerSocketsMap.remove(ownerId, ws);
-                deps.console.log("[relay]", "unsubscribe", {
-                    ownerId,
-                    subscriberCount: ownerSocketsMap.getValues(ownerId)?.size ?? 0,
-                });
+                log.relayOptionUnsubscribe(ownerId, () => ownerSocketsMap.getValues(ownerId)?.size ?? 0);
             },
             broadcast: (ownerId, message) => {
                 const sockets = ownerSocketsMap.getValues(ownerId);
@@ -61,61 +105,53 @@ export const createNodeJsRelay = (deps) => async (config) => {
                         broadcastCount++;
                     }
                 }
-                deps.console.log("[relay]", "broadcast", {
-                    ownerId,
-                    broadcastCount,
-                    totalSubscribers: sockets.size,
-                });
+                log.relayOptionBroadcast(ownerId, broadcastCount, sockets.size);
             },
         };
         ws.on("message", (message) => {
             if (!Uint8Array.is(message))
                 return;
-            deps.console.log("[relay]", "on message", {
-                messageSize: message.length,
-            });
+            log.messageLength(message.length);
             applyProtocolMessageAsRelay({ storage })(message, options)
                 .then((response) => {
                 if (!response.ok) {
-                    deps.console.error("[relay]", "protocol", response.error);
-                    deps.console.error(response.error);
+                    log.applyProtocolMessageAsRelayError(response.error);
                     return;
                 }
                 ws.send(response.value.message, { binary: true });
-                deps.console.log("[relay]", "response", {
-                    responseSize: response.value.message.length,
-                });
+                log.responseLength(response.value.message.length);
             })
-                .catch((error) => {
-                deps.console.error("[relay]", "applyProtocolMessageAsRelay", error);
-            });
+                .catch(log.applyProtocolMessageAsRelayUnknownError);
         });
         ws.on("close", () => {
             ownerSocketsMap.deleteValue(ws);
-            deps.console.log("[relay]", "close", {
-                clientCount: wss.clients.size,
-            });
+            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();
+            dispose();
         },
     };
+    return ok(relay);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/nodejs",
-  "version": "1.0.1-preview.8",
+  "version": "1.0.1-preview.9",
   "description": "Evolu for Node.js",
   "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
   "license": "MIT",
@@ -30,11 +30,11 @@
     "shx": "^0.4.0",
     "typescript": "^5.9.2",
     "vitest": "^4.0.4",
-    "@evolu/common": "6.0.1-preview.20",
+    "@evolu/common": "6.0.1-preview.21",
     "@evolu/tsconfig": "0.0.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^6.0.1-preview.20"
+    "@evolu/common": "^6.0.1-preview.21"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/Evolu/Relay.ts

@@ -3,94 +3,158 @@ import {
   createManyToManyMap,
   createRandom,
   createSqlite,
-  getOrThrow,
+  CreateSqliteDriverDep,
+  ok,
   OwnerId,
+  RandomDep,
+  Result,
   SimpleName,
+  SqliteError,
+  TimingSafeEqualDep,
   Uint8Array,
 } from "@evolu/common";
 import {
   applyProtocolMessageAsRelay,
   ApplyProtocolMessageAsRelayOptions,
-  createRelayStorage,
-  maxProtocolMessageSize,
+  createRelayLogger,
+  createRelaySqliteStorage,
+  defaultProtocolMessageMaxSize,
+  parseOwnerIdFromUrl,
   Relay,
   RelayConfig,
-  RelaySqliteStorageDeps,
 } from "@evolu/common/evolu";
+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 = SimpleName.orThrow("evolu-relay"),
-      enableLogging = false,
-    } = config;
-
-    deps.console.enabled = true;
-    deps.console.log(`Evolu Relay started on port ${port}`);
-    deps.console.enabled = enableLogging;
-
-    const sqlite = getOrThrow(
-      await createSqlite({
-        ...deps,
-        createSqliteDriver: createBetterSqliteDriver,
-      })(name),
-    );
-
-    const relaySqliteStorageDeps: RelaySqliteStorageDeps = {
-      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 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 sqliteResult = await createSqlite(deps)(name);
+    if (!sqliteResult.ok) return sqliteResult;
+    const sqlite = sqliteResult.value;
+
+    const storageResult = createRelaySqliteStorage({ ...deps, sqlite })({
+      onStorageError: log.storageError,
+    });
 
-    const storage = getOrThrow(
-      createRelayStorage(relaySqliteStorageDeps)({
-        onStorageError: (error) => {
-          deps.console.error("[relay]", "storage", error);
-        },
-      }),
-    );
+    if (!storageResult.ok) return storageResult;
+    const storage = storageResult.value;
 
+    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 = parseOwnerIdFromUrl(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) => {
-      deps.console.log("[relay]", "connection", {
-        clientCount: wss.clients.size,
-      });
+      log.connectionEstablished(wss.clients.size);
 
       ws.on("error", (error) => {
-        deps.console.warn("[relay]", "error", { error });
-        deps.console.error(error);
+        log.connectionWebSocketError(error);
       });
 
       const options: ApplyProtocolMessageAsRelayOptions = {
         subscribe: (ownerId) => {
           ownerSocketsMap.add(ownerId, ws);
-          deps.console.log("[relay]", "subscribe", {
+          log.relayOptionSubscribe(
             ownerId,
-            subscriberCount: ownerSocketsMap.getValues(ownerId)?.size ?? 0,
-          });
+            () => ownerSocketsMap.getValues(ownerId)?.size ?? 0,
+          );
         },
 
         unsubscribe: (ownerId) => {
           ownerSocketsMap.remove(ownerId, ws);
-          deps.console.log("[relay]", "unsubscribe", {
+          log.relayOptionUnsubscribe(
             ownerId,
-            subscriberCount: ownerSocketsMap.getValues(ownerId)?.size ?? 0,
-          });
+            () => ownerSocketsMap.getValues(ownerId)?.size ?? 0,
+          );
         },
 
         broadcast: (ownerId, message) => {
@@ -105,49 +169,36 @@ export const createNodeJsRelay =
             }
           }
 
-          deps.console.log("[relay]", "broadcast", {
-            ownerId,
-            broadcastCount,
-            totalSubscribers: sockets.size,
-          });
+          log.relayOptionBroadcast(ownerId, broadcastCount, sockets.size);
         },
       };
 
       ws.on("message", (message) => {
         if (!Uint8Array.is(message)) return;
-
-        deps.console.log("[relay]", "on message", {
-          messageSize: message.length,
-        });
+        log.messageLength(message.length);
 
         applyProtocolMessageAsRelay({ storage })(message, options)
           .then((response) => {
             if (!response.ok) {
-              deps.console.error("[relay]", "protocol", response.error);
-              deps.console.error(response.error);
+              log.applyProtocolMessageAsRelayError(response.error);
               return;
             }
-
             ws.send(response.value.message, { binary: true });
-            deps.console.log("[relay]", "response", {
-              responseSize: response.value.message.length,
-            });
+            log.responseLength(response.value.message.length);
           })
-          .catch((error: unknown) => {
-            deps.console.error("[relay]", "applyProtocolMessageAsRelay", error);
-          });
+          .catch(log.applyProtocolMessageAsRelayUnknownError);
       });
 
       ws.on("close", () => {
         ownerSocketsMap.deleteValue(ws);
-        deps.console.log("[relay]", "close", {
-          clientCount: wss.clients.size,
-        });
+        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) {
@@ -156,18 +207,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();
+        dispose();
       },
     };
+
+    return ok(relay);
   };