@ccmsg/cli 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",

package/src/instance/instance.ts

@@ -522,18 +522,14 @@ export class Instance {
       ...(this.#mesh === undefined ? {} : { cluster: this.#mesh }),
       inbox,
       direct: this.#direct,
-      publish: (topic, data, instance, to) => {
-        this.#topics.publish(topic, data, instance, to);
-      },
+      publish: (topic, data, instance, to) => this.#topics.publish(topic, data, instance, to),
       listeners: (topic, to) => this.#topics.subscriberCount(topic, to),
     });
 
     this.#notify = new Notify({
       self: this.self,
       label: (sid) => sessionLabel(this.#sessions, sid),
-      publish: (topic, data, instance) => {
-        this.#topics.publish(topic, data, instance);
-      },
+      publish: (topic, data, instance) => this.#topics.publish(topic, data, instance),
     });
 
     this.#topics.attach("peers", this.#sessions);

package/src/messaging/delivery.ts

@@ -21,7 +21,7 @@ import {
   OpError,
   type Requester,
 } from "../dispatch/index.ts";
-import type { TopicValue, UpstreamResource } from "../topics/index.ts";
+import type { PublishOutcome, TopicValue, UpstreamResource } from "../topics/index.ts";
 import type { DirectRoute } from "./direct.ts";
 import type { Inbox } from "./inbox.ts";
 
@@ -71,7 +71,7 @@ export interface DeliveryDeps {
   readonly direct: DirectRoute;
   /** The one way a value reaches subscribers (§6.1), narrowed to the session a
    * message is for. */
-  readonly publish: (topic: string, data: unknown, instance: InstanceId, to: Sid) => void;
+  readonly publish: (topic: string, data: unknown, instance: InstanceId, to: Sid) => PublishOutcome;
   /** How many of that session's connections are listening on `inbox`. */
   readonly listeners: (topic: string, to: Sid) => number;
 }
@@ -128,8 +128,14 @@ export class Delivery implements UpstreamResource {
     }
 
     if (this.deps.listeners(INBOX, to) > 0) {
-      this.deps.publish(INBOX, [message], this.deps.self, to);
-      return { delivered: true };
+      if (this.deps.publish(INBOX, [message], this.deps.self, to) === "ok") {
+        return { delivered: true };
+      }
+      // The session is listening but is behind on what it has already been
+      // offered, which is the same standing as route (a) turning the message
+      // away: it waits in the inbox and is offered again (§4.4).
+      this.deps.inbox.hold(to, message);
+      return { delivered: false, reason: "throttled" };
     }
 
     const { evicted } = this.deps.inbox.hold(to, message);

package/src/messaging/notify.ts

@@ -11,7 +11,7 @@ import type {
   Timestamp,
 } from "@ccmsg/protocol";
 import { type HandlerInput, OpError } from "../dispatch/index.ts";
-import type { TopicValue, UpstreamResource } from "../topics/index.ts";
+import type { PublishOutcome, TopicValue, UpstreamResource } from "../topics/index.ts";
 
 /** The one topic a notification reaches a watcher on. */
 const NOTIFY = "notify";
@@ -23,7 +23,7 @@ export interface NotifyDeps {
   readonly label: (sid: Sid) => string;
   /** The one way a value reaches subscribers (§6.1). No `to`: a notification is
    * for whoever is watching, not for one session. */
-  readonly publish: (topic: string, data: unknown, instance: InstanceId) => void;
+  readonly publish: (topic: string, data: unknown, instance: InstanceId) => PublishOutcome;
 }
 
 /** The `notify` topic and the three ops that speak on it.
@@ -99,7 +99,16 @@ export class Notify implements UpstreamResource {
       text,
       sent_at: now,
     };
-    this.deps.publish(NOTIFY, notification, this.deps.self);
+    // A notification is an occurrence, so nothing folds it away and a watcher
+    // that cannot keep up is what stops it. The caller hears that rather than
+    // the notification going nowhere: it is the one that decides whether to
+    // raise another (§6.4).
+    if (this.deps.publish(NOTIFY, notification, this.deps.self) === "rate_limited") {
+      throw new OpError(
+        "internal_error",
+        "a watcher is behind on this topic; the notification was not taken",
+      );
+    }
     return now;
   }
 

package/src/topics/egress.ts

@@ -0,0 +1,162 @@
+import type { Requester } from "../dispatch/index.ts";
+
+/** How long one terminal's frames are gathered before they go out.
+ *
+ * The value bounds two things at once. Towards the reader: a person watching a
+ * list cannot see a change arrive sooner than the display draws it, so frames
+ * closer together than a few display frames are spent on nothing, while a wait
+ * long enough to be read as lag starts around a quarter of a second. Towards
+ * the cluster: a relayed frame waits once per hop, so the delay a subscriber
+ * sees is this value times the hops between it and the instance that produced
+ * the value — at 100 ms a two-hop cluster still answers inside the window a
+ * person reads as immediate, which a longer period would leave.
+ *
+ * It is not a poll. Nothing is looked at when the period elapses: the timer is
+ * armed only by a frame that has to wait, and an idle terminal has none. */
+export const FLUSH_PERIOD_MS = 100;
+
+/** How many frames that cannot be folded one terminal may hold at once.
+ *
+ * Folded frames need no bound — a topic that replaces its value keeps one entry
+ * however often it is stated — so this bounds the occurrences and the deltas,
+ * the frames that mean something twice if they arrive twice. At one flush every
+ * `FLUSH_PERIOD_MS` a terminal that keeps up drains this many every period, so
+ * reaching the limit means the producer has been outrunning the reader by more
+ * than 2500 frames a second for as long as the queue has stood: past anything a
+ * person, a session or a peer produces, and into the storm this layer exists
+ * for. What is over the limit is refused rather than dropped quietly, so the op
+ * that raised it is the one that hears about it. */
+export const QUEUE_LIMIT = 256;
+
+/** The two things the queue asks of time, so a test can hold both still.
+ *
+ * `schedule` answers with the way to cancel what it armed, because a terminal
+ * that goes away while a flush is pending has to leave nothing behind. */
+export interface EgressClock {
+  now(): number;
+  schedule(afterMs: number, run: () => void): () => void;
+}
+
+const REAL_CLOCK: EgressClock = {
+  now: () => Date.now(),
+  schedule: (afterMs, run) => {
+    const timer = setTimeout(run, afterMs);
+    return () => {
+      clearTimeout(timer);
+    };
+  },
+};
+
+/** What a caller may move: the period, the limit, and the clock both are read
+ * against. */
+export interface EgressOptions {
+  readonly periodMs?: number;
+  readonly limit?: number;
+  readonly clock?: EgressClock;
+}
+
+interface Pending {
+  /** The key this frame folds on, absent for one that does not fold. */
+  readonly fold?: string;
+  frame: object;
+}
+
+/** One terminal's outgoing frames, gathered and let go on a period.
+ *
+ * A terminal is a person's connection, a mesh peer or a CLI subscriber, and
+ * this is the same layer for all three: what differs between them is the socket
+ * underneath, not how fast a subscriber can be written to.
+ *
+ * Three things happen here, and the topic's own granularity decides which. A
+ * frame that replaces the value it carries folds onto the one already waiting
+ * under the same key, so a value stated a thousand times between two flushes
+ * leaves one frame and it is the latest — the reader is never handed a value
+ * that has already been superseded, and never misses the last one. A frame that
+ * is an occurrence or a delta cannot fold, so it queues in the order it was
+ * raised and the queue is bounded: past the bound the frame is refused, which is
+ * how the pressure reaches whoever is producing it instead of accumulating
+ * here. Both leave together on the flush, in the order they were queued.
+ *
+ * The first frame after a quiet spell goes out at once: the period bounds how
+ * often a flush happens, not how long a lone change waits. */
+export class Egress {
+  #queue: Pending[] = [];
+  /** The waiting frame per fold key, so a restatement finds its own entry
+   * rather than being appended behind it. */
+  readonly #folded = new Map<string, Pending>();
+  /** How many waiting frames do not fold, which is what the limit counts. */
+  #kept = 0;
+  #lastFlush = Number.NEGATIVE_INFINITY;
+  #cancel: (() => void) | undefined;
+
+  readonly #periodMs: number;
+  readonly #limit: number;
+  readonly #clock: EgressClock;
+
+  constructor(
+    private readonly conn: Requester,
+    options: EgressOptions = {},
+  ) {
+    this.#periodMs = options.periodMs ?? FLUSH_PERIOD_MS;
+    this.#limit = options.limit ?? QUEUE_LIMIT;
+    this.#clock = options.clock ?? REAL_CLOCK;
+  }
+
+  /** Take one frame for this terminal. `fold` is the key it replaces itself
+   * under, absent for a frame that has to be sent as often as it is raised.
+   *
+   * `false` is the queue refusing the frame: it is full of frames that cannot
+   * be folded, and the caller is the one that can answer for it. */
+  push(frame: object, fold?: string): boolean {
+    if (fold === undefined) {
+      if (this.#kept >= this.#limit) return false;
+      this.#kept += 1;
+      this.#queue.push({ frame });
+    } else {
+      const held = this.#folded.get(fold);
+      if (held !== undefined) {
+        // In place: the value moves, its position among the occurrences around
+        // it does not.
+        held.frame = frame;
+        this.#arm();
+        return true;
+      }
+      const entry: Pending = { fold, frame };
+      this.#queue.push(entry);
+      this.#folded.set(fold, entry);
+    }
+    this.#arm();
+    return true;
+  }
+
+  /** Send everything waiting, in the order it was queued. */
+  flush(): void {
+    this.#cancel?.();
+    this.#cancel = undefined;
+    this.#lastFlush = this.#clock.now();
+    const queue = this.#queue;
+    this.#queue = [];
+    this.#folded.clear();
+    this.#kept = 0;
+    for (const entry of queue) this.conn.send(entry.frame);
+  }
+
+  /** The terminal is done with: what was queued goes out, and nothing armed
+   * outlives it. */
+  release(): void {
+    this.flush();
+  }
+
+  #arm(): void {
+    if (this.#cancel !== undefined) return;
+    const wait = this.#periodMs - (this.#clock.now() - this.#lastFlush);
+    if (wait <= 0) {
+      this.flush();
+      return;
+    }
+    this.#cancel = this.#clock.schedule(wait, () => {
+      this.#cancel = undefined;
+      this.flush();
+    });
+  }
+}

package/src/topics/index.ts

@@ -1,2 +1,3 @@
+export * from "./egress.ts";
 export * from "./handlers.ts";
 export * from "./topics.ts";