@rindle/remote 0.1.0-rc.5

package/src/remote-source.ts

@@ -0,0 +1,171 @@
+// RemoteNormalizedSource: a `NormalizedSource` over a network transport — the ws sibling of
+// the in-process native source (NORMALIZED-CHANGES-DESIGN.md §7). It subscribes in normalized
+// mode, owns the epoch/seq/gap protocol (via {@link NormalizedSubscriber}), and emits clean
+// `NormalizedEvent`s upward — so `@rindle/normalized`'s `NormalizedBackend` drives the local
+// engine identically whether the footprint stream comes from in-process or over the wire.
+//
+// On a gap (or epoch/fp drift) it re-subscribes; the server re-registers the query under a NEW
+// epoch and replies with a fresh hello + snapshot, and `NormalizedSync` diffs the new footprint
+// against the old (the set-analogue re-hydrate, §5.3).
+
+import type {
+  Mutation,
+  NormalizedEvent,
+  NormalizedSource,
+  NormalizedTableSchema,
+  QueryId,
+  RemoteQuery,
+} from "@rindle/client";
+
+import { NormalizedSubscriber } from "./normalized.ts";
+import type { NormalizedBatch, NormalizedHello } from "./normalized.ts";
+import { ProtocolError } from "./protocol.ts";
+import type { ServerMsg } from "./protocol.ts";
+import {
+  defaultSubscribeTarget,
+  isThenable,
+  subscribeMessage,
+  type RawMutationSender,
+  type SubscribeResolver,
+  type SubscribeTarget,
+} from "./subscribe.ts";
+import { WsTransport } from "./transport.ts";
+import type { Transport } from "./transport.ts";
+
+interface QState {
+  remote: RemoteQuery;
+  subscriber: NormalizedSubscriber | null;
+  /** The epoch of the current subscription (0 before the first hello). */
+  epoch: number;
+  /** True between sending a re-subscribe and receiving its hello (so a second gap is ignored). */
+  resubscribing: boolean;
+  /** Monotonic token that cancels stale async lease resolutions. */
+  subscribeTicket: number;
+}
+
+export interface RemoteNormalizedSourceOptions {
+  /** Resolve the upstream subscribe target. Defaults to embedded-server `{name,args}`. */
+  resolveSubscribe?: SubscribeResolver;
+  /** Override raw authoritative writes, e.g. POST them to an app API server. */
+  sendMutation?: RawMutationSender;
+}
+
+export class RemoteNormalizedSource implements NormalizedSource {
+  private readonly transport: Transport;
+  private readonly resolveSubscribe: SubscribeResolver;
+  private readonly sendMutation?: RawMutationSender;
+  private handler: (qid: QueryId, ev: NormalizedEvent) => void = () => {};
+  private readonly subs = new Map<QueryId, QState>();
+  /** The client's own typed per-table schemas, for hello validation (CRIT#4); set by the backend. */
+  private clientTables: NormalizedTableSchema[] | undefined;
+
+  constructor(transport: Transport, opts: RemoteNormalizedSourceOptions = {}) {
+    this.transport = transport;
+    this.resolveSubscribe = opts.resolveSubscribe ?? defaultSubscribeTarget;
+    this.sendMutation = opts.sendMutation;
+    this.transport.onMessage((msg) => this.onServerMsg(msg));
+  }
+
+  expectClientSchema(tables: NormalizedTableSchema[]): void {
+    this.clientTables = tables;
+  }
+
+  registerQuery(qid: QueryId, remote: RemoteQuery): void {
+    this.subs.set(qid, { remote, subscriber: null, epoch: 0, resubscribing: false, subscribeTicket: 0 });
+    this.subscribe(qid, remote);
+  }
+
+  unregisterQuery(qid: QueryId): void {
+    this.subs.delete(qid);
+    this.transport.send({ t: "unsubscribe", queryId: qid });
+  }
+
+  mutate(mutations: Mutation[]): Promise<void> {
+    if (this.sendMutation) return Promise.resolve(this.sendMutation(mutations));
+    this.transport.send({ t: "mutate", mutations });
+    return Promise.resolve();
+  }
+
+  onNormalized(handler: (qid: QueryId, ev: NormalizedEvent) => void): void {
+    this.handler = handler;
+  }
+
+  // --- internals ---------------------------------------------------------------
+
+  private subscribe(qid: QueryId, remote: RemoteQuery): void {
+    const s = this.subs.get(qid);
+    if (!s) return;
+    const request = { queryId: qid, remote, mode: "normalized" as const };
+    const ticket = ++s.subscribeTicket;
+    const send = (target: SubscribeTarget) => {
+      const cur = this.subs.get(qid);
+      if (cur !== s || cur.subscribeTicket !== ticket) return;
+      this.transport.send(subscribeMessage(request, target));
+    };
+    const fail = (err: unknown) => {
+      const cur = this.subs.get(qid);
+      if (cur !== s || cur.subscribeTicket !== ticket) return;
+      s.resubscribing = false;
+      console.error(
+        `[rindle-remote] normalized query ${qid} subscribe resolution failed: ${String((err as Error)?.message ?? err)}`,
+      );
+    };
+    try {
+      const target = this.resolveSubscribe(request);
+      if (isThenable(target)) void target.then(send, fail);
+      else send(target);
+    } catch (err) {
+      fail(err);
+    }
+  }
+
+  private onServerMsg(msg: ServerMsg): void {
+    if (msg.t === "queryError") {
+      this.subs.delete(msg.queryId);
+      console.error(`[rindle-remote] normalized query ${msg.queryId} subscription rejected: ${msg.message}`);
+      return;
+    }
+    // This source is normalized-only; it sees `nhello`/`nbatch` (flat frames are ignored).
+    if (msg.t !== "nhello" && msg.t !== "nbatch") return;
+    const s = this.subs.get(msg.queryId);
+    if (!s) return; // unsubscribed / unknown query
+    if (msg.t === "nhello") this.openSubscriber(msg.queryId, s, msg.hello);
+    else this.applyBatch(msg.queryId, s, msg.batch);
+  }
+
+  private openSubscriber(qid: QueryId, s: QState, hello: NormalizedHello): void {
+    try {
+      s.subscriber = new NormalizedSubscriber(hello, (ev) => this.handler(qid, ev), this.clientTables);
+      s.epoch = hello.epoch;
+      s.resubscribing = false;
+    } catch (e) {
+      // A comparator/fp mismatch at hello is unrecoverable (a code-contract divergence).
+      s.subscriber = null;
+      console.error(`[rindle-remote] normalized query ${qid} subscription rejected: ${(e as Error).message}`);
+    }
+  }
+
+  private applyBatch(qid: QueryId, s: QState, batch: NormalizedBatch): void {
+    if (!s.subscriber) return; // no hello yet (or mid re-hydrate)
+    if (batch.epoch < s.epoch) return; // a stale batch from a superseded epoch — drop
+    try {
+      s.subscriber.apply(batch);
+    } catch (e) {
+      if (!(e instanceof ProtocolError)) throw e;
+      if (s.resubscribing) return; // already recovering
+      // Gap / drift → re-hydrate under a new epoch (the server bumps it on re-subscribe).
+      s.resubscribing = true;
+      s.subscriber = null;
+      this.subscribe(qid, s.remote);
+    }
+  }
+}
+
+/** Convenience: a `RemoteNormalizedSource` over a ws URL or a custom transport. */
+export function createRemoteNormalizedSource(
+  urlOrTransport: string | Transport,
+  opts: RemoteNormalizedSourceOptions = {},
+): RemoteNormalizedSource {
+  const transport = typeof urlOrTransport === "string" ? new WsTransport(urlOrTransport) : urlOrTransport;
+  return new RemoteNormalizedSource(transport, opts);
+}

package/src/subscribe.ts

@@ -0,0 +1,40 @@
+import type { Mutation, MutationEnvelope, QueryId, RemoteQuery } from "@rindle/client";
+
+import type { SubscribeClientMsg } from "./protocol.ts";
+
+export type SubscribeMode = "flat" | "normalized";
+
+export interface SubscribeRequest {
+  queryId: QueryId;
+  remote: RemoteQuery;
+  mode: SubscribeMode;
+}
+
+export type SubscribeTarget =
+  | { name: string; args: unknown; leaseToken?: never; wsEndpoint?: never }
+  // A lease may carry the follower's public ws endpoint (READ-ROUTER-DESIGN.md §2.3): the source
+  // connects (or migrates) its transport there before subscribing. Client-side routing only — it is
+  // NOT put on the wire `subscribe` frame.
+  | { leaseToken: string; wsEndpoint?: string; name?: never; args?: never };
+
+export type SubscribeResolver = (request: SubscribeRequest) => SubscribeTarget | PromiseLike<SubscribeTarget>;
+
+export type RawMutationSender = (mutations: Mutation[]) => void | PromiseLike<void>;
+
+export type MutationEnvelopeSender = (envelope: MutationEnvelope) => void | PromiseLike<void>;
+
+export function defaultSubscribeTarget(request: SubscribeRequest): SubscribeTarget {
+  return { name: request.remote.name, args: request.remote.args };
+}
+
+export function subscribeMessage(request: SubscribeRequest, target: SubscribeTarget): SubscribeClientMsg {
+  const mode = request.mode === "normalized" ? { mode: request.mode } : {};
+  if (target.leaseToken !== undefined) {
+    return { t: "subscribe", queryId: request.queryId, leaseToken: target.leaseToken, ...mode };
+  }
+  return { t: "subscribe", queryId: request.queryId, name: target.name, args: target.args, ...mode };
+}
+
+export function isThenable<T>(value: T | PromiseLike<T>): value is PromiseLike<T> {
+  return value != null && typeof (value as { then?: unknown }).then === "function";
+}

package/src/transport.ts

@@ -0,0 +1,127 @@
+// The transport seam: the RemoteBackend talks JSON messages through a `Transport`, so the
+// wire (ws / sse / http) is swappable + mockable. The default {@link WsTransport} uses the
+// global `WebSocket` (Node 22+ and browsers both provide it — zero dependency).
+
+import type { ClientMsg, ServerMsg } from "./protocol.ts";
+
+export interface Transport {
+  /** Send a message up to the server. */
+  send(msg: ClientMsg): void;
+  /** Register the single handler for incoming server messages. */
+  onMessage(handler: (msg: ServerMsg) => void): void;
+  /** Register a handler fired after the connection is RE-established (not the first open) — the
+   *  source uses it to re-`init` + re-subscribe so a dropped/restarted daemon heals. Optional:
+   *  transports without reconnect (mocks, in-process) may omit it. */
+  onReconnect?(handler: () => void): void;
+  /** Register a handler fired when the connection is SUSTAINEDLY down — repeated reconnects to the
+   *  same endpoint have failed (a dead/removed follower, READ-ROUTER-DESIGN.md §3). The source uses
+   *  it to re-lease: the router returns a (possibly new) `wsEndpoint`, and a changed one migrates the
+   *  whole session off the dead node. Optional: transports without failover (mocks, in-process,
+   *  fixed endpoints) may omit it. */
+  onDown?(handler: () => void): void;
+  /** Tear down the connection. */
+  close(): void;
+}
+
+/** A `Transport` over a `WebSocket` (text JSON frames). Messages sent before the socket
+ *  opens are buffered and flushed on open (so `registerQuery`/`mutate` can be called eagerly).
+ *  Reconnects with capped exponential backoff: if the socket drops (e.g. the daemon restarted)
+ *  it reopens and fires `onReconnect` so the source rebuilds its subscriptions. */
+export class WsTransport implements Transport {
+  private readonly url: string;
+  private ws: WebSocket;
+  private handler: (msg: ServerMsg) => void = () => {};
+  private reconnectHandler: () => void = () => {};
+  private downHandler: () => void = () => {};
+  private readonly pending: ClientMsg[] = [];
+  private open = false;
+  private everOpened = false;
+  private closedByUser = false;
+  private attempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  /** Failed reconnect attempts after which the connection is declared "down" (fires `onDown`). */
+  private readonly downThreshold: number;
+  /** True once `onDown` has fired for the CURRENT down episode; reset on the next successful open
+   *  so a later outage fires again (but a single episode fires `onDown` exactly once — no re-lease
+   *  storm while a follower is gone). */
+  private downFired = false;
+
+  constructor(url: string, opts: { downThreshold?: number } = {}) {
+    this.url = url;
+    this.downThreshold = opts.downThreshold ?? 4;
+    this.ws = this.connect();
+  }
+
+  private connect(): WebSocket {
+    const ws = new WebSocket(this.url);
+    ws.addEventListener("open", () => {
+      this.open = true;
+      this.attempt = 0;
+      this.downFired = false; // a fresh connection clears the down episode
+      if (!this.everOpened) {
+        // First connection: flush whatever was buffered eagerly (init + subscribes).
+        this.everOpened = true;
+        for (const m of this.pending) ws.send(JSON.stringify(m));
+        this.pending.length = 0;
+      } else {
+        // A reconnect: drop any stale buffered frames — the source rebuilds the full desired
+        // state (re-init + re-subscribe, re-leasing as it goes) in onReconnect.
+        this.pending.length = 0;
+        this.reconnectHandler();
+      }
+    });
+    ws.addEventListener("message", (ev: MessageEvent) => {
+      this.handler(JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data)) as ServerMsg);
+    });
+    ws.addEventListener("close", () => {
+      this.open = false;
+      if (!this.closedByUser) this.scheduleReconnect();
+    });
+    // `error` is followed by `close`; let the close handler own reconnection.
+    ws.addEventListener("error", () => {});
+    return ws;
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer !== undefined) return;
+    const delay = Math.min(250 * 2 ** this.attempt, 5000);
+    this.attempt++;
+    // Sustained failure (we had a connection, and several reconnects to this endpoint have failed):
+    // declare the connection down ONCE so the source can re-lease and migrate (§3). We keep
+    // reconnecting underneath in case the same follower returns (a reboot, same endpoint).
+    if (this.everOpened && !this.downFired && this.attempt >= this.downThreshold) {
+      this.downFired = true;
+      this.downHandler();
+    }
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      if (!this.closedByUser) this.ws = this.connect();
+    }, delay);
+  }
+
+  send(msg: ClientMsg): void {
+    if (this.open) this.ws.send(JSON.stringify(msg));
+    else this.pending.push(msg);
+  }
+
+  onMessage(handler: (msg: ServerMsg) => void): void {
+    this.handler = handler;
+  }
+
+  onReconnect(handler: () => void): void {
+    this.reconnectHandler = handler;
+  }
+
+  onDown(handler: () => void): void {
+    this.downHandler = handler;
+  }
+
+  close(): void {
+    this.closedByUser = true;
+    if (this.reconnectTimer !== undefined) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+    this.ws.close();
+  }
+}