@liebstoeckel/present-relay 0.3.5

package/src/cli.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from "citty";
+import { S3Client } from "bun";
+import { createRelay, type RelayStorage } from "./relay-server";
+import { relayPublicBaseFromPod } from "./addressing";
+import { initTracing } from "./tracing";
+
+/** Object storage for session snapshots (ADR 0061), wired from S3_* env when present.
+ *  Absent → the relay runs without persistence (transient/CLI use). */
+function s3Storage(): RelayStorage | undefined {
+  const endpoint = process.env.S3_ENDPOINT;
+  const accessKeyId = process.env.S3_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.S3_SECRET_ACCESS_KEY;
+  if (!endpoint || !accessKeyId || !secretAccessKey) return undefined;
+  const client = new S3Client({
+    endpoint,
+    accessKeyId,
+    secretAccessKey,
+    bucket: process.env.S3_BUCKET ?? "decks",
+    region: process.env.S3_REGION ?? "us-east-1",
+  });
+  return {
+    async get(key) {
+      const f = client.file(key);
+      return (await f.exists()) ? new Uint8Array(await f.arrayBuffer()) : null;
+    },
+    async put(key, bytes) {
+      await client.write(key, bytes);
+    },
+  };
+}
+
+const hex = (bytes = 24): string => {
+  const a = new Uint8Array(bytes);
+  crypto.getRandomValues(a);
+  return Array.from(a, (b) => b.toString(16).padStart(2, "0")).join("");
+};
+
+export const relayCommand = defineCommand({
+  meta: {
+    name: "relay",
+    description: "run a public relay (host live sessions for remote audiences)",
+  },
+  args: {
+    port: {
+      type: "string",
+      description: "listen port (or PORT env); auto if omitted",
+      valueHint: "N",
+    },
+    tokens: {
+      type: "string",
+      description: "comma-separated account tokens (or PRESENT_RELAY_TOKENS); one is generated if omitted",
+    },
+    "public-url": {
+      type: "string",
+      description: "public https origin so links/WebSocket use wss:// (or PRESENT_RELAY_PUBLIC_URL)",
+      valueHint: "https://…",
+    },
+  },
+  run({ args }) {
+    initTracing("present-relay"); // gated by OTEL_EXPORTER_OTLP_ENDPOINT (ADR 0073 step 3b)
+    const port = Number(args.port ?? process.env.PORT ?? 0) || 0;
+    // Public base: an explicit override wins (CLI / single-pod env); otherwise a
+    // StatefulSet pod derives its OWN per-pod base from its ordinal + host template
+    // (ADR 0071 §3 / ticket 0016, POD_NAME via the downward API).
+    const publicBaseUrl =
+      args["public-url"] ??
+      process.env.PRESENT_RELAY_PUBLIC_URL ??
+      relayPublicBaseFromPod(process.env.POD_NAME, process.env.PRESENT_RELAY_HOST_TEMPLATE);
+    let tokens = (args.tokens ?? process.env.PRESENT_RELAY_TOKENS ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    let generated = false;
+    if (!tokens.length) {
+      tokens = [hex()];
+      generated = true;
+    }
+
+    const storage = s3Storage();
+    const relay = createRelay({ accountTokens: tokens, port, publicBaseUrl, storage });
+    const base = publicBaseUrl?.replace(/\/$/, "") ?? `http://localhost:${relay.port}`;
+
+    console.log(`\n▶  liebstoeckel relay listening on :${relay.port}`);
+    console.log(`   base url          ${base}`);
+    console.log(`   health            ${base}/healthz`);
+    if (generated) {
+      console.log(`\n   ⚠ no account tokens set, generated one for this run:`);
+      console.log(`       ${tokens[0]}`);
+      console.log(`   persist with PRESENT_RELAY_TOKENS=tok1,tok2 (or --tokens).`);
+    }
+    console.log(`\n   run a deck through it:`);
+    console.log(`       bunx liebstoeckel live <deck> --relay ${base} --relay-token <token>\n`);
+    if (!publicBaseUrl) {
+      console.log(`   note: serve behind TLS (wss://) for public use; set --public-url to the https origin.\n`);
+    }
+
+    // Await the snapshot flush before exiting so a rolling deploy / drain doesn't lose
+    // the last interval's live state (ADR 0071 §5 / ticket 0018). k8s gives us
+    // terminationGracePeriodSeconds (set on the StatefulSet) to finish.
+    const shutdown = async () => {
+      await relay.stop();
+      process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
+  },
+});
+
+if (import.meta.main) void runMain(relayCommand);

package/src/grant.ts

@@ -0,0 +1,63 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// Signed control↔relay grants (ADR 0061). For hosted live presenting the control
+// plane owns the session and authorizes relay actions by minting a short-lived,
+// HMAC-signed grant over a shared secret; the relay verifies it **statelessly**, it
+// never calls back to the control plane per connection. Same trust class as the
+// static relay account token (auth.ts), but scoped to one session + role + expiry.
+
+export interface Grant {
+  /** the live session this grant is scoped to (the relay's session id / audience slug). */
+  session: string;
+  /** the role/action this grant confers, e.g. "presenter" | "runner" | "audience"
+   *  for a peer connection, or "create" to mint a session. Interpreted by the relay. */
+  role: string;
+  /** optional capability scopes, reserved for finer-grained authorization. */
+  scopes?: string[];
+  /** expiry, unix epoch milliseconds. */
+  exp: number;
+}
+
+const b64url = (b: Buffer): string => b.toString("base64url");
+const sign = (data: string, secret: string): Buffer => createHmac("sha256", secret).update(data).digest();
+
+/** Mint a signed grant: `<base64url(payload)>.<base64url(hmacSHA256)>`. */
+export function mintGrant(grant: Grant, secret: string): string {
+  const payload = b64url(Buffer.from(JSON.stringify(grant), "utf8"));
+  return `${payload}.${b64url(sign(payload, secret))}`;
+}
+
+/**
+ * Verify and decode a grant. Returns the payload, or null if it is malformed,
+ * tampered, signed with the wrong secret, or expired (`exp <= now`, unix ms). The
+ * signature compare is constant-time. Fails closed on any error.
+ */
+export function verifyGrant(token: string | null | undefined, secret: string, now: number): Grant | null {
+  if (!token) return null;
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) return null;
+  const payload = token.slice(0, dot);
+  const mac = token.slice(dot + 1);
+
+  let expected: string;
+  try {
+    expected = b64url(sign(payload, secret));
+  } catch {
+    return null;
+  }
+  const a = Buffer.from(mac, "utf8");
+  const b = Buffer.from(expected, "utf8");
+  // Length mismatch short-circuits (the mac's length isn't the secret); equal-length
+  // inputs are compared without early-out.
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
+
+  let grant: Grant;
+  try {
+    grant = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as Grant;
+  } catch {
+    return null;
+  }
+  if (!grant || typeof grant.session !== "string" || typeof grant.role !== "string") return null;
+  if (typeof grant.exp !== "number" || grant.exp <= now) return null;
+  return grant;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { createRelay, type RelayOptions, type RelayServer, type RelayStorage } from "./relay-server";
+export { safeEqual, matchAccount, bearer } from "./auth";
+export { mintGrant, verifyGrant, type Grant } from "./grant";

package/src/metrics.ts

@@ -0,0 +1,152 @@
+// Minimal Prometheus / OpenMetrics text-exposition registry + the relay's metric set
+// (ADR 0073 / ticket 0023). Pure, dependency-free, unit-testable. Intentionally NOT a shared
+// package: present-relay is OSS-published, so a shared `@liebstoeckel/metrics` would force the
+// five-place OSS lock-step for ~80 lines, the registry is duplicated in control-core instead.
+
+type Labels = Record<string, string>;
+
+const sortedKeys = (l: Labels): string[] => Object.keys(l).sort();
+const labelId = (l: Labels): string => sortedKeys(l).map((k) => `${k}=${l[k]}`).join(",");
+const esc = (v: string): string => v.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
+const fmtLabels = (l: Labels): string => {
+  const ks = sortedKeys(l);
+  return ks.length ? "{" + ks.map((k) => `${k}="${esc(l[k]!)}"`).join(",") + "}" : "";
+};
+
+abstract class Metric {
+  constructor(
+    readonly name: string,
+    readonly help: string,
+    readonly type: "counter" | "gauge" | "histogram",
+  ) {}
+  abstract rows(): string[];
+}
+
+export class Counter extends Metric {
+  private v = new Map<string, { labels: Labels; n: number }>();
+  constructor(name: string, help: string) {
+    super(name, help, "counter");
+  }
+  inc(labels: Labels = {}, by = 1): void {
+    const k = labelId(labels);
+    const e = this.v.get(k);
+    if (e) e.n += by;
+    else this.v.set(k, { labels, n: by });
+  }
+  rows(): string[] {
+    return [...this.v.values()].map((e) => `${this.name}${fmtLabels(e.labels)} ${e.n}`);
+  }
+}
+
+export class Gauge extends Metric {
+  private v = new Map<string, { labels: Labels; n: number }>();
+  constructor(name: string, help: string) {
+    super(name, help, "gauge");
+  }
+  set(n: number, labels: Labels = {}): void {
+    this.v.set(labelId(labels), { labels, n });
+  }
+  inc(labels: Labels = {}, by = 1): void {
+    const k = labelId(labels);
+    const e = this.v.get(k);
+    if (e) e.n += by;
+    else this.v.set(k, { labels, n: by });
+  }
+  dec(labels: Labels = {}, by = 1): void {
+    this.inc(labels, -by);
+  }
+  rows(): string[] {
+    return [...this.v.values()].map((e) => `${this.name}${fmtLabels(e.labels)} ${e.n}`);
+  }
+}
+
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+
+export class Histogram extends Metric {
+  private v = new Map<string, { labels: Labels; counts: number[]; sum: number; total: number }>();
+  constructor(
+    name: string,
+    help: string,
+    private buckets: number[] = DEFAULT_BUCKETS,
+  ) {
+    super(name, help, "histogram");
+  }
+  observe(value: number, labels: Labels = {}): void {
+    const k = labelId(labels);
+    let e = this.v.get(k);
+    if (!e) {
+      e = { labels, counts: new Array(this.buckets.length).fill(0), sum: 0, total: 0 };
+      this.v.set(k, e);
+    }
+    e.sum += value;
+    e.total++;
+    for (let i = 0; i < this.buckets.length; i++) if (value <= this.buckets[i]!) e.counts[i]!++;
+  }
+  rows(): string[] {
+    const out: string[] = [];
+    for (const e of this.v.values()) {
+      // `counts[i]` already holds the cumulative count of observations ≤ buckets[i]
+      // (observe() increments every bucket the value falls under), so emit it directly.
+      for (let i = 0; i < this.buckets.length; i++) {
+        out.push(`${this.name}_bucket${fmtLabels({ ...e.labels, le: String(this.buckets[i]) })} ${e.counts[i]}`);
+      }
+      out.push(`${this.name}_bucket${fmtLabels({ ...e.labels, le: "+Inf" })} ${e.total}`);
+      out.push(`${this.name}_sum${fmtLabels(e.labels)} ${e.sum}`);
+      out.push(`${this.name}_count${fmtLabels(e.labels)} ${e.total}`);
+    }
+    return out;
+  }
+}
+
+export class Registry {
+  private metrics: Metric[] = [];
+  private collectors: Array<() => void> = [];
+  register<T extends Metric>(m: T): T {
+    this.metrics.push(m);
+    return m;
+  }
+  /** Refresh callbacks run at scrape time, before render, for gauges read from live state. */
+  onCollect(fn: () => void): void {
+    this.collectors.push(fn);
+  }
+  render(): string {
+    for (const fn of this.collectors) fn();
+    const lines: string[] = [];
+    for (const m of this.metrics) {
+      const rows = m.rows();
+      if (rows.length === 0) continue; // omit metrics with no samples yet
+      lines.push(`# HELP ${m.name} ${m.help}`, `# TYPE ${m.name} ${m.type}`, ...rows);
+    }
+    return lines.join("\n") + "\n";
+  }
+}
+
+/** The relay's metric set (ADR 0073). One registry per relay instance (test-friendly). */
+export function createRelayMetrics(version = "unknown") {
+  const r = new Registry();
+  const m = {
+    registry: r,
+    sessions: r.register(new Gauge("liebstoeckel_relay_sessions", "Active live sessions on this pod")),
+    audiencePeers: r.register(new Gauge("liebstoeckel_relay_audience_peers", "Connected audience peers on this pod")),
+    deckBytes: r.register(new Gauge("liebstoeckel_relay_deck_bytes", "In-memory deck HTML bytes held on this pod")),
+    cordoned: r.register(new Gauge("liebstoeckel_relay_cordoned", "1 if this pod is cordoned (draining)")),
+    startedAt: r.register(new Gauge("liebstoeckel_relay_started_at_seconds", "Process start time (unix seconds)")),
+    sessionCreates: r.register(new Counter("liebstoeckel_relay_session_creates_total", "Sessions provisioned")),
+    sessionRejects: r.register(new Counter("liebstoeckel_relay_session_rejects_total", "Session creates rejected, by reason")),
+    snapshotWrites: r.register(new Counter("liebstoeckel_relay_snapshot_writes_total", "Snapshot persist attempts")),
+    snapshotFailures: r.register(new Counter("liebstoeckel_relay_snapshot_failures_total", "Snapshot persist failures")),
+    snapshotSeed: r.register(new Counter("liebstoeckel_relay_snapshot_seed_total", "Snapshot re-seed on create, by result")),
+    wsOpens: r.register(new Counter("liebstoeckel_relay_ws_opens_total", "WebSocket opens, by role")),
+    wsCloses: r.register(new Counter("liebstoeckel_relay_ws_closes_total", "WebSocket closes, by role")),
+    wsConnections: r.register(new Gauge("liebstoeckel_relay_ws_connections", "Open WebSocket connections, by role")),
+    audienceCapRejects: r.register(new Counter("liebstoeckel_relay_audience_cap_rejections_total", "WS rejected: audience cap reached")),
+    grantDenials: r.register(new Counter("liebstoeckel_relay_grant_denials_total", "Deck/sync requests denied (bad/expired grant)")),
+    wsFrames: r.register(new Counter("liebstoeckel_relay_ws_frames_total", "Yjs WS frames, by direction")),
+    wsBytes: r.register(new Counter("liebstoeckel_relay_ws_bytes_total", "Yjs WS bytes, by direction")),
+    buildInfo: r.register(new Gauge("liebstoeckel_relay_build_info", "Relay build info (constant 1)")),
+  };
+  m.buildInfo.set(1, { version });
+  return m;
+}
+
+export type RelayMetrics = ReturnType<typeof createRelayMetrics>;