@ccmsg/cli 0.1.0

package/src/mesh/probe.ts

@@ -0,0 +1,100 @@
+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 this instance sends itself decides
+ * anything. */
+export const PROBE_TIMEOUT_MS = 3_000;
+
+/** The configured endpoints do not describe this instance.
+ *
+ * Its own class so startup can refuse the same way a broken config does (§8.3,
+ * DV-Q9): `self` is a setting, and one that does not reach this process is a
+ * setting that is wrong. */
+export class SelfEndpointError extends Error {
+  constructor(msg: string) {
+    super(msg);
+    this.name = "SelfEndpointError";
+  }
+}
+
+/** What one round of probes found. */
+export interface PeerReport {
+  /** The configured endpoints that turned out to be this instance — `self`,
+   * and any alias of it a peer list happens to name. They are not dialled: a
+   * link to ourselves is not a link. */
+  readonly ours: readonly 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.
+ *
+ * Since `self` is configured (DR-0001 §2.7), this no longer settles an identity:
+ * it checks the setting. The probe to `self` has to come back here, which is
+ * what catches a `self` that names somebody else, and the rest of the list is
+ * probed to record what can be reached before anything is dialled.
+ *
+ * The table is destroyed when the run finishes: what the exercise leaves behind
+ * is the report 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);
+  }
+
+  /** Ask `self` and every peer who answers there, and refuse to start if the
+   * endpoint this instance calls its own is somebody else's. */
+  async verify(self: Endpoint, peers: readonly Endpoint[]): Promise<PeerReport> {
+    const targets = [...new Set([self, ...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 ours = [...this.#matched];
+    this.#sent = new Map();
+    this.#matched.clear();
+    if (!ours.includes(self)) {
+      throw new SelfEndpointError(
+        unreachable.includes(self)
+          ? `self is ${self}, which did not answer this instance's probe`
+          : `self is ${self}, which answers as another instance`,
+      );
+    }
+    return { ours, 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;
+    }
+  }
+}

package/src/mesh/relay.ts

@@ -0,0 +1,147 @@
+import {
+  type InstanceId,
+  LAST_LIVE_RETENTION_MS,
+  type PeerInfo,
+  PLAIN_TOPICS,
+  type Sid,
+  TOPIC_ATTRIBUTES,
+  type Timestamp,
+} from "@ccmsg/protocol";
+import type { TopicValue } from "../topics/index.ts";
+
+/** The topics a subscriber sees the whole cluster on.
+ *
+ * The per-instance whole is what makes a cluster view possible at all (§6.2):
+ * a frame replaces its own instance's entries and leaves every other
+ * instance's alone, so several instances can state the same topic name without
+ * colliding. A topic of any other granularity has no such rule and is not
+ * relayed — an `element` topic like `inbox` names one instance's topic while
+ * its value belongs to a session, and a frame of it carries no way to say
+ * whose it is. */
+export const CLUSTER_TOPICS: readonly string[] = PLAIN_TOPICS.filter(
+  (topic) => TOPIC_ATTRIBUTES[topic].granularity === "per_instance_whole",
+);
+
+export function isClusterTopic(topic: string): boolean {
+  return CLUSTER_TOPICS.includes(topic);
+}
+
+export interface RelayDeps {
+  /** Hand a relayed frame to this instance's own subscribers, under the
+   * instance that produced it (§7.4). */
+  readonly publish: (topic: string, data: unknown, instance: InstanceId) => void;
+  /** The clock, so a test can move the retention window without waiting it
+   * out. */
+  readonly now?: () => Timestamp;
+}
+
+/** What the peers said, held on this instance so that losing a peer does not
+ * empty the cluster view (§7.5).
+ *
+ * Two things live here and nowhere else: the last whole value each instance
+ * stated per topic, and whether that instance can be reached right now. The
+ * suppression table of the topic mechanism is not the place for either — it
+ * is forgotten the moment a topic has no subscriber, while what a peer last
+ * said has to outlive both the subscription and the link.
+ *
+ * The retention window is read rather than swept: nothing here runs on a
+ * timer (M3), so a value past the window is dropped by the next read that
+ * would have returned it. */
+export class Relay {
+  /** Per instance, the last whole value it stated per topic. */
+  readonly #held = new Map<InstanceId, Map<string, unknown>>();
+  /** The mark of §7.5: when this instance stopped being reachable. Absent
+   * while it is reachable. */
+  readonly #lostAt = new Map<InstanceId, Timestamp>();
+
+  constructor(private readonly deps: RelayDeps) {}
+
+  #now(): Timestamp {
+    return (this.deps.now ?? Date.now)();
+  }
+
+  /** A frame a peer pushed on a topic this instance relays.
+   *
+   * `instance` is the one that produced the value, which is not always the
+   * peer it arrived from: a mesh of three relays transitively, and the frame
+   * names its origin the whole way. Held under that origin, and passed on
+   * unchanged — recomputing it would put the same judgement in two places
+   * (§7.4). */
+  accept(instance: InstanceId, topic: string, data: unknown): void {
+    if (!isClusterTopic(topic)) return;
+    this.#sweep();
+    const held = this.#held.get(instance) ?? new Map<string, unknown>();
+    this.#held.set(instance, held);
+    held.set(topic, data);
+    this.deps.publish(topic, data, instance);
+  }
+
+  /** The link to this instance is gone. What it said is kept and marked,
+   * because dropping it would empty the view until the instance comes back
+   * and restates everything (§7.5). */
+  lost(instance: InstanceId): void {
+    if (!this.#lostAt.has(instance)) this.#lostAt.set(instance, this.#now());
+    this.#sweep();
+  }
+
+  /** The link is back. The mark goes, and what it said stands until the
+   * instance replaces it with the snapshot its subscriptions bring. */
+  restored(instance: InstanceId): void {
+    this.#lostAt.delete(instance);
+  }
+
+  /** Whether this instance is currently held as unreachable. */
+  unreachable(instance: InstanceId): boolean {
+    this.#sweep();
+    return this.#lostAt.has(instance);
+  }
+
+  /** The current value of a relayed topic, one entry per instance that has
+   * stated one. What a fresh local subscriber is handed beside this
+   * instance's own snapshot. */
+  snapshot(topic: string): readonly TopicValue[] {
+    this.#sweep();
+    const values: TopicValue[] = [];
+    for (const [instance, held] of this.#held) {
+      const data = held.get(topic);
+      if (data !== undefined) values.push({ instance, data });
+    }
+    return values;
+  }
+
+  /** Which instance a session belongs to, read from the `peers` values the
+   * cluster stated (§7.3).
+   *
+   * The row names its own instance rather than the one that relayed it, so a
+   * value that travelled through a third instance still points at the session's
+   * own. */
+  owner(sid: Sid): InstanceId | undefined {
+    this.#sweep();
+    for (const held of this.#held.values()) {
+      const value = held.get("peers") as { peers?: PeerInfo[] } | undefined;
+      const row = value?.peers?.find((peer) => peer.sid === sid);
+      if (row !== undefined) return row.instance;
+    }
+    return undefined;
+  }
+
+  /** Drop what an instance said once it has been gone for the retention
+   * window. The window is the contract's, shared with `last_live` and the
+   * inbox: past it, everything the value would point at is gone too
+   * (§7.5, DV-Q12). */
+  #sweep(): void {
+    const now = this.#now();
+    for (const [instance, since] of this.#lostAt) {
+      if (now - since <= LAST_LIVE_RETENTION_MS) continue;
+      this.#lostAt.delete(instance);
+      this.#held.delete(instance);
+    }
+  }
+
+  /** What is held right now, so a test can state that a disconnected
+   * instance's value is still there and that a swept one is not. */
+  get retained(): { instances: number; marked: number } {
+    this.#sweep();
+    return { instances: this.#held.size, marked: this.#lostAt.size };
+  }
+}

package/src/mesh/wire.ts

@@ -0,0 +1,96 @@
+import type { Endpoint } from "@ccmsg/protocol";
+import type { MeshJwk } from "./keys.ts";
+
+/** The paths an instance's endpoint URL stands in front of.
+ *
+ * An `Endpoint` is compared whole, path included (contract, `Endpoint`), so
+ * everything an instance serves hangs below it. That is also what keeps two
+ * instances sharing one origin apart: the key of `wss://h/a` is only ever
+ * fetched from below `/a`, so `wss://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. */
+const WS_PATH = "/ws";
+const JWK_PATH = "/mesh/jwk/";
+const PROBE_PATH = "/mesh/probe";
+
+/** Where a peer's mesh link is dialled. */
+export function wsEndpoint(endpoint: Endpoint): string {
+  return `${endpoint}${WS_PATH}`;
+}
+
+/** Where one connection's key is fetched, and the challenge for it left.
+ *
+ * `http` rather than `ws` because this is the second connection of §6, which
+ * carries one request and closes: the protocol asks that it be a connection of
+ * its own outside the one being authenticated, not that it be a WebSocket. */
+export function jwkEndpoint(endpoint: Endpoint, kid: string): string {
+  return `${httpBase(endpoint)}${JWK_PATH}${encodeURIComponent(kid)}`;
+}
+
+export function probeEndpoint(endpoint: Endpoint): string {
+  return `${httpBase(endpoint)}${PROBE_PATH}`;
+}
+
+/** 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.replace(/\/$/, "")}${JWK_PATH}`;
+  if (!pathname.startsWith(prefix)) return undefined;
+  const kid = decodeURIComponent(pathname.slice(prefix.length));
+  return kid === "" ? undefined : kid;
+}
+
+export function isProbePath(pathname: string, self: Endpoint): boolean {
+  return pathname === `${new URL(self).pathname.replace(/\/$/, "")}${PROBE_PATH}`;
+}
+
+/** The same authority and path, reached over HTTP. A `ws` URL and the `http`
+ * one beside it are one server; the scheme differs and nothing else does. */
+function httpBase(endpoint: Endpoint): string {
+  const url = new URL(endpoint);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  return url.href.replace(/\/$/, "");
+}
+
+/** The subprotocol a dialling instance offers.
+ *
+ * A peer is let through the handshake on this marker alone and proves who it is
+ * afterwards, where a claim can actually be checked: an unproven mesh
+ * connection is anonymous and can reach only the ops that need no identity at
+ * all. What the person\'s entry offers instead is a token bound to a passkey
+ * (DR-0001), which is theirs and not an instance\'s to hold. */
+export const MESH_PROTOCOL = "ccmsg.mesh";
+
+/** A frame on the mesh link that is not an op.
+ *
+ * The contract's op vocabulary holds no mesh ops — an op crosses instances by
+ * carrying the envelope's mesh fields (contract, `Plane`) — so the handshake's
+ * own traffic is spelled apart from it, under a key no request has. */
+export type MeshFrame =
+  | { readonly mesh: "proof"; readonly jws: string }
+  | { readonly mesh: "ping" }
+  | { readonly mesh: "pong" };
+
+export function meshFrameOf(frame: unknown): MeshFrame | undefined {
+  if (typeof frame !== "object" || frame === null) return undefined;
+  const kind = (frame as Record<string, unknown>)["mesh"];
+  if (kind === "ping" || kind === "pong") return { mesh: kind };
+  if (kind !== "proof") return undefined;
+  const jws = (frame as Record<string, unknown>)["jws"];
+  return typeof jws === "string" ? { mesh: "proof", jws } : undefined;
+}
+
+/** What a key request carries: the challenge the proof must sign (§6). */
+export interface JwkRequest {
+  readonly ver: number;
+  readonly challenge: string;
+}
+
+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;
+}