@huynle/hub 0.6.0 → 0.7.1

package/src/central/nodes.ts

@@ -0,0 +1,314 @@
+// NodeRegistry: the hub's view of connected `hub node` daemons (design §6.3), one entry per node connection.
+// Kept apart from the spoke Registry on purpose: a node is never a process, never in the catalog and never makes
+// its machine "online"; it only reports runtimes, labels, capacity and launch progress. Placement (P4-T5) reads
+// list(ownerID); the launch engine (P4-T8) subscribes to progress and connect/disconnect events.
+// Cluster mode (design §9): each pod is the single writer of its own nodes and exports them per owner (clusterSlice);
+// ./cluster/view.ts applies other pods' slices (setRemote), so list/get/forMachine see every node of the cluster (a
+// node on another pod is reached through SpokeHub.requestNode). Events and count() stay local, except for
+// subscribers asking for remote events (the launch supervisor on the leader pod): they also get connected,
+// capacity, progress and disconnected derived from other pods' slice changes. A local node of a machine wins over a
+// remote one.
+import type { NodeCapacity, NodeCapacityFrame, NodeHello, NodeLaunchPhase, NodeLaunchReport, NodeProgress, NodeRuntimeInfo } from "../protocol"
+
+export interface NodeMachine {
+  readonly id: string
+  readonly name: string
+}
+
+/** A connected node, as seen by placement and the launch engine (a copy; changing it changes nothing). */
+export interface NodeView {
+  readonly connID: string
+  readonly machineID: string
+  readonly machineName: string
+  /** The machine's current owner, read live (ownership can move). */
+  readonly ownerID: string | undefined
+  readonly instanceID: string
+  readonly nodeVersion: string
+  readonly features: readonly string[]
+  readonly runtimes: readonly NodeRuntimeInfo[]
+  readonly labels: Readonly<Record<string, string>>
+  readonly capacity: NodeCapacity
+  readonly used: NodeCapacity
+  /** capacity − used, never below zero; memoryMB only when the node reports both. */
+  readonly free: NodeCapacity
+  readonly workspaceRoots: readonly string[]
+  readonly draining: boolean
+  /** Launches the node carries, with their latest phase (cleaned and cancelled ones are dropped). */
+  readonly launches: readonly NodeLaunchReport[]
+  readonly connectedAt: number
+  readonly lastSeen: number
+}
+
+export type NodeEvent =
+  | { readonly type: "connected"; readonly node: NodeView }
+  | { readonly type: "capacity"; readonly node: NodeView }
+  | { readonly type: "progress"; readonly node: NodeView; readonly launchID: string; readonly phase: NodeLaunchPhase; readonly message?: string }
+  | { readonly type: "disconnected"; readonly node: NodeView }
+
+export type NodeListener = (event: NodeEvent) => void
+
+/** One owner's nodes on one pod, as other pods mirror them (JSON-compatible). */
+export interface NodeSlice {
+  readonly nodes: NodeView[]
+}
+
+/** Phases after which the node no longer carries the launch. */
+const GONE: ReadonlySet<NodeLaunchPhase> = new Set(["cleaned", "cancelled"])
+
+interface Entry {
+  readonly connID: string
+  readonly machine: NodeMachine
+  readonly hello: NodeHello
+  labels: Record<string, string>
+  capacity: NodeCapacity
+  used: NodeCapacity
+  draining: boolean
+  readonly launches: Map<string, NodeLaunchReport>
+  readonly connectedAt: number
+  lastSeen: number
+}
+
+export class NodeRegistry {
+  private readonly entries = new Map<string, Entry>()
+  private readonly listeners = new Set<NodeListener>()
+  /** Listeners that also get events derived from other pods' slices (the launch supervisor on the leader pod). */
+  private readonly remoteListeners = new Set<NodeListener>()
+  private readonly localChangeListeners = new Set<(owner: string | undefined) => void>()
+  /** Other pods' nodes: pod → owner → slice. */
+  private readonly remote = new Map<string, Map<string, NodeSlice>>()
+
+  constructor(
+    private readonly ownerOf: (machineID: string) => string | undefined,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  connect(connID: string, machine: NodeMachine, hello: NodeHello): NodeView {
+    const at = this.now()
+    const entry: Entry = {
+      connID,
+      machine: { id: machine.id, name: machine.name },
+      hello,
+      labels: { ...hello.labels },
+      capacity: { ...hello.capacity },
+      used: { ...hello.used },
+      draining: hello.draining,
+      launches: new Map(hello.launches.map((l) => [l.launchID, { ...l }])),
+      connectedAt: at,
+      lastSeen: at,
+    }
+    this.entries.set(connID, entry)
+    const node = this.view(entry)
+    this.emit({ type: "connected", node })
+    return node
+  }
+
+  setCapacity(connID: string, frame: NodeCapacityFrame): void {
+    const entry = this.entries.get(connID)
+    if (!entry) return
+    entry.capacity = { ...frame.capacity }
+    entry.used = { ...frame.used }
+    entry.draining = frame.draining
+    if (frame.labels) entry.labels = { ...frame.labels }
+    this.emit({ type: "capacity", node: this.view(entry) })
+  }
+
+  progress(connID: string, frame: NodeProgress): void {
+    const entry = this.entries.get(connID)
+    if (!entry) return
+    if (GONE.has(frame.phase)) entry.launches.delete(frame.launchID)
+    else {
+      const previous = entry.launches.get(frame.launchID)
+      entry.launches.set(frame.launchID, { ...previous, launchID: frame.launchID, phase: frame.phase })
+    }
+    this.emit({
+      type: "progress",
+      node: this.view(entry),
+      launchID: frame.launchID,
+      phase: frame.phase,
+      ...(frame.message !== undefined ? { message: frame.message } : {}),
+    })
+  }
+
+  touch(connID: string): void {
+    const entry = this.entries.get(connID)
+    if (entry) entry.lastSeen = this.now()
+  }
+
+  disconnect(connID: string): void {
+    const entry = this.entries.get(connID)
+    if (!entry) return
+    this.entries.delete(connID)
+    this.emit({ type: "disconnected", node: this.view(entry) })
+  }
+
+  get(connID: string): NodeView | undefined {
+    const entry = this.entries.get(connID)
+    return entry ? this.view(entry) : this.remoteNodes().find((node) => node.connID === connID)
+  }
+
+  /** The node connection of a machine (at most one: the hub turns away a second one); this pod's first. */
+  forMachine(machineID: string): NodeView | undefined {
+    return this.localForMachine(machineID) ?? this.remoteNodes().find((node) => node.machineID === machineID)
+  }
+
+  /** The node connection of a machine held by this pod. */
+  localForMachine(machineID: string): NodeView | undefined {
+    for (const entry of this.entries.values()) if (entry.machine.id === machineID) return this.view(entry)
+    return undefined
+  }
+
+  /** Connected nodes of `ownerID` (all owned nodes when omitted); a node whose machine has no owner is never listed. */
+  list(ownerID?: string): NodeView[] {
+    const out: NodeView[] = []
+    for (const node of [...[...this.entries.values()].map((entry) => this.view(entry)), ...this.remoteNodes()]) {
+      if (node.ownerID !== undefined && (ownerID === undefined || node.ownerID === ownerID)) out.push(node)
+    }
+    return out
+  }
+
+  // ---------- cluster (design §9) ----------
+
+  /** Listens for changes to this pod's nodes of an owner. */
+  onLocalChange(listener: (owner: string | undefined) => void): () => void {
+    this.localChangeListeners.add(listener)
+    return () => this.localChangeListeners.delete(listener)
+  }
+
+  /** Owners of this pod's nodes. */
+  clusterTenants(): string[] {
+    const owners = new Set<string>()
+    for (const entry of this.entries.values()) {
+      const owner = this.ownerOf(entry.machine.id)
+      if (owner !== undefined) owners.add(owner)
+    }
+    return [...owners]
+  }
+
+  /** This pod's nodes of an owner for other pods (undefined when none). */
+  clusterSlice(owner: string): NodeSlice | undefined {
+    const nodes = [...this.entries.values()].map((entry) => this.view(entry)).filter((node) => node.ownerID === owner)
+    return nodes.length ? { nodes } : undefined
+  }
+
+  /** Applies another pod's nodes of an owner (undefined: it has none any more). */
+  setRemote(pod: string, owner: string, slice: NodeSlice | undefined): void {
+    let slices = this.remote.get(pod)
+    const before = slices?.get(owner)?.nodes ?? []
+    if (slice) {
+      if (!slices) this.remote.set(pod, (slices = new Map()))
+      slices.set(owner, slice)
+    } else if (slices?.delete(owner) && !slices.size) this.remote.delete(pod)
+    if (this.remoteListeners.size) this.emitRemote(before, slice?.nodes ?? [])
+  }
+
+  /**
+   * Events for remote listeners from a change of another pod's slice: nodes connecting and leaving, capacity, and
+   * per launch its new phase, or (gone from the slice) cancelled while preparing, else cleaned.
+   */
+  private emitRemote(before: readonly NodeView[], after: readonly NodeView[]): void {
+    const view = (node: NodeView): NodeView => ({ ...structuredClone(node), ownerID: this.ownerOf(node.machineID) })
+    const old = new Map(before.map((node) => [node.connID, node]))
+    const events: NodeEvent[] = []
+    for (const node of after) {
+      const previous = old.get(node.connID)
+      old.delete(node.connID)
+      if (!previous) {
+        events.push({ type: "connected", node: view(node) })
+        continue
+      }
+      const capacity = (n: NodeView) => JSON.stringify([n.capacity, n.used, n.draining, n.labels])
+      if (capacity(previous) !== capacity(node)) events.push({ type: "capacity", node: view(node) })
+      const phases = new Map(previous.launches.map((l) => [l.launchID, l.phase]))
+      const current = new Set(node.launches.map((l) => l.launchID))
+      // Released launches first, then the new phases.
+      for (const [launchID, phase] of phases) {
+        if (!current.has(launchID)) events.push({ type: "progress", node: view(node), launchID, phase: phase === "preparing" ? "cancelled" : "cleaned" })
+      }
+      for (const launch of node.launches) {
+        if (phases.get(launch.launchID) !== launch.phase) events.push({ type: "progress", node: view(node), launchID: launch.launchID, phase: launch.phase })
+      }
+    }
+    for (const node of old.values()) events.push({ type: "disconnected", node: view(node) })
+    for (const event of events) this.notify(this.remoteListeners, event)
+  }
+
+  /** Other pods' nodes (owner read live), one per machine (the newest), none for a machine with a local node. */
+  private remoteNodes(): NodeView[] {
+    if (!this.remote.size) return []
+    const local = new Set([...this.entries.values()].map((entry) => entry.machine.id))
+    const byMachine = new Map<string, NodeView>()
+    for (const slices of this.remote.values()) {
+      for (const slice of slices.values()) {
+        for (const node of slice.nodes ?? []) {
+          if (local.has(node.machineID) || this.entries.has(node.connID)) continue
+          const known = byMachine.get(node.machineID)
+          if (!known || node.connectedAt > known.connectedAt) byMachine.set(node.machineID, node)
+        }
+      }
+    }
+    return [...byMachine.values()].map((node) => ({ ...structuredClone(node), ownerID: this.ownerOf(node.machineID) }))
+  }
+
+  /** Connected node connections (for /healthz). */
+  count(): number {
+    return this.entries.size
+  }
+
+  /** Events of this pod's nodes; with `remote`, also of other pods' nodes (derived from their slices). */
+  subscribe(listener: NodeListener, options: { readonly remote?: boolean } = {}): () => void {
+    this.listeners.add(listener)
+    if (options.remote) this.remoteListeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+      this.remoteListeners.delete(listener)
+    }
+  }
+
+  private emit(event: NodeEvent): void {
+    for (const listener of [...this.localChangeListeners]) {
+      try {
+        listener(event.node.ownerID)
+      } catch (cause) {
+        console.error("[hub] node change listener failed:", cause instanceof Error ? cause.message : cause)
+      }
+    }
+    this.notify(this.listeners, event)
+  }
+
+  private notify(listeners: ReadonlySet<NodeListener>, event: NodeEvent): void {
+    for (const listener of [...listeners]) {
+      try {
+        listener(event)
+      } catch (cause) {
+        console.error("[hub] node listener failed:", cause instanceof Error ? cause.message : cause)
+      }
+    }
+  }
+
+  private view(entry: Entry): NodeView {
+    const { hello, capacity, used } = entry
+    const free: NodeCapacity = {
+      slots: Math.max(0, capacity.slots - used.slots),
+      ...(capacity.memoryMB !== undefined && used.memoryMB !== undefined ? { memoryMB: Math.max(0, capacity.memoryMB - used.memoryMB) } : {}),
+    }
+    return {
+      connID: entry.connID,
+      machineID: entry.machine.id,
+      machineName: entry.machine.name,
+      ownerID: this.ownerOf(entry.machine.id),
+      instanceID: hello.instanceID,
+      nodeVersion: hello.nodeVersion,
+      features: [...(hello.features ?? [])],
+      runtimes: hello.runtimes.map((r) => structuredClone(r)),
+      labels: { ...entry.labels },
+      capacity: { ...capacity },
+      used: { ...used },
+      free,
+      workspaceRoots: [...hello.workspaceRoots],
+      draining: entry.draining,
+      launches: [...entry.launches.values()].map((l) => ({ ...l })),
+      connectedAt: entry.connectedAt,
+      lastSeen: entry.lastSeen,
+    }
+  }
+}

package/src/central/oidc.ts

@@ -1,8 +1,12 @@
 // OpenID Connect sign-in (authorization code flow with PKCE S256, state and nonce) for multi-user hubs.
 // The ID token comes straight from the token endpoint over TLS (confidential client, client_secret_post),
-// so its signature is not checked (OIDC Core 3.1.3.7, item 6); its claims are. Pending sign-ins live in
-// memory only (a restart invalidates them) and are single use.
+// so its signature is not checked (OIDC Core 3.1.3.7, item 6); its claims are. Pending sign-ins live in the Kv
+// backend (process memory by default, so a restart invalidates them; Valkey in a cluster, so the callback may land
+// on any pod) and are single use (GETDEL).
 import { createHash, randomBytes } from "node:crypto"
+import { MemoryCounters } from "./backend/memory-counters"
+import { MemoryKv } from "./backend/memory-kv"
+import type { Counters, Kv } from "./backend/types"
 import type { OidcConfig } from "./config"
 
 export const OIDC_COOKIE = "voice_oidc"
@@ -11,8 +15,10 @@ export const OIDC_PENDING_TTL_MS = 10 * 60_000
 export const DISCOVERY_CACHE_MS = 60 * 60_000
 /** Clock skew tolerated on `exp`. */
 const SKEW_SECONDS = 60
-/** Most pending sign-ins kept (the oldest are dropped): /auth/login is public. */
-const MAX_PENDING = 1000
+/** Most sign-ins started per pending lifetime (every pod together); /auth/login is public. */
+const MAX_PENDING = 10_000
+const PENDING_KEY = (state: string) => `oidc:pending:${state}`
+const STARTED_KEY = "oidc:started"
 const FETCH_TIMEOUT_MS = 10_000
 const MAX_NEXT_CHARS = 1024
 
@@ -56,6 +62,10 @@ export interface OidcClientOptions {
   readonly publicURL: string
   readonly fetch?: typeof globalThis.fetch
   readonly now?: () => number
+  /** Pending sign-ins (default: in this process, on `now`). */
+  readonly kv?: Kv
+  /** The cap on sign-ins started (default: in this process, on `now`). */
+  readonly counters?: Counters
 }
 
 const random = () => randomBytes(32).toString("base64url")
@@ -129,7 +139,8 @@ export class OidcClient {
   private readonly config: OidcConfig
   private readonly fetch: typeof globalThis.fetch
   private readonly now: () => number
-  private readonly pending = new Map<string, Pending>()
+  private readonly kv: Kv
+  private readonly counters: Counters
   private discovery?: { at: number; doc: Discovery }
   readonly redirectURI: string
 
@@ -137,18 +148,22 @@ export class OidcClient {
     this.config = options.config
     this.fetch = options.fetch ?? globalThis.fetch
     this.now = options.now ?? Date.now
+    this.kv = options.kv ?? new MemoryKv({ now: this.now })
+    this.counters = options.counters ?? new MemoryCounters({ now: this.now })
     this.redirectURI = `${options.publicURL}/auth/callback`
   }
 
   /** Starts a sign-in: the provider URL to redirect to and the state for the voice_oidc cookie. */
   async login(next: string | null): Promise<{ location: string; state: string }> {
     const doc = await this.discover()
-    this.sweep()
+    if ((await this.counters.incr(STARTED_KEY, OIDC_PENDING_TTL_MS)) > MAX_PENDING) {
+      throw new OidcError(429, "Too many sign-ins are in progress. Please try again in a few minutes.", "too many pending sign-ins")
+    }
     const state = random()
     const nonce = random()
     const verifier = random()
-    while (this.pending.size >= MAX_PENDING) this.pending.delete(this.pending.keys().next().value!)
-    this.pending.set(state, { nonce, verifier, next: safeNext(next), expiresAt: this.now() + OIDC_PENDING_TTL_MS })
+    const pending: Pending = { nonce, verifier, next: safeNext(next), expiresAt: this.now() + OIDC_PENDING_TTL_MS }
+    await this.kv.set(PENDING_KEY(state), JSON.stringify(pending), { px: OIDC_PENDING_TTL_MS })
     const url = new URL(doc.authorization_endpoint)
     url.searchParams.set("response_type", "code")
     url.searchParams.set("client_id", this.config.clientId)
@@ -166,13 +181,11 @@ export class OidcClient {
    * pending entry is consumed whatever the outcome once the state matches the cookie.
    */
   async callback(params: URLSearchParams, cookieState: string | undefined): Promise<{ identity: OidcIdentity; next: string }> {
-    this.sweep()
     const state = params.get("state") ?? ""
-    const pending = state && cookieState === state ? this.pending.get(state) : undefined
+    const pending = state && cookieState === state ? await this.consume(state) : undefined
     if (!pending) {
       throw new OidcError(400, "This sign-in has expired or was already used. Please sign in again.", "state invalid")
     }
-    this.pending.delete(state)
     const providerError = params.get("error")
     if (providerError) {
       const description = params.get("error_description")
@@ -270,9 +283,16 @@ export class OidcClient {
     }
   }
 
-  private sweep(): void {
-    const t = this.now()
-    for (const [state, entry] of this.pending) if (entry.expiresAt <= t) this.pending.delete(state)
+  /** Takes a pending sign-in out of the Kv (GETDEL: one callback wins, on any pod); undefined when unknown or expired. */
+  private async consume(state: string): Promise<Pending | undefined> {
+    const raw = await this.kv.getdel(PENDING_KEY(state))
+    if (raw === undefined) return undefined
+    try {
+      const pending = JSON.parse(raw) as Pending
+      return pending.expiresAt > this.now() ? pending : undefined
+    } catch {
+      return undefined
+    }
   }
 }
 

package/src/central/push-target.ts

@@ -1,7 +1,10 @@
-// Push endpoints come from browsers, and the hub POSTs to them: without checks a subscription could make the
-// hub send requests into its own network (SSRF). An endpoint must be https on a public hostname; hosts are
-// resolved at subscribe time and rejected when any address is loopback, private, link-local, CGNAT, ULA,
-// unspecified or multicast. Real push services (FCM, Mozilla, Apple, WNS) are public names on public addresses.
+// URLs users give the hub (push endpoints from browsers, webhook URLs from apps) are URLs the hub POSTs to: without
+// checks a subscription could make the hub send requests into its own network (SSRF). publicURLProblem: https on a
+// public hostname whose every resolved address is public (not loopback, private, link-local, CGNAT, ULA,
+// unspecified or multicast); an admin opt-in (allowPrivate, webhooks only) admits http and private targets.
+// Push checks endpoints at subscribe time (real push services are public names on public addresses); webhooks
+// send through publicFetch, which re-checks (and re-resolves) right before every request, never follows a
+// redirect, times out and reads a bounded body.
 import { lookup } from "node:dns/promises"
 import { isIPv4, isIPv6 } from "node:net"
 
@@ -10,7 +13,7 @@ export type ResolveHost = (host: string) => Promise<readonly string[]>
 /** Every address the system resolver returns for a host. */
 export const resolveHost: ResolveHost = async (host) => (await lookup(host, { all: true, verbatim: true })).map((a) => a.address)
 
-/** IPv4 [network, prefix length] blocks that never reach a public push service. */
+/** IPv4 [network, prefix length] blocks that are never a public service. */
 const V4_BLOCKED: ReadonlyArray<readonly [string, number]> = [
   ["0.0.0.0", 8], // "this network", unspecified
   ["10.0.0.0", 8], // private
@@ -47,7 +50,7 @@ function v6Groups(ip: string): number[] {
   return [...left, ...fill, ...right].map((g) => parseInt(g, 16))
 }
 
-/** True for addresses a push endpoint must not resolve to. Anything that is not an IP counts as private. */
+/** True for addresses a public URL must not resolve to. Anything that is not an IP counts as private. */
 export function isPrivateAddress(address: string): boolean {
   const ip = address.trim().replace(/^\[(.*)\]$/, "$1")
   if (isIPv4(ip)) return privateV4(ip)
@@ -70,28 +73,125 @@ export function isPrivateAddress(address: string): boolean {
 
 const LOCAL_SUFFIXES = [".localhost", ".local", ".internal", ".localdomain", ".home.arpa", ".lan"]
 
-/** Why an endpoint is not acceptable for Web Push, or undefined when it is. */
-export async function pushEndpointProblem(endpoint: string, resolve: ResolveHost): Promise<string | undefined> {
+export interface PublicURLOptions {
+  readonly resolve: ResolveHost
+  /** How problems name the URL (default "URL"). */
+  readonly label?: string
+  /**
+   * The admin opt-in for private targets (hub.json agents.webhooks.allowPrivate): http, loopback, private
+   * addresses and local names pass without a lookup. Other schemes and credentials still fail.
+   */
+  readonly allowPrivate?: boolean
+}
+
+/** Why the hub must not send to a URL (SSRF), or undefined when it may. */
+export async function publicURLProblem(raw: string, options: PublicURLOptions): Promise<string | undefined> {
+  const label = options.label ?? "URL"
   let url: URL
   try {
-    url = new URL(endpoint)
+    url = new URL(raw)
   } catch {
-    return "Push endpoint is not a URL"
+    return `${label} is not a URL`
   }
-  if (url.protocol !== "https:") return "Push endpoint must be https"
-  if (url.username || url.password) return "Push endpoint must not carry credentials"
+  if (options.allowPrivate) {
+    if (url.protocol !== "https:" && url.protocol !== "http:") return `${label} must be http or https`
+  } else if (url.protocol !== "https:") return `${label} must be https`
+  if (url.username || url.password) return `${label} must not carry credentials`
+  if (options.allowPrivate) return undefined
   const host = url.hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1").replace(/\.$/, "")
-  if (isIPv4(host) || isIPv6(host)) return isPrivateAddress(host) ? "Push endpoint is a private or local address" : undefined
+  if (isIPv4(host) || isIPv6(host)) return isPrivateAddress(host) ? `${label} is a private or local address` : undefined
   if (host === "localhost" || !host.includes(".") || LOCAL_SUFFIXES.some((suffix) => host.endsWith(suffix))) {
-    return "Push endpoint is a local hostname"
+    return `${label} is a local hostname`
   }
   let addresses: readonly string[]
   try {
-    addresses = await resolve(host)
+    addresses = await options.resolve(host)
   } catch {
-    return `Push endpoint host ${host} does not resolve`
+    return `${label} host ${host} does not resolve`
   }
-  if (addresses.length === 0) return `Push endpoint host ${host} does not resolve`
-  if (addresses.some(isPrivateAddress)) return "Push endpoint resolves to a private or local address"
+  if (addresses.length === 0) return `${label} host ${host} does not resolve`
+  if (addresses.some(isPrivateAddress)) return `${label} resolves to a private or local address`
   return undefined
 }
+
+/** Why an endpoint is not acceptable for Web Push, or undefined when it is. */
+export async function pushEndpointProblem(endpoint: string, resolve: ResolveHost): Promise<string | undefined> {
+  return publicURLProblem(endpoint, { resolve, label: "Push endpoint" })
+}
+
+/** The URL failed publicURLProblem at send time; nothing was sent. */
+export class PublicURLError extends Error {
+  constructor(readonly problem: string) {
+    super(problem)
+    this.name = "PublicURLError"
+  }
+}
+
+export interface PublicFetchOptions extends PublicURLOptions {
+  /** For the whole exchange, body included. */
+  readonly timeoutMs: number
+  /** Bytes of the response body read at most; the rest is discarded. */
+  readonly maxBytes: number
+  readonly fetch?: typeof globalThis.fetch
+}
+
+export interface PublicFetchResult {
+  readonly status: number
+  /** The first maxBytes of the body (UTF-8, lossy). */
+  readonly body: string
+  readonly truncated: boolean
+}
+
+/**
+ * One request to a user-supplied URL: the URL is checked (and its host re-resolved) right before sending, so a
+ * name that changed to a private address since registration is refused; redirects are never followed (a 3xx is
+ * returned as is); the timeout covers the body; at most maxBytes of the body are read.
+ * A rebinding between this lookup and fetch's own remains possible; private targets need the admin opt-in.
+ */
+export async function publicFetch(
+  url: string,
+  init: { readonly method: string; readonly headers?: Record<string, string>; readonly body: string },
+  options: PublicFetchOptions,
+): Promise<PublicFetchResult> {
+  const problem = await publicURLProblem(url, options)
+  if (problem) throw new PublicURLError(problem)
+  const controller = new AbortController()
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    controller.abort()
+  }, options.timeoutMs)
+  try {
+    const response = await (options.fetch ?? globalThis.fetch)(url, { ...init, redirect: "manual", signal: controller.signal })
+    const { body, truncated } = await readCapped(response, options.maxBytes)
+    return { status: response.status, body, truncated }
+  } catch (cause) {
+    if (timedOut) throw new Error(`timed out after ${options.timeoutMs} ms`)
+    throw cause
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+async function readCapped(response: Response, maxBytes: number): Promise<{ body: string; truncated: boolean }> {
+  if (!response.body) return { body: "", truncated: false }
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  let truncated = false
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    const room = maxBytes - size
+    if (value.byteLength > room) {
+      chunks.push(value.subarray(0, room))
+      size = maxBytes
+      truncated = true
+      await reader.cancel().catch(() => {})
+      break
+    }
+    chunks.push(value)
+    size += value.byteLength
+  }
+  return { body: Buffer.concat(chunks).toString("utf8"), truncated }
+}