my-durable 0.0.0-stage → 0.0.2

package/apps/dpi-playground/apps/dpi-playground-hub/src/monitor.ts

@@ -0,0 +1,320 @@
+// One loop per registry device: probe /v1/device, classify, then follow /v1/events for trees.
+// Status machine: checking → online | offline | unauthorized | mismatch | incompatible, retrying
+// with backoff (offline: 1s → 30s; states only a human can fix: 30s or an explicit check()).
+import { DpiError } from "../../../../dpi-sdk/src/errors.js";
+import { transportFor, type DeviceTransport } from "./transport.js";
+import type {
+  DeviceInfo,
+  DeviceStatus,
+  DeviceTree,
+  NetworkDevice,
+  TunnelDiagnostics,
+} from "../../../../dpi-sdk/src/api.js";
+import { toPublic, type NetworkRegistry } from "../../../../dpi-sdk/src/node/registry.js";
+import { Backoff } from "../../../../dpi-sdk/src/protocol/backoff.js";
+import { MONITOR_BACKOFF_S } from "../../../../dpi-sdk/src/protocol/limits.js";
+
+export interface LiveState {
+  status: DeviceStatus;
+  error?: string;
+  info?: DeviceInfo;
+  tree?: DeviceTree;
+  lastSeenAt?: number;
+}
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => (clearTimeout(timer), resolve()), { once: true });
+  });
+
+export interface TunnelTransportSource {
+  dispatcherFor(row: { id: string; transport: string }): DeviceTransport;
+  /** True when the device currently has an authenticated tunnel connection. */
+  hasLiveConnection(deviceId: string): boolean;
+  diagnostics?(deviceId: string): TunnelDiagnostics;
+}
+
+export class DeviceMonitor {
+  private live = new Map<string, LiveState>();
+  private loops = new Map<string, AbortController>();
+  private wakers = new Map<string, () => void>();
+  private listeners = new Set<() => void>();
+  private persistedAt = new Map<string, number>();
+  private emitTimer?: ReturnType<typeof setTimeout>;
+
+  private tunnel?: TunnelTransportSource;
+
+  constructor(private readonly registry: NetworkRegistry) {}
+
+  start() {
+    for (const device of this.registry.list()) this.watch(device.id);
+  }
+
+  stop() {
+    for (const ctl of this.loops.values()) ctl.abort();
+    this.loops.clear();
+  }
+
+  watch(id: string) {
+    this.loops.get(id)?.abort();
+    const ctl = new AbortController();
+    this.loops.set(id, ctl);
+    this.live.set(id, { ...this.live.get(id), status: "checking", error: undefined });
+    this.emit();
+    void this.loop(id, ctl.signal);
+  }
+
+  forget(id: string) {
+    this.loops.get(id)?.abort();
+    this.loops.delete(id);
+    this.live.delete(id);
+    this.emit();
+  }
+
+  /** Re-probe now (after a token edit or a manual refresh). */
+  check(id: string) {
+    this.watch(id);
+  }
+
+  state(id: string): LiveState | undefined {
+    return this.live.get(id);
+  }
+
+  network(): NetworkDevice[] {
+    const pairings = this.registry.publicPairings();
+    return this.registry.list().map((row) =>
+      toPublic(row, this.live.get(row.id), {
+        pairing: pairings.get(row.id),
+        ...(row.transport === "tunnel"
+          ? {
+              tunnel: this.tunnel?.diagnostics?.(row.id) ?? {
+                state: this.tunnel?.hasLiveConnection(row.id) ? "connected" : "disconnected",
+                readerCount: 0,
+              },
+            }
+          : {}),
+      }),
+    );
+  }
+
+  /** Wire the tunnel dispatcher source (main.ts, after construction). */
+  setTunnelSource(source: TunnelTransportSource): void {
+    this.tunnel = source;
+    for (const device of this.registry.list())
+      if (device.transport === "tunnel") this.watch(device.id);
+  }
+
+  onChange(fn: () => void) {
+    this.listeners.add(fn);
+    return () => void this.listeners.delete(fn);
+  }
+
+  /** Pairing/transport metadata changed independently of the device health loop. */
+  refresh() {
+    this.emit();
+  }
+
+  /** Resolve once the device is online (or the signal aborts). */
+  async whenOnline(id: string, signal: AbortSignal) {
+    while (!signal.aborted && this.live.get(id)?.status !== "online") {
+      await new Promise<void>((resolve) => {
+        const off = this.onChange(() => {
+          if (this.live.get(id)?.status === "online") done();
+        });
+        const timer = setTimeout(() => done(), 5000);
+        const done = () => {
+          off();
+          clearTimeout(timer);
+          signal.removeEventListener("abort", done);
+          resolve();
+        };
+        signal.addEventListener("abort", done, { once: true });
+      });
+    }
+  }
+
+  /** Resolve when the device leaves `checking` (bounded). */
+  async settled(id: string, timeoutMs = 8000) {
+    const end = Date.now() + timeoutMs;
+    while (Date.now() < end && this.live.get(id)?.status === "checking")
+      await new Promise((r) => setTimeout(r, 100));
+    return this.network().find((d) => d.id === id);
+  }
+
+  private emit() {
+    if (this.emitTimer) return;
+    this.emitTimer = setTimeout(() => {
+      this.emitTimer = undefined;
+      for (const fn of this.listeners) fn();
+    }, 50);
+  }
+
+  private update(id: string, patch: Partial<LiveState>) {
+    if (!this.loops.has(id)) return;
+    const previous = this.live.get(id);
+    const next: LiveState = { ...previous, ...patch } as LiveState;
+    this.live.set(id, next);
+    const statusChanged = previous?.status !== next.status || previous?.error !== next.error;
+    const now = Date.now();
+    if (statusChanged || now - (this.persistedAt.get(id) ?? 0) > 10_000) {
+      this.persistedAt.set(id, now);
+      try {
+        this.registry.recordStatus(id, {
+          status: next.status,
+          error: next.error ?? null,
+          ...(next.lastSeenAt ? { seenAt: next.lastSeenAt } : {}),
+          ...(next.info ? { info: next.info } : {}),
+          ...(next.tree ? { tree: next.tree } : {}),
+        });
+      } catch {}
+    }
+    this.emit();
+  }
+
+  private async loop(id: string, signal: AbortSignal) {
+    const backoff = new Backoff(MONITOR_BACKOFF_S);
+    while (!signal.aborted) {
+      const device = this.registry.get(id);
+      if (!device) return;
+      let wait = backoff.ms;
+      if (device.transport === "tunnel" && this.tunnel) {
+        // Park offline (never unauthorized) while no tunnel connection is
+        // live, but wake within 5s of one appearing — the 30s backoff cap
+        // below belongs to probe failures, not to connection arrival.
+        if (!this.tunnel.hasLiveConnection(id)) {
+          this.update(id, {
+            status: "offline",
+            error: "paired over tunnel; no tunnel connection is live",
+          });
+          let appeared = false;
+          for (let i = 0; i < 6 && !signal.aborted; i++) {
+            await sleep(5_000, signal);
+            if (this.tunnel.hasLiveConnection(id)) {
+              appeared = true;
+              break;
+            }
+          }
+          if (!appeared && !this.tunnel.hasLiveConnection(id)) continue;
+        }
+      } else if (device.transport === "tunnel") {
+        // No dispatcher wired (unit contexts only): honest offline, never LAN.
+        this.update(id, {
+          status: "offline",
+          error: "paired over tunnel; no tunnel connection is live",
+        });
+        await sleep(30_000, signal);
+        continue;
+      }
+      if (device.transport !== "tunnel" && (!device.url || !device.token)) {
+        this.update(id, {
+          status: "unauthorized",
+          error: `No token for ${id}. Run: just net register ${id}`,
+        });
+        await sleep(30_000, signal);
+        continue;
+      }
+      if (this.live.get(id)?.status !== "online") this.update(id, { status: "checking" });
+      const transport = transportFor(device, this.tunnel);
+      if (!transport || (device.transport === "lan" && !transport.available)) {
+        this.update(id, {
+          status: "unauthorized",
+          error: `No token for ${id}. Run: just net register ${id}`,
+        });
+        await sleep(30_000, signal);
+        continue;
+      }
+      try {
+        const probe = await Promise.race([
+          transport.request({ method: "GET", path: "/v1/device" }, signal),
+          sleep(6_000, signal).then(() => null),
+        ]);
+        if (probe === null) throw new DpiError("offline", `Probe timeout for ${device.url}`);
+        if (probe.status === 401)
+          throw new DpiError("unauthorized", "Device rejected the token", 401);
+        if (probe.status !== 200)
+          throw new DpiError("offline", `/v1/device answered ${probe.status}`, probe.status);
+        let parsed: { apiVersion?: number; uid?: string; name?: string } | undefined;
+        try {
+          parsed = typeof probe.body === "string" ? JSON.parse(probe.body) : (probe.body as never);
+        } catch {
+          throw new DpiError("invalid", `/v1/device returned a non-JSON body`);
+        }
+        const info = {
+          ...parsed,
+          apiVersion: parsed?.apiVersion ?? 0,
+          uid: parsed?.uid ?? "",
+          name: parsed?.name ?? "",
+        } as DeviceInfo;
+        if (info.apiVersion !== 1) {
+          this.update(id, {
+            status: "incompatible",
+            error: `${device.url} speaks API v${info.apiVersion}; this hub speaks v1`,
+          });
+          await sleep(30_000, signal);
+          continue;
+        }
+        if (device.deviceUid && device.deviceUid !== info.uid) {
+          this.update(id, {
+            status: "mismatch",
+            error: `${device.url} now answers as "${info.name}" (uid ${info.uid.slice(0, 8)}), not the device first seen there (uid ${device.deviceUid.slice(0, 8)})`,
+          });
+          await sleep(30_000, signal);
+          continue;
+        }
+        const learned = this.registry.learnUid(id, info.uid);
+        if (!learned.ok) {
+          this.update(id, {
+            status: learned.conflict ? "mismatch" : "offline",
+            error: learned.conflict
+              ? `uid ${info.uid.slice(0, 8)}… already belongs to device "${learned.conflict}" (identity conflict — resolve manually)`
+              : `device answered with a non-canonical uid`,
+          });
+          await sleep(30_000, signal);
+          continue;
+        }
+        this.update(id, { status: "online", error: undefined, info, lastSeenAt: Date.now() });
+        backoff.reset();
+        for await (const frame of transport.watch(
+          { path: "/v1/events", consumerId: `monitor:${id}` },
+          signal,
+        )) {
+          if (frame.type === "tree")
+            this.update(id, {
+              status: "online",
+              error: undefined,
+              tree: frame.tree,
+              lastSeenAt: Date.now(),
+            });
+        }
+        if (signal.aborted) return;
+        // The stream was live until now: that is the last time the device was seen.
+        this.update(id, {
+          status: "offline",
+          error: "Event stream ended (device restarting?)",
+          lastSeenAt: Date.now(),
+        });
+        wait = 500;
+      } catch (e) {
+        if (signal.aborted) return;
+        const err =
+          e instanceof DpiError ? e : new DpiError("offline", String((e as Error)?.message ?? e));
+        if (err.code === "unauthorized") {
+          this.update(id, { status: "unauthorized", error: "Token rejected by the device" });
+          wait = 30_000;
+        } else {
+          // A stream that was live until it failed: the device was seen just now.
+          const wasOnline = this.live.get(id)?.status === "online";
+          this.update(id, {
+            status: "offline",
+            error: err.message,
+            ...(wasOnline ? { lastSeenAt: Date.now() } : {}),
+          });
+        }
+      }
+      await sleep(wait, signal);
+      backoff.advance();
+    }
+  }
+}

package/apps/dpi-playground/apps/dpi-playground-hub/src/mux.ts

@@ -0,0 +1,277 @@
+// One SSE connection per browser tab. The tab names the streams it wants (subscription keys);
+// the hub opens one authenticated upstream per key and tags every frame with its key.
+//   network                                  registry + live status of every device
+//   <device>/device[?docs=a,b]               device stream
+//   <device>/session/<sessionId>             session stream
+//   <device>/agent/<sessionId>/<agentId>[?docs=a,b]
+import { randomUUID } from "node:crypto";
+import type { Request, Response } from "express";
+import { DpiError } from "../../../../dpi-sdk/src/errors.js";
+import { transportFor } from "./transport.js";
+import type { MuxFrame } from "../../../../dpi-sdk/src/api.js";
+import type { NetworkRegistry } from "../../../../dpi-sdk/src/node/registry.js";
+import type { DeviceMonitor, TunnelTransportSource } from "./monitor.js";
+import { ByteBudget } from "../../../../dpi-sdk/src/node/chunk.js";
+import {
+  createPacedSseWriter,
+  type PacedSseWriter,
+} from "../../../../dpi-sdk/src/node/sse-writer.js";
+import { checkDeviceFrame } from "../../../../dpi-sdk/src/protocol/tunnel.js";
+import { Backoff } from "../../../../dpi-sdk/src/protocol/backoff.js";
+import {
+  HUB_BUFFER_BUDGET_BYTES,
+  LOGICAL_MESSAGE_MAX_BYTES,
+  READERS_PER_DEVICE,
+  READERS_PER_HUB,
+  RECONNECT_BACKOFF_S,
+  SSE_HUB_VIEWER_BYTES,
+} from "../../../../dpi-sdk/src/protocol/limits.js";
+
+interface BrowserStream {
+  send(frame: MuxFrame): void;
+  upstreams: Map<string, AbortController>;
+}
+
+const sseBudget = new ByteBudget("hub-sse", HUB_BUFFER_BUDGET_BYTES);
+
+/**
+ * Serialized paced writer (04 §10): complete SSE events only, split into
+ * ≤64 KiB segments, waiting for drain between segments. The chain guarantees
+ * a `: ping` can never land inside a half-written event, and a slow viewer is
+ * cut at the CANON hub cap instead of buffering without bound.
+ */
+export function pacedSseWriter(
+  res: Response,
+  opts: { budget?: ByteBudget; onClose?: () => void } = {},
+): PacedSseWriter {
+  return createPacedSseWriter(res, {
+    maxBufferedBytes: SSE_HUB_VIEWER_BYTES,
+    budget: opts.budget ?? sseBudget,
+    onClose: opts.onClose,
+  });
+}
+
+const KEY =
+  /^([a-z0-9][a-z0-9-]{0,31})\/(device|session|agent)(?:\/([^/?]+))?(?:\/([^/?]+))?(?:\?docs=([a-z0-9.,-]*))?$/;
+
+const invalidKey = () => Object.assign(Error("Invalid subscription key"), { status: 400 });
+
+export function parseSubKey(key: string) {
+  const m = key.match(KEY);
+  if (!m) throw invalidKey();
+  const [, deviceId, scope, a, b, docs] = m;
+  const q = docs ? `?docs=${docs}` : "";
+  const enc = (part: string) => {
+    try {
+      return encodeURIComponent(decodeURIComponent(part));
+    } catch {
+      throw invalidKey();
+    }
+  };
+  if (scope === "device") return { key, deviceId, path: `/v1/events${q}` };
+  if (scope === "session" && a && !b)
+    return { key, deviceId, path: `/v1/sessions/${enc(a)}/events` };
+  if (scope === "agent" && a && b)
+    return { key, deviceId, path: `/v1/sessions/${enc(a)}/agents/${enc(b)}/events${q}` };
+  throw invalidKey();
+}
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => (clearTimeout(timer), resolve()), { once: true });
+  });
+
+export class StreamMux {
+  private streams = new Map<string, BrowserStream>();
+  private tunnel?: TunnelTransportSource;
+  /** Live reader count per deviceId across all tabs (monitor adds its own). */
+  private readersByDevice = new Map<string, number>();
+
+  constructor(
+    private readonly registry: NetworkRegistry,
+    private readonly monitor: DeviceMonitor,
+    private readonly options: { budget?: ByteBudget } = {},
+  ) {}
+
+  private readerCount(deviceId: string): number {
+    const mux = this.readersByDevice.get(deviceId) ?? 0;
+    // The monitor owns one reader per tunnel device (P2-15).
+    const monitorReader = this.tunnel?.hasLiveConnection(deviceId) ? 1 : 0;
+    return mux + monitorReader;
+  }
+
+  private hubReaderCount(): number {
+    let total = 0;
+    for (const n of this.readersByDevice.values()) total += n;
+    return total;
+  }
+
+  get size() {
+    return this.streams.size;
+  }
+
+  /** Wire the tunnel dispatcher source (main.ts, after construction). */
+  setTunnelSource(source: TunnelTransportSource): void {
+    this.tunnel = source;
+  }
+
+  open(_req: Request, res: Response) {
+    const streamId = randomUUID();
+    res.status(200).set({
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      "x-accel-buffering": "no",
+    });
+    res.flushHeaders();
+    let closed = false;
+    let ping: NodeJS.Timeout | undefined;
+    let off = () => {};
+    const cleanup = () => {
+      if (closed) return;
+      closed = true;
+      writer.close();
+      clearInterval(ping);
+      off();
+      for (const [key, ctl] of stream.upstreams) {
+        ctl.abort();
+        this.releaseReader(key);
+      }
+      stream.upstreams.clear();
+      this.streams.delete(streamId);
+    };
+    const writer = pacedSseWriter(res, { budget: this.options.budget, onClose: cleanup });
+    const stream: BrowserStream = {
+      upstreams: new Map(),
+      send: (frame) => {
+        if (writer.write(`data: ${JSON.stringify(frame)}\n\n`) === "too-large") {
+          stream.send({
+            sub: frame.sub,
+            frame: {
+              type: "fault",
+              error: {
+                code: "invalid",
+                message: `Stream event exceeds ${LOGICAL_MESSAGE_MAX_BYTES} bytes; reduce the scope or payload`,
+              },
+            },
+          });
+        }
+      },
+    };
+    this.streams.set(streamId, stream);
+    stream.send({ sub: "hello", frame: { type: "stream", streamId } });
+    if (closed) return;
+    const pushNetwork = () =>
+      stream.send({ sub: "network", frame: { type: "network", devices: this.monitor.network() } });
+    pushNetwork();
+    if (closed) return;
+    off = this.monitor.onChange(pushNetwork);
+    // Ping rides the SAME chain as events: it can only land between complete
+    // events, never inside a half-written one.
+    ping = setInterval(() => !closed && writer.write(": ping\n\n"), 15_000);
+  }
+
+  /** Replace a tab's subscription set: open new upstreams, close dropped ones. */
+  subscribe(streamId: string, keys: unknown) {
+    const stream = this.streams.get(streamId);
+    if (!stream) throw Object.assign(Error("Stream closed; reconnect"), { status: 404 });
+    if (!Array.isArray(keys) || keys.some((k) => typeof k !== "string") || keys.length > 20)
+      throw Object.assign(Error("subs must be a list of up to 20 keys"), { status: 400 });
+    const wanted = new Map(
+      (keys as string[]).filter((k) => k !== "network").map((k) => [k, parseSubKey(k)]),
+    );
+    for (const [key, ctl] of stream.upstreams)
+      if (!wanted.has(key)) {
+        ctl.abort();
+        stream.upstreams.delete(key);
+        this.releaseReader(key);
+      }
+    for (const [key, sub] of wanted)
+      if (!stream.upstreams.has(key)) {
+        if (!this.registry.get(sub.deviceId))
+          throw Object.assign(Error(`No device ${sub.deviceId}`), { status: 404 });
+        // Reader caps (04 §8): 128/device incl. the monitor's reader, 1024
+        // hub-wide. A rejected NEW reader must not disturb existing readers.
+        if (
+          this.readerCount(sub.deviceId) >= READERS_PER_DEVICE ||
+          this.hubReaderCount() >= READERS_PER_HUB
+        ) {
+          stream.send({
+            sub: key,
+            frame: {
+              type: "fault",
+              error: {
+                code: "unavailable",
+                message: `Reader cap reached for ${sub.deviceId}; close other tabs or retry`,
+              },
+            },
+          });
+          continue;
+        }
+        this.acquireReader(sub.deviceId);
+        const ctl = new AbortController();
+        stream.upstreams.set(key, ctl);
+        void this.follow(stream, sub, ctl.signal);
+      }
+    return { subs: ["network", ...wanted.keys()] };
+  }
+
+  private acquireReader(deviceId: string): void {
+    this.readersByDevice.set(deviceId, (this.readersByDevice.get(deviceId) ?? 0) + 1);
+  }
+
+  private releaseReader(key: string): void {
+    try {
+      const sub = parseSubKey(key);
+      const n = this.readersByDevice.get(sub.deviceId) ?? 0;
+      if (n <= 1) this.readersByDevice.delete(sub.deviceId);
+      else this.readersByDevice.set(sub.deviceId, n - 1);
+    } catch {
+      /* non-parsable key never acquired a reader */
+    }
+  }
+
+  private async follow(
+    stream: BrowserStream,
+    sub: ReturnType<typeof parseSubKey>,
+    signal: AbortSignal,
+  ) {
+    const backoff = new Backoff(RECONNECT_BACKOFF_S);
+    while (!signal.aborted) {
+      await this.monitor.whenOnline(sub.deviceId, signal);
+      if (signal.aborted) return;
+      const device = this.registry.get(sub.deviceId);
+      const transport = device ? transportFor(device, this.tunnel) : undefined;
+      if (!transport?.available) return;
+      try {
+        for await (const frame of transport.watch(
+          { path: sub.path, consumerId: `mux:${sub.key}` },
+          signal,
+        )) {
+          if (!checkDeviceFrame(frame))
+            throw new DpiError("invalid", "Invalid device stream frame");
+          stream.send({ sub: sub.key, frame });
+          if (frame.type === "hello") backoff.reset();
+        }
+        if (signal.aborted) return;
+        stream.send({ sub: sub.key, frame: { type: "disconnected", reason: "Stream ended" } });
+      } catch (e) {
+        if (signal.aborted) return;
+        const err =
+          e instanceof DpiError ? e : new DpiError("offline", String((e as Error)?.message ?? e));
+        if (err.code === "not_found" || err.code === "invalid" || err.code === "ambiguous") {
+          stream.send({
+            sub: sub.key,
+            frame: { type: "fault", error: { code: err.code, message: err.message } },
+          });
+          return;
+        }
+        stream.send({ sub: sub.key, frame: { type: "disconnected", reason: err.message } });
+      }
+      await sleep(backoff.ms, signal);
+      backoff.advance();
+    }
+  }
+}