@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/runtime/docker/ingress/index.ts

@@ -0,0 +1,16 @@
+// @yourrealm/sdk/runtime/docker/ingress — the Docker worker's ingress renderer.
+//
+// Transforms `WorkerState.ingress` (from @yourrealm/sdk/worker-protocol) into
+// a Caddy JSON config document. The sibling of `runtime/docker/compose`: same
+// wire, same injection point in `platform/worker`, one renderer per half of
+// the protocol. Caddy is this implementation's choice of proxy, not a
+// Realm-wide one - a different worker satisfies the same `ingress` field with
+// whatever its runtime routes traffic through.
+//
+// No I/O, no docker socket, no network, and nothing at module load: this entry
+// is on the SDK's exports map, so an author's realm.ts may import it and have
+// it evaluated inside QuickJS, which `worker-protocol/quickjs-safe.test.ts`
+// keeps honest.
+
+export { ACME_CA_ROOT_PATH, type BuildInput, buildCaddyConfig } from "./build-config.ts";
+export type { CaddyConfig } from "./types.ts";

package/src/runtime/docker/ingress/types.ts

@@ -0,0 +1,182 @@
+// The shape of Caddy's config document — what `caddy run --config` reads.
+// Types only; `build-config.ts` is what fills them in.
+
+export interface CaddyConfig {
+  admin: { listen: string };
+  apps: {
+    http: { servers: { main: CaddyServer } };
+    tls: {
+      // `certificates.automate` is what actually makes Caddy *obtain* a cert
+      // for a name; the automation policy's `subjects` only selects which
+      // issuer to use. Without the wildcard listed here Caddy manages a
+      // per-host cert for each route's exact Host (e.g. the dashboard host),
+      // whose DNS-01 challenge (`_acme-challenge.<host>`) the acme-dns shim
+      // never writes - it writes only the wildcard challenge at the workerId
+      // level.
+      certificates?: { automate: string[] };
+      automation: { policies: CaddyTlsPolicy[] };
+    };
+    // Present iff acme-dns is configured: keeps the worker's wildcard A
+    // (`*.{workerId}.{baseDomain}`) pointed at its own public IP.
+    dynamic_dns?: CaddyDynamicDns;
+  };
+}
+
+// caddy-dynamicdns app config. `domains` maps a zone to the subdomain labels
+// to keep updated - here the single worker-id label under the slug base. The
+// `realm` provider POSTs each to the shim's /a; the shim records the request
+// source IP and ignores any supplied value, so the `simple_http` ip_source
+// (the shim's /ip echo) only decides *when* to write. A-only (ipv4).
+export interface CaddyDynamicDns {
+  domains: Record<string, string[]>;
+  dns_provider: { name: "realm"; server_url: string; username: string; api_key: string };
+  ip_sources: Array<{ source: "simple_http"; endpoints: string[] }>;
+  check_interval: string;
+  versions: { ipv4: boolean; ipv6: boolean };
+}
+
+export type CaddyProvider =
+  // Module IDs are the no-hyphen form (`dns.providers.acmedns`) matching
+  // the plugin import paths under github.com/caddy-dns/<id>. The acme-dns
+  // config field names come from libdns/acmedns's Provider struct json
+  // tags (server_url, username, password, subdomain).
+  | { name: "acmedns"; server_url: string; username: string; password: string; subdomain: string }
+  // BYO public-DNS tokens, inlined: Home decrypts the operator's stored token
+  // and puts the plaintext on the per-worker encrypted wire, because the
+  // caddy-dns modules read their libdns struct fields verbatim and never run
+  // Caddy's placeholder replacer, so an `{env.X}` form would reach the provider
+  // as a literal string.
+  | { name: "cloudflare"; api_token: string }
+  | { name: "hetzner"; api_token: string };
+
+export type CaddyIssuer =
+  | {
+      module: "acme";
+      challenges: {
+        dns: {
+          provider: CaddyProvider;
+          // Hard wait after writing the TXT before Caddy asks the CA to
+          // validate, so a Let's Encrypt perspective can't query before the
+          // write has reached every authoritative NS ("During secondary
+          // validation: No TXT record found"). Only emitted for the acme-dns
+          // issuer.
+          propagation_delay?: string;
+        };
+      };
+      // Omitted = Caddy's default ACME endpoint (Let's Encrypt prod).
+      ca?: string;
+      // Roots to trust for the ACME endpoint, for a non-public test CA.
+      trusted_roots_pem_files?: string[];
+    }
+  // Caddy's built-in self-signed CA. Bootstrap fallback when no real
+  // DNS-01 provider is configured (dev, e2e, first-boot before installer).
+  | { module: "internal" };
+
+export interface CaddyTlsPolicy {
+  // Omitted = catch-all (matches any host not covered by an earlier policy).
+  subjects?: string[];
+  issuers: CaddyIssuer[];
+}
+
+interface CaddyServer {
+  listen: string[];
+  routes: CaddyRoute[];
+  // Server-level real-client-IP resolution. Present iff at least one CDN is
+  // declared in front. `source: "cdn"` is Realm's own ip_source module baked
+  // into the ingress image, which holds each provider's list URLs and refreshes
+  // them on a timer, so no range ever appears in this config. Caddy takes one
+  // ip_source per server, so several CDNs mean one module trusting the union.
+  // `trusted_proxies_strict` forces right-to-left XFF parsing;
+  // `client_ip_headers` is the header set `{http.vars.client_ip}` reads from.
+  trusted_proxies?: { source: "cdn"; providers: string[] };
+  trusted_proxies_strict?: 1;
+  client_ip_headers?: string[];
+  // Error handler chain. Reached when a handler fails rather than answers —
+  // notably a reverse_proxy that cannot dial its upstream, which is how a
+  // route to a not-yet-running container surfaces.
+  errors?: { routes: CaddyErrorRoute[] };
+}
+
+// A matcher with no `host` matches every host the server answers - the asset
+// links route is the one that does, and a path-only matcher adds nothing to
+// Caddy's managed-certificate set.
+export interface CaddyRoute {
+  match: Array<{ host?: string[]; path?: string[] }>;
+  handle: CaddyHandler[];
+  terminal: true;
+}
+
+// `not` excludes hosts that have their own meaning for an error (the dashboard:
+// a 502 there means Home is down, not that an app is starting). `expression` is
+// CEL over the error, narrowing to dial/timeout failures so a 413 or a 429 from
+// a healthy app doesn't get reported as a container that isn't up.
+export interface CaddyErrorRoute {
+  match: Array<{ host: string[]; not?: Array<{ host: string[] }>; expression?: string }>;
+  handle: CaddyHandler[];
+  terminal: true;
+}
+
+// A header rewrite (request or response). The forward_auth hop sets request
+// headers; the security-header handler uses `response`; the Cookie-strip uses
+// `request.replace` to snip just the Home session cookie out of the header.
+export interface CaddyHeaderRewrite {
+  set?: Record<string, string[]>;
+  delete?: string[];
+  replace?: Record<string, Array<{ search_regexp: string; replace: string }>>;
+}
+
+export type CaddyHandler =
+  | { handler: "encode"; encodings: { gzip: Record<string, never> }; prefer: string[] }
+  | {
+      handler: "headers";
+      response?: CaddyHeaderRewrite;
+      request?: CaddyHeaderRewrite;
+    }
+  | { handler: "request_body"; max_size: number }
+  | {
+      handler: "rate_limit";
+      rate_limits: Record<string, { key: string; window: string; max_events: number }>;
+    }
+  // Sets request-scoped variables. Used inside the forward_auth 2xx branch,
+  // where it both keeps the chain going (it answers nothing, so handling falls
+  // through to the app proxy) and records that Home approved — the error routes
+  // read that back to tell a dead app from an unreachable Home.
+  | { handler: "vars"; realm_auth_ok?: string }
+  // The plain app proxy is just `upstreams`. The forward_auth hop reuses
+  // the same handler with `rewrite` (uri → verify path), `headers.request`
+  // (X-Forwarded-*), and `handle_response` (on 2xx run a no-op route so the
+  // chain continues to the app; relay non-2xx verbatim).
+  //
+  // `headers.response` needs no `deferred` flag here: reverse_proxy applies
+  // response ops directly to the upstream's header map before copying it out,
+  // unlike the standalone `headers` handler, which has to wrap the
+  // ResponseWriter and therefore defers.
+  | {
+      handler: "reverse_proxy";
+      upstreams: Array<{ dial: string }>;
+      rewrite?: { method: string; uri: string };
+      headers?: { request?: CaddyHeaderRewrite; response?: CaddyHeaderRewrite };
+      // A sub-route may carry a `not vars` guard: the brokered-header sets
+      // run only when the verify response actually carried the header, so
+      // an anonymous admit (2xx, no identity) hands the app nothing rather
+      // than the unresolved placeholder text.
+      handle_response?: Array<{
+        match: { status_code: number[] };
+        routes: Array<{
+          match?: Array<{ not: Array<{ vars: Record<string, string[]> }> }>;
+          handle: CaddyHandler[];
+        }>;
+      }>;
+      // How long an upgraded stream survives a config reload, as a Go duration
+      // string (`caddy.Duration`). Only the dashboard route sets it: remote
+      // workers' uplinks ride it, and every deploy on Home's box reloads Caddy.
+      stream_close_delay?: string;
+    }
+  | {
+      handler: "static_response";
+      headers: Record<string, string[]>;
+      status_code: number;
+      // Response body. Caddy runs this through its placeholder replacer, so a
+      // literal `{` opens a placeholder — see NOT_ROUTED_PAGE in build-config.
+      body?: string;
+    };

package/src/runtime/docker/log-frames.ts

@@ -0,0 +1,121 @@
+// Shared Docker stream-frame demux. Docker's streaming endpoints
+// (`/containers/X/logs?follow=true`, `/events`) respond with HTTP chunked
+// transfer encoding wrapping an inner format. `dechunkedReader` peels off
+// the chunk framing; `streamDockerLogFrames` parses the multiplexed
+// stdout/stderr frames inside a logs body.
+//
+// Used by both the logs server (tails every managed container) and the
+// spawn broker (relays a single box's output back over `spawn.sock`).
+
+const decoder = new TextDecoder();
+
+interface DockerLogFrame {
+  stream: "stdout" | "stderr";
+  timestamp: number;
+  message: string;
+}
+
+const STREAM_TYPES: Record<number, "stdout" | "stderr"> = {
+  1: "stdout",
+  2: "stderr",
+};
+
+function parseTimestamp(rfc3339: string): number {
+  if (!rfc3339) return 0;
+  const ms = Date.parse(rfc3339);
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+// HTTP chunked transfer encoding decoder. Yields the body bytes between
+// chunk-size headers. Stops at the terminator chunk (`0\r\n\r\n`) or EOF.
+export async function* dechunkedReader(conn: Deno.Conn): AsyncIterable<Uint8Array> {
+  let buf = new Uint8Array(0);
+  const readBuf = new Uint8Array(8192);
+
+  async function ensure(min: number): Promise<boolean> {
+    while (buf.length < min) {
+      const n = await conn.read(readBuf).catch(() => null);
+      if (n === null) return false;
+      if (n === 0) continue;
+      const next = new Uint8Array(buf.length + n);
+      next.set(buf);
+      next.set(readBuf.slice(0, n), buf.length);
+      buf = next;
+    }
+    return true;
+  }
+
+  while (true) {
+    // Find the next \r\n that terminates the chunk-size line.
+    let nlIdx = -1;
+    while (nlIdx === -1) {
+      for (let i = 0; i < buf.length - 1; i++) {
+        if (buf[i] === 0x0d && buf[i + 1] === 0x0a) {
+          nlIdx = i;
+          break;
+        }
+      }
+      if (nlIdx !== -1) break;
+      const more = await conn.read(readBuf).catch(() => null);
+      if (more === null) return;
+      if (more === 0) continue;
+      const next = new Uint8Array(buf.length + more);
+      next.set(buf);
+      next.set(readBuf.slice(0, more), buf.length);
+      buf = next;
+    }
+
+    const sizeLine = decoder.decode(buf.slice(0, nlIdx));
+    const size = parseInt(sizeLine.split(";")[0]!, 16);
+    buf = buf.slice(nlIdx + 2);
+
+    if (!Number.isFinite(size) || size < 0) return;
+    if (size === 0) return; // end-of-chunks
+
+    if (!(await ensure(size + 2))) return;
+    yield buf.slice(0, size);
+    // Skip the trailing \r\n after the chunk data.
+    buf = buf.slice(size + 2);
+  }
+}
+
+// Parse docker's multiplexed-stream frames out of a dechunked body.
+// Each frame: 1 byte stream-type, 3 bytes pad, 4 bytes BE size, then
+// `size` bytes of payload. With timestamps=true the payload is
+// "<RFC3339> <message>\n".
+export async function* streamDockerLogFrames(
+  body: AsyncIterable<Uint8Array>,
+): AsyncIterable<DockerLogFrame> {
+  // Per-instance, streaming decoder so a multi-byte UTF-8 sequence
+  // straddling two frame payloads survives the boundary.
+  const decoder = new TextDecoder("utf-8");
+  let buf = new Uint8Array(0);
+  for await (const chunk of body) {
+    const next = new Uint8Array(buf.length + chunk.length);
+    next.set(buf);
+    next.set(chunk, buf.length);
+    buf = next;
+
+    while (buf.length >= 8) {
+      const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+      const streamType = STREAM_TYPES[buf[0]!] ?? "stdout";
+      const size = view.getUint32(4);
+      if (buf.length < 8 + size) break;
+      const payload = decoder.decode(buf.slice(8, 8 + size), { stream: true });
+      buf = buf.slice(8 + size);
+      for (const line of payload.split("\n")) {
+        if (!line) continue;
+        const sp = line.indexOf(" ");
+        if (sp === -1) {
+          yield { stream: streamType, timestamp: 0, message: line };
+        } else {
+          yield {
+            stream: streamType,
+            timestamp: parseTimestamp(line.slice(0, sp)),
+            message: line.slice(sp + 1),
+          };
+        }
+      }
+    }
+  }
+}

package/src/runtime/docker/logs-server/index.ts

@@ -0,0 +1,366 @@
+// Worker-side logs server. Binds a unix socket; consumers connect, send
+// a single line `{"since":<unix-ms>}\n` (or just `\n`), and receive a
+// JSON Lines stream of `LogLine` records — one line per stdout/stderr
+// line from any `realm.managed=true` container on the host.
+//
+// Discovery: list all matching containers at connect time; subscribe to
+// docker events for new starts. Container exits stop their tail; the
+// stream stays open for live ones.
+//
+// Docker's streaming endpoints (`/containers/X/logs?follow=true`, `/events`)
+// respond with HTTP chunked transfer encoding, so `dechunkedReader` peels that
+// off before the inner multiplexed-frame (logs) or JSON Lines (events) format
+// is parsed.
+
+import { dirname } from "@std/path";
+import { LABELS, ode } from "@local/docker";
+import { z } from "zod";
+import { REALM_LOGS_SOCKET } from "../../../worker-protocol/logs-socket-path.ts";
+import { type LogLine } from "../../log-line.ts";
+import { dechunkedReader, streamDockerLogFrames } from "../log-frames.ts";
+
+export { REALM_LOGS_SOCKET };
+export type { LogLine };
+
+// Request line a consumer may send before the stream starts: {"since":<unix-ms>}.
+const sinceRequestSchema = z.object({ since: z.number().optional() });
+// Docker `/events` JSON Lines: each line is an arbitrary JSON object.
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+
+interface StartOpts {
+  /** Defaults to {@link REALM_LOGS_SOCKET}. Override for tests. */
+  socketPath?: string;
+}
+
+interface ServerHandle {
+  /** Stop the server: close listener, drop all active connections, remove the socket file. */
+  stop(): Promise<void>;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export async function startLogsServer(opts: StartOpts = {}): Promise<ServerHandle> {
+  const socketPath = opts.socketPath ?? REALM_LOGS_SOCKET;
+  // The socket lives alone in its own directory (apps mount the dir, not the
+  // socket file — a file bind-mount of a unix socket doesn't wire across
+  // containers on macOS Docker). Ensure the dir exists before binding.
+  await Deno.mkdir(dirname(socketPath), { recursive: true });
+  await Deno.remove(socketPath).catch(() => {});
+
+  const listener = Deno.listen({ transport: "unix", path: socketPath });
+  const sessions = new Set<Session>();
+
+  void acceptLoop(listener, sessions);
+
+  return {
+    async stop() {
+      try {
+        listener.close();
+      } catch {}
+      for (const s of sessions) s.close();
+      sessions.clear();
+      await Deno.remove(socketPath).catch(() => {});
+    },
+  };
+}
+
+async function acceptLoop(listener: Deno.Listener, sessions: Set<Session>): Promise<void> {
+  try {
+    for await (const conn of listener) {
+      const session = new Session(conn as Deno.UnixConn);
+      sessions.add(session);
+      session.run().finally(() => sessions.delete(session));
+    }
+  } catch {
+    // Listener was closed via stop().
+  }
+}
+
+/**
+ * How far a container's log has already been forwarded. `count` is how
+ * many frames carried that exact millisecond, which is what lets a
+ * resume be exact despite docker's second-granularity `?since=`.
+ */
+interface ResumeMark {
+  ts: number;
+  count: number;
+}
+
+interface TailHandle {
+  state: { stopped: boolean };
+  /** Set once the docker logs conn is established. Lets session.close() preempt the pending read. */
+  conn?: Deno.Conn;
+}
+
+class Session {
+  private readonly conn: Deno.UnixConn;
+  private readonly tails = new Map<string, TailHandle>();
+  // Per-container resume point. A container keeps its id across a
+  // restart, so this is what a re-tail resumes from instead of replaying
+  // the whole retained json log. Entries outlive their tail on purpose:
+  // the tail is gone precisely while the container is between restarts,
+  // which is exactly when the mark is needed.
+  private readonly resume = new Map<string, ResumeMark>();
+  private eventsClose?: () => void;
+  private writer?: WritableStreamDefaultWriter<Uint8Array>;
+  private closed = false;
+
+  constructor(conn: Deno.UnixConn) {
+    this.conn = conn;
+  }
+
+  async run(): Promise<void> {
+    try {
+      const since = await readSinceLine(this.conn);
+      this.writer = this.conn.writable.getWriter();
+
+      // Subscribe to docker events FIRST so the subscription is live before
+      // the enumeration below: anything started after this point lands in the
+      // events stream, anything earlier in the snapshot, and the overlap is
+      // deduped by `tails.has(id)` in startTail.
+      await this.startEvents(since);
+
+      // Initial enumeration: every realm-managed container, running and
+      // exited. `all: true` includes exited ones; their tail returns the
+      // historical chunk and exits.
+      const containers = await ode.listContainers({
+        all: true,
+        filters: { label: [`${LABELS.MANAGED}=true`] },
+      });
+      for (const c of containers) {
+        const id = c.Id;
+        const labels = c.Labels ?? {};
+        if (!id) continue;
+        this.startTail(id, labelsOf(labels), since);
+      }
+
+      // Block until the client closes.
+      await drainConn(this.conn);
+    } catch (err) {
+      console.error("logs-server session error:", err);
+    } finally {
+      this.close();
+    }
+  }
+
+  private startTail(id: string, meta: ContainerMeta, since: number | undefined): void {
+    if (this.tails.has(id)) return;
+    const handle: TailHandle = { state: { stopped: false } };
+    this.tails.set(id, handle);
+    // Never rewind behind what this container already emitted. `since` is
+    // the session's connect-time cursor and stays fixed for the session's
+    // whole life, so on its own it replays the container's entire retained
+    // log on every restart — a container keeps its id across one, and
+    // runTail drops it from `tails` on exit, so nothing else stops it.
+    const mark = this.resume.get(id);
+    const from = mark !== undefined ? Math.max(since ?? 0, mark.ts) : since;
+    void this.runTail(id, meta, from, handle);
+  }
+
+  private async runTail(
+    id: string,
+    meta: ContainerMeta,
+    since: number | undefined,
+    handle: TailHandle,
+  ): Promise<void> {
+    try {
+      // The wire's `since` is unix ms (matches LogLine.timestamp);
+      // docker's `?since=` is unix seconds. Floor so that the boundary
+      // line at exactly the cursor stays inclusive. `undefined` means
+      // "from epoch" — docker returns whatever's still in retention
+      // (capped per default-hardening at 10m × 3 files per container).
+      const sinceSeconds = since !== undefined ? Math.floor(since / 1000) : 0;
+      const { conn } = await ode.followContainerLogs(id, {
+        stdout: true,
+        stderr: true,
+        timestamps: true,
+        since: sinceSeconds,
+      });
+      handle.conn = conn;
+      // session.close() may have run while followContainerLogs was in flight.
+      if (handle.state.stopped || this.closed) {
+        try {
+          conn.close();
+        } catch {}
+        return;
+      }
+      // Docker's `?since=` is second-granularity, so the request above
+      // always re-delivers up to a second of lines we already wrote.
+      // Drop them: everything below the mark is written, and at the mark's
+      // own millisecond the first `count` frames are the ones we saw.
+      // Docker replays a container's log in order, so the prefix matches.
+      const mark = this.resume.get(id);
+      let remaining = mark?.count ?? 0;
+      let skipping = mark !== undefined;
+      try {
+        for await (const frame of streamDockerLogFrames(dechunkedReader(conn))) {
+          if (handle.state.stopped || this.closed) break;
+          if (skipping && mark) {
+            if (frame.timestamp < mark.ts) continue;
+            if (frame.timestamp === mark.ts && remaining > 0) {
+              remaining--;
+              continue;
+            }
+            skipping = false;
+          }
+          const prev = this.resume.get(id);
+          if (prev && prev.ts === frame.timestamp) prev.count++;
+          else this.resume.set(id, { ts: frame.timestamp, count: 1 });
+          this.write({
+            appId: meta.appId,
+            service: meta.service,
+            containerId: id,
+            timestamp: frame.timestamp,
+            stream: frame.stream,
+            line: frame.message,
+          });
+        }
+      } finally {
+        try {
+          conn.close();
+        } catch {}
+      }
+    } catch {
+      // Container may have been removed between list and follow.
+    } finally {
+      handle.state.stopped = true;
+      this.tails.delete(id);
+    }
+  }
+
+  // Awaits subscription establishment (the streamEvents promise resolves
+  // once docker's response headers are in), then consumes events in the
+  // background. Returning means the subscription is live, so any
+  // subsequent listContainers race is closed.
+  private async startEvents(since: number | undefined): Promise<void> {
+    const { conn } = await ode.streamEvents({
+      filters: {
+        type: ["container"],
+        event: ["start"],
+        label: [`${LABELS.MANAGED}=true`],
+      },
+    });
+    // session.close() may have run while streamEvents was in flight.
+    if (this.closed) {
+      try {
+        conn.close();
+      } catch {}
+      return;
+    }
+    this.eventsClose = () => {
+      try {
+        conn.close();
+      } catch {}
+    };
+    void this.consumeEvents(conn, since);
+  }
+
+  private async consumeEvents(conn: Deno.Conn, since: number | undefined): Promise<void> {
+    try {
+      for await (const event of streamDockerJsonLines(dechunkedReader(conn))) {
+        if (this.closed) break;
+        const id = (event.Actor as { ID?: string } | undefined)?.ID;
+        const attrs = (event.Actor as { Attributes?: Record<string, string> } | undefined)
+          ?.Attributes;
+        if (!id || !attrs) continue;
+        this.startTail(id, labelsOf(attrs), since);
+      }
+    } catch {
+      // Events stream died — new containers won't be picked up. Live
+      // tails continue working until they exit.
+    }
+  }
+
+  private write(env: LogLine): void {
+    if (this.closed || !this.writer) return;
+    const bytes = encoder.encode(JSON.stringify(env) + "\n");
+    this.writer.write(bytes).catch(() => {
+      // Client closed mid-write.
+      this.close();
+    });
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const handle of this.tails.values()) {
+      handle.state.stopped = true;
+      // Closing the docker conn preempts the pending read in
+      // dechunkedReader so the runTail loop unwinds promptly.
+      try {
+        handle.conn?.close();
+      } catch {}
+    }
+    this.tails.clear();
+    this.resume.clear();
+    this.eventsClose?.();
+    try {
+      this.writer?.releaseLock();
+    } catch {}
+    try {
+      this.conn.close();
+    } catch {}
+  }
+}
+
+interface ContainerMeta {
+  appId: string;
+  service: string;
+}
+
+function labelsOf(labels: Record<string, string>): ContainerMeta {
+  return {
+    appId: labels[LABELS.APP] ?? "",
+    service: labels[LABELS.SERVICE] ?? "",
+  };
+}
+
+async function readSinceLine(conn: Deno.UnixConn): Promise<number | undefined> {
+  const buf = new Uint8Array(1);
+  const collected: number[] = [];
+  while (collected.length < 4096) {
+    const n = await conn.read(buf);
+    if (n === null) break;
+    if (n === 0) continue;
+    if (buf[0] === 0x0a) break;
+    collected.push(buf[0]!);
+  }
+  const raw = decoder.decode(new Uint8Array(collected)).trim();
+  if (!raw) return undefined;
+  try {
+    const parsed = sinceRequestSchema.parse(JSON.parse(raw));
+    if (parsed.since !== undefined && Number.isFinite(parsed.since)) return parsed.since;
+  } catch {}
+  return undefined;
+}
+
+async function drainConn(conn: Deno.Conn): Promise<void> {
+  const buf = new Uint8Array(1024);
+  while (true) {
+    const n = await conn.read(buf).catch(() => null);
+    if (n === null) return;
+  }
+}
+
+// Parse newline-delimited JSON from a dechunked body.
+async function* streamDockerJsonLines(
+  body: AsyncIterable<Uint8Array>,
+): AsyncIterable<Record<string, unknown>> {
+  // Per-instance, streaming decoder so multi-byte UTF-8 across HTTP
+  // chunk boundaries doesn't get corrupted into U+FFFD.
+  const decoder = new TextDecoder("utf-8");
+  let remainder = "";
+  for await (const chunk of body) {
+    remainder += decoder.decode(chunk, { stream: true });
+    let nl: number;
+    while ((nl = remainder.indexOf("\n")) !== -1) {
+      const line = remainder.slice(0, nl).trim();
+      remainder = remainder.slice(nl + 1);
+      if (!line) continue;
+      try {
+        yield jsonObjectSchema.parse(JSON.parse(line));
+      } catch {}
+    }
+  }
+}