@haikit/server 0.18.0 → 0.20.0

package/src/runtime.ts

@@ -10,6 +10,8 @@ import {
   type ModelAdapter,
   type Notify,
   type Progress,
+  type SendSignal,
+  type Signal,
   type StoreAdapter,
   type Tool,
   type ToolCtx,
@@ -18,6 +20,7 @@ import {
   type UpdateOptions,
   type WireEvent,
 } from "@haikit/core";
+import { Broadcast } from "./signals.js";
 
 export interface HaiConfig {
   model: ModelAdapter;
@@ -74,6 +77,20 @@ export interface HaiConfig {
    * with `wake` asks for.
    */
   updates?: boolean;
+  /**
+   * The signals this app sends with `hai.signal`: short-lived broadcasts to
+   * every open browser. A signal not listed here is refused. With any listed,
+   * the browser opens the events stream, which is how a signal reaches it.
+   */
+  signals?: Signal<any>[];
+  /**
+   * How presence is counted (`hai.onPresence`). `graceMs`: how long a
+   * conversation whose events stream closed still counts, so a browser that
+   * reconnects doesn't flicker the count; default 5 s. `heartbeatMs`: how
+   * often servers sharing a store tell each other their counts; a server not
+   * heard from for three beats stops counting; default 10 s.
+   */
+  presence?: { graceMs?: number; heartbeatMs?: number };
 }
 
 /**
@@ -143,6 +160,9 @@ interface UpdateQueue {
   next: UpdateJob | null;
 }
 
+/** The longest delay a Node timer keeps; past it, one fires after about a millisecond. */
+const MAX_TIMER_MS = 2_147_483_647;
+
 /** How long `hai.update` waits for a turn to let the conversation go, by default. */
 const UPDATE_TIMEOUT_MS = 30_000;
 /** How many conversations `hai.update` remembers its surfaces' handles for. */
@@ -167,6 +187,9 @@ export class Hai {
   private readonly queryUi: Tool;
   /** Handles each conversation has a revision of in flight, so two calls can't revise one at once. */
   private readonly revising = new WeakMap<Conversation, Set<string>>();
+  private readonly signals = new Map<string, Signal<any>>();
+  /** Signals sent, streams open, and presence, here and on the other servers. */
+  private readonly broadcast: Broadcast;
   /** `hai.update` calls by conversation and surface: one writing, and the newest waiting behind it. */
   private readonly updating = new Map<string, UpdateQueue>();
   /**
@@ -203,6 +226,25 @@ export class Hai {
       );
     }
     this.maxWakes = { count, perMs };
+    for (const s of config.signals ?? []) {
+      if (this.signals.has(s.name)) throw new Error(`two signals are named "${s.name}"`);
+      this.signals.set(s.name, s);
+    }
+    const { graceMs = 5_000, heartbeatMs = 10_000 } = config.presence ?? {};
+    for (const [name, ms] of [["graceMs", graceMs], ["heartbeatMs", heartbeatMs]] as const) {
+      // Past the longest timer Node keeps, it fires after about a millisecond:
+      // a grace would end at once, and a heartbeat would spin.
+      // Whole milliseconds, as timers count them: a fractional one would be
+      // scheduled shorter than the staleness arithmetic assumes.
+      if (typeof ms !== "number" || !Number.isInteger(ms) || ms <= 0 || ms > MAX_TIMER_MS) {
+        throw new RangeError(
+          `presence.${name} must be a whole number of milliseconds, from 1 to ${MAX_TIMER_MS} (got ${String(ms)})`,
+        );
+      }
+    }
+    this.broadcast = new Broadcast(config.store, graceMs, heartbeatMs);
+    // hear the other servers' signals from now, so a stream that opens later gets their latest
+    if (this.signals.size) this.broadcast.start();
     // query_ui is DERIVED, never authored. It cannot drift from the surfaces
     // that actually exist, and it always exists.
     const queryUi = this.buildQueryUiTool();
@@ -218,13 +260,22 @@ export class Hai {
   }
 
   /**
-   * Whether this app sends notices, `hai.update`'s included, so the browser
-   * should open the events stream.
+   * Whether this app sends notices, `hai.update`'s included: what the
+   * conversation's history may have unread, and the events stream may have to
+   * deliver.
    */
   get sendsNotices(): boolean {
     return this.notices.size > 0 || this.config.updates === true;
   }
 
+  /**
+   * Whether the browser should open the events stream: for notices, or for
+   * signals, which travel on it too.
+   */
+  get streamsEvents(): boolean {
+    return this.sendsNotices || this.signals.size > 0;
+  }
+
   /**
    * Whether any of its notices may be `wake` notices, which the events route
    * starts turns for: a registered one, or an update sent with `wake`.
@@ -277,6 +328,57 @@ export class Hai {
     return { seq: record.seq };
   };
 
+  /**
+   * Send a signal to every open events stream, on this server and, through a
+   * store with `publish` and `subscribe`, on the others. Not stored, not
+   * numbered, never in the model's context or the transcript: the browser
+   * hands it to the app's handler for it. Each signal's latest payload is
+   * kept, and a stream that opens later is sent it first.
+   *
+   * Throws for a signal not listed in `signals`, or a payload that fails its
+   * schema.
+   */
+  readonly signal: SendSignal = (signal, payload) => {
+    const name = signal?.name;
+    if (this.signals.get(name) !== signal) {
+      throw new Error(`signal "${name}" is not registered: list it in createHai({ signals })`);
+    }
+    this.broadcast.send({ type: "signal", name, version: signal.version, payload: signal.payload.parse(payload) });
+  };
+
+  /**
+   * How many conversations have an events stream open, on every server
+   * sharing the store: a tab with the app open, as near as the server can
+   * tell. `listener` hears the count now and whenever it changes. A stream
+   * that closes still counts for `presence.graceMs`, so a reconnect doesn't
+   * flicker it. Returns a function that stops listening.
+   *
+   * Each server counts its own and the totals are summed, so a conversation
+   * counts once per server it has a stream on: one that reconnects to another
+   * server counts on both until the grace runs out, and one with streams on
+   * two servers at once counts twice. (The client opens one stream per
+   * conversation, so the second doesn't happen with it.)
+   *
+   * Only the number leaves a server: no conversation ids, and nothing the
+   * model sees. An app with no notices, updates or signals opens no events
+   * stream, so counts nothing.
+   */
+  onPresence(listener: (count: number) => void): () => void {
+    return this.broadcast.onPresence(listener);
+  }
+
+  /**
+   * An events stream opened for `conversationId`: it hears every signal from
+   * now on, starting with each one's latest payload, and counts toward
+   * presence. The events route calls this; call it too if you serve the
+   * stream yourself, and call what it returns when the stream closes. The
+   * latest payloads go through `replay` when given, so a caller can tell them
+   * from new ones.
+   */
+  streamOpened(conversationId: string, emit: Emit, replay?: Emit): () => void {
+    return this.broadcast.opened(conversationId, emit, replay);
+  }
+
   /**
    * Revise a surface from outside any turn: a webhook, a job, a price feed.
    * The revision is stored and attached as `ctx.update` does, under the

package/src/signals.ts

@@ -0,0 +1,221 @@
+import type { Emit, StoreAdapter, WireEvent } from "@haikit/core";
+
+/**
+ * The channel signals and presence travel on between servers, through the
+ * store's `publish` and `subscribe`. Those are keyed by conversation; this
+ * name has a colon, which no conversation id a store issues has, so it can't
+ * be mistaken for one.
+ */
+export const SIGNAL_CHANNEL = "haikit:signals";
+
+type SignalEvent = Extract<WireEvent, { type: "signal" }>;
+
+/**
+ * What one Hai broadcasts, and who is watching: every open events stream in
+ * this process, each signal's latest payload, and how many conversations have
+ * a stream open, here and on the other servers sharing the store.
+ */
+export class Broadcast {
+  /** Every events stream open in this process. */
+  private readonly streams = new Set<Emit>();
+  /** Each signal's latest payload, by name, for a stream that opens later. */
+  private readonly latest = new Map<string, SignalEvent>();
+  /** Conversations with a stream open here, and how many. */
+  private readonly open = new Map<string, number>();
+  /** Conversations whose last stream closed, still counted until the grace ends. */
+  private readonly leaving = new Map<string, ReturnType<typeof setTimeout>>();
+  /** The other servers' counts, by origin, with when each was last heard. */
+  private readonly peers = new Map<string, { count: number; heard: number }>();
+  private readonly listeners = new Set<(count: number) => void>();
+  private total = 0;
+  /** The local count other servers last heard from this one. */
+  private told = 0;
+  private started = false;
+  /** Settles once this server hears the others: before then, what they send is missed. */
+  private hearing: Promise<void> = Promise.resolve();
+  /** A publish to the other servers in flight, and what waits behind it: the latest of each kind only. */
+  private publishing = false;
+  private readonly unsent = new Map<string, object>();
+  readonly origin = globalThis.crypto.randomUUID();
+
+  constructor(
+    private readonly store: StoreAdapter,
+    private readonly graceMs: number,
+    private readonly heartbeatMs: number,
+  ) {}
+
+  /** Send a signal to every stream, here and on the other servers, and keep it for later ones. */
+  send(event: SignalEvent) {
+    this.latest.set(event.name, event);
+    for (const send of this.streams) send(event);
+    this.publish({ kind: "signal", event });
+  }
+
+  /**
+   * An events stream opened for `conversationId`: it hears signals from now
+   * on, through `emit`, starting with each one's latest payload, through
+   * `replay`; and the conversation counts as present. Call what this returns
+   * when the stream closes.
+   */
+  opened(conversationId: string, emit: Emit, replay: Emit = emit): () => void {
+    this.start();
+    this.streams.add(emit);
+    let closed = false;
+    // Each signal's latest, once this server hears the others, so one they
+    // sent is among them. A live one may come first; the latest is still the
+    // latest, so at worst one arrives twice.
+    void this.hearing.then(() => {
+      if (!closed) for (const event of this.latest.values()) replay(event);
+    });
+
+    const wasLeaving = this.leaving.get(conversationId);
+    if (wasLeaving !== undefined) {
+      // back within the grace: it never stopped counting
+      clearTimeout(wasLeaving);
+      this.leaving.delete(conversationId);
+    }
+    const before = this.open.get(conversationId) ?? 0;
+    this.open.set(conversationId, before + 1);
+    if (before === 0 && wasLeaving === undefined) this.changed();
+
+    return () => {
+      if (closed) return;
+      closed = true;
+      this.streams.delete(emit);
+      const left = (this.open.get(conversationId) ?? 1) - 1;
+      if (left > 0) {
+        this.open.set(conversationId, left);
+        return;
+      }
+      this.open.delete(conversationId);
+      // A browser that drops its stream reconnects within a second or two:
+      // keep counting it a little longer, so the number doesn't flicker.
+      const timer = setTimeout(() => {
+        this.leaving.delete(conversationId);
+        this.changed();
+      }, this.graceMs);
+      timer.unref?.();
+      this.leaving.set(conversationId, timer);
+    };
+  }
+
+  /** Hear the total now and whenever it changes. Returns a function that stops. */
+  onPresence(listener: (count: number) => void): () => void {
+    this.start();
+    this.listeners.add(listener);
+    try {
+      listener(this.total);
+    } catch (err) {
+      // never handed its way to stop, so it must not stay
+      this.listeners.delete(listener);
+      throw err;
+    }
+    return () => void this.listeners.delete(listener);
+  }
+
+  /** Conversations with a stream open in this process, or within the grace. */
+  private get local() {
+    return this.open.size + this.leaving.size;
+  }
+
+  /**
+   * Start hearing the other servers, and telling them this one's count, once.
+   * A Hai that sends signals starts as it is created, so it has the others'
+   * latest values before its first stream opens; any other, when one does.
+   */
+  start() {
+    if (this.started) return;
+    this.started = true;
+    // For as long as this Hai lives. A store that can't listen still resolves,
+    // and hears nothing: signals and presence then stay on this server.
+    const subscribed = this.store.subscribe?.(SIGNAL_CHANNEL, (message) => this.hear(message), new AbortController().signal);
+    if (subscribed) this.hearing = Promise.resolve(subscribed).catch(() => {});
+    const beat = setInterval(() => this.beat(), this.heartbeatMs);
+    beat.unref?.();
+  }
+
+  private hear(message: string) {
+    let heard: { origin?: string; kind?: string; event?: SignalEvent; count?: number };
+    try {
+      heard = JSON.parse(message);
+    } catch {
+      return;
+    }
+    if (!heard || heard.origin === this.origin || typeof heard.origin !== "string") return;
+    if (heard.kind === "signal" && heard.event?.type === "signal" && typeof heard.event.name === "string") {
+      this.latest.set(heard.event.name, heard.event);
+      for (const send of this.streams) send(heard.event);
+    } else if (heard.kind === "presence" && Number.isSafeInteger(heard.count) && heard.count! >= 0) {
+      // a count is a number of conversations: a whole number, never Infinity
+      const known = this.peers.has(heard.origin);
+      const count = heard.count!;
+      if (count > 0) this.peers.set(heard.origin, { count, heard: Date.now() });
+      else this.peers.delete(heard.origin);
+      // a server it hadn't heard from yet hasn't heard from it either
+      if (!known && count > 0 && this.local > 0) this.publish({ kind: "presence", count: this.local });
+      this.recount();
+    }
+  }
+
+  /** This server's count changed: tell the listeners, and the other servers. */
+  private changed() {
+    this.recount();
+    if (this.local !== this.told) {
+      this.told = this.local;
+      this.publish({ kind: "presence", count: this.local });
+    }
+  }
+
+  /** On a timer: drop servers gone quiet, and remind the others this one is here. */
+  private beat() {
+    this.recount();
+    if (this.local > 0) this.publish({ kind: "presence", count: this.local });
+  }
+
+  private recount() {
+    // three missed beats and a server's count no longer counts: it has gone
+    const stale = Date.now() - 3 * this.heartbeatMs;
+    let others = 0;
+    for (const [origin, peer] of this.peers) {
+      if (peer.heard < stale) this.peers.delete(origin);
+      else others += peer.count;
+    }
+    // a sum of whole counts, kept a safe integer however large the peers claim to be
+    const total = Math.min(this.local + others, Number.MAX_SAFE_INTEGER);
+    if (total === this.total) return;
+    this.total = total;
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(total);
+      } catch {
+        // one listener's mistake doesn't stop the others hearing
+      }
+    }
+  }
+
+  /**
+   * Tell the other servers. One publish is in flight at a time, and only the
+   * latest of each signal, and of this server's count, waits behind it: a
+   * burst of signals can't queue every obsolete payload in the store.
+   */
+  private publish(body: { kind: "signal"; event: SignalEvent } | { kind: "presence"; count: number }) {
+    if (!this.store.publish) return;
+    this.unsent.delete(body.kind === "signal" ? `signal:${body.event.name}` : "presence");
+    this.unsent.set(body.kind === "signal" ? `signal:${body.event.name}` : "presence", body);
+    if (!this.publishing) void this.flush();
+  }
+
+  private async flush() {
+    this.publishing = true;
+    while (this.unsent.size) {
+      const [key, body] = this.unsent.entries().next().value!;
+      this.unsent.delete(key);
+      try {
+        await this.store.publish!(SIGNAL_CHANNEL, JSON.stringify({ origin: this.origin, ...body }));
+      } catch {
+        // best effort: the other servers miss this one, and the next beat corrects presence
+      }
+    }
+    this.publishing = false;
+  }
+}