@ccmsg/cli 0.10.1 → 0.11.0

package/src/instance/identity.ts

@@ -13,9 +13,9 @@ export const ID = /^[0-9a-f]{32}$/;
 
 /** A fresh id of that width, for whatever is being named.
  *
- * Shared with the cluster ids rather than written again there: what an id has
- * to be is unguessable-by-accident and the same width wherever it is read, and
- * a second generator is a second answer to how wide that is. */
+ * One generator rather than one per kind of id: what an id has to be is
+ * unguessable-by-accident and the same width wherever it is read, and a second
+ * generator is a second answer to how wide that is. */
 export function newId(): string {
   return randomBytes(ID_BYTES).toString("hex");
 }

package/src/instance/instance.ts

@@ -89,7 +89,14 @@ import {
   recordsDir,
 } from "../auth/index.ts";
 import { type Cidr, clientAddress, parseCidr } from "./client.ts";
-import { type EntryConfig, type InstanceConfig, loadConfig } from "./config.ts";
+import {
+  applied,
+  configOf,
+  DEFAULT_CONFIG,
+  type EntryConfig,
+  type InstanceConfig,
+  settle,
+} from "./config.ts";
 import { completeHandlers } from "./handlers.ts";
 import { acquireLock, type Held, isHeldByUs, type Lock } from "./lock.ts";
 import { Log } from "./log.ts";
@@ -112,6 +119,15 @@ export interface StartOptions {
   readonly configHome?: string;
   /** Mirror the log to stderr. A foreground run wants it; a test does not. */
   readonly echoLog?: boolean;
+  /** Whether this start is the one that reads the edited files and writes down
+   * what checked out (§8.2).
+   *
+   * A supervisor does that for the instances it starts, so its children read
+   * what it applied and write nothing: one writer means no two processes
+   * racing over the same file, and it means `config diff --satisfied` compares
+   * against a value exactly one thing produced. A foreground start with no
+   * supervisor above it is the writer, because there is nobody else to be. */
+  readonly settle?: boolean;
   /** Overrides the confirmation poll of the sessions watch, for tests. */
   readonly pollMs?: number;
   /** Overrides the mesh's own intervals, for a test that cannot wait out a
@@ -176,7 +192,7 @@ export async function start(options: StartOptions = {}): Promise<StartOutcome> {
   try {
     // 3. the config. A broken one ends the start rather than turning the
     // setting it carried silently off (DV-Q9).
-    const config = await loadConfig(paths.configDir, paths.configHome);
+    const config = await configFor(paths, log, options.settle ?? true);
     // What the config says of the gateway, resolved before anything is built
     // from it: a webhook source whose secret cannot be read ends the start
     // here, for the same reason a broken config does (DV-Q9).
@@ -192,12 +208,12 @@ export async function start(options: StartOptions = {}): Promise<StartOutcome> {
     // `daemon run` on one the shared file does not list — gets its id now
     // rather than from an `add` that never happened (DR-0001 §2.1).
     const id = instanceIdentity(paths.instanceIdFile);
-    // 5. the endpoint list, for an instance that has a mesh.
+    // 5. the mesh, for an instance the data names an address for.
     //
-    // Which entry of it is this instance is settled by the probe, and the probe
-    // has to arrive at a listener — so the WebSocket is bound here and handed
-    // to the instance. A list that names this instance no times, or twice, ends
-    // the start.
+    // Which entry of the list is this instance is its own row, so nothing has
+    // to be asked of the network to settle it (§7.1). The WebSocket is still
+    // bound here and handed over, because the instance does not exist yet and
+    // a peer may dial the moment the address is up.
     const mesh = meshFor(id, config, log, options.meshTiming);
     const wiring = mesh === undefined ? undefined : await bindForMesh(config, mesh);
     // 6-8 are the instance's own construction and listen.
@@ -223,6 +239,35 @@ export async function start(options: StartOptions = {}): Promise<StartOutcome> {
   }
 }
 
+/** What this config home runs with: the settings that were read and checked.
+ *
+ * Either read from what was applied, or — on the start that has nobody above
+ * it — read from the edited files and written down if it holds. Both end at
+ * the same place: what this instance runs with is a value that checked out.
+ * A config that does not hold leaves the applied one standing and is written
+ * to the log, because an instance that was serving a session is not something
+ * a typo should take down (§8.3).
+ *
+ * A config home nothing states settings for runs the built-in ones, which is
+ * the unix socket and no mesh: `daemon run` on a directory nobody registered
+ * is a thing a person may do. */
+async function configFor(paths: InstancePaths, log: Log, check: boolean): Promise<InstanceConfig> {
+  if (!check) {
+    // Read, and nothing else: whoever started this instance has already read
+    // the files and written down what held.
+    const standing = applied(paths.stateRoot);
+    return (
+      (standing === undefined ? undefined : configOf(standing, paths.configHome)?.config) ??
+      DEFAULT_CONFIG
+    );
+  }
+  const settled = await settle(paths.configDir, paths.stateRoot);
+  for (const problem of settled.problems) {
+    log.write("config refused", { file: problem.file, problem: problem.msg });
+  }
+  return configOf(settled.satisfied, paths.configHome)?.config ?? DEFAULT_CONFIG;
+}
+
 /** The mesh, on an instance configured for one.
  *
  * Two things have to be true: peers to dial, and an address they can dial back.
@@ -234,10 +279,14 @@ function meshFor(
   log: Log,
   timing?: MeshTiming,
 ): Mesh | undefined {
-  if (config.peers.length === 0 || config.entry === undefined) return undefined;
+  const self = config.endpoint;
+  if (self === undefined || config.endpoints.length === 0 || config.entry === undefined) {
+    return undefined;
+  }
   return new Mesh({
     id,
-    peers: config.peers,
+    self,
+    peers: config.endpoints.map((row) => row.endpoint),
     conns: new ConnRegistry(),
     log: (msg, fields) => {
       log.write(msg, fields);
@@ -259,12 +308,11 @@ export interface MeshWiring {
   attach(instance: Instance): void;
 }
 
-/** Bind the WebSocket, settle which endpoint this instance is, and hand both on.
+/** Bind the WebSocket before the instance exists, and hand it on.
  *
- * The listener answers the two pre-authentication routes from the moment it is
- * up — the probe of self-identification and the key of mesh-peer-auth §6 — and
- * refuses everything else until the instance exists, which is a window of one
- * round of probes. */
+ * A peer may dial the moment the address is up, so the listener answers the one
+ * pre-authentication route from that moment — the key of mesh-peer-auth §6 —
+ * and refuses everything else until there is an instance to answer. */
 async function bindForMesh(config: InstanceConfig, mesh: Mesh): Promise<MeshWiring> {
   const entry = config.entry as EntryConfig;
   let instance: Instance | undefined;
@@ -284,16 +332,6 @@ async function bindForMesh(config: InstanceConfig, mesh: Mesh): Promise<MeshWiri
       instance?.accepted(conn, info);
     },
   });
-  try {
-    await mesh.identify();
-  } catch (cause) {
-    // The listener is bound before the endpoint list is checked, so it is this
-    // function's to release when the check refuses — nothing else holds it yet,
-    // and a port left bound by a refused start is one the next start cannot
-    // have.
-    await ws.close();
-    throw cause;
-  }
   return {
     conns: mesh.conns,
     ws,
@@ -718,7 +756,7 @@ export class Instance {
       pid: process.pid,
       socket: this.paths.socket,
       http: this.http,
-      peers: this.config.peers.length,
+      peers: this.config.endpoints.length,
     });
   }
 

package/src/instance/paths.ts

@@ -2,7 +2,15 @@ import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, isAbsolute, join } from "node:path";
 import { currentSession, HARNESS } from "../harness/index.ts";
-import { CLUSTERS_DIR, CLUSTERS_FILE, CONFIG_FILE, INSTANCES_DIR } from "./config.ts";
+import {
+  CONFIG_FILE,
+  ENDPOINTS_FILE,
+  INSTANCES_DIR,
+  REJECTED_DIR,
+  SATISFIED_FILE,
+  STATE_CONFIG_DIR,
+  SUPERVISOR_FILE,
+} from "./config.ts";
 
 /** Every path one instance uses, decided in one place (daemon-v2 §8.1).
  *
@@ -23,9 +31,15 @@ export interface InstancePaths {
   readonly configFile: string;
   /** Where the file naming this config home lives, one per instance. */
   readonly instancesDir: string;
-  /** Which clusters this host knows of, and where each one's file is. */
-  readonly clustersFile: string;
-  readonly clustersDir: string;
+  /** The mesh as data, and which of it this host starts. */
+  readonly endpointsFile: string;
+  readonly supervisorFile: string;
+  /** Where what has been read and checked is kept, which is the only thing the
+   * supervisor and the instances read (§8.2). */
+  readonly stateRoot: string;
+  readonly satisfiedFile: string;
+  /** Where a file is put before it is overwritten by the checked copy. */
+  readonly rejectedDir: string;
   readonly stateDir: string;
   /** The address clients connect to. A symlink to whichever `socketReal` is
    * currently serving, so a client's path outlives the process behind it. */
@@ -119,6 +133,7 @@ export function resolvePaths(env: Env = process.env): InstancePaths {
 export function resolvePathsFor(configHome: string, env: Env = process.env): InstancePaths {
   const key = instanceKey(configHome);
   const configDir = resolveConfigDir(env);
+  const stateRoot = resolveStateRoot(env);
   const stateDir = appDir(env, "CCMSG_STATE_DIR", "XDG_STATE_HOME", [".local", "state"], key);
   const socketDir = socketDirFor(stateDir, key);
   return {
@@ -127,8 +142,11 @@ export function resolvePathsFor(configHome: string, env: Env = process.env): Ins
     configDir,
     configFile: join(configDir, CONFIG_FILE),
     instancesDir: join(configDir, INSTANCES_DIR),
-    clustersFile: join(configDir, CLUSTERS_FILE),
-    clustersDir: join(configDir, CLUSTERS_DIR),
+    endpointsFile: join(configDir, ENDPOINTS_FILE),
+    supervisorFile: join(configDir, SUPERVISOR_FILE),
+    stateRoot,
+    satisfiedFile: join(stateRoot, STATE_CONFIG_DIR, SATISFIED_FILE),
+    rejectedDir: join(stateRoot, REJECTED_DIR),
     stateDir,
     socketDir,
     socket: join(socketDir, SOCKET_NAME),

package/src/mesh/index.ts

@@ -1,6 +1,5 @@
 export * from "./instances.ts";
 export * from "./keys.ts";
 export * from "./mesh.ts";
-export * from "./probe.ts";
 export * from "./relay.ts";
 export * from "./wire.ts";

package/src/mesh/mesh.ts

@@ -30,16 +30,13 @@ import {
   randomId,
   verifyProof,
 } from "./keys.ts";
-import { PeerProbe, type PeerReport } from "./probe.ts";
 import {
-  isProbePath,
   jwkEndpoint,
   type JwkRequest,
   type JwkResponse,
   kidOfPath,
   MESH_PROTOCOL,
   meshFrameOf,
-  type ProbeBody,
   wsEndpoint,
 } from "./wire.ts";
 
@@ -135,9 +132,10 @@ export interface MeshHost {
 export interface MeshDeps {
   /** This instance's id, which is what it is called on the wire. */
   readonly id: InstanceId;
-  /** Every mesh endpoint, this instance's own among them. Which one that is is
-   * settled by `identify`, not configured (DR-0001 §2.7). */
+  /** Every mesh endpoint, this instance's own among them. */
   readonly peers: readonly Endpoint[];
+  /** Which of them is this instance, as the data says (§7.1). */
+  readonly self: Endpoint;
   readonly conns: ConnRegistry;
   readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
   /** Something changed about which peers are reachable. */
@@ -259,10 +257,9 @@ export class Mesh {
   readonly #minted = new Map<string, Minted>();
   readonly #retries = new Map<Endpoint, ReturnType<typeof setTimeout>>();
   readonly #backoff = new Map<Endpoint, number>();
-  readonly #probe = new PeerProbe();
-  /** Which of the configured endpoints is this instance, settled by `identify`
+  /** Which of the configured endpoints is this instance, as the data said
    * before anything is dialled and fixed from then on (§5.5). */
-  #self: Endpoint | undefined;
+  readonly #self: Endpoint;
   /** The authenticated endpoint-to-id mapping (DR-0001 §2.1), in both
    * directions: a handshake writes it, `to_instance` reads it to find the link
    * to dial down, and a disconnection leaves it standing so a peer that is out
@@ -293,6 +290,12 @@ export class Mesh {
   readonly relay: Relay;
 
   constructor(private readonly deps: MeshDeps) {
+    this.#self = deps.self;
+    // The one binding this instance did not have to learn: its own. That is
+    // what makes "an id already answering elsewhere" cover the case of a peer
+    // claiming to be us — which is what the instance at a moved instance's old
+    // URL looks like from the new one.
+    this.#bind(deps.self, deps.id);
     this.relay = new Relay({
       publish: (topic, data, instance) => {
         this.#host?.publish(topic, data, instance);
@@ -365,14 +368,10 @@ export class Mesh {
     return true;
   }
 
-  /** Where peers reach this instance, as the probe settled it (§7.1).
-   *
-   * Asked only after `identify`: everything that reads it — the handshake's
-   * `aud`, the mesh's own routes, what `hello` reports — happens on an instance
-   * that has already started, and a start where the probe did not settle ends
-   * instead. */
+  /** Where peers reach this instance: the row of the mesh carrying its own id
+   * (§7.1). Everything that reads it — the handshake's `aud`, the mesh's own
+   * routes, what `hello` reports — is the one address the data states. */
   get self(): Endpoint {
-    if (this.#self === undefined) throw new Error("this mesh has not identified itself yet");
     return this.#self;
   }
 
@@ -608,24 +607,6 @@ export class Mesh {
     else conn.send(frame);
   }
 
-  /** Settle which configured endpoint is this instance, before anything is
-   * dialled (§7.1).
-   *
-   * Run once the listener is up, because the probe this instance sends itself
-   * has to arrive somewhere. A list that reaches this instance no times or
-   * more than once ends the start; a peer that is merely asleep is recorded
-   * and dialled later. */
-  async identify(): Promise<PeerReport> {
-    const report = await this.#probe.identify(this.deps.peers);
-    this.#self = report.self;
-    // The table opens with the one binding this instance did not have to learn:
-    // its own. That is what makes "an id already answering elsewhere" cover the
-    // case of a peer claiming to be us — which is what the instance at a moved
-    // instance's old URL looks like from the new one.
-    this.#bind(report.self, this.deps.id);
-    return report;
-  }
-
   /** Start dialling. Each peer is attempted independently, and a peer that is
    * not there is retried rather than waited for. */
   connect(): void {
@@ -801,45 +782,21 @@ export class Mesh {
     return this.#pending.has(conn);
   }
 
-  // --- the HTTP surface: the key of §6 and the probe of self-identification ---
+  // --- the HTTP surface: the key of §6 ---
 
-  /** Answer the two requests that are served before anything is proven, or
-   * nothing when the request is not one of them. */
+  /** Answer the one request that is served before anything is proven, or
+   * nothing when the request is not it. */
   async route(request: Request): Promise<Response | undefined> {
     const pathname = new URL(request.url).pathname;
-    // The probe is matched by the end of the path, because it is what settles
-    // which endpoint this instance is: while one is arriving there is no
-    // endpoint to hang it under.
-    if (isProbePath(pathname)) return await this.#answerProbe(request);
     // The key is below this instance's own endpoint and nowhere else, which is
     // what keeps two instances on one origin from answering for each other's
     // keys (mesh-peer-auth §6.3); the person's entry is matched by the end of
-    // the path instead (DR-0001 §2.7). The probe has settled that endpoint by
-    // the time any key is asked for: a request arriving before then belongs to
-    // no handshake, since nothing has been dialled yet.
-    if (this.#self === undefined) return undefined;
+    // the path instead (DR-0001 §2.7).
     const kid = kidOfPath(pathname, this.#self);
     if (kid !== undefined) return await this.#serveKey(kid, request);
     return undefined;
   }
 
-  async #answerProbe(request: Request): Promise<Response> {
-    let body: unknown;
-    try {
-      body = await request.json();
-    } catch {
-      return new Response("a probe is a JSON object", { status: 400 });
-    }
-    const probe = body as Partial<ProbeBody>;
-    // An unknown generation is ignored rather than refused: the comparison is
-    // the sender's, so a receiver that cannot read the probe costs the sender
-    // nothing it could not already have (§5.1).
-    if (probe.ver === MESH_VER && typeof probe.token === "string") {
-      this.#probe.accept(probe.token);
-    }
-    return Response.json({});
-  }
-
   async #serveKey(kid: string, request: Request): Promise<Response> {
     if (!this.#allowKeyRequest()) {
       return new Response("too many key requests", { status: 429 });

package/src/mesh/wire.ts

@@ -9,15 +9,9 @@ import type { MeshJwk } from "./keys.ts";
  * sharing one origin apart: the key of `https://h/a/` is only ever fetched from
  * below `/a/`, so `https://h/b/` cannot answer for it and a proof made with b's
  * key cannot pass as a's (mesh-peer-auth §6.3). The separation is the shape of
- * the URLs rather than a rule written somewhere.
- *
- * The probe is the exception, and has to be: it is what tells an instance which
- * endpoint it is, so while one is arriving there is nothing yet to hang it
- * under. */
+ * the URLs rather than a rule written somewhere. */
 const WS_ROUTE = "ws";
 const JWK_ROUTE = "mesh/jwk/";
-const PROBE_ROUTE = "mesh/probe";
-const PROBE_PATH = `/${PROBE_ROUTE}`;
 
 /** Where a peer's mesh link is dialled.
  *
@@ -36,10 +30,6 @@ export function jwkEndpoint(endpoint: Endpoint, kid: string): string {
   return `${endpoint}${JWK_ROUTE}${encodeURIComponent(kid)}`;
 }
 
-export function probeEndpoint(endpoint: Endpoint): string {
-  return `${endpoint}${PROBE_ROUTE}`;
-}
-
 /** The `kid` a request names, or nothing when the path is not a key request. */
 export function kidOfPath(pathname: string, self: Endpoint): string | undefined {
   const prefix = `${new URL(self).pathname}${JWK_ROUTE}`;
@@ -48,18 +38,6 @@ export function kidOfPath(pathname: string, self: Endpoint): string | undefined
   return kid === "" ? undefined : kid;
 }
 
-/** Whether this request is a probe.
- *
- * Matched by the end of the path and not below an endpoint, because a probe is
- * what settles which endpoint this instance is: at the moment one arrives there
- * is no endpoint to hang it under, and the prefix it came in on is whatever the
- * sender's list or a proxy in front of it says. Nothing is decided here anyway
- * — the receiver only echoes acceptance, and the comparison belongs to whoever
- * minted the token (§5.1). */
-export function isProbePath(pathname: string): boolean {
-  return pathname.endsWith(PROBE_PATH);
-}
-
 /** The subprotocol a dialling instance offers.
  *
  * A peer is let through the handshake on this marker alone and proves who it is
@@ -97,9 +75,3 @@ export interface JwkRequest {
 export interface JwkResponse {
   readonly jwk: MeshJwk;
 }
-
-/** What a self-identification probe carries (mesh-self-identification §5.1). */
-export interface ProbeBody {
-  readonly ver: number;
-  readonly token: string;
-}

package/src/mesh/probe.ts

@@ -1,105 +0,0 @@
-import type { Endpoint } from "@ccmsg/protocol";
-import { MESH_VER, randomId } from "./keys.ts";
-import { probeEndpoint, type ProbeBody } from "./wire.ts";
-
-/** How long a probe may take to come back.
- *
- * An endpoint that does not answer is either asleep or misconfigured, and
- * waiting longer tells the two apart no better. It bounds startup rather than
- * deciding correctness: only the probe that lands back here decides anything. */
-export const PROBE_TIMEOUT_MS = 3_000;
-
-/** The configured endpoints do not say which instance this is.
- *
- * Its own class so startup can refuse the same way a broken config does (§8.3,
- * DV-Q9): a list that names this instance zero times, or twice, is a list that
- * cannot be acted on. */
-export class SelfEndpointError extends Error {
-  constructor(msg: string) {
-    super(msg);
-    this.name = "SelfEndpointError";
-  }
-}
-
-/** What one round of probes settled. */
-export interface PeerReport {
-  /** The one configured endpoint that turned out to be this instance. */
-  readonly self: Endpoint;
-  /** The endpoints that did not answer. Recorded and not refused: a peer that
-   * is asleep is the normal state of this mesh (§7.1, DV-Q11). */
-  readonly unreachable: readonly Endpoint[];
-}
-
-/** The probes in flight, and the endpoint each was sent to.
- *
- * This is where an instance learns which of the configured endpoints it is
- * (mesh-self-identification §5). A `token` is minted per endpoint and sent
- * there; the one that arrives back at this process was sent to this process,
- * and the endpoint it was addressed to is therefore this instance's own.
- *
- * Every endpoint is probed, this instance's own included: the probe to
- * ourselves is the one that always lands, which is what makes a peer echoing
- * a stolen token show up as two matches rather than as a wrong answer (§4.2).
- *
- * The table is destroyed when the run finishes: what the exercise leaves behind
- * is the settled endpoint and nothing else (§7.3). */
-export class PeerProbe {
-  #sent = new Map<string, Endpoint>();
-  readonly #matched = new Set<Endpoint>();
-
-  /** A probe arrived here. Answering is unconditional and holds no state: the
-   * comparison is the sender's, and this instance is the sender for exactly one
-   * of the probes it is currently answering (§5.1). */
-  accept(token: string): void {
-    const sentTo = this.#sent.get(token);
-    if (sentTo !== undefined) this.#matched.add(sentTo);
-  }
-
-  /** Probe every configured endpoint and settle which one is this instance.
-   *
-   * An endpoint that did not answer is left out of the count rather than
-   * refused, so a mesh whose other host is asleep still starts (DV-Q11): the
-   * count only ever decides on endpoints that answered, and the probe to
-   * ourselves always does. */
-  async identify(peers: readonly Endpoint[]): Promise<PeerReport> {
-    const targets = [...new Set(peers)];
-    this.#sent = new Map(targets.map((target) => [randomId(), target]));
-    const unreachable: Endpoint[] = [];
-    await Promise.all(
-      [...this.#sent].map(async ([token, target]) => {
-        if (!(await this.#probe(target, token))) unreachable.push(target);
-      }),
-    );
-    const matched = [...this.#matched];
-    this.#sent = new Map();
-    this.#matched.clear();
-    if (matched.length !== 1) {
-      throw new SelfEndpointError(
-        matched.length === 0
-          ? `none of the configured endpoints reached this instance: ${targets.join(", ")}`
-          : `several configured endpoints reach this instance: ${matched.join(", ")}`,
-      );
-    }
-    return { self: matched[0] as Endpoint, unreachable };
-  }
-
-  /** Whether the endpoint answered. What it answered does not matter: the
-   * comparison happens where the probe lands, not in its reply. */
-  async #probe(target: Endpoint, token: string): Promise<boolean> {
-    const body: ProbeBody = { ver: MESH_VER, token };
-    try {
-      const response = await fetch(probeEndpoint(target), {
-        method: "POST",
-        // Closed after the one round trip it is: a probe is sent once at
-        // startup, and a pooled connection kept open for it would outlive the
-        // exercise and hold the listener at the far end.
-        headers: { "content-type": "application/json", connection: "close" },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
-      });
-      return response.ok;
-    } catch {
-      return false;
-    }
-  }
-}