@evolu/nodejs 2.4.0 → 3.0.0-next.1

package/src/local-first/Relay.ts

@@ -1,120 +1,154 @@
 import {
-  ConsoleDep,
-  createRelation,
+  AbortError,
+  assert,
+  callback,
   createRandom,
+  createRelation,
   createSqlite,
-  CreateSqliteDriverDep,
-  isAsync,
+  type CreateSqliteDriverDep,
+  Name,
   ok,
   OwnerId,
-  RandomDep,
-  Result,
-  SimpleName,
-  SqliteError,
-  TimingSafeEqualDep,
+  type RandomDep,
+  type Task,
+  type TimingSafeEqualDep,
   Uint8Array,
 } from "@evolu/common";
 import {
   applyProtocolMessageAsRelay,
-  ApplyProtocolMessageAsRelayOptions,
+  type ApplyProtocolMessageAsRelayOptions,
   createBaseSqliteStorageTables,
-  createRelayLogger,
   createRelaySqliteStorage,
   createRelayStorageTables,
   defaultProtocolMessageMaxSize,
   parseOwnerIdFromOwnerWebSocketTransportUrl,
-  Relay,
-  RelayConfig,
+  type Relay,
+  type RelayConfig,
 } from "@evolu/common/local-first";
+import { once } from "events";
 import { existsSync } from "fs";
 import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
-import { createBetterSqliteDriver } from "../BetterSqliteDriver.js";
 import { createTimingSafeEqual } from "../Crypto.js";
+import { createBetterSqliteDriver } from "../Sqlite.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) =>
-  (config: NodeJsRelayConfig): Promise<Result<Relay, SqliteError>> =>
-    createNodeJsRelayWithSqliteDriver({
-      ...deps,
-      createSqliteDriver: createBetterSqliteDriver,
-    })(config);
+export type RelayDeps = CreateSqliteDriverDep & RandomDep & TimingSafeEqualDep;
+
+/** Dependencies for {@link startRelay} using better-sqlite3. */
+export const createRelayDeps = (): RelayDeps => ({
+  createSqliteDriver: createBetterSqliteDriver,
+  random: createRandom(),
+  timingSafeEqual: createTimingSafeEqual(),
+});
 
 /**
- * Creates an Evolu relay server with a custom SQLite driver.
+ * Starts an Evolu relay server using Node.js.
+ *
+ * Use {@link createRelayDeps} to create dependencies for better-sqlite3, or
+ * provide a custom SQLite driver implementation.
+ *
+ * ### Example
  *
- * Use this when you need to provide a different SQLite driver implementation
- * (e.g., using alternative SQLite libraries).
+ * ```ts
+ * // Ensure the database is created in a predictable location for Docker.
+ * mkdirSync("data", { recursive: true });
+ * process.chdir("data");
+ *
+ * const console = createConsole({
+ *   // level: "debug",
+ *   formatter: createConsoleFormatter()({
+ *     timestampFormat: "relative",
+ *   }),
+ * });
+ *
+ * const deps = { ...createRelayDeps(), console };
+ *
+ * await using run = createRun(deps);
+ * await using stack = new AsyncDisposableStack();
+ *
+ * stack.use(
+ *   await run.orThrow(
+ *     startRelay({
+ *       port: 4000,
+ *
+ *       // Note: Relay requires URL in format ws://host:port?ownerId=<ownerId>
+ *       // isOwnerAllowed: (_ownerId, { signal: _signal }) => true,
+ *
+ *       isOwnerWithinQuota: (_ownerId, requiredBytes) => {
+ *         const maxBytes = 1024 * 1024; // 1MB
+ *         return requiredBytes <= maxBytes;
+ *       },
+ *     }),
+ *   ),
+ * );
+ *
+ * await run.deps.shutdown;
+ * ```
  */
-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 ({
+export const startRelay =
+  ({
     port = 443,
-    name = SimpleName.orThrow("evolu-relay"),
-    enableLogging = false,
+    name = Name.orThrow("evolu-relay"),
     isOwnerAllowed,
     isOwnerWithinQuota,
-  }: NodeJsRelayConfig): Promise<Result<Relay, SqliteError>> => {
-    const log = createRelayLogger(deps);
-    log.started(enableLogging, port);
+  }: NodeJsRelayConfig): Task<Relay, never, RelayDeps> =>
+  async (run) => {
+    await using stack = new AsyncDisposableStack();
+    const console = run.deps.console.child("relay");
 
-    const dbFileExists = existsSync(`${name}.db`);
-
-    const sqlite = await createSqlite(deps)(name);
-    if (!sqlite.ok) return sqlite;
+    stack.defer(() => {
+      console.info("Shutdown complete");
+    });
 
-    const depsWithSqlite = { ...deps, sqlite: sqlite.value };
+    const dbFileExists = existsSync(`${name}.db`);
+    const sqlite = stack.use(await run.orThrow(createSqlite(name)));
+    const deps = { ...run.deps, sqlite };
 
     if (!dbFileExists) {
-      {
-        const result = createBaseSqliteStorageTables(depsWithSqlite);
-        if (!result.ok) return result;
-      }
-      {
-        const result = createRelayStorageTables(depsWithSqlite);
-        if (!result.ok) return result;
-      }
+      createBaseSqliteStorageTables(deps);
+      createRelayStorageTables(deps);
     }
 
-    const storage = createRelaySqliteStorage(depsWithSqlite)({
-      onStorageError: log.storageError,
-      isOwnerWithinQuota,
+    const server = stack.use(createServer());
+    server.once("close", () => {
+      console.info("HTTP server closed");
     });
 
-    const server = createServer();
-    const wss = new WebSocketServer({
-      maxPayload: defaultProtocolMessageMaxSize,
-      noServer: true,
-    });
+    const wss = stack.adopt(
+      new WebSocketServer({
+        maxPayload: defaultProtocolMessageMaxSize,
+        noServer: true,
+      }),
+      (wss) =>
+        new Promise<void>((resolve) => {
+          wss.close(() => {
+            console.info("WebSocketServer closed");
+            resolve();
+          });
+        }),
+    );
 
     const ownerSocketRelation = createRelation<OwnerId, WebSocket>();
 
+    const relayRun = stack.use(
+      run.create().addDeps({
+        storage: createRelaySqliteStorage(deps)({
+          isOwnerWithinQuota,
+        }),
+      }),
+    );
+
     server.on("upgrade", (request, socket, head) => {
-      socket.on("error", log.upgradeSocketError);
+      socket.on("error", console.debug);
 
       const completeUpgrade = () => {
-        socket.removeListener("error", log.upgradeSocketError);
+        socket.removeListener("error", console.debug);
+
         wss.handleUpgrade(request, socket, head, (ws) => {
           wss.emit("connection", ws, request);
         });
@@ -125,122 +159,152 @@ const createNodeJsRelayWithDeps =
         return;
       }
 
-      const ownerId = parseOwnerIdFromOwnerWebSocketTransportUrl(
-        request.url ?? "",
-      );
+      const respondAndDestroy = (
+        statusCode: keyof typeof HttpStatusTextByCode,
+      ) => {
+        if (socket.destroyed) return;
+        socket.write(
+          `HTTP/1.1 ${statusCode} ${HttpStatusTextByCode[statusCode]}\r\n\r\n`,
+        );
+        socket.destroy();
+      };
+
+      const requestUrl = request.url;
+      const ownerId = requestUrl
+        ? parseOwnerIdFromOwnerWebSocketTransportUrl(requestUrl)
+        : undefined;
 
       if (!ownerId) {
-        log.invalidOrMissingOwnerIdInUrl(request.url);
-        socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
-        socket.destroy();
+        console.debug("invalid or missing ownerId in URL", requestUrl);
+        respondAndDestroy(400);
         return;
       }
 
-      void (async () => {
-        const result = isOwnerAllowed(ownerId);
-        const isAllowed = isAsync(result) ? await result : result;
-        if (!isAllowed) {
-          log.unauthorizedOwner(ownerId);
-          socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+      const authorizationFiber = relayRun(
+        callback<boolean, unknown>(({ ok, err, signal }) => {
+          void Promise.try(() => isOwnerAllowed(ownerId, { signal })).then(
+            ok,
+            err,
+          );
+        }),
+      );
+
+      const abortAuthorization = () => {
+        authorizationFiber.abort("WebSocket upgrade request socket closed");
+      };
+
+      socket.once("close", abortAuthorization);
+      socket.once("error", abortAuthorization);
+
+      void authorizationFiber.then((result) => {
+        socket.removeListener("close", abortAuthorization);
+        socket.removeListener("error", abortAuthorization);
+
+        if (!result.ok) {
+          if (!AbortError.is(result.error)) {
+            console.error("isOwnerAllowed failed", ownerId, result.error);
+            respondAndDestroy(503);
+            return;
+          }
           socket.destroy();
           return;
         }
+
+        if (!result.value) {
+          console.debug("unauthorized owner", ownerId);
+          respondAndDestroy(401);
+          return;
+        }
+
         completeUpgrade();
-      })();
+      });
     });
 
     wss.on("connection", (ws) => {
-      log.connectionEstablished(wss.clients.size);
-
-      ws.on("error", (error) => {
-        log.connectionWebSocketError(error);
-      });
+      console.debug("on connection", wss.clients.size);
 
       const options: ApplyProtocolMessageAsRelayOptions = {
         subscribe: (ownerId) => {
           ownerSocketRelation.add(ownerId, ws);
-          log.relayOptionSubscribe(
+          console.debug(
+            "subscribe",
             ownerId,
-            () => ownerSocketRelation.getB(ownerId)?.size ?? 0,
+            ownerSocketRelation.bCountForA(ownerId),
           );
         },
 
         unsubscribe: (ownerId) => {
           ownerSocketRelation.remove(ownerId, ws);
-          log.relayOptionUnsubscribe(
+          console.debug(
+            "unsubscribe",
             ownerId,
-            () => ownerSocketRelation.getB(ownerId)?.size ?? 0,
+            ownerSocketRelation.bCountForA(ownerId),
           );
         },
 
         broadcast: (ownerId, message) => {
-          const sockets = ownerSocketRelation.getB(ownerId);
-          if (!sockets) return;
-
-          let broadcastCount = 0;
-          for (const socket of sockets) {
+          for (const socket of ownerSocketRelation.iterateB(ownerId)) {
             if (socket !== ws && socket.readyState === WebSocket.OPEN) {
               socket.send(message, { binary: true });
-              broadcastCount++;
             }
           }
 
-          log.relayOptionBroadcast(ownerId, broadcastCount, sockets.size);
+          console.debug(
+            "broadcast",
+            ownerId,
+            ownerSocketRelation.bCountForA(ownerId),
+          );
         },
       };
 
       ws.on("message", (message) => {
         if (!Uint8Array.is(message)) return;
-        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);
+        void (async () => {
+          const response = await relayRun(
+            applyProtocolMessageAsRelay(message, options),
+          );
+          if (!response.ok) {
+            console.error(response);
+            return;
+          }
+          ws.send(response.value.message, { binary: true });
+        })();
       });
 
       ws.on("close", () => {
-        ownerSocketRelation.deleteB(ws);
-        log.connectionClosed(wss.clients.size);
+        ownerSocketRelation.removeByB(ws);
+        console.debug("ws close", wss.clients.size);
       });
     });
 
-    server.listen(port);
-
-    const dispose = () => {
-      log.shuttingDown();
-
-      wss.clients.forEach((client) => {
+    stack.defer(() => {
+      console.info("Shutting down...");
+      for (const client of wss.clients) {
         if (client.readyState === WebSocket.OPEN) {
           client.close(1000, "Evolu Relay shutting down");
         }
-      });
+      }
+    });
 
-      wss.close(() => {
-        log.webSocketServerDisposed();
-      });
+    server.listen(port);
+    await once(server, "listening");
 
-      server.close(() => {
-        log.httpServerDisposed();
-      });
-    };
+    const address = server.address();
+    assert(address && typeof address !== "string", "Expected TCP address");
 
-    let isDisposed = false;
+    const moved = stack.move();
 
-    const relay: Relay = {
-      [Symbol.dispose]: () => {
-        if (isDisposed) return;
-        isDisposed = true;
-        sqlite.value[Symbol.dispose]();
-        dispose();
-      },
-    };
+    console.info(`Started on port ${address.port}`);
 
-    return ok(relay);
+    return ok({
+      port: address.port,
+      [Symbol.asyncDispose]: () => moved.disposeAsync(),
+    });
   };
+
+const HttpStatusTextByCode = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  503: "Service Unavailable",
+} as const;

package/dist/BetterSqliteDriver.d.ts

@@ -1,3 +0,0 @@
-import { CreateSqliteDriver } from "@evolu/common";
-export declare const createBetterSqliteDriver: CreateSqliteDriver;
-//# sourceMappingURL=BetterSqliteDriver.d.ts.map

package/dist/BetterSqliteDriver.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"BetterSqliteDriver.d.ts","sourceRoot":"","sources":["../src/BetterSqliteDriver.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,kBAAkB,EAGnB,MAAM,eAAe,CAAC;AAGvB,eAAO,MAAM,wBAAwB,EAAE,kBAqCtC,CAAC"}

package/dist/BetterSqliteDriver.js

@@ -1,31 +0,0 @@
-import { constVoid, createPreparedStatementsCache, } from "@evolu/common";
-import BetterSQLite from "better-sqlite3";
-export const createBetterSqliteDriver = (name, options) => {
-    const filename = options?.memory ? ":memory:" : `${name}.db`;
-    const db = new BetterSQLite(filename);
-    let isDisposed = false;
-    const cache = createPreparedStatementsCache((sql) => db.prepare(sql), 
-    // Not needed.
-    // https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#class-statement
-    constVoid);
-    const driver = {
-        exec: (query, isMutation) => {
-            // Always prepare is recommended for better-sqlite3
-            const prepared = cache.get(query, true);
-            const rows = isMutation
-                ? []
-                : prepared.all(query.parameters);
-            const changes = isMutation ? prepared.run(query.parameters).changes : 0;
-            return { rows, changes };
-        },
-        export: () => db.serialize(),
-        [Symbol.dispose]: () => {
-            if (isDisposed)
-                return;
-            isDisposed = true;
-            cache[Symbol.dispose]();
-            db.close();
-        },
-    };
-    return Promise.resolve(driver);
-};

package/dist/Crypto.d.ts.map

@@ -1 +0,0 @@
-{"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/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./BetterSqliteDriver.js";
-export * from "./local-first/Relay.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -1,2 +0,0 @@
-export * from "./BetterSqliteDriver.js";
-export * from "./local-first/Relay.js";

package/dist/local-first/Relay.d.ts

@@ -1,22 +0,0 @@
-import { ConsoleDep, CreateSqliteDriverDep, Result, SqliteError } from "@evolu/common";
-import { Relay, RelayConfig } from "@evolu/common/local-first";
-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 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/local-first/Relay.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../src/local-first/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAIV,qBAAqB,EAKrB,MAAM,EAEN,WAAW,EAGZ,MAAM,eAAe,CAAC;AACvB,OAAO,EASL,KAAK,EACL,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAOnC,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"}