replica-bridge 0.3.13 → 0.3.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replica-bridge",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
   "type": "module",
   "bin": {

package/src/bridge/board.js

@@ -1,15 +1,18 @@
 // The optional 任务 board (PROTOCOL.md "看板"): reads AgensWork's agens-backend, which only listens on this computer, for
 // a phone that asked. The bridge does not start the backend or care how it started: it knows a port, and a computer
 // where nothing answers there simply has no board. Reads and writes are short allowlists, and the only background traffic
-// is one poll of /v1/changes while a phone is subscribed, because reading the lists counts as the user having seen them.
+// is the change log (/v1/changes, or its push stream /v1/changes/stream where the backend has one) while a phone is
+// subscribed, because reading the lists counts as the user having seen them. Each subscriber has its own place in the
+// log, so a phone that comes back says where it was and gets only what changed since (0.3.14).
 // The bridge stays thin: it checks the shape of a write and leaves what it means to the backend, whose status and body
 // (REC_NOT_FOUND, REC_STATE_CONFLICT, …) go back to the phone unchanged.
-                                                              
+                                                                           
+import { PACKAGE_VERSION } from "./install.js";
 
 /** agens-backend's default port, which its own AGENS_BACKEND_PORT changes. */
 export const DEFAULT_BOARD_PORT = 4753;
-/** agens-backend's own page polls every 10 s. */
-const DEFAULT_POLL_SECONDS = 10;
+/** How often the log is read when the backend cannot push it; one indexed query on this computer. */
+const DEFAULT_POLL_SECONDS = 1;
 /** Past this the backend is treated as gone, so a hung one cannot hold a phone waiting. */
 const READ_TIMEOUT_MS = 5000;
 /** Well under RELAY_REPLY_LIMIT, since the bridge sends board answers in one frame. */
@@ -17,6 +20,10 @@ const BODY_MAX_BYTES = 8 * 1024 * 1024;
 const CHANGES_PAGE = 100;
 /** Stops a catch-up on a change log that never ends; the backend keeps 30 days of it. */
 const CATCH_UP_PAGES = 1000;
+/** More changed tasks than this in one event, and the phone reads the whole board instead. */
+export const CHANGED_ITEMS_MAX = 200;
+/** What this bridge can do beyond reading, for board/state (PROTOCOL.md "看板"). */
+export const BOARD_CAPS = ["post", "delta"]         ;
 
 /** The backend's own cap on a request body (agens-backend src/http.mjs BODY_MAX). */
 export const POST_BODY_MAX_BYTES = 16 * 1024;
@@ -80,29 +87,76 @@ export function boardPortFrom(env                    = process.env)         {
                                
                 
                        
+                                                                                                                
+                             
+                                                                                                                         
+                              
  
 
+/** Three missed heartbeats. */
+const DEFAULT_STREAM_IDLE_SECONDS = 45;
+const DEFAULT_STREAM_RETRY_SECONDS = 30;
+
+                                            
+
+/** One subscriber and how far through the change log it has been told. */
+               
+                     
+                                                                                                           
+                        
+                                                                         
+                        
+                     
+ 
+
+/** Changes as a phone gets them: one per task, the latest, or a reset when there are too many. */
+function changedEvent(items               )             {
+  const latest = new Map                     ();
+  for (const item of items) { latest.delete(item.recId); latest.set(item.recId, item); }
+  return latest.size > CHANGED_ITEMS_MAX ? { t: "board/changed", reset: true } : { t: "board/changed", items: [...latest.values()] };
+}
+
+function changeOf(value         )                     {
+  const item = value                                                             ;
+  if (!item || !Number.isSafeInteger(item.seq) || typeof item.recId !== "string" || typeof item.kind !== "string") return null;
+  return { seq: item.seq          , recId: item.recId, kind: item.kind };
+}
+
 export class BoardReader {
                    port        ;
                    pollMs        ;
-                   listeners = new Set                             ();
+                   subs = new Set     ();
           timer                        = null;
           polling = false;
-  /** Where the change log was read to; null until a poll has found its end. */
-          after                = null;
+  /** Where the change log was read to; null until a read has found its end. Kept while the backend is away. */
+          end                = null;
           up                 = null;
-  /** Bumped when polling stops, so a poll still on its way does not speak for the next round. */
+  /** Bumped when polling stops, so a read still on its way does not speak for the next round. */
           round = 0;
+  /** The backend's push stream: open, unknown (try it), or not there (an older backend answers 404). */
+          stream                         = null;
+          streamSupported                 = null;
+  /** Not before this time (ms) after the backend refused a stream for a passing reason. */
+          streamRetryAt = 0;
+                   streamIdleMs        ;
+                   streamRetryMs        ;
 
   constructor(options               = {}) {
     this.port = options.port ?? boardPortFrom();
     this.pollMs = (options.pollSeconds ?? DEFAULT_POLL_SECONDS) * 1000;
+    this.streamIdleMs = (options.streamIdleSeconds ?? DEFAULT_STREAM_IDLE_SECONDS) * 1000;
+    this.streamRetryMs = (options.streamRetrySeconds ?? DEFAULT_STREAM_RETRY_SECONDS) * 1000;
   }
 
+  /** How many phones are subscribed. */
+  get listeners()                   { return this.subs; }
+  /** Whether the backend is pushing changes now, rather than being polled. */
+  get streaming()          { return this.stream !== null; }
+
   /** The fetch adds the Host header the backend insists on (127.0.0.1:<port>) and no Origin, as a local caller. */
-          fetch(pathAndQuery        , post         )                    {
+          fetch(pathAndQuery        , post         , signal              = AbortSignal.timeout(READ_TIMEOUT_MS))                    {
     return fetch(`http://127.0.0.1:${this.port}${pathAndQuery}`, {
-      redirect: "error", signal: AbortSignal.timeout(READ_TIMEOUT_MS),
+      redirect: "error", signal,
       ...(post === undefined ? {} : { method: "POST", headers: { "content-type": "application/json" }, body: post }),
     });
   }
@@ -130,72 +184,209 @@ export class BoardReader {
     }
   }
 
-  /** Tells `listener` about the board until the returned function is called. Polls only while someone listens. */
-  subscribe(listener                             )             {
-    this.listeners.add(listener);
-    if (this.up !== null) listener({ t: "board/state", up: this.up });
+  /**
+   * Tells `listener` about the board until the returned function is called. Its first board/state carries `seq`, the
+   * point in the change log it starts from; with `after` (where the phone was) it then gets what changed since, else it
+   * reads the whole board. The log is read only while someone listens.
+   */
+  subscribe(listener          , after         )             {
+    const sub      = { listener, wanted: Number.isSafeInteger(after) && after  >= 0 ? after  : null, cursor: null, admitting: false };
+    this.subs.add(sub);
+    if (this.up === false) listener(this.state(false, null));
     if (!this.timer) {
       this.timer = setInterval(() => void this.poll(), this.pollMs);
       this.timer.unref();
       void this.poll();
-    }
+    } else if (this.up && this.end !== null) void this.admit(sub);
     return () => {
-      this.listeners.delete(listener);
-      if (!this.listeners.size) this.stop();
+      this.subs.delete(sub);
+      if (!this.subs.size) this.stop();
     };
   }
 
   stop() {
-    this.listeners.clear();
+    this.subs.clear();
     if (this.timer) clearInterval(this.timer);
     this.timer = null;
-    this.after = null;
+    this.stream?.abort();
+    this.stream = null;
+    this.streamSupported = null;
+    this.streamRetryAt = 0;
+    this.end = null;
     this.up = null;
     this.polling = false;
     this.round++;
   }
 
-          emit(event            ) {
-    for (const listener of this.listeners) listener(event);
+          state(up         , seq               )             {
+    return up && seq !== null ? { t: "board/state", up, seq, caps: [...BOARD_CAPS], bridge: PACKAGE_VERSION } : { t: "board/state", up };
   }
 
-          async changes(after        )                                              {
+          async changes(after        )                                                  {
     const response = await this.fetch(`/v1/changes?after=${after}&limit=${CHANGES_PAGE}`);
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
     const page = await response.json()                                       ;
     if (!Array.isArray(page.items)) throw new Error("not a page of changes");
-    return { items: page.items, next: typeof page.next === "number" ? page.next : after };
+    const items = page.items.map(changeOf).filter((item)                      => item !== null);
+    return { items, next: typeof page.next === "number" ? page.next : after };
+  }
+
+  /** Brings a new subscriber to the end of the log: its board/state, then what it missed, or a reset. */
+          async admit(sub     ) {
+    if (sub.admitting || sub.cursor !== null || this.end === null) return;
+    sub.admitting = true;
+    const round = this.round;
+    const missed                = [];
+    let reset = false, cursor = sub.wanted;
+    try {
+      if (cursor !== null && cursor > this.end) { reset = true; cursor = this.end; } // a log that went backwards: another backend, or a new database
+      // Read until this subscriber is at least where the shared reader is, so nothing falls between the two.
+      for (let page = 0; !reset && cursor !== null && cursor < this.end  && page < CATCH_UP_PAGES; page++) {
+        const { items, next } = await this.changes(cursor);
+        if (round !== this.round || !this.subs.has(sub)) return;
+        // The log keeps 30 days: a first change past the next number means some were deleted unseen.
+        if (page === 0 && items.length && items[0].seq > cursor + 1) reset = true;
+        missed.push(...items);
+        if (missed.length > CHANGED_ITEMS_MAX * 4) reset = true;
+        if (next === cursor && items.length === 0) break;
+        cursor = next;
+      }
+    } catch {
+      sub.admitting = false;
+      // Try again shortly. Polling would admit it on its next read, but while the backend pushes nothing polls.
+      const retry = setTimeout(() => { if (round === this.round && this.subs.has(sub)) void this.admit(sub); }, this.pollMs);
+      retry.unref();
+      return;
+    }
+    if (round !== this.round || !this.subs.has(sub)) return;
+    sub.admitting = false;
+    sub.cursor = Math.max(cursor ?? this.end , this.end );
+    sub.listener(this.state(true, sub.cursor));
+    if (reset) sub.listener({ t: "board/changed", reset: true });
+    else if (missed.length) sub.listener(changedEvent(missed));
+  }
+
+  /** New changes up to `end`: each subscriber gets those past its own place. */
+          deliver(items               , end        ) {
+    for (const sub of this.subs) {
+      if (sub.cursor === null) continue;
+      const fresh = items.filter((item) => item.seq > sub.cursor );
+      sub.cursor = Math.max(sub.cursor, end);
+      if (fresh.length) sub.listener(changedEvent(fresh));
+    }
+  }
+
+          setUp(up         ) {
+    if (up === this.up) return;
+    this.up = up;
+    for (const sub of this.subs) {
+      if (!up) sub.listener(this.state(false, null));
+      else if (sub.cursor !== null) sub.listener(this.state(true, sub.cursor));
+    }
   }
 
           async poll() {
-    if (this.polling) return;
+    if (this.polling || this.stream) return;
     this.polling = true;
     const round = this.round;
-    let changed = false, up = true, after = this.after;
+    let items                = [], up = true, end = this.end;
     try {
-      // The first poll only finds the end of the log: what happened before someone was listening is not news.
-      if (after === null) {
-        after = 0;
+      // The first read only finds the end of the log: what happened before someone was listening is not news.
+      if (end === null) {
+        end = 0;
         for (let page = 0; page < CATCH_UP_PAGES; page++) {
-          const { items, next } = await this.changes(after);
-          after = next;
-          if (items.length < CHANGES_PAGE) break;
+          const { items: found, next } = await this.changes(end);
+          end = next;
+          if (found.length < CHANGES_PAGE) break;
         }
       } else {
-        const { items, next } = await this.changes(after);
-        after = next;
-        changed = items.length > 0;
+        const page = await this.changes(end);
+        items = page.items;
+        end = page.next;
       }
     } catch {
       up = false;
     }
     if (round !== this.round) return;
     this.polling = false;
-    if (up) this.after = after;
-    if (up !== this.up) {
-      this.up = up;
-      this.emit({ t: "board/state", up });
+    if (up) this.end = end;
+    this.setUp(up);
+    if (!up) return;
+    if (items.length) this.deliver(items, end );
+    for (const sub of this.subs) if (sub.cursor === null) void this.admit(sub);
+    if (this.streamSupported !== false && Date.now() >= this.streamRetryAt) void this.openStream(round);
+  }
+
+  /**
+   * Listens to the backend's push stream from where the log was read to. A backend without one answers 404 (or not as
+   * an event stream), and the bridge keeps polling; a stream that ends hands back to polling, which reopens it.
+   */
+          async openStream(round        ) {
+    if (this.stream || this.end === null) return;
+    const controller = new AbortController();
+    this.stream = controller;
+    // A backend that takes the connection and then says nothing must not hold the bridge: while a stream is open
+    // nothing polls, so silence would also hide the backend going away. Its heartbeat keeps this from firing.
+    let idle = setTimeout(() => controller.abort(), READ_TIMEOUT_MS);
+    idle.unref();
+    const heard = () => {
+      clearTimeout(idle);
+      idle = setTimeout(() => controller.abort(), this.streamIdleMs);
+      idle.unref();
+    };
+    let response          ;
+    try {
+      response = await this.fetch(`/v1/changes/stream?after=${this.end}`, undefined, controller.signal);
+    } catch {
+      clearTimeout(idle);
+      if (this.stream === controller) this.stream = null;
+      return;
+    }
+    if (round !== this.round || this.stream !== controller) { clearTimeout(idle); controller.abort(); return; }
+    const eventStream = (response.headers.get("content-type") ?? "").startsWith("text/event-stream");
+    if (!response.ok || !eventStream || !response.body) {
+      clearTimeout(idle);
+      // Only an older backend lacks it (404, or a 200 that is not an event stream); busy (429) or starting (5xx) passes.
+      if (response.status === 404 || (response.ok && !eventStream)) this.streamSupported = false;
+      else this.streamRetryAt = Date.now() + this.streamRetryMs;
+      this.stream = null;
+      controller.abort();
+      return;
     }
-    if (changed) this.emit({ t: "board/changed" });
+    this.streamSupported = true;
+    heard();
+    let buffer = "", pending                = [], flush                        = null;
+    const send = () => {
+      flush = null;
+      if (round !== this.round || this.stream !== controller) return;
+      const batch = pending;
+      pending = [];
+      const end = Math.max(this.end ?? 0, ...batch.map((item) => item.seq));
+      this.end = end;
+      this.deliver(batch, end);
+    };
+    try {
+      const decoder = new TextDecoder();
+      for await (const chunk of response.body                                        ) {
+        heard();
+        buffer += decoder.decode(chunk, { stream: true });
+        let split        ;
+        while ((split = buffer.search(/\r?\n\r?\n/)) >= 0) {
+          const event = buffer.slice(0, split);
+          buffer = buffer.slice(split).replace(/^\r?\n\r?\n/, "");
+          const data = event.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+          if (!data) continue; // a heartbeat
+          let item                     = null;
+          try { item = changeOf(JSON.parse(data)); } catch { /* not a change */ }
+          if (!item || item.seq <= (this.end ?? 0)) continue;
+          pending.push(item);
+          // Changes that land together (a maintenance round) go to the phone as one event.
+          flush ??= setTimeout(send, 20);
+        }
+      }
+    } catch { /* aborted, or the backend went away */ }
+    clearTimeout(idle);
+    if (flush) { clearTimeout(flush); send(); }
+    if (this.stream === controller) this.stream = null;
   }
 }

package/src/bridge/service.js

@@ -272,7 +272,7 @@ export class BridgeService {
     } else if (message.t === "board/post") {
       void this.board.post(message.path, message.body).then((answer) => this.sendInner(conn, { t: "board/res", id: message.id, ...answer }));
     } else if (message.t === "board/sub") {
-      conn.boardUnsubscribe ??= this.board.subscribe((event) => this.sendInner(conn, event));
+      conn.boardUnsubscribe ??= this.board.subscribe((event) => this.sendInner(conn, event), message.after);
     } else if (message.t === "board/unsub") {
       conn.boardUnsubscribe?.();
       conn.boardUnsubscribe = null;

package/src/protocol.js

@@ -241,13 +241,21 @@ export class FrameCipher {
                                                 
                                                                 
                                                   
-                      
+                                      
                         
                
 
 /** A read or write of the optional board: the backend's status and body, or why there is none (PROTOCOL.md "看板"). */
                                                                                                                               
-                                                                                    
+/** One task that changed, from agens-backend's change log (0.3.14). */
+                                                                       
+/**
+ * What a subscriber hears. From 0.3.14 a board/state that says up also gives `seq` (where in the change log the phone
+ * starts), `caps` and the bridge's version, and board/changed names the tasks, or says `reset` when there are too many.
+ */
+                        
+                                                                                     
+                                                                
 
                                                                  
 /** One segment of a long line: `data` is base64 of bytes [segment * chunk size, …) of the payload, `size` its length. */