@huynle/hub 0.8.2 → 0.8.3

package/src/central/recording/ingest.ts

@@ -0,0 +1,209 @@
+// REC-01 event ingest (contract: Events). Console batches: idempotent by seq (seq ≤ consoleThrough dropped, a
+// later first seq counted as a gap), one page blob per batch under index key c<firstNewSeq> written with
+// ifVersion 0 (an existing key is a page stored before a crash: treated as stored), then the record CAS-updated.
+// Hub events: buffered per pod and recording, written as pages of up to hubFlushEvents every hubFlushMs (and at
+// end and drain) under h<podTag>-<n>; a pod that dies loses at most its last hubFlushMs of hub events.
+import { type ConsoleEvent, type HubEventKind, RECORDING_LIMITS, type RecordingEvent } from "../../protocol"
+import { BlobQuotaError } from "../artifacts/blob-store"
+import type { Clock, Timers } from "../backend/types"
+import { consoleRecord, hubRecord } from "./schema"
+import { consoleKey, hubKey, type RecordingRecord, type RecordingStore } from "./store"
+
+const L = RECORDING_LIMITS
+/** Event pages may exceed the audio cap (events continue while audio is capped): headroom for every active recording. */
+export const PAGE_QUOTA_BYTES = L.userBytes + L.activePerUser * L.eventBytesPerRecording
+/** Room past PAGE_QUOTA_BYTES for the end markers of a recording whose user filled the page quota. */
+export const CONTROL_HEADROOM_BYTES = 1024 * 1024
+const CONTROL_KINDS = new Set<string>(["cap.reached", "recording.ended", "error"])
+/** A page is the batch plus the envelope the hub adds (≈ 50 bytes per event). */
+const PAGE_MAX_BYTES = L.batchBytes + L.eventsPerBatch * 128
+
+const encoder = new TextEncoder()
+export const ndjson = (events: readonly RecordingEvent[]) => encoder.encode(events.map((e) => JSON.stringify(e)).join("\n") + "\n")
+
+export type ConsoleIngest =
+  | { readonly kind: "stored"; readonly record: RecordingRecord }
+  | { readonly kind: "limit" }
+  /** The user's event-page quota (PAGE_QUOTA_BYTES) is full. */
+  | { readonly kind: "quota" }
+  | { readonly kind: "gone" }
+
+/** Stores a checked console batch for a recording that accepts appends. */
+export async function ingestConsole(store: RecordingStore, userID: string, record: RecordingRecord, events: readonly ConsoleEvent[], now: Clock): Promise<ConsoleIngest> {
+  const fresh = events.filter((e) => e.seq > record.consoleThrough)
+  if (!fresh.length) return { kind: "stored", record }
+  const at = now()
+  const records = fresh.map((e) => consoleRecord(e, at))
+  const page = ndjson(records)
+  if (record.events + records.length > L.eventsPerRecording || record.eventBytes + page.length > L.eventBytesPerRecording) return { kind: "limit" }
+  const first = fresh[0]!.seq
+  const last = fresh.at(-1)!.seq
+  let ref
+  try {
+    ref = await store.putBlob(userID, page, "application/x-ndjson", PAGE_MAX_BYTES, PAGE_QUOTA_BYTES)
+  } catch (cause) {
+    if (cause instanceof BlobQuotaError) return { kind: "quota" }
+    throw cause
+  }
+  // An existing key: the page of a batch whose record update was lost (a crash); it holds these events.
+  if (!(await store.putIndex(userID, record.id, consoleKey(first), { hash: ref.hash, bytes: ref.bytes, first, last, at }))) {
+    const existing = await store.indexEntry<{ hash?: string }>(userID, record.id, consoleKey(first))
+    if (existing?.hash !== ref.hash) await store.dropIfUnindexed(userID, ref.hash, at)
+  }
+  const redacted = records.filter((e) => e.redacted?.length).length
+  const updated = await store.update(userID, record.id, (current) => {
+    if (current.state === "deleting" || current.consoleThrough >= last) return undefined
+    const gap = Math.max(0, first - (current.consoleThrough + 1))
+    return {
+      ...current,
+      consoleThrough: last,
+      consoleGaps: current.consoleGaps + gap,
+      events: current.events + records.length,
+      eventBytes: current.eventBytes + ref.bytes,
+      bytes: current.bytes + ref.bytes,
+      pages: current.pages + 1,
+      redactions: current.redactions + redacted,
+      lastEventAt: at,
+    }
+  })
+  // A deletion that ran meanwhile did not see this page: undo it (delete is real).
+  if (await store.undoIfDeleted(userID, record.id, consoleKey(first), ref.hash)) return { kind: "gone" }
+  if (!updated) return { kind: "gone" }
+  return { kind: "stored", record: updated.record }
+}
+
+interface Pending {
+  readonly userID: string
+  readonly recordingID: string
+  events: RecordingEvent[]
+  timer?: unknown
+  writing?: Promise<void>
+}
+
+export interface HubWriterOptions {
+  readonly store: RecordingStore
+  readonly now: Clock
+  /** Unique per process: page keys and event IDs never collide across pods or restarts. */
+  readonly podTag: string
+  readonly timers?: Timers
+  readonly flushMs?: number
+  readonly flushEvents?: number
+  /** A write failed (logged without content or IDs by the caller). */
+  readonly failed?: (cause: unknown) => void
+  /** A hub page would pass the recording's event caps, or the user's page quota is full: the recording ends (limit). */
+  readonly overLimit?: (userID: string, recordingID: string, scope: "recording" | "user") => void
+}
+
+const realTimers: Timers = {
+  set: (fn, ms) => {
+    const t = setTimeout(fn, ms)
+    ;(t as { unref?: () => void }).unref?.()
+    return t
+  },
+  clear: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+}
+
+export class HubEventWriter {
+  private readonly pending = new Map<string, Pending>()
+  private n = 0
+  private pages = 0
+  private readonly timers: Timers
+
+  constructor(private readonly options: HubWriterOptions) {
+    this.timers = options.timers ?? realTimers
+  }
+
+  /** Buffers a hub event for one recording (scrubbed and cut now, written with the next page). */
+  add(userID: string, recordingID: string, kind: HubEventKind, fields: Record<string, unknown>, at = this.options.now()): void {
+    const key = `${userID}\n${recordingID}`
+    let p = this.pending.get(key)
+    if (!p) this.pending.set(key, (p = { userID, recordingID, events: [] }))
+    p.events.push(hubRecord(kind, fields, { id: `${this.options.podTag}.${++this.n}`, at }))
+    if (p.events.length >= (this.options.flushEvents ?? L.hubFlushEvents)) void this.flushOne(key)
+    else if (p.timer === undefined) p.timer = this.timers.set(() => void this.flushOne(key), this.options.flushMs ?? L.hubFlushMs)
+  }
+
+  /** Writes the buffered events of one recording (all when omitted). */
+  async flush(userID?: string, recordingID?: string): Promise<void> {
+    const keys = userID !== undefined && recordingID !== undefined ? [`${userID}\n${recordingID}`] : [...this.pending.keys()]
+    await Promise.all(keys.map((key) => this.flushOne(key)))
+  }
+
+  /** Drops what a recording buffered (it is being deleted). */
+  discard(userID: string, recordingID: string): void {
+    const p = this.pending.get(`${userID}\n${recordingID}`)
+    if (p?.timer !== undefined) this.timers.clear(p.timer)
+    this.pending.delete(`${userID}\n${recordingID}`)
+  }
+
+  private async flushOne(key: string): Promise<void> {
+    const p = this.pending.get(key)
+    if (!p) return
+    // One write at a time per recording, in order.
+    while (p.writing) await p.writing
+    if (p.timer !== undefined) this.timers.clear(p.timer)
+    p.timer = undefined
+    const events = p.events.splice(0, this.options.flushEvents ?? L.hubFlushEvents)
+    if (!events.length) {
+      if (this.pending.get(key) === p) this.pending.delete(key)
+      return
+    }
+    const run = this.write(p.userID, p.recordingID, events).catch((cause) => this.options.failed?.(cause))
+    p.writing = run
+    await run
+    p.writing = undefined
+    if (p.events.length) await this.flushOne(key)
+    else if (this.pending.get(key) === p && p.timer === undefined) this.pending.delete(key)
+  }
+
+  private async write(userID: string, recordingID: string, events: RecordingEvent[]): Promise<void> {
+    const { store } = this.options
+    const got = await store.get(userID, recordingID)
+    if (!got || got.value.state === "deleting") return
+    // An ended recording takes only what happened up to its end (its recording.ended included): a pod whose active
+    // index is stale (the bus message missed or late) never adds events after it.
+    const endedAt = got.value.state === "ended" ? got.value.endedAt : undefined
+    if (endedAt !== undefined) events = events.filter((e) => (e.at ?? 0) <= endedAt)
+    if (!events.length) return
+    let page = ndjson(events)
+    if (got.value.events + events.length > L.eventsPerRecording || got.value.eventBytes + page.length > L.eventBytesPerRecording) {
+      this.options.overLimit?.(userID, recordingID, "recording")
+      return
+    }
+    let ref
+    try {
+      ref = await store.putBlob(userID, page, "application/x-ndjson", PAGE_MAX_BYTES, PAGE_QUOTA_BYTES)
+    } catch (cause) {
+      if (!(cause instanceof BlobQuotaError)) throw cause
+      // The page quota is full: the end markers (cap.reached, recording.ended, errors) still go, in a small headroom,
+      // so the export says why the recording stopped; the rest is dropped.
+      const control = events.filter((e) => CONTROL_KINDS.has(e.kind))
+      if (control.length) {
+        events = control
+        page = ndjson(events)
+        ref = await store.putBlob(userID, page, "application/x-ndjson", PAGE_MAX_BYTES, PAGE_QUOTA_BYTES + CONTROL_HEADROOM_BYTES).catch(() => undefined)
+      }
+      if (!control.some((e) => e.kind === "recording.ended")) this.options.overLimit?.(userID, recordingID, "user")
+      if (!ref) return
+    }
+    const at = this.options.now()
+    const key = hubKey(this.options.podTag, ++this.pages)
+    await store.putIndex(userID, recordingID, key, { hash: ref.hash, bytes: ref.bytes, count: events.length, at })
+    const redacted = events.filter((e) => e.redacted?.length).length
+    await store.update(userID, recordingID, (current) =>
+      current.state === "deleting"
+        ? undefined
+        : {
+            ...current,
+            events: current.events + events.length,
+            eventBytes: current.eventBytes + ref.bytes,
+            bytes: current.bytes + ref.bytes,
+            hubPages: current.hubPages + 1,
+            pages: current.pages + 1,
+            redactions: current.redactions + redacted,
+          },
+    )
+    // A deletion that ran meanwhile did not see this page: undo it.
+    await store.undoIfDeleted(userID, recordingID, key, ref.hash)
+  }
+}

package/src/central/recording/retention.ts

@@ -0,0 +1,71 @@
+// REC-01 retention sweep (contract: Limits and caps → Retention sweep). Runs on the `voice-recordings` leader
+// every sweepMs (first run one interval after election) over every user: finishes deletions, deletes expired
+// recordings (active ones are ended `stale` first), ends idle and over-long active ones. One user's failure is
+// logged without IDs and the run goes on.
+import { RECORDING_LIMITS } from "../../protocol"
+
+export interface RetentionOptions {
+  readonly users: () => Promise<readonly string[]>
+  /** Sweeps one user; answers how many expired recordings it deleted. */
+  readonly sweepUser: (userID: string) => Promise<number>
+  readonly sweepMs?: number
+  readonly log?: (message: string) => void
+}
+
+export class RecordingRetention {
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private running: Promise<number> | undefined
+  private started = false
+
+  constructor(private readonly options: RetentionOptions) {}
+
+  start(): void {
+    if (this.started) return
+    this.started = true
+    this.schedule()
+  }
+
+  stop(): void {
+    this.started = false
+    if (this.timer !== undefined) clearTimeout(this.timer)
+    this.timer = undefined
+  }
+
+  /** One pass over every user (concurrent calls share it); answers the expired recordings deleted. */
+  runOnce(): Promise<number> {
+    this.running ??= this.pass().finally(() => (this.running = undefined))
+    return this.running
+  }
+
+  /** Waits for a pass in progress. */
+  async idle(): Promise<void> {
+    await this.running?.catch(() => undefined)
+  }
+
+  private schedule(): void {
+    if (!this.started) return
+    this.timer = setTimeout(() => {
+      void this.runOnce().finally(() => this.schedule())
+    }, this.options.sweepMs ?? RECORDING_LIMITS.sweepMs)
+    ;(this.timer as { unref?: () => void }).unref?.()
+  }
+
+  private async pass(): Promise<number> {
+    let total = 0
+    let users: readonly string[] = []
+    try {
+      users = await this.options.users()
+    } catch (cause) {
+      this.options.log?.(`[hub] recording sweep could not list users: ${(cause as Error).message}`)
+      return 0
+    }
+    for (const userID of users) {
+      try {
+        total += await this.options.sweepUser(userID)
+      } catch (cause) {
+        this.options.log?.(`[hub] recording sweep failed for a user: ${(cause as Error).message}`)
+      }
+    }
+    return total
+  }
+}

package/src/central/recording/routes.ts

@@ -0,0 +1,281 @@
+// REC-01 recording routes (contract: Setting and indicator, Recordings, Audio, List/read/export/delete). Every route
+// is a console route with access "user": the user's cookie or device token only (the hub refuses session, app and
+// act tokens before these run), so no agent, not even the Concierge, can read or export a recording, and there is
+// no admin route. Every lookup is by (user.id, id); another user's, an unknown and a deleted ID answer 404 alike.
+import { RECORDING_AUDIO_TYPE, RECORDING_LIMITS, type RecordingClient } from "../../protocol"
+import { readBounded } from "../agent/body"
+import { checkConsoleBatch } from "./schema"
+import { audioKey, blobTenant, isSegmentNumber, summaryOf, type AudioEntry } from "./store"
+import { exportEntries } from "./export"
+import type { RecordingService, StartInput } from "./index"
+import { zipStream } from "./zip"
+
+const L = RECORDING_LIMITS
+const NO_STORE = { "cache-control": "no-store" }
+const PRIVATE = { "cache-control": "private, no-store", "x-content-type-options": "nosniff", "content-security-policy": "default-src 'none'; sandbox" }
+const JSON_MAX = 64 * 1024
+
+export interface RecordingRouteContext {
+  readonly request: Request
+  readonly url: URL
+  readonly params: Record<string, string>
+  readonly user: { readonly id: string }
+  readonly device: { readonly id: string; readonly name?: string }
+}
+
+export interface RecordingRoute {
+  readonly method: string
+  readonly path: string
+  handle(context: RecordingRouteContext): Promise<Response>
+}
+
+const fail = (status: number, error: string, code?: string, extra: Record<string, unknown> = {}) => Response.json({ error, ...(code ? { code } : {}), ...extra }, { status, headers: NO_STORE })
+const notFound = () => fail(404, "Not found")
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+class BadInput extends Error {}
+
+/** The body's bytes within `max` (413 limit beyond), or a Response to answer. */
+async function bytesOf(request: Request, max: number): Promise<Uint8Array | Response> {
+  const read = await readBounded(request, max)
+  if (read.ok) return read.bytes
+  if (read.reason === "timeout") return fail(408, "Request body too slow")
+  return Response.json({ error: `Request body too large (at most ${max} bytes)`, code: "limit" }, { status: 413, headers: { ...NO_STORE, ...(read.close ? { connection: "close" } : {}) } })
+}
+
+async function jsonOf(request: Request, max = JSON_MAX): Promise<Record<string, unknown> | Response> {
+  const bytes = await bytesOf(request, max)
+  if (bytes instanceof Response) return bytes
+  let value: unknown
+  try {
+    value = bytes.length ? JSON.parse(Buffer.from(bytes).toString("utf8")) : {}
+  } catch {
+    return fail(400, "Invalid JSON", "invalid")
+  }
+  return isRecord(value) ? value : fail(400, "Expected a JSON object", "invalid")
+}
+
+function only(input: Record<string, unknown>, allowed: readonly string[], where = ""): void {
+  for (const key of Object.keys(input)) if (!allowed.includes(key)) throw new BadInput(`unknown field ${where}${/^[A-Za-z0-9_-]{1,40}$/.test(key) ? key : "?"}`)
+}
+
+const text = (v: unknown, max: number, name: string): string => {
+  if (typeof v !== "string" || !v || v.length > max) throw new BadInput(`${name} must be text of 1–${max} characters`)
+  return v
+}
+
+/** POST /api/recordings body (strict). */
+function startInput(input: Record<string, unknown>): StartInput {
+  only(input, ["sessionID", "clientID", "anchor", "client"])
+  const sessionID = text(input.sessionID, 300, "sessionID")
+  const clientID = text(input.clientID, 100, "clientID")
+  if (!/^[A-Za-z0-9_-]+$/.test(clientID)) throw new BadInput("clientID must be an ID (letters, digits, - and _)")
+  let anchor: StartInput["anchor"]
+  if (input.anchor !== undefined) {
+    if (!isRecord(input.anchor)) throw new BadInput("anchor must be {perf, epoch}")
+    only(input.anchor, ["perf", "epoch"], "anchor.")
+    const { perf, epoch } = input.anchor
+    if (typeof perf !== "number" || !Number.isFinite(perf) || perf < 0 || typeof epoch !== "number" || !Number.isFinite(epoch)) throw new BadInput("anchor must be {perf, epoch}: finite numbers")
+    anchor = { perf, epoch }
+  }
+  let client: RecordingClient | undefined
+  if (input.client !== undefined) {
+    if (!isRecord(input.client)) throw new BadInput("client must be an object")
+    const c = input.client
+    only(c, ["app", "platform", "detector", "sensitivity", "cues", "background", "streaming", "timings"], "client.")
+    const label = (v: unknown, name: string) => (v === undefined ? undefined : text(v, 60, name))
+    const flag = (v: unknown, name: string) => {
+      if (v !== undefined && typeof v !== "boolean") throw new BadInput(`${name} must be true or false`)
+      return v as boolean | undefined
+    }
+    if (c.detector !== undefined && c.detector !== "silero" && c.detector !== "energy") throw new BadInput("client.detector must be silero or energy")
+    if (c.sensitivity !== undefined && !["low", "normal", "high"].includes(c.sensitivity as string)) throw new BadInput("client.sensitivity must be low, normal or high")
+    let timings: Record<string, number> | undefined
+    if (c.timings !== undefined) {
+      if (!isRecord(c.timings) || Object.keys(c.timings).length > 20) throw new BadInput("client.timings must be at most 20 numbers")
+      timings = {}
+      for (const [key, value] of Object.entries(c.timings)) {
+        if (!/^[A-Za-z0-9_]{1,40}$/.test(key) || typeof value !== "number" || !Number.isFinite(value)) throw new BadInput("client.timings must map names to numbers")
+        timings[key] = value
+      }
+    }
+    const entries = {
+      app: label(c.app, "client.app"),
+      platform: label(c.platform, "client.platform"),
+      detector: c.detector as RecordingClient["detector"],
+      sensitivity: c.sensitivity as RecordingClient["sensitivity"],
+      cues: flag(c.cues, "client.cues"),
+      background: flag(c.background, "client.background"),
+      streaming: flag(c.streaming, "client.streaming"),
+      timings,
+    }
+    client = Object.fromEntries(Object.entries(entries).filter(([, v]) => v !== undefined)) as RecordingClient
+  }
+  return { sessionID, clientID, ...(anchor ? { anchor } : {}), ...(client ? { client } : {}) }
+}
+
+const utcDate = (ms: number) => new Date(ms).toISOString().slice(0, 10)
+
+/** A zip response; the export slot is released when the stream ends or is cancelled. */
+function zipResponse(stream: ReadableStream<Uint8Array>, name: string, release: () => void): Response {
+  const reader = stream.getReader()
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read()
+        if (done) {
+          release()
+          controller.close()
+        } else controller.enqueue(value)
+      } catch (cause) {
+        release()
+        controller.error(cause)
+      }
+    },
+    async cancel(reason) {
+      release()
+      await reader.cancel(reason).catch(() => undefined)
+    },
+  })
+  return new Response(body, { headers: { ...PRIVATE, "content-type": "application/zip", "content-disposition": `attachment; filename="${name}"` } })
+}
+
+export function recordingRoutes(service: RecordingService, options: { readonly version: string; readonly now: () => number; readonly audit: (entry: { actor: string; action: string; target?: string; detail?: string }) => Promise<void> }): RecordingRoute[] {
+  const handled = (handle: RecordingRoute["handle"]): RecordingRoute["handle"] => async (context) => {
+    try {
+      return await handle(context)
+    } catch (cause) {
+      if (cause instanceof BadInput) return fail(400, cause.message, "invalid")
+      throw cause
+    }
+  }
+  const route = (method: string, path: string, handle: RecordingRoute["handle"]): RecordingRoute => ({ method, path, handle: handled(handle) })
+
+  const exportOf = async (userID: string, ids: "all" | string): Promise<Response> => {
+    const records = ids === "all" ? (await service.list(userID)).reverse() : [await service.visible(userID, ids)].filter((r) => r !== undefined)
+    if (ids !== "all" && !records.length) return notFound()
+    const release = service.exportSlot(userID)
+    if (!release) return fail(429, "Two exports are already running; wait for one to finish", "rate_limited")
+    await service.flush()
+    await options.audit({ actor: userID, action: "recording.export", target: ids, detail: String(records.length) })
+    const stream = zipStream(exportEntries(service.store, userID, records, ids !== "all", { version: options.version, now: options.now }))
+    return zipResponse(stream, `hub-voice-${ids}-${utcDate(options.now())}.zip`, release)
+  }
+
+  const segmentNumber = (raw: string | undefined): number => {
+    if (!raw || !/^\d{1,6}$/.test(raw)) throw new BadInput("segment must be a number 0–999999")
+    const n = Number(raw)
+    if (!isSegmentNumber(n)) throw new BadInput("segment must be a number 0–999999")
+    return n
+  }
+
+  return [
+    route("GET", "/api/settings/recording", async ({ user }) =>
+      Response.json({ settings: await service.settings.get(user.id), usage: await service.usage(user.id), limits: { retentionDays: L.retentionMs / 86_400_000, userBytes: L.userBytes, recordingBytes: L.recordingBytes } }, { headers: NO_STORE }),
+    ),
+    route("PUT", "/api/settings/recording", async ({ request, user, device }) => {
+      const input = await jsonOf(request)
+      if (input instanceof Response) return input
+      only(input, ["enabled", "expectedRevision"])
+      if (typeof input.enabled !== "boolean" || !Number.isSafeInteger(input.expectedRevision) || (input.expectedRevision as number) < 0) {
+        throw new BadInput("Expected {enabled: boolean, expectedRevision: number}")
+      }
+      const result = await service.setEnabled(user.id, device.id, input.enabled, input.expectedRevision as number)
+      if (!result.ok) return fail(409, "The setting changed meanwhile; reload it", "conflict", { currentRevision: result.currentRevision })
+      return Response.json({ settings: result.settings }, { headers: NO_STORE })
+    }),
+    route("POST", "/api/recordings", async ({ request, user, device }) => {
+      const input = await jsonOf(request)
+      if (input instanceof Response) return input
+      const started = await service.start(user.id, device, startInput(input))
+      switch (started.kind) {
+        case "off":
+          return fail(409, "Recording is off in Settings → Voice", "recording_off")
+        case "not_found":
+          return notFound()
+        case "rate_limited":
+          return fail(429, `At most ${L.activePerUser} recordings run at once`, "rate_limited", { limit: L.activePerUser })
+        case "limit":
+          return fail(429, `At most ${L.recordingsStored} recordings are kept; delete some in Settings → Voice`, "limit", { limit: L.recordingsStored })
+      }
+      const record = started.record
+      return Response.json({ recording: summaryOf(record), audio: record.audio, hubAt: options.now() }, { status: started.kind === "created" ? 201 : 200, headers: NO_STORE })
+    }),
+    route("GET", "/api/recordings", async ({ url, user }) => {
+      const limitRaw = url.searchParams.get("limit")
+      const limit = limitRaw === null ? 50 : Number(limitRaw)
+      if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new BadInput("limit must be 1–200")
+      const cursor = url.searchParams.get("cursor")
+      let start = 0
+      if (cursor !== null) {
+        const decoded = Number(Buffer.from(cursor, "base64url").toString("utf8"))
+        if (!Number.isSafeInteger(decoded) || decoded < 0 || cursor.length > 40) throw new BadInput("cursor is not valid")
+        start = decoded
+      }
+      const all = await service.list(user.id)
+      const page = all.slice(start, start + limit)
+      const next = start + limit < all.length ? Buffer.from(String(start + limit), "utf8").toString("base64url") : undefined
+      return Response.json({ recordings: page.map(summaryOf), usage: await service.usage(user.id), ...(next ? { next } : {}) }, { headers: NO_STORE })
+    }),
+    // Before /:id (the pattern would take "export" as an ID).
+    route("GET", "/api/recordings/export", ({ user }) => exportOf(user.id, "all")),
+    route("DELETE", "/api/recordings", async ({ user }) => Response.json({ deleted: await service.deleteAll(user.id) }, { headers: NO_STORE })),
+    route("GET", "/api/recordings/:id", async ({ params, user }) => {
+      const record = await service.visible(user.id, params.id!)
+      return record ? Response.json({ recording: summaryOf(record) }, { headers: NO_STORE }) : notFound()
+    }),
+    route("POST", "/api/recordings/:id/end", async ({ request, params, user }) => {
+      const record = await service.visible(user.id, params.id!)
+      if (!record) return notFound()
+      const input = await jsonOf(request)
+      if (input instanceof Response) return input
+      only(input, ["reason"])
+      if (input.reason !== undefined && input.reason !== "stopped" && input.reason !== "conversation_off") throw new BadInput("reason must be stopped or conversation_off")
+      const after = await service.end(user.id, record.id, (input.reason as "stopped" | "conversation_off" | undefined) ?? "stopped")
+      return after ? Response.json({ recording: summaryOf(after) }, { headers: NO_STORE }) : notFound()
+    }),
+    route("POST", "/api/recordings/:id/events", async ({ request, params, user, device }) => {
+      const appendable = await service.appendable(user.id, device.id, params.id!)
+      if (appendable.kind === "not_found") return notFound()
+      if (appendable.kind === "ended") return fail(409, "This recording has ended", "recording_ended", { reason: appendable.reason })
+      const input = await jsonOf(request, L.batchBytes)
+      if (input instanceof Response) return input
+      only(input, ["events"])
+      const checked = checkConsoleBatch(input.events)
+      if (!checked.ok) return checked.limit ? fail(413, checked.problem, "limit") : fail(400, checked.problem, "invalid", checked.seq !== undefined ? { seq: checked.seq } : {})
+      const appended = await service.appendConsole(user.id, appendable.record, checked.events)
+      if (appended.kind === "not_found") return notFound()
+      if (appended.kind === "limit") return fail(413, "This recording reached its event limit and has ended", "limit")
+      return Response.json({ through: appended.through, hubAt: options.now(), audio: appended.audio }, { headers: NO_STORE })
+    }),
+    route("PUT", "/api/recordings/:id/segments/:n", async ({ request, params, user, device }) => {
+      const appendable = await service.appendable(user.id, device.id, params.id!)
+      if (appendable.kind === "not_found") return notFound()
+      const n = segmentNumber(params.n)
+      if (appendable.kind === "ended") return fail(409, "This recording has ended", "recording_ended", { reason: appendable.reason })
+      const type = request.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase()
+      if (type !== RECORDING_AUDIO_TYPE) return fail(415, `Segments are ${RECORDING_AUDIO_TYPE}`, "unsupported")
+      const bytes = await bytesOf(request, L.segmentBytes)
+      if (bytes instanceof Response) return bytes
+      if (!bytes.length) throw new BadInput("Empty segment")
+      const stored = await service.storeAudio(user.id, appendable.record, n, bytes, "put")
+      if (stored.kind === "cap") return fail(413, "Recording storage is full: audio is not saved", "limit")
+      if (stored.kind === "gone") return notFound()
+      if (stored.kind === "failed") return fail(503, "The segment could not be stored; retry", "unavailable")
+      return Response.json({ segment: { n, bytes: stored.entry.bytes, hash: stored.entry.hash } }, { status: stored.fresh ? 201 : 200, headers: NO_STORE })
+    }),
+    route("GET", "/api/recordings/:id/segments/:n", async ({ params, user }) => {
+      const record = await service.visible(user.id, params.id!)
+      if (!record) return notFound()
+      const n = segmentNumber(params.n)
+      const entry = await service.store.indexEntry<AudioEntry>(user.id, record.id, audioKey(n))
+      const blob = entry ? await service.store.blobs.get(blobTenant(user.id), entry.hash) : undefined
+      if (!blob) return notFound()
+      return new Response(blob.body, {
+        headers: { ...PRIVATE, "content-type": RECORDING_AUDIO_TYPE, "content-length": String(blob.bytes), "cross-origin-resource-policy": "same-origin", "content-disposition": `attachment; filename="${record.id}-${n}.wav"` },
+      })
+    }),
+    route("GET", "/api/recordings/:id/export", async ({ params, user }) => ((await service.visible(user.id, params.id!)) ? exportOf(user.id, params.id!) : notFound())),
+    route("DELETE", "/api/recordings/:id", async ({ params, user }) => ((await service.deleteOne(user.id, params.id!)) ? new Response(null, { status: 204 }) : notFound())),
+  ]
+}