@ccmsg/cli 0.13.0 → 0.14.1

package/src/kv/store.ts

@@ -1,4 +1,5 @@
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type {
   KvDeleteArgs,
@@ -28,15 +29,38 @@ export const KV_DIR = "kv";
  * One file per namespace, whole-file: a namespace holds a handful of small
  * values, and the whole of it is what both a snapshot and a reload state. The
  * write lands through a temporary and a rename, so a kill leaves either the
- * previous namespace or the new one. */
+ * previous namespace or the new one.
+ *
+ * The files are read here, as the store is built — before this instance is
+ * accepting anything, so nobody is waiting on the read (DR-0015). Reading them
+ * when a namespace was first asked about would put the read inside the turn
+ * that answers a `kv.read` or opens a `kv:<ns>` subscription, and a snapshot is
+ * answered from what is held rather than from a promise. A namespace with no
+ * file starts empty, which is the same thing a namespace written for the first
+ * time after this starts from. */
 export class KvStore implements UpstreamResource {
   readonly #namespaces = new Map<string, Map<string, Held>>();
 
+  /** Per namespace, the writes already asked for, as one chain. */
+  readonly #writing = new Map<string, Promise<void>>();
+
   constructor(
     private readonly dir: string,
     private readonly self: InstanceId,
     private readonly publish: (topic: string, data: unknown) => void,
-  ) {}
+  ) {
+    let names: string[];
+    try {
+      names = readdirSync(this.dir);
+    } catch {
+      // No directory yet, which is an instance nobody has written a value to.
+      return;
+    }
+    for (const name of names) {
+      if (!name.endsWith(".json")) continue;
+      this.#namespaces.set(name.slice(0, -".json".length), read(join(this.dir, name)));
+    }
+  }
 
   read(args: KvReadArgs): KvReadResult {
     const held = this.#load(args.ns).get(args.key);
@@ -54,7 +78,7 @@ export class KvStore implements UpstreamResource {
    * was unreachable must not displace what was written since. The answer is
    * what the key carries now — equal to what the caller stated when its write
    * stands, and later than it when an existing value did. */
-  write(args: KvWriteArgs, now: Timestamp = Date.now()): KvWriteResult {
+  async write(args: KvWriteArgs, now: Timestamp = Date.now()): Promise<KvWriteResult> {
     const entries = this.#load(args.ns);
     const updatedAt = args.updated_at ?? now;
     const held = entries.get(args.key);
@@ -65,7 +89,9 @@ export class KvStore implements UpstreamResource {
       return { updated_at: held.updated_at };
     }
     entries.set(args.key, { value: args.value, updated_at: updatedAt });
-    this.#persist(args.ns, entries);
+    // Told to the subscribers once it is written down, so nobody is holding a
+    // value this instance would not have after a restart.
+    await this.#persist(args.ns, entries);
     this.publish(`kv:${args.ns}`, {
       entries: [{ key: args.key, value: args.value, updated_at: updatedAt }],
     });
@@ -75,14 +101,14 @@ export class KvStore implements UpstreamResource {
   /** A key that was not there is no error: the caller wanted the namespace
    * without it, and it is. The removal is still announced, because a subscriber
    * that has the entry has to be told it is gone. */
-  delete(args: KvDeleteArgs, now: Timestamp = Date.now()): KvDeleteResult {
+  async delete(args: KvDeleteArgs, now: Timestamp = Date.now()): Promise<KvDeleteResult> {
     const entries = this.#load(args.ns);
     const before = entries.get(args.key);
     // A removal older than what the key holds undoes nothing, which is the
     // same rule a write is held to.
     if (before !== undefined && before.updated_at > now) return {};
     entries.set(args.key, { updated_at: now, deleted: true });
-    this.#persist(args.ns, entries);
+    await this.#persist(args.ns, entries);
     // A removal is announced only when something was there to remove: a
     // subscriber holding no entry has nothing to be told is gone.
     if (before !== undefined && before.deleted !== true) {
@@ -94,8 +120,7 @@ export class KvStore implements UpstreamResource {
   }
 
   /** Nothing to start or stop: the values are here whether anyone is watching
-   * or not, and the file they live in is read the first time the namespace is
-   * touched. */
+   * or not, and the files they live in were read as this was built. */
   start(): void {}
   stop(): void {}
 
@@ -110,57 +135,51 @@ export class KvStore implements UpstreamResource {
     return [{ instance: this.self, data: { entries } }];
   }
 
+  /** Settle once every write asked for so far has landed. What a stop waits on
+   * before it lets go of the config home (DESIGN §8.5 step 4). */
+  async flush(): Promise<void> {
+    await Promise.allSettled(this.#writing.values());
+  }
+
+  /** What the namespace holds, dropping the removals nothing can still be
+   * carrying an older write for. A name this store read no file for is a
+   * namespace with nothing in it. */
   #load(ns: string, now: Timestamp = Date.now()): Map<string, Held> {
-    const known = this.#namespaces.get(ns);
-    if (known !== undefined) return forget(known, now);
-    const entries = new Map<string, Held>();
-    let text: string;
-    try {
-      text = readFileSync(this.#file(ns), "utf8");
-    } catch {
-      this.#namespaces.set(ns, entries);
-      return entries;
-    }
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(text);
-    } catch {
-      // A file a kill damaged states nothing this instance can act on, and
-      // refusing every read of the namespace would be worse than starting it
-      // empty: the next write replaces the file.
-      parsed = undefined;
-    }
-    if (typeof parsed === "object" && parsed !== null) {
-      for (const [key, held] of Object.entries(parsed as Record<string, unknown>)) {
-        if (typeof held !== "object" || held === null) continue;
-        const fields = held as Record<string, unknown>;
-        const updatedAt = fields["updated_at"];
-        if (typeof updatedAt !== "number") continue;
-        entries.set(
-          key,
-          fields["deleted"] === true
-            ? { updated_at: updatedAt, deleted: true }
-            : { value: fields["value"], updated_at: updatedAt },
-        );
-      }
-    }
-    this.#namespaces.set(ns, entries);
-    return forget(entries, now);
+    const known = this.#namespaces.get(ns) ?? new Map<string, Held>();
+    this.#namespaces.set(ns, known);
+    return forget(known, now);
   }
 
-  #persist(ns: string, entries: Map<string, Held>): void {
-    mkdirSync(this.dir, { recursive: true });
+  /** The namespace as it stands, written whole.
+   *
+   * The body is taken here, before anything is awaited, so what is written is
+   * the namespace as it was when the write was answered. Writes to one
+   * namespace are chained rather than started side by side: two of them would
+   * otherwise be racing for one file, and the older could land last (DR-0015).
+   * Namespaces do not wait on each other, having nothing in common but this
+   * directory. */
+  #persist(ns: string, entries: Map<string, Held>): Promise<void> {
     const file = this.#file(ns);
     const body: Record<string, Held> = {};
     for (const [key, held] of entries) body[key] = held;
-    const temporary = `${file}.ccmsg-${process.pid}-${Date.now()}`;
-    writeFileSync(temporary, JSON.stringify(body));
-    try {
-      renameSync(temporary, file);
-    } catch (cause) {
-      unlinkSync(temporary);
-      throw cause;
-    }
+    const written = (this.#writing.get(ns) ?? Promise.resolve()).then(async () => {
+      await mkdir(this.dir, { recursive: true });
+      const temporary = `${file}.ccmsg-${process.pid}-${Date.now()}`;
+      await writeFile(temporary, JSON.stringify(body));
+      try {
+        await rename(temporary, file);
+      } catch (cause) {
+        await unlink(temporary);
+        throw cause;
+      }
+    });
+    // The chain carries the order, not the outcome: a write that failed is
+    // answered to its own caller, and the ones behind it still go.
+    this.#writing.set(
+      ns,
+      written.catch(() => {}),
+    );
+    return written;
   }
 
   /** The namespace's file. A namespace is an identifier, so its name is a file
@@ -170,6 +189,35 @@ export class KvStore implements UpstreamResource {
   }
 }
 
+/** One namespace's file, as the entries it states.
+ *
+ * A file a kill damaged states nothing this instance can act on, and refusing
+ * every read of the namespace would be worse than starting it empty: the next
+ * write replaces the file. */
+function read(file: string): Map<string, Held> {
+  const entries = new Map<string, Held>();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return entries;
+  }
+  if (typeof parsed !== "object" || parsed === null) return entries;
+  for (const [key, held] of Object.entries(parsed as Record<string, unknown>)) {
+    if (typeof held !== "object" || held === null) continue;
+    const fields = held as Record<string, unknown>;
+    const updatedAt = fields["updated_at"];
+    if (typeof updatedAt !== "number") continue;
+    entries.set(
+      key,
+      fields["deleted"] === true
+        ? { updated_at: updatedAt, deleted: true }
+        : { value: fields["value"], updated_at: updatedAt },
+    );
+  }
+  return entries;
+}
+
 /** Drop the removals nothing can still be carrying an older write for.
  *
  * Done where the namespace is read rather than on a clock of its own: a timer
@@ -188,9 +236,9 @@ export function kvHandlers(store: KvStore) {
   return {
     "kv.read": (input: HandlerInput): KvReadResult =>
       store.read(input.args as unknown as KvReadArgs),
-    "kv.write": (input: HandlerInput): KvWriteResult =>
+    "kv.write": (input: HandlerInput): Promise<KvWriteResult> =>
       store.write(input.args as unknown as KvWriteArgs),
-    "kv.delete": (input: HandlerInput): KvDeleteResult =>
+    "kv.delete": (input: HandlerInput): Promise<KvDeleteResult> =>
       store.delete(input.args as unknown as KvDeleteArgs),
   };
 }

package/src/launcher/launcher.ts

@@ -67,17 +67,20 @@ export class Launcher {
       templates: this.config.templates.map((template) => ({
         name: template.name,
         command: template.command,
-        params: template.params.map((param) => ({ name: param.name, default: param.default })),
+        params: template.params.map((param) => ({
+          name: param.name,
+          default: param.default,
+        })),
       })),
     };
   }
 
-  tree(args: DirTreeArgs): DirTreeResult {
+  tree(args: DirTreeArgs): Promise<DirTreeResult> {
     return dirTree(this.config, args);
   }
 
-  run(args: LauncherRunArgs): Promise<LauncherRunResult> {
-    const cwd = insideRoots(this.config, args.cwd);
+  async run(args: LauncherRunArgs): Promise<LauncherRunResult> {
+    const cwd = await insideRoots(this.config, args.cwd);
     if (cwd === undefined) {
       // The op states no refusal for a path, so a directory outside the roots
       // is answered as what it is from here: an argument this launcher cannot
@@ -129,7 +132,7 @@ export function launcherHandlers(launcher: Launcher) {
     "launcher.config.read": (): LauncherConfigReadResult => launcher.configRead(),
     "launcher.run": (input: HandlerInput): Promise<LauncherRunResult> =>
       launcher.run(input.args as unknown as LauncherRunArgs),
-    "dir.tree": (input: HandlerInput): DirTreeResult =>
+    "dir.tree": (input: HandlerInput): Promise<DirTreeResult> =>
       launcher.tree(input.args as unknown as DirTreeArgs),
   };
 }

package/src/launcher/roots.ts

@@ -1,4 +1,4 @@
-import { statSync } from "node:fs";
+import { stat } from "node:fs/promises";
 import { isAbsolute } from "node:path";
 import type { LauncherConfig } from "../instance/config.ts";
 import { canonical, within } from "../files/index.ts";
@@ -13,19 +13,22 @@ import { canonical, within } from "../files/index.ts";
  *
  * A root that no longer resolves grants nothing and stops nothing: another
  * configured root may still hold the candidate. */
-export function insideRoots(config: LauncherConfig, path: string): string | undefined {
+export async function insideRoots(
+  config: LauncherConfig,
+  path: string,
+): Promise<string | undefined> {
   if (!isAbsolute(path)) return undefined;
-  const real = canonical(path);
-  if (!isDirectory(real)) return undefined;
+  const real = await canonical(path);
+  if (!(await isDirectory(real))) return undefined;
   for (const root of config.root_dirs) {
-    if (within(real, canonical(root))) return real;
+    if (within(real, await canonical(root))) return real;
   }
   return undefined;
 }
 
-export function isDirectory(path: string): boolean {
+export async function isDirectory(path: string): Promise<boolean> {
   try {
-    return statSync(path).isDirectory();
+    return (await stat(path)).isDirectory();
   } catch {
     return false;
   }

package/src/launcher/tree.ts

@@ -1,4 +1,4 @@
-import { readdirSync } from "node:fs";
+import { readdir } from "node:fs/promises";
 import { join, relative } from "node:path";
 import type { DirTreeArgs, DirTreeEntry, DirTreeResult } from "@ccmsg/protocol";
 import type { LauncherConfig } from "../instance/config.ts";
@@ -18,29 +18,29 @@ const MAX_DEPTH = 5;
  * not hold contributes nothing rather than failing the request: the op states no
  * refusal for a path, and a tree assembled from several roots would otherwise be
  * lost whole because one of them went away. */
-export function dirTree(config: LauncherConfig, args: DirTreeArgs): DirTreeResult {
+export async function dirTree(config: LauncherConfig, args: DirTreeArgs): Promise<DirTreeResult> {
   const depth = Math.min(MAX_DEPTH, args.depth ?? config.depth);
   // A filter of nothing is not a filter: an emptied search box shows the tree
   // rather than hiding all of it.
   const filter = args.filter === undefined || args.filter === "" ? undefined : args.filter;
   const entries: DirTreeEntry[] = [];
   for (const root of args.roots) {
-    const real = insideRoots(config, root);
+    const real = await insideRoots(config, root);
     if (real === undefined) continue;
-    entries.push(...walk(config, real, real, depth, filter));
+    entries.push(...(await walk(config, real, real, depth, filter)));
   }
   return { entries: sorted(entries) };
 }
 
-function walk(
+async function walk(
   config: LauncherConfig,
   root: string,
   at: string,
   depth: number,
   filter: string | undefined,
-): DirTreeEntry[] {
+): Promise<DirTreeEntry[]> {
   const entries: DirTreeEntry[] = [];
-  for (const dirent of read(at)) {
+  for (const dirent of await read(at)) {
     // Design rationale: dot-directories are left out. This answers "where could
     // a session run", and a repository's `.git` is not one of those places —
     // browsing a session's own files is a different op with different rules.
@@ -49,24 +49,27 @@ function walk(
     if (dirent.isSymbolicLink()) {
       // A link is a place to run only if what it points at is one, so it goes
       // through the same containment its target would.
-      if (insideRoots(config, path) === undefined) continue;
+      if ((await insideRoots(config, path)) === undefined) continue;
     } else if (!dirent.isDirectory()) continue;
 
-    const children = depth > 1 ? walk(config, root, path, depth - 1, filter) : undefined;
+    const children = depth > 1 ? await walk(config, root, path, depth - 1, filter) : undefined;
     if (filter !== undefined) {
       const matches = relative(root, path).includes(filter);
       // An ancestor of a match survives the filter: without it a match several
       // levels down would have nothing to hang from.
       if (!matches && (children === undefined || children.length === 0)) continue;
     }
-    entries.push({ path, ...(children === undefined ? {} : { children: sorted(children) }) });
+    entries.push({
+      path,
+      ...(children === undefined ? {} : { children: sorted(children) }),
+    });
   }
   return entries;
 }
 
-function read(dir: string) {
+async function read(dir: string) {
   try {
-    return readdirSync(dir, { withFileTypes: true });
+    return await readdir(dir, { withFileTypes: true });
   } catch {
     // A directory that cannot be read is still a place to run; what it holds is
     // simply not known, which is the same answer as holding nothing.

package/src/messaging/delivery.ts

@@ -143,7 +143,7 @@ export class Delivery implements UpstreamResource {
     if (direct === "refused") {
       // Turned away for now, which is neither delivered nor undeliverable: it
       // waits in the inbox and is offered again (DESIGN §6.8).
-      this.#hold(to, message);
+      await this.#hold(to, message);
       return { delivered: false, reason: "throttled" };
     }
 
@@ -160,11 +160,11 @@ export class Delivery implements UpstreamResource {
       // 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 (DESIGN §6.8).
-      this.#hold(to, message);
+      await this.#hold(to, message);
       return { delivered: false, reason: "throttled" };
     }
 
-    const { evicted } = this.#hold(to, message);
+    const { evicted } = await this.#hold(to, message);
     return this.#undelivered(to, evicted ? "inbox_full" : this.#reason(state));
   };
 
@@ -173,9 +173,9 @@ export class Delivery implements UpstreamResource {
    * Stated before it is held, so that a message dropped to make room for it
    * reads in the order the two happened: a removal of something the watcher
    * has, rather than of something it is about to be told about. */
-  #hold(to: Sid, message: InboxMessage): { evicted: boolean } {
+  async #hold(to: Sid, message: InboxMessage): Promise<{ evicted: boolean }> {
     this.#watchers(to, [message]);
-    return this.deps.inbox.hold(to, message);
+    return await this.deps.inbox.hold(to, message);
   }
 
   /** What is waiting, as somebody looking at it from outside reads it.
@@ -247,11 +247,18 @@ export class Delivery implements UpstreamResource {
    * nothing waiting are not asked about, so the cost of a change nobody is owed
    * anything after is one map read. */
   retry = async (): Promise<void> => {
+    const offers: Promise<void>[] = [];
     for (const sid of this.deps.inbox.sids()) {
       const state = this.deps.sessions.classify(sid);
       if (state === undefined || state === "paused" || state === "disappeared") continue;
-      await this.#offer(sid);
+      // One session at a time within its own offer, every session at once
+      // across them: a session that is slow to answer, or that never does
+      // before its deadline, is not a reason the next session waits (DR-0015).
+      // The order within a session is what `#offer` holds to, and it guards
+      // itself per sid.
+      offers.push(this.#offer(sid));
     }
+    await Promise.all(offers);
   };
 
   /** Hand a session what it is owed, oldest first, over route (a).
@@ -275,7 +282,7 @@ export class Delivery implements UpstreamResource {
         // delivered, and a daemon killed here must not offer those again.
         if (outcome !== "delivered") break;
         this.#claimed.get(to)?.delete(message.mid);
-        this.deps.inbox.delivered(to, [message.mid]);
+        await this.deps.inbox.delivered(to, [message.mid]);
       }
     } finally {
       this.#claimed.delete(to);
@@ -324,10 +331,20 @@ export class Delivery implements UpstreamResource {
     const held = this.deps.inbox
       .undelivered(sid)
       .filter((message) => claimed?.has(message.mid) !== true);
-    this.deps.inbox.delivered(
-      sid,
-      held.map((message) => message.mid),
-    );
+    // The messages leave the inbox here, in memory, and the lines saying so go
+    // behind whatever the file already owes (DR-0015): the frame carrying them
+    // is queued on the connection before this returns, so what the session has
+    // been handed is settled whether or not the line has landed yet.
+    void this.deps.inbox
+      .delivered(
+        sid,
+        held.map((message) => message.mid),
+      )
+      .catch(() => {
+        // A line that could not be written costs a message being offered again
+        // on the next run, which is what the inbox does about anything it is
+        // unsure of.
+      });
     return [{ instance: this.deps.self, data: held }];
   }