@scp-dev/broker 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -143,7 +143,8 @@ declare class RelayClient {
     }>;
     /**
      * at a stop: the spawned workers' unread messages, held for the hook to print, waiting up to `wait_s` while workers still run, none came,
-     * pushes are left and no prompt moved the `prompts` mark inject handed out
+     * pushes are left and no prompt moved the `prompts` mark inject handed out; with `wait_s` above 0 and other workers still running, the
+     * broker gathers more of their results into the same push for up to ${LIMITS.pushGraceS} s, which may run past `wait_s`
      */
     stopWait(waitS?: number, prompts?: number): Promise<StopWaitResult>;
     group(params: GroupParams): Promise<unknown>;
@@ -221,6 +222,8 @@ interface Bridge {
     /** the endpoints of other accounts this account's contacts let it reach */
     contacts(): Promise<XListed[]>;
     status(): BridgeStatus;
+    /** reads the credential again and reconnects now, also after the hub revoked or replaced this bridge */
+    relink(): void;
     stop(): Promise<void>;
 }
 /** a WebSocket constructor that takes request headers, as Bun's and Node's do */
@@ -400,6 +403,8 @@ interface BrokerOptions {
     machine?: string | undefined;
     /** the link to the hub; without it the broker never opens a network connection */
     bridge?: BridgeConfig | undefined;
+    /** reads the bridge configuration again for bridge_relink; one that appeared or names another hub or machine restarts the broker */
+    bridgeConfig?: (() => Promise<BridgeConfig | undefined>) | undefined;
     /** how often presence that decays without a request (a hook-only endpoint) is checked for changes (default 60 s) */
     presenceEveryMs?: number | undefined;
     /** where a judge model's key_env is read (default the broker's environment) */

package/dist/index.js

@@ -408,7 +408,8 @@ var RelayClient = class _RelayClient {
   }
   /**
    * at a stop: the spawned workers' unread messages, held for the hook to print, waiting up to `wait_s` while workers still run, none came,
-   * pushes are left and no prompt moved the `prompts` mark inject handed out
+   * pushes are left and no prompt moved the `prompts` mark inject handed out; with `wait_s` above 0 and other workers still running, the
+   * broker gathers more of their results into the same push for up to ${LIMITS.pushGraceS} s, which may run past `wait_s`
    */
   stopWait(waitS = 0, prompts) {
     return this.request("stop_wait", { wait_s: waitS, ...prompts !== void 0 ? { prompts } : {} });
@@ -562,6 +563,7 @@ function startBridge(options) {
   let connected = false;
   let ready = false;
   let stopped = false;
+  let shutDown = false;
   let lastError = options.token ? null : options.tokenError ?? "no hub credential; the broker runs local-only";
   let since = (/* @__PURE__ */ new Date()).toISOString();
   let attempt = 0;
@@ -602,7 +604,7 @@ function startBridge(options) {
     });
   }
   function connect() {
-    if (stopped || !token) return;
+    if (stopped || !token || ws) return;
     let socket;
     try {
       socket = new Socket(relaySocketUrl(options.url), { headers: { Authorization: `Bearer ${token}` } });
@@ -1008,8 +1010,19 @@ function startBridge(options) {
   function status() {
     return { enabled: true, machine, url: options.url, connected, last_error: lastError, since };
   }
+  function relink() {
+    if (shutDown) return;
+    stopped = false;
+    attempt = 0;
+    clearTimeout(retryTimer);
+    if (ws) return;
+    void reconnect().then(() => {
+      if (!token && !ws) setState(false, "no hub credential; log in again");
+    });
+  }
   async function stop() {
     stopped = true;
+    shutDown = true;
     clearTimeout(retryTimer);
     for (const fn of waitingForLink.splice(0)) fn();
     const socket = ws;
@@ -1021,7 +1034,7 @@ function startBridge(options) {
     if (socket && socket.readyState <= 1) socket.close(1e3, "the broker stopped");
   }
   connect();
-  return { forward, changed, resync, activity, contacts, status, stop };
+  return { forward, changed, resync, activity, contacts, status, relink, stop };
 }
 
 // src/server.ts
@@ -1576,7 +1589,7 @@ function openDatabase(path) {
 // src/server.ts
 var SWEEP_MS = 10 * 6e4;
 var PRESENCE_MS = 6e4;
-var OBSERVER_METHODS = /* @__PURE__ */ new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status"]);
+var OBSERVER_METHODS = /* @__PURE__ */ new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status", "bridge_relink"]);
 var SCOPE_METHODS = /* @__PURE__ */ new Set([
   "rules",
   "rules_set",
@@ -1598,6 +1611,13 @@ var ASK_RECHECK_MS = 1e3;
 var STOP_RECHECK_MS = 1e3;
 var TRANSIENT_METHODS = /* @__PURE__ */ new Set(["event", "status", "whoami", "inject", "injected", "peek_turn", "stop_wait", "prompted"]);
 var GRANT_UNBOUND = `a spawn-env grant binds only a new harness process: run the harness with it, or name the child (${CLI_NAME} spawn-env --name / --as)`;
+function workerResults(result) {
+  return result.messages.length - (result.others_shown ?? 0) + result.more;
+}
+function othersRunning(result) {
+  const senders = new Set(result.messages.slice(0, result.messages.length - (result.others_shown ?? 0)).map((m) => m.from.address));
+  return result.workers.filter((address) => !senders.has(address)).length + result.starting;
+}
 function running(pid) {
   try {
     process.kill(pid, 0);
@@ -1726,6 +1746,15 @@ async function startBroker(options) {
       }
     });
   }
+  async function relink() {
+    const config = options.bridgeConfig ? await options.bridgeConfig() : options.bridge;
+    if (!config || bridge && config.url === options.bridge?.url && config.machine === options.bridge?.machine) {
+      bridge?.relink();
+      return bridge?.status() ?? { enabled: false };
+    }
+    setImmediate(() => void stop());
+    return { enabled: false, restarting: true };
+  }
   function activity() {
     if (idleTimer) clearTimeout(idleTimer);
     idleTimer = void 0;
@@ -1886,6 +1915,21 @@ async function startBroker(options) {
       if (s.data.closed) done();
     });
   }
+  async function gather(me, result, peek, s) {
+    const gathering = (r) => workerResults(r) > 0 && !r.more && !r.prompted && othersRunning(r) > 0;
+    const cap = Date.now() + LIMITS2.pushGraceS * 1e3;
+    let quiet = Date.now() + LIMITS2.pushQuietS * 1e3;
+    let results = workerResults(result);
+    while (gathering(result) && !s.data.closed && Date.now() < Math.min(quiet, cap)) {
+      await waitFor(me, Math.min(quiet, cap) - Date.now(), s);
+      if (closing) throw new RelayError4("unauthorized", "the relay broker is stopping");
+      result = core.stopWait(me, peek);
+      if (workerResults(result) > results) {
+        results = workerResults(result);
+        quiet = Date.now() + LIMITS2.pushQuietS * 1e3;
+      }
+    }
+  }
   function onData(s, chunk) {
     const { lines, tooLong } = s.data.reader.push(chunk);
     for (const line of lines) s.data.queue.push(line);
@@ -2206,22 +2250,28 @@ async function startBroker(options) {
           ...hookOf(s)
         });
       case "stop_wait": {
-        const deadline = Date.now() + waitSeconds(params.wait_s);
+        const waitMs = waitSeconds(params.wait_s);
+        const deadline = Date.now() + waitMs;
         const options2 = { ...hookOf(s), ...typeof params.prompts === "number" ? { prompts: params.prompts } : {} };
-        let result = core.stopWait(me, options2);
+        const peek = { ...options2, peek: true };
+        let result = core.stopWait(me, peek);
         const idle = (r) => !r.messages.length && !r.more && r.workers.length + r.starting > 0 && r.pushes_left > 0 && !r.prompted;
         while (idle(result) && !s.data.closed && Date.now() < deadline) {
           await waitFor(me, Math.min(STOP_RECHECK_MS, deadline - Date.now()), s);
           if (closing) throw new RelayError4("unauthorized", "the relay broker is stopping");
-          result = core.stopWait(me, options2);
+          result = core.stopWait(me, peek);
         }
-        return result;
+        if (waitMs > 0) await gather(me, result, peek, s);
+        return core.stopWait(me, options2);
+      }
+      case "prompted": {
+        const prompted = core.prompted(me, hookOf(s));
+        if (prompted) wake(me);
+        return { prompted };
       }
-      case "prompted":
-        return { prompted: core.prompted(me, hookOf(s)) };
       case "injected":
         return {
-          injected: core.injected(params.seqs, params.hold, { endpoint: me, read: params.read }),
+          injected: core.injected(params.seqs, params.hold, { endpoint: me, read: params.read, deferred: params.deferred === true }),
           ...params.stop === true ? { held: core.stopHeld(me, hookOf(s)) } : {},
           ...params.push === true ? { pushed: core.pushed(me, params.read, hookOf(s)) } : {},
           ...params.nudged !== void 0 ? { nudged: core.nudged(me, params.nudged, hookOf(s)) } : {},
@@ -2231,6 +2281,8 @@ async function startBroker(options) {
         };
       case "message":
         return { message: core.delivered(me, params.id) ?? (params.member === true ? core.threadMessage(me, params.id) : null) };
+      case "receipts":
+        return core.receipts(me, params.id);
     }
     throw new RelayError4("method_not_found", `no method ${method}`);
   }
@@ -2304,6 +2356,8 @@ async function startBroker(options) {
       }
       case "cloud_status":
         return bridge?.status() ?? { enabled: false };
+      case "bridge_relink":
+        return relink();
     }
     throw new RelayError4("method_not_found", `no method ${method}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/broker",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Swarm Communication Protocol local broker: a unix socket JSON-RPC daemon over the relay core, its client and the bridge to an account hub.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",
@@ -37,8 +37,8 @@
     "typecheck": "tsc -p ."
   },
   "dependencies": {
-    "@scp-dev/core": "0.1.0",
-    "@scp-dev/hub": "0.1.0"
+    "@scp-dev/core": "0.1.1",
+    "@scp-dev/hub": "0.1.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/bridge.ts

@@ -78,6 +78,8 @@ export interface Bridge {
   /** the endpoints of other accounts this account's contacts let it reach */
   contacts(): Promise<XListed[]>
   status(): BridgeStatus
+  /** reads the credential again and reconnects now, also after the hub revoked or replaced this bridge */
+  relink(): void
   stop(): Promise<void>
 }
 
@@ -132,7 +134,9 @@ export function startBridge(options: BridgeOptions): Bridge {
   let connected = false
   /** hello went through on the current socket: deltas may go out */
   let ready = false
+  /** the hub turned this bridge away, or the broker stopped it: no more retries until relink */
   let stopped = false
+  let shutDown = false
   let lastError: string | null = options.token ? null : (options.tokenError ?? "no hub credential; the broker runs local-only")
   let since = new Date().toISOString()
   let attempt = 0
@@ -177,7 +181,7 @@ export function startBridge(options: BridgeOptions): Bridge {
   }
 
   function connect() {
-    if (stopped || !token) return
+    if (stopped || !token || ws) return
     let socket: WebSocket
     try {
       socket = new Socket(relaySocketUrl(options.url), { headers: { Authorization: `Bearer ${token}` } })
@@ -624,8 +628,20 @@ export function startBridge(options: BridgeOptions): Bridge {
     return { enabled: true, machine, url: options.url, connected, last_error: lastError, since }
   }
 
+  function relink() {
+    if (shutDown) return
+    stopped = false
+    attempt = 0
+    clearTimeout(retryTimer)
+    if (ws) return
+    void reconnect().then(() => {
+      if (!token && !ws) setState(false, "no hub credential; log in again")
+    })
+  }
+
   async function stop() {
     stopped = true
+    shutDown = true
     clearTimeout(retryTimer)
     for (const fn of waitingForLink.splice(0)) fn()
     const socket = ws
@@ -638,5 +654,5 @@ export function startBridge(options: BridgeOptions): Bridge {
   }
 
   connect()
-  return { forward, changed, resync, activity, contacts, status, stop }
+  return { forward, changed, resync, activity, contacts, status, relink, stop }
 }

package/src/client.ts

@@ -196,7 +196,8 @@ export class RelayClient {
 
   /**
    * at a stop: the spawned workers' unread messages, held for the hook to print, waiting up to `wait_s` while workers still run, none came,
-   * pushes are left and no prompt moved the `prompts` mark inject handed out
+   * pushes are left and no prompt moved the `prompts` mark inject handed out; with `wait_s` above 0 and other workers still running, the
+   * broker gathers more of their results into the same push for up to ${LIMITS.pushGraceS} s, which may run past `wait_s`
    */
   stopWait(waitS = 0, prompts?: number): Promise<StopWaitResult> {
     return this.request<StopWaitResult>("stop_wait", { wait_s: waitS, ...(prompts !== undefined ? { prompts } : {}) })

package/src/server.ts

@@ -57,6 +57,8 @@ export interface BrokerOptions {
   machine?: string | undefined
   /** the link to the hub; without it the broker never opens a network connection */
   bridge?: BridgeConfig | undefined
+  /** reads the bridge configuration again for bridge_relink; one that appeared or names another hub or machine restarts the broker */
+  bridgeConfig?: (() => Promise<BridgeConfig | undefined>) | undefined
   /** how often presence that decays without a request (a hook-only endpoint) is checked for changes (default 60 s) */
   presenceEveryMs?: number | undefined
   /** where a judge model's key_env is read (default the broker's environment) */
@@ -110,7 +112,7 @@ interface Connection {
 
 const SWEEP_MS = 10 * 60_000
 const PRESENCE_MS = 60_000
-const OBSERVER_METHODS = new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status"])
+const OBSERVER_METHODS = new Set(["list", "snapshot", "watch", "log", "policy", "policy_check", "cloud_status", "bridge_relink"])
 const SCOPE_METHODS = new Set([
   "rules",
   "rules_set",
@@ -135,6 +137,17 @@ const STOP_RECHECK_MS = 1000
 const TRANSIENT_METHODS = new Set(["event", "status", "whoami", "inject", "injected", "peek_turn", "stop_wait", "prompted"])
 const GRANT_UNBOUND = `a spawn-env grant binds only a new harness process: run the harness with it, or name the child (${CLI_NAME} spawn-env --name / --as)`
 
+/** the workers' messages and handbacks a stop's push would show, and those of theirs left unread past it */
+function workerResults(result: StopWaitResult): number {
+  return result.messages.length - (result.others_shown ?? 0) + result.more
+}
+
+/** the workers still running that sent none of the messages a stop's push would show, and those not joined yet */
+function othersRunning(result: StopWaitResult): number {
+  const senders = new Set(result.messages.slice(0, result.messages.length - (result.others_shown ?? 0)).map((m) => m.from.address))
+  return result.workers.filter((address) => !senders.has(address)).length + result.starting
+}
+
 type Request = { jsonrpc?: string; id?: string | number | null; method?: unknown; params?: unknown }
 
 /** whether a process runs (one of another user's counts too) */
@@ -270,6 +283,17 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     })
   }
 
+  /** links the bridge again with the credential on disk; a configuration this broker cannot take without a restart stops it */
+  async function relink(): Promise<object> {
+    const config = options.bridgeConfig ? await options.bridgeConfig() : options.bridge
+    if (!config || (bridge && config.url === options.bridge?.url && config.machine === options.bridge?.machine)) {
+      bridge?.relink()
+      return bridge?.status() ?? { enabled: false }
+    }
+    setImmediate(() => void stop())
+    return { enabled: false, restarting: true }
+  }
+
   function activity() {
     if (idleTimer) clearTimeout(idleTimer)
     idleTimer = undefined
@@ -461,6 +485,32 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     })
   }
 
+  /**
+   * a stop's push with worker results to show while other workers still run: waits on, peeking, for more of theirs to show with them until
+   * none came for ${LIMITS.pushQuietS} s, ${LIMITS.pushGraceS} s after it began (which may run past the stop's wait), the push budget is
+   * full (`more`), no other worker runs ({@link othersRunning}), a prompt came or the connection closed
+   */
+  async function gather(
+    me: string,
+    result: StopWaitResult,
+    peek: ReturnType<typeof hookOf> & { prompts?: number; peek: boolean },
+    s: Conn<Connection>,
+  ): Promise<void> {
+    const gathering = (r: StopWaitResult) => workerResults(r) > 0 && !r.more && !r.prompted && othersRunning(r) > 0
+    const cap = Date.now() + LIMITS.pushGraceS * 1000
+    let quiet = Date.now() + LIMITS.pushQuietS * 1000
+    let results = workerResults(result)
+    while (gathering(result) && !s.data.closed && Date.now() < Math.min(quiet, cap)) {
+      await waitFor(me, Math.min(quiet, cap) - Date.now(), s)
+      if (closing) throw new RelayError("unauthorized", "the relay broker is stopping")
+      result = core.stopWait(me, peek)
+      if (workerResults(result) > results) {
+        results = workerResults(result)
+        quiet = Date.now() + LIMITS.pushQuietS * 1000
+      }
+    }
+  }
+
   function onData(s: Conn<Connection>, chunk: Uint8Array) {
     const { lines, tooLong } = s.data.reader.push(chunk)
     for (const line of lines) s.data.queue.push(line)
@@ -796,22 +846,28 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
           ...hookOf(s),
         })
       case "stop_wait": {
-        const deadline = Date.now() + waitSeconds(params.wait_s)
+        const waitMs = waitSeconds(params.wait_s)
+        const deadline = Date.now() + waitMs
         const options = { ...hookOf(s), ...(typeof params.prompts === "number" ? { prompts: params.prompts } : {}) }
-        let result = core.stopWait(me, options)
+        const peek = { ...options, peek: true }
+        let result = core.stopWait(me, peek)
         const idle = (r: StopWaitResult) => !r.messages.length && !r.more && r.workers.length + r.starting > 0 && r.pushes_left > 0 && !r.prompted
         while (idle(result) && !s.data.closed && Date.now() < deadline) {
           await waitFor(me, Math.min(STOP_RECHECK_MS, deadline - Date.now()), s)
           if (closing) throw new RelayError("unauthorized", "the relay broker is stopping")
-          result = core.stopWait(me, options)
+          result = core.stopWait(me, peek)
         }
-        return result
+        if (waitMs > 0) await gather(me, result, peek, s)
+        return core.stopWait(me, options)
+      }
+      case "prompted": {
+        const prompted = core.prompted(me, hookOf(s))
+        if (prompted) wake(me)
+        return { prompted }
       }
-      case "prompted":
-        return { prompted: core.prompted(me, hookOf(s)) }
       case "injected":
         return {
-          injected: core.injected(params.seqs, params.hold, { endpoint: me, read: params.read }),
+          injected: core.injected(params.seqs, params.hold, { endpoint: me, read: params.read, deferred: params.deferred === true }),
           ...(params.stop === true ? { held: core.stopHeld(me, hookOf(s)) } : {}),
           ...(params.push === true ? { pushed: core.pushed(me, params.read, hookOf(s)) } : {}),
           ...(params.nudged !== undefined ? { nudged: core.nudged(me, params.nudged, hookOf(s)) } : {}),
@@ -821,6 +877,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
         }
       case "message":
         return { message: core.delivered(me, params.id) ?? (params.member === true ? core.threadMessage(me, params.id) : null) }
+      case "receipts":
+        return core.receipts(me, params.id)
     }
     throw new RelayError("method_not_found", `no method ${method}`)
   }
@@ -903,6 +961,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       }
       case "cloud_status":
         return bridge?.status() ?? { enabled: false }
+      case "bridge_relink":
+        return relink()
     }
     throw new RelayError("method_not_found", `no method ${method}`)
   }