@ccmsg/cli 0.1.0

package/src/transport/conn.ts

@@ -0,0 +1,129 @@
+import {
+  ANONYMOUS,
+  type ConnIdentity,
+  type Requester,
+  type SettledIdentity,
+} from "../dispatch/index.ts";
+
+/** One accepted connection, as the layers above transport see it.
+ *
+ * UDS and WS produce this same type, so nothing above transport can tell them
+ * apart (daemon-v2 §3.1). Everything that differs between the two — how a line
+ * reaches the peer, how a blocked write is retried — is settled behind `send`. */
+export interface Conn extends Requester {
+  /** Distinguishes connections within one process run. It is not an identity:
+   * a connection is anonymous until `hello` settles one. */
+  readonly id: number;
+  /** Anonymous until `hello` binds a role and, for a session, its sid. */
+  readonly identity: ConnIdentity;
+  /** Bind the identity `hello` established. Called once, by the transport
+   * driver, at the moment the `hello` reply goes out. */
+  settle(identity: SettledIdentity): void;
+  /** Queue one frame as a line. Ordering is preserved; delivery is
+   * best-effort, as it is for any socket that may go away mid-write. */
+  send(frame: object): void;
+  /** Queue one frame to go out once the reply to the request in flight has.
+   * `flushDeferred` is what releases it, and only the driver calls that. */
+  deferSend(frame: object): void;
+  /** Send everything `deferSend` queued, in the order it was queued. */
+  flushDeferred(): void;
+  /** Close the underlying socket. Idempotent.
+   *
+   * A code says why, for the one closure a peer must not read as a fault: the
+   * loser of a glare is closed deliberately and is normal at the other end
+   * (mesh-peer-auth §8.1). Transports that carry no such code ignore it. */
+  close(code?: number, reason?: string): void;
+  /** Run when the connection is gone. Anything held per connection — the
+   * subscriptions of §6.3 once they exist — is released here, because a closed
+   * connection is the only end a subscription has. */
+  onClose(listener: () => void): void;
+}
+
+/** What a transport implementation supplies for one accepted socket: the two
+ * operations that differ between UDS and WS. */
+export interface ConnSocket {
+  send(line: string): void;
+  close(code?: number, reason?: string): void;
+}
+
+/** The `Conn` half that is the same for every transport. */
+export class BaseConn implements Conn {
+  #identity: ConnIdentity = ANONYMOUS;
+  #closed = false;
+  readonly #listeners: (() => void)[] = [];
+  readonly #deferred: object[] = [];
+
+  constructor(
+    readonly id: number,
+    private readonly socket: ConnSocket,
+  ) {}
+
+  get identity(): ConnIdentity {
+    return this.#identity;
+  }
+
+  settle(identity: SettledIdentity): void {
+    this.#identity = identity;
+  }
+
+  send(frame: object): void {
+    if (this.#closed) return;
+    this.socket.send(`${JSON.stringify(frame)}\n`);
+  }
+
+  deferSend(frame: object): void {
+    this.#deferred.push(frame);
+  }
+
+  flushDeferred(): void {
+    for (const frame of this.#deferred.splice(0)) this.send(frame);
+  }
+
+  close(code?: number, reason?: string): void {
+    this.socket.close(code, reason);
+  }
+
+  onClose(listener: () => void): void {
+    if (this.#closed) {
+      listener();
+      return;
+    }
+    this.#listeners.push(listener);
+  }
+
+  /** Called by the transport when the socket is gone, once. */
+  closed(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const listener of this.#listeners.splice(0)) listener();
+  }
+}
+
+/** The connections one instance currently holds.
+ *
+ * It exists so shutdown (§8.5 step 3) can reach every connection before any
+ * listener is closed, and so tests can see that a closed connection is gone. */
+export class ConnRegistry {
+  readonly #conns = new Set<Conn>();
+  #nextId = 1;
+
+  get size(): number {
+    return this.#conns.size;
+  }
+
+  [Symbol.iterator](): Iterator<Conn> {
+    return this.#conns[Symbol.iterator]();
+  }
+
+  nextId(): number {
+    return this.#nextId++;
+  }
+
+  add(conn: Conn): void {
+    this.#conns.add(conn);
+  }
+
+  remove(conn: Conn): void {
+    this.#conns.delete(conn);
+  }
+}

package/src/transport/dial.ts

@@ -0,0 +1,65 @@
+import { BaseConn, type Conn, type ConnRegistry } from "./conn.ts";
+
+export interface DialOptions {
+  readonly url: string;
+  readonly protocols?: readonly string[];
+  readonly conns: ConnRegistry;
+  /** One frame the far end wrote. A dialled connection is one this instance
+   * speaks on rather than one it serves, so what arrives is answered by whoever
+   * dialled rather than by dispatch. */
+  readonly onFrame: (frame: unknown, conn: Conn) => void;
+  /** Why the connection ended, as the far end stated it. The code is what
+   * separates a closure that is a fault from one that is the other end's
+   * normal course (mesh-peer-auth §8.1). */
+  readonly onClose?: (code: number) => void;
+}
+
+/** A connection this instance opened, as the same `Conn` an accepted one is.
+ *
+ * daemon-v2 §3.1 has one connection type above transport, and a mesh link is a
+ * connection of that layer whichever end dialled it: the two differ in who
+ * opened the socket and in nothing the layers above can see. */
+export async function dialWs(options: DialOptions): Promise<Conn> {
+  const ws =
+    options.protocols === undefined
+      ? new WebSocket(options.url)
+      : new WebSocket(options.url, [...options.protocols]);
+  const conn = new BaseConn(options.conns.nextId(), {
+    send: (line) => {
+      ws.send(line);
+    },
+    close: (code, reason) => {
+      if (code === undefined) ws.close();
+      else ws.close(code, reason);
+    },
+  });
+  await new Promise<void>((resolve, reject) => {
+    ws.addEventListener("open", () => {
+      resolve();
+    });
+    ws.addEventListener("error", () => {
+      reject(new Error(`${options.url} did not accept a connection`));
+    });
+  });
+  options.conns.add(conn);
+  ws.addEventListener("message", (event: MessageEvent) => {
+    // One message is one frame here, as it is on the accepting side, and the
+    // far end writes whole lines.
+    for (const line of String(event.data).split("\n")) {
+      if (line.trim() === "") continue;
+      let frame: unknown;
+      try {
+        frame = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      options.onFrame(frame, conn);
+    }
+  });
+  ws.addEventListener("close", (event: CloseEvent) => {
+    options.conns.remove(conn);
+    conn.closed();
+    options.onClose?.(event.code);
+  });
+  return conn;
+}

package/src/transport/driver.ts

@@ -0,0 +1,102 @@
+import { MAX_FRAME_BYTES, type OpName, type Role, type Sid } from "@ccmsg/protocol";
+import { type DispatchResult, failure, type Requester } from "../dispatch/index.ts";
+import type { Conn } from "./conn.ts";
+
+/** What transport calls once a line is a frame. In the instance this is
+ * `dispatch` bound to its deps; in tests it is whatever the test needs. */
+export interface FrameHandler {
+  (frame: unknown, conn: Requester): Promise<DispatchResult>;
+}
+
+/** The op whose reply settles the connection's identity. Transport knows this
+ * one op name because binding the identity is its job (daemon-v2 §3.1); every
+ * other op is opaque to it. */
+const HELLO = "hello" satisfies OpName;
+
+/** Drive one connection: a line in, a frame answered on the same connection.
+ *
+ * The same driver runs for UDS and WS. It holds no framing (that is
+ * `LineReader`) and no authorization (that is dispatch) — only the two things
+ * that belong to a connection: turning text into a frame, and binding the
+ * identity that `hello` establishes. */
+export function createDriver(conn: Conn, handle: FrameHandler) {
+  return {
+    line(text: string): void {
+      let frame: unknown;
+      try {
+        frame = JSON.parse(text);
+      } catch {
+        conn.send(
+          failure(undefined, "bad_request", "a request must be one JSON object per line").response,
+        );
+        return;
+      }
+      void handle(frame, conn).then(
+        (result) => {
+          if (result.kind === "none") return;
+          settleIfHello(conn, frame, result);
+          conn.send(responseOf(result));
+          // Whatever the implementation queued for after its reply — the
+          // snapshot of a fresh subscription (§6.1) — goes out here.
+          conn.flushDeferred();
+        },
+        (cause: unknown) => {
+          // The handler settles every refusal of its own into an answer, so a
+          // rejection reaching here is this instance failing rather than the
+          // caller asking for something wrong.
+          conn.send(
+            failure(
+              requestIdOf(frame),
+              "internal_error",
+              `the request could not be answered: ${String(cause)}`,
+            ).response,
+          );
+        },
+      );
+    },
+
+    overflow(bytes: number): void {
+      conn.send(
+        failure(
+          undefined,
+          "bad_request",
+          `a request line may not exceed ${MAX_FRAME_BYTES} bytes (got at least ${bytes})`,
+        ).response,
+      );
+    },
+  };
+}
+
+/** Bind role and sid at the moment the `hello` reply goes out.
+ *
+ * The frame is safe to read because dispatch only answers `reply` after the
+ * op's own schema accepted it, so `role` is a role and `sid` — required of a
+ * session and absent otherwise — is a sid. */
+function settleIfHello(conn: Conn, frame: unknown, result: DispatchResult): void {
+  if (result.kind !== "reply") return;
+  const fields = frame as Record<string, unknown>;
+  if (fields["op"] !== HELLO) return;
+  const sid = fields["sid"];
+  conn.settle({
+    state: "settled",
+    role: fields["role"] as Role,
+    ...(typeof sid === "string" ? { sid: sid as Sid } : {}),
+  });
+}
+
+function responseOf(result: Exclude<DispatchResult, { kind: "none" }>): object {
+  if (result.kind === "forward") {
+    // Mesh is what carries a forwarded op to its instance, and there is none
+    // yet: the destination exists but nothing can reach it, which is the code
+    // the contract gives that outcome.
+    const requestId = requestIdOf(result.frame);
+    return failure(requestId, "instance_unreachable", `${result.to} cannot be reached`).response;
+  }
+  return result.response;
+}
+
+function requestIdOf(frame: unknown): string | undefined {
+  if (typeof frame !== "object" || frame === null) return undefined;
+  const id = (frame as Record<string, unknown>)["request_id"];
+  return typeof id === "string" && id.length > 0 ? id : undefined;
+}

package/src/transport/entry.ts

@@ -0,0 +1,39 @@
+/** Who is allowed to reach this instance at all (daemon-v2 §3.1, "入口の許可").
+ *
+ * Two questions, because they are asked of different things. `allowRequest`
+ * runs for every HTTP request the listener takes, the routed ones included, and
+ * answers "may this address, presenting this `Origin`, speak to us at all".
+ * `allowUpgrade` runs only for the WebSocket handshake and answers what the
+ * connection is let in as, which is what decides the subprotocol the reply
+ * selects.
+ *
+ * The checks are config-driven and the instance supplies them; transport only
+ * asks, so no policy is written into the listener. */
+export interface EntryPolicy {
+  /** Decide one incoming request before anything is done with it.
+   *
+   * `source` is the peer address the server observed. It is passed rather than
+   * read off the request because a forwarding header is written by whoever is
+   * in front of us, and this allowlist is about who actually connected. */
+  allowRequest?(request: Request, source: string | undefined): boolean;
+  /** Decide the WebSocket handshake itself. */
+  allowUpgrade?(request: Request): UpgradeDecision;
+}
+
+/** The handshake's answer. `protocol` is the subprotocol to select, which the
+ * handshake must echo when the client offered any: a browser fails a connection
+ * whose reply names none of what it asked for. */
+export type UpgradeDecision =
+  | {
+      readonly ok: true;
+      readonly protocol?: string;
+      /** Let in as a peer. Such a connection has shown nothing yet: what it is
+       * gets decided by the mesh handshake, so until that finishes it may do
+       * only the one thing that can decide it. */
+      readonly mesh?: boolean;
+    }
+  | { readonly ok: false; readonly reason: string };
+
+/** Accepts everything. A listener given no policy is open to whatever can reach
+ * the address it is bound to. */
+export const OPEN: EntryPolicy = {};

package/src/transport/framing.ts

@@ -0,0 +1,131 @@
+/** Newline-delimited JSON, in one place for both transports (daemon-v2 §3.1).
+ *
+ * The limit and the backpressure handling live here rather than in the UDS and
+ * WS listeners, so the two cannot drift into two framings. */
+
+import { MAX_FRAME_BYTES } from "@ccmsg/protocol";
+
+const NEWLINE = 0x0a;
+
+export interface LineReaderSink {
+  /** One complete, non-empty line, decoded as UTF-8. */
+  line(text: string): void;
+  /** A line that reached `MAX_FRAME_BYTES` before its newline. The bytes are
+   * dropped and reading resumes at the next newline, so one oversized line
+   * costs that line and not the connection. */
+  overflow(bytes: number): void;
+}
+
+/** Accumulates bytes and hands out whole lines.
+ *
+ * Bytes are split before they are decoded, so a multi-byte character straddling
+ * two chunks is decoded once, whole, at the line boundary. */
+export class LineReader {
+  #buffer = new Uint8Array(0);
+  /** Set after an overflow: bytes are discarded up to the next newline. */
+  #discarding = false;
+  #discarded = 0;
+  readonly #decoder = new TextDecoder();
+
+  constructor(private readonly sink: LineReaderSink) {}
+
+  push(chunk: Uint8Array): void {
+    let rest = chunk;
+    while (rest.length > 0) {
+      if (this.#discarding) {
+        const at = rest.indexOf(NEWLINE);
+        if (at < 0) {
+          this.#discarded += rest.length;
+          return;
+        }
+        this.#discarding = false;
+        this.sink.overflow(this.#discarded + at);
+        this.#discarded = 0;
+        rest = rest.subarray(at + 1);
+        continue;
+      }
+      const at = rest.indexOf(NEWLINE);
+      if (at < 0) {
+        this.#append(rest);
+        if (this.#buffer.length > MAX_FRAME_BYTES) this.#startDiscarding();
+        return;
+      }
+      this.#append(rest.subarray(0, at));
+      rest = rest.subarray(at + 1);
+      if (this.#buffer.length > MAX_FRAME_BYTES) {
+        this.sink.overflow(this.#buffer.length);
+        this.#buffer = new Uint8Array(0);
+        continue;
+      }
+      const text = this.#decoder.decode(this.#buffer);
+      this.#buffer = new Uint8Array(0);
+      if (text.trim() !== "") this.sink.line(text);
+    }
+  }
+
+  #startDiscarding(): void {
+    this.#discarding = true;
+    this.#discarded = this.#buffer.length;
+    this.#buffer = new Uint8Array(0);
+  }
+
+  #append(bytes: Uint8Array): void {
+    if (bytes.length === 0) return;
+    const grown = new Uint8Array(this.#buffer.length + bytes.length);
+    grown.set(this.#buffer);
+    grown.set(bytes, this.#buffer.length);
+    this.#buffer = grown;
+  }
+}
+
+/** How one transport hands a line to its socket.
+ *
+ * `write` returns what the socket would not take: `undefined` when the whole
+ * chunk went. This is the one shape both backpressure behaviours fit — a UDS
+ * `write` returns a short count and leaves the tail to us, a WS `send` either
+ * buffers the whole message itself or drops it whole. */
+export interface ChunkSink<T> {
+  encode(line: string): T;
+  write(chunk: T): T | undefined;
+  /** Nudge the socket to push what it accepted, where that is a separate step. */
+  flush?(): void;
+}
+
+/** Lines waiting for a socket that is not taking them yet.
+ *
+ * Every line goes through the queue, including the ones that are written
+ * immediately, so a line queued behind a blocked one can never overtake it. */
+export class WriteQueue<T> {
+  readonly #pending: T[] = [];
+
+  constructor(private readonly sink: ChunkSink<T>) {}
+
+  push(line: string): void {
+    this.#pending.push(this.sink.encode(line));
+    this.drain();
+  }
+
+  /** Write what the socket will take. Called on every push and again whenever
+   * the socket reports it has room. */
+  drain(): void {
+    while (this.#pending.length > 0) {
+      const chunk = this.#pending[0] as T;
+      let remainder: T | undefined;
+      try {
+        remainder = this.sink.write(chunk);
+      } catch {
+        // The socket is going away mid-write; delivery is best-effort.
+        this.#pending.length = 0;
+        return;
+      }
+      if (remainder !== undefined) {
+        // Still blocked: keep the unsent part at the front and wait to be
+        // drained again rather than spinning on a full socket buffer.
+        this.#pending[0] = remainder;
+        break;
+      }
+      this.#pending.shift();
+    }
+    this.sink.flush?.();
+  }
+}

package/src/transport/index.ts

@@ -0,0 +1,8 @@
+export * from "./conn.ts";
+export * from "./dial.ts";
+export * from "./driver.ts";
+export * from "./entry.ts";
+export * from "./framing.ts";
+export * from "./listener.ts";
+export * from "./uds.ts";
+export * from "./ws.ts";

package/src/transport/listener.ts

@@ -0,0 +1,39 @@
+/** One bound address, and the way to give it up.
+ *
+ * `kind` exists for the stop order of daemon-v2 §8.5: the UDS is released after
+ * everything else, because a client reads "the unix socket refuses" as the
+ * instance having finished leaving, and a successor may take the resources it
+ * sees freed before that. */
+export interface Listener {
+  readonly kind: "uds" | "ws";
+  /** The socket path, or the bound `host:port` — resolved, so an ephemeral
+   * port is readable here. */
+  readonly address: string;
+  close(): Promise<void>;
+}
+
+/** The listeners one instance holds, closed in the order §8.5 requires. */
+export class Transport {
+  readonly #listeners: Listener[] = [];
+
+  add<T extends Listener>(listener: T): T {
+    this.#listeners.push(listener);
+    return listener;
+  }
+
+  get listeners(): readonly Listener[] {
+    return this.#listeners;
+  }
+
+  /** Release every address, the unix socket last. Callers do the steps that
+   * come before this one (§8.5 1-4: refuse new work, stop upstream watches,
+   * tell the connections, settle what is persisted). */
+  async close(): Promise<void> {
+    const ordered = [
+      ...this.#listeners.filter((l) => l.kind !== "uds"),
+      ...this.#listeners.filter((l) => l.kind === "uds"),
+    ];
+    this.#listeners.length = 0;
+    for (const listener of ordered) await listener.close();
+  }
+}

package/src/transport/uds.ts

@@ -0,0 +1,88 @@
+import { chmodSync } from "node:fs";
+import { BaseConn, type Conn, type ConnRegistry } from "./conn.ts";
+import { createDriver, type FrameHandler } from "./driver.ts";
+import { LineReader, WriteQueue } from "./framing.ts";
+import type { Listener } from "./listener.ts";
+
+interface UdsState {
+  conn: BaseConn;
+  reader: LineReader;
+  queue: WriteQueue<Uint8Array>;
+}
+
+export interface UdsOptions {
+  /** The socket path.
+   *
+   * §8.5 asks that closing leave the path alone, because a successor's socket
+   * may already stand there. Bun's listener unlinks it in `stop()` regardless
+   * (measured against Bun 1.3.13: the path is gone the moment `stop` returns),
+   * so this layer cannot honour that on its own — what it can do is not add a
+   * second removal of its own. */
+  readonly path: string;
+  readonly conns: ConnRegistry;
+  readonly handle: FrameHandler;
+  /** Runs for each accepted connection, before any frame is read. */
+  readonly onConn?: (conn: Conn) => void;
+}
+
+/** Accept sessions and the CLI on the instance's unix socket.
+ *
+ * `socket.write` hands the bytes to sendto(2) and returns a short count when
+ * the socket buffer is full, so the unsent tail is kept by the queue and
+ * written again on `drain` — the difference from WS that §3.1 puts in this
+ * layer. */
+export function listenUds(options: UdsOptions): Listener {
+  const server = Bun.listen<UdsState>({
+    unix: options.path,
+    socket: {
+      open(socket) {
+        const queue = new WriteQueue<Uint8Array>({
+          encode: (line) => new TextEncoder().encode(line),
+          write(chunk) {
+            const written = socket.write(chunk);
+            if (written < 0) return undefined; // closing: nothing more will go
+            return written === chunk.length ? undefined : chunk.subarray(written);
+          },
+          flush: () => {
+            socket.flush();
+          },
+        });
+        const conn = new BaseConn(options.conns.nextId(), {
+          send: (line) => {
+            queue.push(line);
+          },
+          close: () => {
+            socket.end();
+          },
+        });
+        const driver = createDriver(conn, options.handle);
+        socket.data = { conn, queue, reader: new LineReader(driver) };
+        options.conns.add(conn);
+        options.onConn?.(conn);
+      },
+      data(socket, chunk) {
+        socket.data.reader.push(chunk);
+      },
+      drain(socket) {
+        socket.data.queue.drain();
+      },
+      close(socket) {
+        const state = socket.data as UdsState | undefined;
+        if (state === undefined) return;
+        options.conns.remove(state.conn);
+        state.conn.closed();
+      },
+    },
+  });
+  // Only this user's sessions may speak to the instance; the socket's own mode
+  // is the whole of the entry check on this transport.
+  chmodSync(options.path, 0o600);
+
+  return {
+    kind: "uds",
+    address: options.path,
+    async close() {
+      server.stop(true);
+    },
+  };
+}