@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.51

package/server-managed/github-pulls.ts

@@ -0,0 +1,227 @@
+import { type GithubFixRef, type GithubFixResult, type GithubFixStatus, githubIssueClosedReason, isGithubRepoName, parseGithubFixUrl } from '../common/github-pr.ts'
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, TeamReportAccessSnapshot } from './db.ts'
+import type { GithubMetadata, GithubRepositoryVisibility } from './github-metadata.ts'
+import { ensureUserAccessToken } from './github-oauth.ts'
+
+type Metadata = Pick<GithubMetadata, 'title' | 'description' | 'status' | 'stateReason'>
+const MAX_GITHUB_LOOKUPS = 200
+const GITHUB_LOOKUP_TIMEOUT_MS = 10_000
+const GITHUB_METADATA_TTL_MS = 60_000
+const GITHUB_PUBLIC_VISIBILITY_TTL_MS = 60_000
+const GITHUB_PRIVATE_REPOSITORIES_URL = 'https://api.github.com/user/repos?visibility=private&per_page=100&page=1'
+
+type Repository = TeamReportAccessSnapshot['repositories'][number]
+type RepositoryPayload = { id?: unknown; full_name?: unknown; private?: unknown; visibility?: unknown; permissions?: { pull?: unknown } }
+type RepositoryChecks = { remaining: number; verified: Set<string> }
+type RepositoryAccessContext = {
+  db: ManagedDb
+  visibility: GithubRepositoryVisibility[]
+  publicRepos: Set<string>
+  token: string | null
+  signal: AbortSignal
+  fetchImpl: typeof fetch
+  checks: RepositoryChecks
+  includePrivateList?: boolean
+}
+
+function githubRequest(token: string | null): RequestInit {
+  return {
+    headers: {
+      ...(token ? { authorization: `Bearer ${token}` } : {}), accept: 'application/vnd.github+json',
+      'user-agent': 'deepview-triage', 'x-github-api-version': '2022-11-28',
+    },
+    redirect: 'error',
+  }
+}
+
+function repositoryMatches(repo: Repository, body: RepositoryPayload | null): boolean {
+  return body?.id === repo.repoId && typeof body.full_name === 'string' && body.full_name.toLowerCase() === repo.github.toLowerCase()
+}
+
+async function listPrivateRepositories(token: string, signal: AbortSignal, fetchImpl: typeof fetch): Promise<(RepositoryPayload | null)[]> {
+  try {
+    const response = await fetchImpl(GITHUB_PRIVATE_REPOSITORIES_URL, githubRequest(token))
+    if (!response.ok) return []
+    const body = await response.json() as (RepositoryPayload | null)[] | null
+    return Array.isArray(body) && body.length <= 100 && !signal.aborted ? body : []
+  } catch { return [] } // A failed list is unknown access; direct checks can still verify it.
+}
+
+// Public visibility can be reused briefly across users. Private access stays
+// request-local: one page of the viewer's own repo list grants matching repos,
+// then direct checks cover omissions, pagination and failed list requests.
+async function readableRepositories(repositories: Repository[], { db, visibility, publicRepos, token, signal, fetchImpl, checks, includePrivateList = true }: RepositoryAccessContext): Promise<Set<string>> {
+  const readable = new Set(publicRepos)
+  const byId = new Map(repositories.map(repo => [repo.repoId, repo]))
+  const unverified = repositories.filter(repo => !readable.has(repo.github))
+  const updates = new Map<number, GithubRepositoryVisibility>()
+  const grant = (repo: Repository, body: RepositoryPayload, checkedAt: number) => {
+    const isPublic = body.private === false && body.visibility === 'public'
+    readable.add(repo.github)
+    checks.verified.add(repo.github)
+    if (isPublic) publicRepos.add(repo.github)
+    updates.set(repo.repoId, { repoId: repo.repoId, github: repo.github, public: isPublic, checkedAt })
+  }
+  if (includePrivateList && token && unverified.length > 0 && !signal.aborted) {
+    const checkedAt = Date.now()
+    for (const entry of await listPrivateRepositories(token, signal, fetchImpl)) {
+      const repo = typeof entry?.id === 'number' ? byId.get(entry.id) : undefined
+      if (repo && !readable.has(repo.github) && repositoryMatches(repo, entry) && entry?.permissions?.pull === true) grant(repo, entry, checkedAt)
+    }
+  }
+  const formerlyPublic = new Set(visibility.filter(entry => entry.public
+    && byId.get(entry.repoId)?.github.toLowerCase() === entry.github.toLowerCase()).map(entry => entry.repoId))
+  const pending = unverified.filter(repo => !readable.has(repo.github) && (token || formerlyPublic.has(repo.repoId))).slice(0, checks.remaining)
+  checks.remaining -= pending.length
+  for (let i = 0; i < pending.length && !signal.aborted; i += 4) {
+    await Promise.all(pending.slice(i, i + 4).map(async repo => {
+      if (signal.aborted) return
+      const checkedAt = Date.now()
+      try {
+        const response = await fetchImpl(`https://api.github.com/repos/${repo.github}`, githubRequest(token))
+        if (!response.ok) return
+        const body = await response.json() as RepositoryPayload | null
+        if (!signal.aborted && body && repositoryMatches(repo, body)
+          && (token || (body.private === false && body.visibility === 'public'))) grant(repo, body, checkedAt)
+      } catch { /* Unverified access must never expose cached metadata. */ }
+    }))
+  }
+  if (updates.size > 0) await db.setGithubRepositoryVisibility([...updates.values()])
+  return readable
+}
+
+async function verifyPublicRefreshes(config: ManagedConfig, userId: string, repositories: Repository[], context: RepositoryAccessContext): Promise<string | null> {
+  // Cached public metadata needs no credentials. New content uses a viewer
+  // token only after a live check, so privatization cannot publish private data
+  // under an old public grant. Anonymous reads remain available without a token.
+  const { db, publicRepos } = context
+  const token = context.token ?? await ensureUserAccessToken(config, db, userId, Date.now(), context.fetchImpl)
+  if (token) {
+    const currentPublic = new Set<string>()
+    const readable = await readableRepositories(repositories, { ...context, publicRepos: currentPublic, token, includePrivateList: false })
+    for (const repo of repositories) if (readable.has(repo.github) && !currentPublic.has(repo.github)) publicRepos.delete(repo.github)
+  }
+  return token
+}
+
+// ref.repo is always the canonical name from managed_selected_repo, never an
+// owner/repo/path taken from a Fix URL. Redirects cannot move the user token.
+async function fetchMetadata(ref: GithubFixRef, token: string | null, fetchImpl: typeof fetch): Promise<Metadata | null> {
+  try {
+    const response = await fetchImpl(`https://api.github.com/repos/${ref.repo}/${ref.kind === 'pull' ? 'pulls' : 'issues'}/${ref.number}`, githubRequest(token))
+    if (!response.ok) return null
+    const body = await response.json() as { number?: unknown; title?: unknown; body?: unknown; state?: unknown; merged?: unknown;
+      draft?: unknown; base?: { repo?: { full_name?: unknown } }; repository_url?: unknown; pull_request?: unknown; state_reason?: unknown } | null
+    if (body?.number !== ref.number || typeof body.title !== 'string' || !body.title.trim() || body.title.length > 1024
+      || !['open', 'closed'].includes(String(body.state)) || (body.body != null && typeof body.body !== 'string')) return null
+    let status: GithubFixStatus
+    if (ref.kind === 'pull') {
+      if (typeof body.merged !== 'boolean' || typeof body.base?.repo?.full_name !== 'string'
+        || body.base.repo.full_name.toLowerCase() !== ref.repo.toLowerCase()) return null
+      status = body.merged ? 'merged' : body.state === 'closed' ? 'closed' : body.draft === true ? 'draft' : 'open'
+    } else {
+      // The issues API also accepts PR numbers. Do not cache a PR as a closed
+      // ordinary issue: only the pulls API can establish its merged state.
+      if (body.pull_request != null || typeof body.repository_url !== 'string'
+        || body.repository_url.toLowerCase() !== `https://api.github.com/repos/${ref.repo}`.toLowerCase()) return null
+      status = body.state === 'closed' ? 'closed' : 'open'
+    }
+    const stateReason = ref.kind === 'issue' && status === 'closed' ? githubIssueClosedReason(body.state_reason) : null
+    return { title: body.title, description: body.body ?? null, status, stateReason }
+  } catch { return null }
+}
+
+// The workspace handler checks user -> team membership and finding visibility.
+// Shared private metadata also requires this viewer's live GitHub access,
+// including for admins. Only recently verified public repos skip that check.
+export async function lookupFixes(config: ManagedConfig, db: ManagedDb, snapshot: TeamReportAccessSnapshot, urls: string[], fetchImpl: typeof fetch = globalThis.fetch): Promise<GithubFixResult[]> {
+  const allowed = new Map(snapshot.repositories.filter(repo => isGithubRepoName(repo.github)).map(repo => [repo.github.toLowerCase(), repo]))
+  const parsed = urls.map(parseGithubFixUrl)
+  const jobs = new Map<string, GithubFixRef>()
+  const keys = parsed.map(ref => {
+    const repo = ref && allowed.get(ref.repo.toLowerCase())
+    if (!ref || !repo) return null
+    const key = `${repo.repoId}:${ref.kind}:${ref.number}`
+    jobs.set(key, { ...ref, repo: repo.github })
+    return key
+  })
+  if (jobs.size === 0) return []
+  const now = Date.now()
+  const signal = AbortSignal.timeout(GITHUB_LOOKUP_TIMEOUT_MS)
+  const fetchWithinDeadline: typeof fetch = (input, init) => {
+    signal.throwIfAborted()
+    return fetchImpl(input, { ...init, signal })
+  }
+  const repositories = [...new Map([...jobs.values()].map(ref => {
+    const repo = allowed.get(ref.repo.toLowerCase())!
+    return [repo.repoId, repo] as const
+  })).values()]
+  const visibility = await db.listGithubRepositoryVisibility(repositories.map(repo => repo.repoId))
+  const byId = new Map(repositories.map(repo => [repo.repoId, repo]))
+  const publicRepos = new Set(visibility.filter(entry => entry.public && entry.checkedAt <= now
+    && entry.checkedAt + GITHUB_PUBLIC_VISIBILITY_TTL_MS > now
+    && byId.get(entry.repoId)?.github.toLowerCase() === entry.github.toLowerCase()).map(entry => byId.get(entry.repoId)!.github))
+  let token = repositories.some(repo => !publicRepos.has(repo.github))
+    ? await ensureUserAccessToken(config, db, snapshot.user.id, now, fetchWithinDeadline) : null
+  const checks: RepositoryChecks = { remaining: MAX_GITHUB_LOOKUPS, verified: new Set() }
+  const context = { db, visibility, publicRepos, token, signal, fetchImpl: fetchWithinDeadline, checks }
+  const readable = await readableRepositories(repositories, context)
+  const authorized = [...jobs.entries()].filter(([, ref]) => readable.has(ref.repo))
+  const metadata = new Map((await db.listGithubMetadata(authorized.map(([key]) => key))).map(entry => [entry.key, entry]))
+  const lastCheckedAt = (key: string) => {
+    const cached = metadata.get(key)
+    return Math.max(cached?.fetchedAt ?? 0, cached?.attemptedAt ?? 0)
+  }
+  const pending = authorized.filter(([key, ref]) => {
+    const cached = metadata.get(key)
+    // Backfill closed issues cached before closure reasons existed, within the
+    // same authorized/capped queue. Even an unknown reason completes backfill.
+    return !cached || (ref.kind === 'issue' && cached.status === 'closed' && cached.stateReason == null)
+      || (['open', 'draft'].includes(cached.status) && cached.fetchedAt + GITHUB_METADATA_TTL_MS <= now)
+  }).toSorted(([a], [b]) => lastCheckedAt(a) - lastCheckedAt(b)).slice(0, MAX_GITHUB_LOOKUPS)
+  // Only stale/missing, distinct, authorized entries consume the request budget.
+  // Prioritize missing/oldest entries so a large workspace makes progress.
+  if (pending.length > 0) {
+    const publicRefreshes = new Set(pending.filter(([, ref]) => publicRepos.has(ref.repo) && !checks.verified.has(ref.repo)).map(([, ref]) => ref.repo))
+    if (publicRefreshes.size > 0) token = await verifyPublicRefreshes(config, snapshot.user.id, repositories.filter(repo => publicRefreshes.has(repo.github)), context)
+    const fresh: Omit<GithubMetadata, 'attemptedAt'>[] = []
+    const attempted: string[] = []
+    // All waves and access checks share one deadline and four-call limit.
+    for (let i = 0; i < pending.length && !signal.aborted; i += 4) {
+      await Promise.all(pending.slice(i, i + 4).map(async ([key, ref]) => {
+        if (signal.aborted) return
+        if (metadata.has(key)) attempted.push(key)
+        const result = await fetchMetadata(ref, publicRepos.has(ref.repo) && !checks.verified.has(ref.repo) ? null : token, fetchWithinDeadline)
+        if (result) fresh.push({ key, ...result, fetchedAt: Date.now() })
+      }))
+    }
+    // Only started cached reads rotate. Missing entries retain priority, and
+    // jobs skipped by the cap, deadline or absent token keep their place.
+    if (attempted.length > 0) await db.recordGithubMetadataAttempts(attempted, Date.now())
+    if (fresh.length > 0) {
+      await db.setGithubMetadata(fresh)
+      // A concurrent merged result must win over a slower open/closed read.
+      for (const entry of await db.listGithubMetadata(fresh.map(row => row.key))) metadata.set(entry.key, entry)
+    }
+  }
+  if (publicRepos.size > 0) {
+    // Another request may already have discovered a public -> private change
+    // and written new private metadata. Honor that newer visibility observation.
+    const current = await db.listGithubRepositoryVisibility(repositories.filter(repo => publicRepos.has(repo.github)).map(repo => repo.repoId))
+    const stillPublic = new Set(current.filter(entry => entry.public
+      && byId.get(entry.repoId)?.github.toLowerCase() === entry.github.toLowerCase()).map(entry => byId.get(entry.repoId)!.github))
+    for (const [key, ref] of authorized) if (publicRepos.has(ref.repo) && !stillPublic.has(ref.repo)) metadata.delete(key)
+  }
+  // The handler rechecks workspace access and saved Fix links before returning.
+  return urls.flatMap((url, index): GithubFixResult[] => {
+    const key = keys[index]
+    if (!key) return []
+    const found = metadata.get(key)
+    return [found ? { url, title: found.title, description: found.description, status: found.status, stateReason: found.stateReason } : { url, error: 'unavailable' }]
+  })
+}
+
+export function storedFixUrls(fixes: string[]): string[] {
+  return [...new Set(fixes.filter(fix => parseGithubFixUrl(fix)))].toSorted()
+}

package/server-managed/github-requests.ts

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto'
+import { GithubApiError, githubUnreachable, throwGithubResponseError } from './github-errors.ts'
+import { timed } from './request-timing.ts'
+
+const API_VERSION = '2022-11-28'
+export const USER_AGENT = 'deepview-triage'
+
+// Only outstanding reads: a completed answer (or failure) is never reused.
+// Keep transports and credentials separate, including anonymous reads. When
+// full, new reads proceed normally rather than waiting for an unrelated one.
+const MAX_PENDING_READS = 1000
+type PendingRead = { promise: Promise<unknown>; shared: boolean }
+const pendingReads = new WeakMap<typeof fetch, Map<string, PendingRead>>()
+
+// Invalidate installation credentials and access verdicts when GitHub rejects
+// a token, including when several callers share the rejected request.
+const rejectedTokenListeners = new Set<(token: string, fetchImpl: typeof fetch) => void>()
+export function onTokenRejected(listener: (token: string, fetchImpl: typeof fetch) => void): void {
+  rejectedTokenListeners.add(listener)
+}
+export function tokenRejected(token: string, fetchImpl: typeof fetch): void {
+  for (const listener of rejectedTokenListeners) listener(token, fetchImpl)
+}
+
+export async function shareGithubRead<T>(fetchImpl: typeof fetch, request: string, read: () => Promise<T>): Promise<T> {
+  let pending = pendingReads.get(fetchImpl)
+  if (!pending) { pending = new Map(); pendingReads.set(fetchImpl, pending) }
+  // The request includes credentials and query variables. Retain only its hash.
+  const key = createHash('sha256').update(request).digest('hex')
+  const held = pending.get(key)
+  if (held) {
+    held.shared = true
+    return structuredClone(await held.promise) as T
+  }
+  if (pending.size >= MAX_PENDING_READS) return read()
+  const entry: PendingRead = { promise: read(), shared: false }
+  pending.set(key, entry)
+  try {
+    const value = await entry.promise
+    // Independent objects for coalesced callers, without copying large trees
+    // or histories when nobody joined the read.
+    return (entry.shared ? structuredClone(value) : value) as T
+  } finally { pending.delete(key) }
+}
+
+// GitHub's answers to GETs that came with an ETag, by the request (its URL
+// and credential, hashed as outstanding reads are): the next asked again
+// If-None-Match, GitHub checking the credential as ever, and a 304, which
+// it doesn't count against the rate limit, answered by the body kept. Each
+// transport's own, as many as MAX_TAGGED_READS and MAX_TAGGED_BYTES hold,
+// the least recently used first to go; none larger than MAX_TAGGED_READ_BYTES.
+const MAX_TAGGED_READS = 1000
+const MAX_TAGGED_BYTES = 32 * 1024 * 1024
+const MAX_TAGGED_READ_BYTES = 1024 * 1024
+type TaggedRead = { etag: string; text: string }
+const taggedReads = new WeakMap<typeof fetch, { reads: Map<string, TaggedRead>; bytes: number }>()
+const taggedOf = (fetchImpl: typeof fetch) => {
+  let tagged = taggedReads.get(fetchImpl)
+  if (!tagged) taggedReads.set(fetchImpl, tagged = { reads: new Map(), bytes: 0 })
+  return tagged
+}
+const requestKey = (request: string) => createHash('sha256').update(request).digest('hex')
+
+// The answer kept to `request`, its ETag and body as GitHub wrote it.
+export function taggedRead(fetchImpl: typeof fetch, request: string): TaggedRead | undefined {
+  const { reads } = taggedOf(fetchImpl)
+  const key = requestKey(request)
+  const read = reads.get(key)
+  if (read) { reads.delete(key); reads.set(key, read) }
+  return read
+}
+
+// `text` kept as GitHub's answer to `request`, by its ETag.
+export function keepTaggedRead(fetchImpl: typeof fetch, request: string, etag: string, text: string): void {
+  const tagged = taggedOf(fetchImpl)
+  const key = requestKey(request)
+  const before = tagged.reads.get(key)
+  if (before) { tagged.reads.delete(key); tagged.bytes -= before.text.length }
+  if (text.length > MAX_TAGGED_READ_BYTES) return
+  tagged.reads.set(key, { etag, text })
+  tagged.bytes += text.length
+  for (const [oldest, read] of tagged.reads) {
+    if (tagged.reads.size <= MAX_TAGGED_READS && tagged.bytes <= MAX_TAGGED_BYTES) break
+    tagged.reads.delete(oldest)
+    tagged.bytes -= read.text.length
+  }
+}
+
+// One GitHub API call returning parsed JSON, optionally Bearer-authed by a
+// user token, App JWT, or installation token, `body` sent as JSON (a GraphQL
+// query's, given longer to answer). Network / non-2xx / malformed fold into a
+// GithubApiError (401 passes through for the caller to handle). Identical GETs
+// share an outstanding read through its body; one GitHub answered with an
+// ETag is asked again If-None-Match, its body kept answering a 304
+// (taggedRead). POSTs only opt in for read-only GraphQL
+// queries (repository-history.ts), never for mutations or token mints.
+export function githubJson(url: string, token: string | null, fetchImpl: typeof fetch, method: 'GET' | 'POST' = 'GET', body?: unknown,
+  readOnly = method === 'GET'): Promise<unknown> {
+  if (readOnly) return shareGithubRead(fetchImpl, JSON.stringify([url, token, method, body]), () => githubJson(url, token, fetchImpl, method, body, false))
+  const request = method === 'GET' && body === undefined ? JSON.stringify([url, token]) : null
+  const tagged = request === null ? undefined : taggedRead(fetchImpl, request)
+  // Each call told in its request's Server-Timing (request-timing.ts).
+  return timed('gh', async () => {
+    let res: Response
+    const started = Date.now()
+    try {
+      res = await fetchImpl(url, {
+        method,
+        signal: AbortSignal.timeout(body === undefined ? 10_000 : 20_000),
+        redirect: 'error',
+        headers: {
+          ...(token == null ? {} : { authorization: `Bearer ${token}` }), 'accept': 'application/vnd.github+json',
+          ...(body === undefined ? {} : { 'content-type': 'application/json' }), 'user-agent': USER_AGENT, 'x-github-api-version': API_VERSION,
+          ...(tagged ? { 'if-none-match': tagged.etag } : {}),
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      })
+    } catch (error) { throw githubUnreachable(error, started) }
+    if (res.status === 401 && token) tokenRejected(token, fetchImpl)
+    if (res.status === 304 && tagged) return JSON.parse(tagged.text) as unknown
+    if (!res.ok) await throwGithubResponseError(res)
+    // The answer's body is read within the same timeout: one not read whole is
+    // GitHub not reached, as one not answered is; only one that isn't JSON is
+    // malformed.
+    const etag = request === null ? null : res.headers?.get('etag') ?? null
+    try {
+      if (etag === null) return await res.json()
+      const text = await res.text()
+      const value = JSON.parse(text) as unknown
+      keepTaggedRead(fetchImpl, request!, etag, text)
+      return value
+    } catch (error) {
+      throw error instanceof SyntaxError ? new GithubApiError(502, 'github-malformed') : githubUnreachable(error, started)
+    }
+  })
+}

package/server-managed/github-users.ts

@@ -0,0 +1,30 @@
+// The app's users and agents where a repository's activity names their
+// GitHub accounts (GET /api/admin/repositories/history, issues, item, agents
+// and pulse): of the accounts an answer names (common/managed/github-logins.ts),
+// the agents' (common/managed/github-agents.ts), and those an approved user
+// signs in with or linked to theirs (github-links.ts), each as that user
+// shows in the app, linked accounts as their user; each by its numeric id
+// where the answer names it, else by its login. Resolved as each answer is
+// sent, never kept with it, and only for the accounts it names: a reader is
+// never sent a list of users.
+import { type GithubAgentId, githubAgent } from '../common/managed/github-agents.ts'
+import { namedAccounts } from '../common/managed/github-logins.ts'
+import type { ManagedDb } from './db.ts'
+import type { AppUser } from './github-links.ts'
+
+// An agent, as the app draws it (GITHUB_AGENTS).
+export interface AppAgentUser { agent: GithubAgentId }
+
+// `answer` with the app's users and agents its accounts are (`users`, by
+// login), as a new object: what was kept of it, every reader's, is left as
+// it was. A login it names by more than one account is no one's.
+export async function withAppUsers<T extends object>(db: ManagedDb, answer: T): Promise<T & { users: Record<string, AppUser | AppAgentUser> }> {
+  const agents: Record<string, AppAgentUser> = {}
+  const accounts = [...namedAccounts(answer)].flatMap(([login, githubId]) => {
+    if (githubId === 'ambiguous') return []
+    const agent = githubAgent(login, githubId)
+    if (agent) agents[login] = { agent }
+    return agent ? [] : [{ login, githubId }]
+  })
+  return { ...answer, users: { ...await db.listUsersByAccount(accounts), ...agents } }
+}

package/server-managed/http-response.ts

@@ -0,0 +1,76 @@
+import type { ServerResponse } from 'node:http'
+import { Buffer } from 'node:buffer'
+import { pipeline } from 'node:stream/promises'
+import { createBrotliCompress, constants as zlibConstants } from 'node:zlib'
+import { UPLOAD_CHUNK_BYTES } from './uploads.ts'
+
+// Keep the header ASCII while filename* carries the original UTF-8 name.
+export function attachmentDisposition(filename: string): string {
+  const fallback = filename.replaceAll(/[^\u0020-\u007E]|["\\%]/gu, '_')
+  const encoded = encodeURIComponent(filename.toWellFormed()).replaceAll(/['()*]/gu, ch => `%${ch.codePointAt(0)!.toString(16).toUpperCase()}`)
+  return `attachment; filename="${fallback}"; filename*=UTF-8''${encoded}`
+}
+
+// Writing body chunks enables the function's streamed-response path. Data is
+// already materialized by the authorization/filtering layer before we get here.
+export function writeResponse(res: ServerResponse, body: string | Buffer): void {
+  const bytes = typeof body === 'string' ? Buffer.from(body) : body
+  writeResponseParts(res, [bytes], bytes.length)
+}
+
+// A body of `length` bytes held in parts, written as writeResponse writes
+// one without first copying them into one buffer.
+export function writeResponseParts(res: ServerResponse, parts: Buffer[], length: number): void {
+  if (length <= UPLOAD_CHUNK_BYTES) { res.end(parts.length === 1 ? parts[0] : Buffer.concat(parts, length)); return }
+  for (const part of parts) {
+    for (let offset = 0; offset < part.length; offset += 64 * 1024) res.write(part.subarray(offset, offset + 64 * 1024))
+  }
+  res.end()
+}
+
+export function sendJson(res: ServerResponse, status: number, body: unknown, headers: Record<string, string> = {}): void {
+  res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', ...headers })
+  writeResponse(res, JSON.stringify(body))
+}
+
+// Lines of JSON, Brotli-encoded and sent as each is written, so the reader
+// has each while the next is made. A reader gone, or no longer `allowed`
+// before a line, has the response cut short, as is one whose lines fail: a
+// response that ends is one with every line.
+export async function sendLines(res: ServerResponse, lines: AsyncIterable<unknown>, allowed: () => Promise<boolean>) {
+  const out = openLines(res)
+  try {
+    for await (const line of lines) {
+      if (res.destroyed || !await allowed()) { out.cut(); return }
+      await out.write(line)
+    }
+  } catch (err) {
+    console.warn('managed: a streamed response failed:', err)
+    out.cut()
+    return
+  }
+  await out.end()
+}
+
+// A response of lines of JSON as sendLines sends them, written as its caller
+// has each: `write` sends one, flushed, false where the reader is gone; `end`
+// ends it with every line; `cut` ends it short.
+export function openLines(res: ServerResponse) {
+  res.writeHead(200, { 'content-type': 'application/x-ndjson', 'content-encoding': 'br', 'cache-control': 'private, no-store', 'x-content-type-options': 'nosniff' })
+  const encoder = createBrotliCompress({ params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 } })
+  const sent = pipeline(encoder, res).catch(() => {})
+  const closed = new Promise(resolve => { res.once('close', resolve) })
+  return {
+    async write(line: unknown): Promise<boolean> {
+      if (res.destroyed) return false
+      encoder.write(`${JSON.stringify(line)}\n`)
+      await Promise.race([new Promise<void>(resolve => { encoder.flush(() => { resolve() }) }), closed])
+      return !res.destroyed
+    },
+    async end() {
+      encoder.end()
+      await sent
+    },
+    cut() { res.destroy() },
+  }
+}