@nativedesktop/rpc 0.1.0

package/src/fake-transport.ts

@@ -0,0 +1,101 @@
+// Test double for the Transport seam (not exported from index.ts). Mimics
+// the built-in transports' contract exactly: events fire asynchronously
+// never during the factory call, and nothing is delivered after the client
+// calls close().
+
+import type { Transport, TransportFactory, TransportHandlers } from "./transport.ts";
+
+export interface FakeFrame {
+  jsonrpc: "2.0";
+  id?: number;
+  method?: string;
+  params?: unknown;
+}
+
+export class FakeConn {
+  readonly sent: string[] = [];
+  clientClosed = false;
+  #handlers: TransportHandlers;
+  #serverClosed = false;
+
+  constructor(handlers: TransportHandlers) {
+    this.#handlers = handlers;
+  }
+
+  get transport(): Transport {
+    return {
+      send: (frame) => {
+        if (!this.clientClosed && !this.#serverClosed) this.sent.push(frame);
+      },
+      close: () => {
+        this.clientClosed = true;
+      },
+    };
+  }
+
+  get closed(): boolean {
+    return this.clientClosed || this.#serverClosed;
+  }
+
+  /** Frames the client sent, parsed. */
+  calls(): FakeFrame[] {
+    return this.sent.map((s) => JSON.parse(s) as FakeFrame);
+  }
+
+  lastCall(): FakeFrame | undefined {
+    return this.calls().at(-1);
+  }
+
+  callFor(method: string): FakeFrame | undefined {
+    return this.calls().find((c) => c.method === method);
+  }
+
+  open(): void {
+    if (!this.closed) this.#handlers.onOpen();
+  }
+
+  deliver(obj: unknown): void {
+    if (!this.closed) this.#handlers.onMessage(JSON.stringify(obj));
+  }
+
+  reply(id: number, result: unknown): void {
+    this.deliver({ jsonrpc: "2.0", id, result });
+  }
+
+  replyError(id: number, code: number, message: string, data?: unknown): void {
+    this.deliver({ jsonrpc: "2.0", id, error: { code, message, data } });
+  }
+
+  notify(method: string, params: unknown): void {
+    this.deliver({ jsonrpc: "2.0", method, params });
+  }
+
+  /** Server-side drop (RST/close). Inert after the client already closed. */
+  drop(): void {
+    if (this.closed) return;
+    this.#serverClosed = true;
+    this.#handlers.onClose();
+  }
+}
+
+export interface FakeTransport {
+  factory: TransportFactory;
+  conns: FakeConn[];
+  latest(): FakeConn;
+}
+
+export function fakeTransport(): FakeTransport {
+  const conns: FakeConn[] = [];
+  return {
+    factory: (handlers) => {
+      const conn = new FakeConn(handlers);
+      conns.push(conn);
+      return conn.transport;
+    },
+    conns,
+    latest: () => {
+      if (conns.length === 0) throw new Error("no fake connection dialed yet");
+      return conns[conns.length - 1]!;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { backoffDelayMs, ConnectionLadder, RECONNECT_BASE_MS, RECONNECT_MAX_MS, STABILITY_WINDOW_MS } from "./backoff.ts";
+export type { LadderOptions } from "./backoff.ts";
+export { socketTransport, webSocketTransport } from "./transport.ts";
+export type { Transport, TransportFactory, TransportHandlers } from "./transport.ts";
+export { RpcClient, RpcError } from "./client.ts";
+export type { RpcClientOptions, RpcContract, RpcState } from "./client.ts";

package/src/react.ts

@@ -0,0 +1,17 @@
+// React binding, at its own entry point (`@nativedesktop/rpc/react`) so the
+// core client stays free of a React dependency. Hooks come from
+// @nativedesktop/react, never react directly (dev-react.ts's
+// pinned-dispatcher contract for `nd dev` hot re-eval).
+
+import { useMemo, useSyncExternalStore } from "@nativedesktop/react";
+import type { RpcClient, RpcContract } from "./client.ts";
+import { createRpcStatusStore } from "./status-store.ts";
+import type { RpcStatus } from "./status-store.ts";
+
+export type { RpcStatus } from "./status-store.ts";
+
+/** Subscribes a component to the client's connection status. */
+export function useRpcStatus<C extends RpcContract>(client: RpcClient<C>): RpcStatus {
+  const source = useMemo(() => createRpcStatusStore(client), [client]);
+  return useSyncExternalStore(source.subscribe, source.get);
+}

package/src/status-store.test.ts

@@ -0,0 +1,46 @@
+// Pins the subscribe-time resync: a transition landing between the store's
+// creation (render) and subscribe (passive effect) fires into an empty
+// handler set, and subscribe must rebuild the snapshot so the
+// useSyncExternalStore post-subscribe re-read can observe it.
+
+import { describe, expect, test } from "bun:test";
+import { RpcClient } from "./client.ts";
+import type { RpcContract } from "./client.ts";
+import { fakeTransport } from "./fake-transport.ts";
+import { createRpcStatusStore } from "./status-store.ts";
+
+describe("createRpcStatusStore", () => {
+  test("subscribe resyncs a transition that fired before any subscriber", async () => {
+    const ft = fakeTransport();
+    const client = new RpcClient<RpcContract>({
+      transport: ft.factory,
+      handshake: { method: "hello", params: {} },
+    });
+    const p = client.connect();
+    const store = createRpcStatusStore(client); // "renders" while connecting
+    expect(store.get().state).toBe("connecting");
+    const conn = ft.latest();
+    conn.open();
+    conn.reply(conn.callFor("hello")!.id!, { ok: true });
+    await p; // ready now, with nothing subscribed
+    let notified = 0;
+    const off = store.subscribe(() => (notified += 1));
+    expect(store.get().state).toBe("ready");
+    expect(notified).toBe(1);
+    off();
+    client.close();
+  });
+
+  test("subscribe with no missed transition leaves the snapshot alone", () => {
+    const ft = fakeTransport();
+    const client = new RpcClient<RpcContract>({ transport: ft.factory });
+    const store = createRpcStatusStore(client);
+    const before = store.get();
+    let notified = 0;
+    const off = store.subscribe(() => (notified += 1));
+    expect(store.get()).toBe(before);
+    expect(notified).toBe(0);
+    off();
+    client.close();
+  });
+});

package/src/status-store.ts

@@ -0,0 +1,56 @@
+// Snapshot store behind useRpcStatus, React-free so the subscribe-time
+// resync is testable without a renderer. The snapshot is rebuilt inside the
+// state-change callback, where `attempt`/`nextRetryInMs` are guaranteed to
+// already reflect the transition being notified.
+
+import type { RpcClient, RpcContract, RpcState } from "./client.ts";
+
+export interface RpcStatus {
+  state: RpcState;
+  attempt: number;
+  nextRetryInMs: number | undefined;
+  detail: string | undefined;
+}
+
+export interface RpcStatusStore {
+  subscribe(onChange: () => void): () => void;
+  get(): RpcStatus;
+}
+
+export function createRpcStatusStore<C extends RpcContract>(client: RpcClient<C>): RpcStatusStore {
+  let snapshot: RpcStatus = {
+    state: client.state,
+    attempt: client.attempt,
+    nextRetryInMs: client.nextRetryInMs,
+    detail: undefined,
+  };
+  return {
+    subscribe: (onChange) => {
+      const off = client.onStateChange((state, detail) => {
+        snapshot = { state, attempt: client.attempt, nextRetryInMs: client.nextRetryInMs, detail };
+        onChange();
+      });
+      // A transition in the render-to-subscribe gap (a local handshake can
+      // settle before passive effects flush) fired into an empty handler
+      // set. Rebuild the snapshot so useSyncExternalStore's post-subscribe
+      // getSnapshot() re-read observes it; returning the stale capture
+      // would defeat that guard and stick the UI on the old state forever.
+      // Its detail belonged to the missed transition, so it resets.
+      if (
+        client.state !== snapshot.state ||
+        client.attempt !== snapshot.attempt ||
+        client.nextRetryInMs !== snapshot.nextRetryInMs
+      ) {
+        snapshot = {
+          state: client.state,
+          attempt: client.attempt,
+          nextRetryInMs: client.nextRetryInMs,
+          detail: undefined,
+        };
+        onChange();
+      }
+      return off;
+    },
+    get: () => snapshot,
+  };
+}

package/src/transport.test.ts

@@ -0,0 +1,48 @@
+// Pins socketTransport's drain-driven outbox: Bun's socket.write accepts
+// fewer bytes than given under backpressure, and the remainder must survive
+// to the next drain with byte-exact framing (a dropped tail mis-frames the
+// NDJSON stream for the rest of the connection).
+
+import { describe, expect, test } from "bun:test";
+import { socketTransport } from "./transport.ts";
+
+describe("socketTransport", () => {
+  test("a frame larger than the send buffer arrives intact, in order", async () => {
+    const lines: string[] = [];
+    let lineBuffer = "";
+    const decoder = new TextDecoder();
+    const gotTwo = Promise.withResolvers<void>();
+    const server = Bun.listen({
+      hostname: "127.0.0.1",
+      port: 0,
+      socket: {
+        data(_s, chunk) {
+          lineBuffer += decoder.decode(chunk, { stream: true });
+          let newline: number;
+          while ((newline = lineBuffer.indexOf("\n")) >= 0) {
+            lines.push(lineBuffer.slice(0, newline));
+            lineBuffer = lineBuffer.slice(newline + 1);
+          }
+          if (lines.length >= 2) gotTwo.resolve();
+        },
+      },
+    });
+    const opened = Promise.withResolvers<void>();
+    const transport = socketTransport({ host: "127.0.0.1", port: server.port })({
+      onOpen: () => opened.resolve(),
+      onMessage: () => {},
+      onClose: () => {},
+    });
+    await opened.promise;
+    // Multi-byte characters make the frame's byte length differ from its
+    // string length, so a character-based outbox offset would corrupt it.
+    const big = JSON.stringify({ body: "π".repeat(2 * 1024 * 1024) });
+    transport.send(big);
+    transport.send("tail"); // queues behind the still-draining big frame
+    await gotTwo.promise;
+    expect(lines[0]).toBe(big);
+    expect(lines[1]).toBe("tail");
+    transport.close();
+    server.stop();
+  });
+});

package/src/transport.ts

@@ -0,0 +1,142 @@
+// Transport seam for RpcClient: one factory call per dial, WebSocket
+// semantics (constructing it starts the connect). The client never touches
+// the underlying socket; `close()` must detach every underlying handler
+// BEFORE closing, so a dying socket can't deliver late events against the
+// fresh connection the client dials next (client.ts invariant (a) lives
+// here for the built-in transports).
+
+export interface Transport {
+  send(frame: string): void;
+  close(): void;
+}
+
+export interface TransportHandlers {
+  onOpen(): void;
+  onMessage(frame: string): void;
+  onClose(): void;
+}
+
+/** Called once per dial. Constructing it starts the connect (WebSocket semantics).
+ * A synchronous throw here is caught by the client and rides the ladder. */
+export type TransportFactory = (handlers: TransportHandlers) => Transport;
+
+export function webSocketTransport(url: string, protocols?: string | string[]): TransportFactory {
+  return (handlers) => {
+    const ws = new WebSocket(url, protocols);
+    let closed = false;
+    ws.onopen = () => {
+      if (!closed) handlers.onOpen();
+    };
+    ws.onmessage = (ev) => {
+      if (!closed) handlers.onMessage(String(ev.data));
+    };
+    ws.onclose = () => {
+      if (closed) return;
+      closed = true;
+      handlers.onClose();
+    };
+    ws.onerror = () => {
+      /* the close event that follows drives all recovery/rejection logic */
+    };
+    return {
+      send: (frame) => ws.send(frame),
+      close: () => {
+        closed = true;
+        ws.onopen = null;
+        ws.onmessage = null;
+        ws.onclose = null;
+        ws.onerror = null;
+        try {
+          ws.close();
+        } catch {
+          // A dead socket may throw on close; the client doesn't care.
+        }
+      },
+    };
+  };
+}
+
+/** Raw socket transport with NDJSON framing (one JSON frame per newline).
+ * `path` dials a unix socket, `host`/`port` a TCP one. */
+export function socketTransport(target: { path: string } | { host: string; port: number }): TransportFactory {
+  return (handlers) => {
+    let closed = false;
+    let sock: import("bun").Socket | undefined;
+    let buffer = "";
+    const decoder = new TextDecoder();
+    const encoder = new TextEncoder();
+    // Outbound backpressure (the hazard runtime/ndp.ts documents): a Bun
+    // socket write can accept fewer bytes than given (or -1 while closing),
+    // and the unwritten remainder must be queued and flushed from `drain`,
+    // or it is silently lost and the NDJSON stream is mis-framed from that
+    // point on. A FIFO of whole frames — byte-encoded up front so the
+    // offset arithmetic survives multi-byte UTF-8 — keeps a second send()
+    // ordered behind a still-draining large frame.
+    const outbox: Uint8Array[] = [];
+    let outboxOffset = 0;
+    const pump = (s: import("bun").Socket): void => {
+      while (outbox.length > 0) {
+        const front = outbox[0]!;
+        const n = s.write(front.subarray(outboxOffset));
+        if (n <= 0) return; // buffer full (or closing); wait for the next drain
+        outboxOffset += n;
+        if (outboxOffset >= front.length) {
+          outbox.shift();
+          outboxOffset = 0;
+        } else {
+          return; // partial write; the rest goes out on drain
+        }
+      }
+    };
+    const emitClose = (): void => {
+      if (closed) return;
+      closed = true;
+      handlers.onClose();
+    };
+    const socketHandlers = {
+      open(s: import("bun").Socket) {
+        sock = s;
+        if (closed) s.end();
+        else handlers.onOpen();
+      },
+      data(_s: import("bun").Socket, chunk: Uint8Array) {
+        if (closed) return;
+        buffer += decoder.decode(chunk, { stream: true });
+        let newline: number;
+        while (!closed && (newline = buffer.indexOf("\n")) >= 0) {
+          const line = buffer.slice(0, newline);
+          buffer = buffer.slice(newline + 1);
+          if (line.length > 0) handlers.onMessage(line);
+        }
+      },
+      drain(s: import("bun").Socket) {
+        if (!closed) pump(s);
+      },
+      close() {
+        emitClose();
+      },
+      error() {
+        /* the close event that follows drives all recovery/rejection logic */
+      },
+      connectError() {
+        emitClose();
+      },
+    };
+    const connecting =
+      "path" in target
+        ? Bun.connect({ unix: target.path, socket: socketHandlers })
+        : Bun.connect({ hostname: target.host, port: target.port, socket: socketHandlers });
+    connecting.catch(() => emitClose());
+    return {
+      send: (frame) => {
+        if (closed || !sock) return;
+        outbox.push(encoder.encode(frame + "\n"));
+        pump(sock);
+      },
+      close: () => {
+        closed = true;
+        sock?.end();
+      },
+    };
+  };
+}