@evolu/nodejs 3.0.0-next.2 → 3.0.0

package/src/Time.ts

@@ -0,0 +1,55 @@
+/**
+ * Node.js-specific time utilities.
+ *
+ * @module
+ */
+
+import {
+  assert,
+  createTime,
+  type Brand,
+  Millis,
+  type Time,
+} from "@evolu/common";
+
+/** {@link Time} with Node.js high-resolution nanosecond readings. */
+export interface NodejsTime extends Time {
+  /** Returns a monotonic high-resolution timestamp in nanoseconds. */
+  readonly hrtime: () => HrTime;
+}
+
+/** Monotonic high-resolution timestamp in nanoseconds. */
+export type HrTime = bigint & Brand<"HrTime">;
+
+/** Elapsed nanoseconds measured using {@link HrTime}. */
+export type HrDuration = bigint & Brand<"HrDuration">;
+
+/** Creates a {@link NodejsTime} using `process.hrtime.bigint()`. */
+export const createNodejsTime = (): NodejsTime => ({
+  ...createTime(),
+  hrtime: () => process.hrtime.bigint() as HrTime,
+});
+
+/**
+ * Returns the elapsed nanoseconds between two high-resolution timestamps.
+ *
+ * Throws if `end` precedes `start`.
+ */
+export const hrDurationBetween = (start: HrTime, end: HrTime): HrDuration => {
+  assert(end >= start, "High-resolution end time must not precede start time");
+  return (end - start) as HrDuration;
+};
+
+/** Converts a high-resolution duration to the nearest millisecond. */
+export const hrDurationToMillis = (duration: HrDuration): Millis =>
+  Millis.orThrow(
+    Number(
+      (duration + nanosecondsPerMillisecond / 2n) / nanosecondsPerMillisecond,
+    ),
+  );
+
+/** Converts milliseconds to an exact high-resolution duration. */
+export const millisToHrDuration = (millis: Millis): HrDuration =>
+  (BigInt(millis) * nanosecondsPerMillisecond) as HrDuration;
+
+const nanosecondsPerMillisecond = 1_000_000n;

package/src/Worker.ts

@@ -1,3 +1,47 @@
+import type { BroadcastChannel, CreateBroadcastChannel } from "@evolu/common";
+import { disposable } from "@evolu/common";
+
+/** Creates a {@link BroadcastChannel} from a Node.js BroadcastChannel. */
+export const createBroadcastChannel: CreateBroadcastChannel = <
+  Input,
+  Output = Input,
+>(
+  name: string,
+): BroadcastChannel<Input, Output> => {
+  const nativeBroadcastChannel = new globalThis.BroadcastChannel(name);
+  using disposer = new DisposableStack();
+  let disposed = false;
+
+  disposer.defer(() => {
+    disposed = true;
+    nativeBroadcastChannel.onmessage = null;
+    nativeBroadcastChannel.close();
+  });
+
+  let onMessageHandler: ((message: Output) => void) | null = null;
+
+  return disposable<BroadcastChannel<Input, Output>>(
+    {
+      postMessage: (message) => {
+        nativeBroadcastChannel.postMessage(message);
+      },
+      get onMessage() {
+        return disposed ? null : onMessageHandler;
+      },
+      set onMessage(fn) {
+        if (disposed) return;
+        onMessageHandler = fn;
+        nativeBroadcastChannel.onmessage = fn
+          ? (event: MessageEvent<Output>) => {
+              fn(event.data);
+            }
+          : null;
+      },
+    },
+    disposer,
+  );
+};
+
 // TODO: Implement Node.js Worker API
 //
 // This module should provide Node.js implementations of the common Worker API:

package/src/index.ts

@@ -1,5 +1,14 @@
-export * from "./Sqlite.js";
-export * from "./Crypto.js";
-export * from "./local-first/Relay.js";
-export * from "./Task.js";
-export * from "./WebSocket.js";
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
+export * from "./Cli.ts";
+export * from "./Crypto.ts";
+export * from "./local-first/Relay.ts";
+export * from "./Platform.ts";
+export * from "./Sqlite.ts";
+export * from "./Task.ts";
+export * from "./Time.ts";
+export * from "./WebSocket.ts";
+export * from "./Worker.ts";

package/src/local-first/Relay.ts

@@ -1,17 +1,17 @@
 import {
-  AbortError,
   assert,
-  callback,
   createRandom,
   createRelation,
   createSqlite,
   type CreateSqliteDriverDep,
+  daemon,
   Name,
   ok,
   OwnerId,
   type RandomDep,
   type Task,
   type TimingSafeEqualDep,
+  tryAsync,
   Uint8Array,
 } from "@evolu/common";
 import {
@@ -29,8 +29,8 @@ import { once } from "events";
 import { existsSync } from "fs";
 import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
-import { createTimingSafeEqual } from "../Crypto.js";
-import { createBetterSqliteDriver } from "../Sqlite.js";
+import { createTimingSafeEqual } from "../Crypto.ts";
+import { createBetterSqliteDriver } from "../Sqlite.ts";
 
 export interface NodeJsRelayConfig extends RelayConfig {
   /** The port number for the HTTP server. */
@@ -39,7 +39,7 @@ export interface NodeJsRelayConfig extends RelayConfig {
 
 export type RelayDeps = CreateSqliteDriverDep & RandomDep & TimingSafeEqualDep;
 
-/** Dependencies for {@link startRelay} using better-sqlite3. */
+/** Dependencies for {@link createRelay} using better-sqlite3. */
 export const createRelayDeps = (): RelayDeps => ({
   createSqliteDriver: createBetterSqliteDriver,
   random: createRandom(),
@@ -47,7 +47,7 @@ export const createRelayDeps = (): RelayDeps => ({
 });
 
 /**
- * Starts an Evolu relay server using Node.js.
+ * Creates an Evolu Relay server resource using Node.js.
  *
  * Use {@link createRelayDeps} to create dependencies for better-sqlite3, or
  * provide a custom SQLite driver implementation.
@@ -68,29 +68,22 @@ export const createRelayDeps = (): RelayDeps => ({
  *
  * const deps = { ...createRelayDeps(), console };
  *
- * await using run = createRun(deps);
- * await using stack = new AsyncDisposableStack();
+ * await runMain(deps)(
+ *   createRelay({
+ *     port: 4000,
  *
- * stack.use(
- *   await run.orThrow(
- *     startRelay({
- *       port: 4000,
+ *     // Note: Relay requires URL in format ws://host:port?ownerId=<ownerId>
+ *     // isOwnerAllowed: (_ownerId, { signal: _signal }) => true,
  *
- *       // 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;
- *       },
- *     }),
- *   ),
+ *     isOwnerWithinQuota: (_ownerId, requiredBytes) => {
+ *       const maxBytes = 1024 * 1024; // 1MB
+ *       return requiredBytes <= maxBytes;
+ *     },
+ *   }),
  * );
- *
- * await run.deps.shutdown;
  * ```
  */
-export const startRelay =
+export const createRelay =
   ({
     port = 443,
     name = Name.orThrow("evolu-relay"),
@@ -98,15 +91,11 @@ export const startRelay =
     isOwnerWithinQuota,
   }: NodeJsRelayConfig): Task<Relay, never, RelayDeps> =>
   async (run) => {
-    await using stack = new AsyncDisposableStack();
+    await using disposer = new AsyncDisposableStack();
     const console = run.deps.console.child("relay");
 
-    stack.defer(() => {
-      console.info("Shutdown complete");
-    });
-
     const dbFileExists = existsSync(`${name}.db`);
-    const sqlite = stack.use(await run.orThrow(createSqlite(name)));
+    const sqlite = disposer.use(await run.ok(createSqlite(name)));
     const deps = { ...run.deps, sqlite };
 
     if (!dbFileExists) {
@@ -114,12 +103,12 @@ export const startRelay =
       createRelayStorageTables(deps);
     }
 
-    const server = stack.use(createServer());
+    const server = disposer.use(createServer());
     server.once("close", () => {
       console.info("HTTP server closed");
     });
 
-    const wss = stack.adopt(
+    const wss = disposer.adopt(
       new WebSocketServer({
         maxPayload: defaultProtocolMessageMaxSize,
         noServer: true,
@@ -135,13 +124,8 @@ export const startRelay =
 
     const ownerSocketRelation = createRelation<OwnerId, WebSocket>();
 
-    const relayRun = stack.use(
-      run.create().addDeps({
-        storage: createRelaySqliteStorage(deps)({
-          isOwnerWithinQuota,
-        }),
-      }),
-    );
+    const storage = createRelaySqliteStorage(deps)({ isOwnerWithinQuota });
+    const relayRun = disposer.use(run.create({ storage }));
 
     server.on("upgrade", (request, socket, head) => {
       socket.on("error", console.debug);
@@ -180,33 +164,43 @@ export const startRelay =
         return;
       }
 
-      const authorizationFiber = relayRun(
-        callback<boolean, unknown>(({ ok, err, signal }) => {
-          void Promise.try(() => isOwnerAllowed(ownerId, { signal })).then(
-            ok,
-            err,
-          );
-        }),
+      const authorizationFiber = relayRun.abortable(
+        // Use daemon because authorization can call an external service that
+        // ignores abort. The daemon runs in the root Run, so aborting the
+        // current Run does not make its Fiber wait for the service Promise to
+        // settle.
+        daemon(
+          async (run) =>
+            await tryAsync(
+              () => isOwnerAllowed(ownerId, { signal: run.signal }),
+              (error) => ({ type: "OwnerAuthorizationError", error }) as const,
+            ),
+        ),
       );
 
       const abortAuthorization = () => {
-        authorizationFiber.abort("WebSocket upgrade request socket closed");
+        authorizationFiber.abort({
+          type: "WebSocketUpgradeSocketClosed",
+        });
       };
 
       socket.once("close", abortAuthorization);
       socket.once("error", abortAuthorization);
 
-      void authorizationFiber.then((result) => {
+      void (async () => {
+        const result = await authorizationFiber;
+
         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);
+          if (result.error.type === "AbortError") {
+            socket.destroy();
             return;
           }
-          socket.destroy();
+
+          console.error(result.error.error);
+          respondAndDestroy(503);
           return;
         }
 
@@ -217,7 +211,7 @@ export const startRelay =
         }
 
         completeUpgrade();
-      });
+      })();
     });
 
     wss.on("connection", (ws) => {
@@ -261,13 +255,16 @@ export const startRelay =
         if (!Uint8Array.is(message)) return;
 
         void (async () => {
-          const response = await relayRun(
+          const response = await relayRun.abortable(
             applyProtocolMessageAsRelay(message, options),
           );
+
           if (!response.ok) {
+            if (response.error.type === "AbortError") return;
             console.error(response);
             return;
           }
+
           ws.send(response.value.message, { binary: true });
         })();
       });
@@ -278,8 +275,7 @@ export const startRelay =
       });
     });
 
-    stack.defer(() => {
-      console.info("Shutting down...");
+    disposer.defer(() => {
       for (const client of wss.clients) {
         if (client.readyState === WebSocket.OPEN) {
           client.close(1000, "Evolu Relay shutting down");
@@ -293,13 +289,13 @@ export const startRelay =
     const address = server.address();
     assert(address && typeof address !== "string", "Expected TCP address");
 
-    const moved = stack.move();
+    const disposables = disposer.move();
 
     console.info(`Started on port ${address.port}`);
 
     return ok({
       port: address.port,
-      [Symbol.asyncDispose]: () => moved.disposeAsync(),
+      [Symbol.asyncDispose]: () => disposables.disposeAsync(),
     });
   };