@ccmsg/cli 0.3.3 → 0.3.5

package/package.json

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

package/src/cli.ts

@@ -34,11 +34,22 @@ const SESSION_ENV = HARNESSES.flatMap((harness) => [...HARNESS[harness].sessionE
 import { hookEvent, type StatedMeta, statedMeta } from "./greeting/index.ts";
 import {
   isRunning,
+  MERGE_RULES,
   resolveConfigHome,
   resolvePaths,
   resolvePathsFor,
   start,
 } from "./instance/index.ts";
+
+/** The merge rules as the help prints them: one line per field path, in the
+ * order the schema declares them, so the table a person reads is the table the
+ * merge runs on. */
+const MERGE_DOCS: readonly Doc[] = Object.entries(MERGE_RULES).map(([path, rule]) => [
+  path,
+  rule === "merge"
+    ? "instances[] 側にある field だけを defaults に重ねる"
+    : "instances[] 側にあれば丸ごと置換する (追加・和にはならない)",
+]);
 import {
   type Agent,
   AGENTS,
@@ -98,6 +109,10 @@ interface Command {
   readonly usage?: string;
   readonly options?: readonly Doc[];
   readonly env?: readonly Doc[];
+  /** Anything else this level has to state as a list of names, under a title of
+   * its own. Options and environment are the two every level shares; this is
+   * for what only one of them has. */
+  readonly notes?: readonly { readonly title: string; readonly docs: readonly Doc[] }[];
   readonly children?: readonly Command[];
   readonly run?: (args: readonly string[]) => Promise<unknown>;
   /** Whether running it with nothing after it is a command rather than a
@@ -148,6 +163,13 @@ const ROOT: Command = {
               `config home が動かすもの: ${HARNESSES.join(" | ")} (既定 ${DEFAULT_HARNESS})`,
             ],
           ],
+          notes: [
+            {
+              title:
+                "共通 config で instances[] の値が defaults に重なる規則 (掲載の無いパスは丸ごと置換):",
+              docs: MERGE_DOCS,
+            },
+          ],
           run: (args) => added(args),
         },
         {
@@ -488,6 +510,7 @@ function help(path: readonly Command[]): string {
     }
     lines.push("");
   }
+  for (const note of at.notes ?? []) section(lines, note.title, note.docs);
   section(lines, "このレベルのオプション:", at.options);
   section(lines, "グローバルオプション:", GLOBAL_OPTIONS);
   section(lines, "環境変数:", [...(at.env ?? []), ...GLOBAL_ENV]);

package/src/daemon/registry.ts

@@ -3,7 +3,9 @@ import { basename, isAbsolute, join, resolve } from "node:path";
 import type { Endpoint, InstanceId, InstancePingResult } from "@ccmsg/protocol";
 import { DEFAULT_HARNESS, type Harness, HARNESS, isHarness } from "../harness/index.ts";
 import {
+  type InstanceConfig,
   type InstanceEntry,
+  loadConfig,
   loadShared,
   saveShared,
   settingsFor,
@@ -61,6 +63,14 @@ export interface InstanceRow {
 /** One row of `daemon status`: the list's row, plus what the instance itself
  * says when there is one to ask. */
 export interface StatusRow extends InstanceRow {
+  /** What this config home's instance is configured with, after the shared
+   * file's defaults and its own entry are merged (§8.2).
+   *
+   * Answered whether or not anything is running, and read from the file rather
+   * than asked of the instance: this is what a restart would apply, which is
+   * the question an operator who just edited the file has. It carries no
+   * secret — the gateway's token is named by the path it is kept at. */
+  readonly config: InstanceConfig;
   readonly version?: string;
   readonly network?: InstancePingResult["network"];
   /** The other instances this one names, each with where it is dialled: the id
@@ -155,7 +165,7 @@ export function list(env: Env): InstanceRow[] {
 /** Ask one instance how it is. A config home with nothing behind it answers the
  * list's row and nothing more: not running is a state, not a failure. */
 export async function status(target: Target): Promise<StatusRow> {
-  const row = rowFor(target);
+  const row = { ...rowFor(target), config: loadConfig(target.paths.configFile, target.dir) };
   const conn = await connect(target.paths.socket);
   if (conn === undefined) return row;
   try {

package/src/instance/config.ts

@@ -230,13 +230,68 @@ export function saveShared(file: string, shared: SharedConfig): void {
   writeFileSync(file, `${JSON.stringify({ defaults: shared.defaults, instances }, null, 2)}\n`);
 }
 
+/** How one field of the shared file combines an instance's entry with the
+ * defaults.
+ *
+ * `merge` takes the two field by field, so an instance states only what it
+ * differs in; `replace` takes the instance's value whole. */
+export type MergeRule = "merge" | "replace";
+
+/** The rule for every field path that holds an object or an array, which are
+ * the only ones where "combine" could mean more than one thing.
+ *
+ * Declared beside the parsers rather than derived from the values, because
+ * whether a list is a sequence or a set is a fact about what the field means
+ * and every list looks the same without it. A path not named here replaces:
+ * that is what a scalar can do, and it is what an array does until some field
+ * is a set and says so. */
+export const MERGE_RULES: Readonly<Record<string, MergeRule>> = {
+  // The same finished list goes to every instance (§7.1), so an instance that
+  // writes its own means to run with that one and no other.
+  peers: "replace",
+  entry: "merge",
+  "entry.source_ips": "replace",
+  "entry.trusted_proxies": "replace",
+  upstream: "merge",
+  "upstream.launcher": "merge",
+  "upstream.launcher.root_dirs": "replace",
+  "upstream.launcher.templates": "replace",
+  "upstream.launcher.clean_env": "replace",
+  "upstream.launcher.keep_env": "replace",
+};
+
+function ruleFor(path: string): MergeRule {
+  return MERGE_RULES[path] ?? "replace";
+}
+
+function plainObject(raw: unknown): raw is Record<string, unknown> {
+  return typeof raw === "object" && raw !== null && !Array.isArray(raw);
+}
+
+function merged(
+  base: Record<string, unknown>,
+  over: Record<string, unknown>,
+  at: string,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [name, value] of Object.entries(over)) {
+    const path = at === "" ? name : `${at}.${name}`;
+    const under = out[name];
+    out[name] =
+      ruleFor(path) === "merge" && plainObject(under) && plainObject(value)
+        ? merged(under, value, path)
+        : value;
+  }
+  return out;
+}
+
 /** What one config home's instance is configured with: its own entry over the
- * shared defaults, key by key. A config home the file does not list still
- * resolves — `daemon run` on an unregistered directory is the defaults plus
- * the built-ins. */
+ * shared defaults, by the rule each field path declares. A config home the file
+ * does not list still resolves — `daemon run` on an unregistered directory is
+ * the defaults plus the built-ins. */
 export function settingsFor(shared: SharedConfig, dir: string): Record<string, unknown> {
   const entry = shared.instances.find((one) => one.dir === dir);
-  return { ...shared.defaults, ...entry?.settings };
+  return merged(shared.defaults, entry?.settings ?? {}, "");
 }
 
 /** One instance's settings, read at the shape the instance uses them. */

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";