@threadedstack/wmd-web 0.1.17 → 0.1.18

package/src/build/builder.js

@@ -0,0 +1,791 @@
+// Dockerfile builds in the browser with BuildKit (docs/plans/web-buildkit-impl.md, D-547).
+//
+// createBuilder boots one builder machine: moby's BuildKit image plus wmd's start script (web/builder/), as a
+// privileged container with the guest network on a relay and BuildKit's storage on a disk in OPFS
+// (host/disk.js). build() sends the context as a tar into the builder's memory (/run/ctx), runs buildctl, reads
+// the image back as a Docker tar on buildctl's stdout and converts it with loadImageTar. A Dockerfile with no RUN
+// is built in the page instead (fast.js), unless fast: false.
+
+import { bootWmd } from '../boot.js'
+import { MAIN_PROC_ID, containerBundle, fillRunRequest } from '../host/ctl.js'
+import { DiskError, deleteDisk, openDisk, sweepDisks } from '../host/disk.js'
+import { p9MountOptions } from '../host/p9mount.js'
+import { loadImageTar } from '../registry/load-tar.js'
+import { packContext, readTarFile } from './context.js'
+import { BUILDER_PINS } from './pin.js'
+import { FastRefused, fastBuild, fastEligible } from './fast.js'
+
+export const ARCHES = {
+  arm64: {
+    platform: 'linux/arm64',
+    machine: ['--arch', 'a64', '--board', 'arm64'],
+    kernel: 'guest/Image',
+    console: ['console=ttyAMA0', 'earlycon=pl011,0x9000000'],
+  },
+  amd64: {
+    platform: 'linux/amd64',
+    machine: ['--arch', 'x86', '--board', 'x86'],
+    kernel: 'guest/bzImage',
+    console: ['console=ttyS0,115200', 'earlyprintk=serial,ttyS0', 'tsc=reliable', 'no_timer_check', 'virtio_mmio.device=4K@0xd0000000:5'],
+  },
+}
+const P9_PORT = 564
+const CONTROL_PORT = 8
+const NET_PORT = 9
+const MAC = '02:00:00:00:00:01'
+const LOG_LINES = 2000
+const LOG_TAIL = 64 << 10
+const SAY = 'wmd-buildkitd: '
+const ROOM_WATCH_MS = 1000 // how often a build checks /bk's free room
+const FULL_MIB = 64 // /bk with less free than this during a failed build: the build failed for want of room
+const enc = new TextEncoder()
+/** host/jit.js's line when the engine's code pool is full (D-515). */
+export const POOL_FULL_RE = /wmd-web: jit: the engine's code pool is full/
+
+export class BuildError extends Error {
+  constructor(message, { step = null, tail = '', reason = null } = {}) {
+    super(message)
+    this.name = 'BuildError'
+    this.step = step
+    this.tail = tail
+    this.reason = reason // 'no-space' | 'quota' | 'disk' | 'timeout' | 'pin' | 'secret' | null
+  }
+}
+export class BuildCancelled extends Error {
+  constructor(message = 'the build was cancelled') {
+    super(message)
+    this.name = 'BuildCancelled'
+  }
+}
+export class BuildRefused extends Error {
+  constructor(feature, message) {
+    super(message)
+    this.name = 'BuildRefused'
+    this.feature = feature
+  }
+}
+
+/**
+ * The builder's no-RUN fast path (fast.js): (dockerfile, req, onEvent) -> {index, packs, name} for a Dockerfile it can
+ * build in the page, else null (the caller then runs BuildKit). `req.keepTars` also returns the new layers' tars (tars). Declining emits {t:'fast', ok:false, why}; a
+ * FastRefused from the build (a base with ONBUILD, a pull with no rawConfig, a context path BuildKit would handle
+ * differently...) does too, with refused: true. Without `pull` (no registry fetch in the page) it always declines.
+ */
+export function makeFast({ pull, converter, platform }) {
+  return async (dockerfile, req, onEvent) => {
+    const decline = (why, extra) => {
+      onEvent({ t: 'fast', ok: false, why, ...extra })
+      return null
+    }
+    const e = fastEligible(dockerfile, { args: req.args, target: req.target, platform })
+    if (!e.ok) return decline(e.why)
+    if (!pull) return decline('no pull')
+    try {
+      const r = await fastBuild({
+        plan: e.plan,
+        context: req.context || {},
+        pull,
+        converter,
+        platform,
+        args: req.args,
+        target: req.target,
+        limits: req.limits,
+        omitDockerfile: req.dockerfile != null,
+        ref: req.tag || '',
+        keepTars: !!req.keepTars,
+        onEvent: ev => ev.t !== 'done' && onEvent(ev), // runBuild reports the one 'done'
+      })
+      return { index: r.index, packs: r.packs, name: req.tag || null, ...(r.tars ? { tars: r.tars } : {}) }
+    } catch (err) {
+      if (err instanceof FastRefused) return decline(err.message, { refused: true })
+      throw err
+    }
+  }
+}
+
+/** A namespace names a disk: lowercase letters, digits, '_' and '-', at most 64; 'tmp-' is the builder's own. */
+export function checkNamespace(ns) {
+  if (typeof ns !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(ns) || /^tmp-/.test(ns)) {
+    throw new TypeError(`bad disk namespace ${JSON.stringify(ns)}: lowercase letters, digits, '_' and '-', at most 64, not starting with 'tmp-'`)
+  }
+  return ns
+}
+
+/** A registry host (name[:port]) as buildkitd.toml takes it. */
+function checkHost(h) {
+  if (!/^[A-Za-z0-9.-]+(:\d{1,5})?$/.test(h)) throw new TypeError(`bad registry host ${JSON.stringify(h)}`)
+  return h
+}
+
+/** The features a page cannot give BuildKit, refused before any work (plan section 4); null when none. */
+export function refusals(dockerfile, req = {}) {
+  if (req.ssh || /--mount=(?:[^\s]*,)?type=ssh\b/i.test(dockerfile)) {
+    return new BuildRefused('ssh', 'RUN --mount=type=ssh needs an SSH agent, and a page has none; pass the key as a secret (RUN --mount=type=secret) instead')
+  }
+  if (req.output) return new BuildRefused('output', 'the browser builder gives the image, its Docker tar (tar: true) and a push (push: {name}); other outputs are not supported')
+  return null
+}
+
+async function sha256Hex(bytes) {
+  const d = await crypto.subtle.digest('SHA-256', bytes)
+  return [...new Uint8Array(d)].map(x => x.toString(16).padStart(2, '0')).join('')
+}
+
+/** Base64 of a string's UTF-8 bytes (btoa takes Latin-1 only). */
+export function b64utf8(str) {
+  const u8 = new TextEncoder().encode(String(str))
+  let bin = ''
+  for (let i = 0; i < u8.length; i += 0x8000) bin += String.fromCharCode(...u8.subarray(i, i + 0x8000))
+  return btoa(bin)
+}
+
+const hexOfBytes = u8 => [...u8].map(x => x.toString(16).padStart(2, '0')).join('')
+
+/** JSON with sorted keys: the same value always gives the same text. */
+function canonicalJSON(v) {
+  if (Array.isArray(v)) return `[${v.map(canonicalJSON).join(',')}]`
+  if (v && typeof v === 'object') return `{${Object.keys(v).sort().filter(k => v[k] !== undefined).map(k => `${JSON.stringify(k)}:${canonicalJSON(v[k])}`).join(',')}}`
+  return JSON.stringify(v) ?? 'null'
+}
+
+const REF_COMPONENT = /^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*$/
+const REF_HOST = /^(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])(?:\.(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))*(?::\d{1,5})?$/
+const REF_TAG = /^\w[\w.-]{0,127}$/
+
+/** An image reference by docker's grammar ([host[:port]/]path[:tag][@sha256:hex]); anything else is a TypeError. */
+export function checkRef(ref, what = 'image reference') {
+  const bad = () => new TypeError(`bad ${what} ${JSON.stringify(String(ref).slice(0, 200))}: [registry[:port]/]lowercase/path[:tag][@sha256:<64 hex>]`)
+  if (typeof ref !== 'string' || !ref || ref.length > 255) throw bad()
+  let rest = ref
+  const at = rest.indexOf('@')
+  if (at >= 0) {
+    if (!/^sha256:[0-9a-f]{64}$/.test(rest.slice(at + 1))) throw bad()
+    rest = rest.slice(0, at)
+  }
+  const colon = rest.lastIndexOf(':')
+  if (colon > rest.lastIndexOf('/')) {
+    if (!REF_TAG.test(rest.slice(colon + 1))) throw bad()
+    rest = rest.slice(0, colon)
+  }
+  const parts = rest.split('/')
+  if (parts.length > 1 && (parts[0].includes('.') || parts[0].includes(':') || parts[0] === 'localhost')) {
+    if (!REF_HOST.test(parts[0])) throw bad()
+    parts.shift()
+  }
+  if (!parts.length || !parts.every(c => REF_COMPONENT.test(c))) throw bad()
+  return ref
+}
+
+/** Secrets as {id, name, text}: ids by /^[A-Za-z0-9_.-]{1,128}$/, the env name from the id's hex, values as UTF-8 text without NUL. */
+function checkSecrets(secrets) {
+  const out = []
+  for (const [sid, val] of Object.entries(secrets || {})) {
+    if (!/^[A-Za-z0-9_.-]{1,128}$/.test(sid)) throw new TypeError(`bad secret id ${JSON.stringify(sid.slice(0, 200))}: letters, digits, '_', '.' and '-', at most 128`)
+    let text
+    if (typeof val === 'string') text = val
+    else {
+      try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(val)
+      } catch {
+        throw new BuildError(`secret ${sid} is not valid UTF-8; secrets travel as environment values`, { reason: 'secret' })
+      }
+    }
+    if (text.includes('\0')) throw new TypeError(`secret ${sid} holds a NUL byte; secrets travel as environment values`)
+    out.push({ id: sid, name: `WMD_SECRET_${hexOfBytes(enc.encode(sid))}`, text })
+  }
+  return out
+}
+
+/** The packs against the index's layer digests (top first, both): a mismatch is a BuildError 'pin'. */
+async function checkPacks(img, what) {
+  const layers = img?.index?.layers || []
+  const packs = img?.packs
+  const bad = why => new BuildError(`${what}: ${why}`, { reason: 'pin' })
+  if (!Array.isArray(packs) || packs.length !== layers.length) throw bad(`${packs?.length} packs for ${layers.length} layers in its index`)
+  for (let i = 0; i < packs.length; i++) {
+    const want = layers[i]?.pack
+    if (!(packs[i] instanceof Uint8Array)) throw bad(`pack ${i} is not bytes`)
+    const got = `sha256:${await sha256Hex(packs[i])}`
+    if (got !== want) throw bad(`pack ${i} is ${got}, its index says ${want}`)
+  }
+  return img
+}
+
+/** The digest a builder's state directory is named by: the index's own, else the hash of its canonical JSON. */
+async function indexDigest(index) {
+  for (const d of [index?.manifest, index?.index]) if (typeof d === 'string' && /^sha256:[0-9a-f]{64}$/.test(d)) return d.slice(7)
+  return sha256Hex(enc.encode(canonicalJSON(index ?? null)))
+}
+
+async function bytesOf(x, fetchFn) {
+  if (x instanceof Uint8Array) return x
+  if (x instanceof ArrayBuffer) return new Uint8Array(x)
+  if (typeof Blob !== 'undefined' && x instanceof Blob) return new Uint8Array(await x.arrayBuffer())
+  const r = await fetchFn(x)
+  if (!r.ok) throw new Error(`${x}: ${r.status} ${r.statusText}`)
+  return new Uint8Array(await r.arrayBuffer())
+}
+
+/**
+ * The builder image as {index, packs}: given as such, or as {tar, sha256} (a `docker save` tar of the image,
+ * URL or bytes, checked against sha256 before it is read). With a store, the converted image is kept under
+ * `builder:<sha256>`.
+ */
+async function builderImage(image, { converter, platform, archName, fetchFn, store }) {
+  if (image?.index && image?.packs) {
+    await checkPacks(image, 'the builder image')
+    return image
+  }
+  if (!image?.tar || !/^[0-9a-f]{64}$/.test(image.sha256 || '')) throw new TypeError('image: {index, packs} or {tar, sha256}')
+  if (image.unpinned !== true && image.sha256 !== BUILDER_PINS[archName]?.sha256) {
+    throw new BuildError(`the builder image sha256:${image.sha256} is not the one this wmd-web pins for ${archName} (sha256:${BUILDER_PINS[archName]?.sha256}); image.unpinned: true allows another, for tests and development`, { reason: 'pin' })
+  }
+  const key = `builder:${image.sha256}`
+  if (store?.get) {
+    const hit = await store.get(key).catch(() => null)
+    if (hit?.index && hit?.packs) return checkPacks(hit, 'the builder image from the store')
+  }
+  const tar = await bytesOf(image.tar, fetchFn)
+  const got = await sha256Hex(tar)
+  if (got !== image.sha256) throw new BuildError(`the builder image tar is sha256:${got}, not the pinned sha256:${image.sha256}`, { reason: 'pin' })
+  const r = await loadImageTar(tar, { converter, platform })
+  if (store?.put) await store.put(key, { index: r.index, packs: r.packs }).catch(() => {})
+  return r
+}
+
+/** BuildKit's rawjson progress (one SolveStatus per line) into step events and log lines. */
+export function progressReader({ onStep, onLog }) {
+  const vertexes = new Map()
+  let buf = ''
+  const dec = new TextDecoder()
+  return {
+    vertexes,
+    push(text) {
+      buf += text
+      let i
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i)
+        buf = buf.slice(i + 1)
+        let s = null
+        if (line.startsWith('{')) {
+          try {
+            s = JSON.parse(line)
+          } catch {}
+        }
+        if (!s) {
+          if (line.trim()) onLog(line, null)
+          continue
+        }
+        for (const v of s.vertexes || []) {
+          const old = vertexes.get(v.digest) || {}
+          const cur = { ...old, ...v }
+          const status = cur.error ? 'error' : cur.completed ? 'done' : cur.started ? 'running' : 'waiting'
+          if (status !== old._status) {
+            cur._status = status
+            onStep({ t: 'step', name: cur.name, status, cached: !!cur.cached, error: cur.error || null, digest: v.digest })
+          } else cur._status = old._status
+          vertexes.set(v.digest, cur)
+        }
+        for (const l of s.logs || []) {
+          let data = ''
+          try {
+            data = dec.decode(Uint8Array.from(atob(l.data || ''), c => c.charCodeAt(0)))
+          } catch {}
+          const name = vertexes.get(l.vertex)?.name || null
+          for (const part of data.split('\n')) if (part) onLog(part, name)
+        }
+      }
+    },
+  }
+}
+
+/** Log lines kept for the result: the first LOG_LINES lines, and always the last LOG_TAIL bytes. */
+export function logKeeper(maxLines = LOG_LINES, tailBytes = LOG_TAIL) {
+  const lines = []
+  let tail = ''
+  let dropped = 0
+  return {
+    add(line) {
+      if (lines.length < maxLines) lines.push(line)
+      else dropped++
+      tail = (tail + line + '\n').slice(-tailBytes)
+    },
+    get lines() {
+      return dropped ? [...lines, `[${dropped} lines left out; the last ${tailBytes >> 10} KiB follow]`, ...tail.split('\n').filter(Boolean)] : [...lines]
+    },
+    get tail() {
+      return tail
+    },
+  }
+}
+
+function aborted(signal) {
+  if (!signal) return new Promise(() => {})
+  return new Promise((_, rej) => {
+    if (signal.aborted) rej(new BuildCancelled())
+    signal.addEventListener('abort', () => rej(new BuildCancelled()), { once: true })
+  })
+}
+
+/**
+ * Boots a builder machine.
+ * @param {object} o
+ * @param {string|Uint8Array} o.vmUrl        vm.wasm (as bootWmd)
+ * @param {object} o.files                   guest files for o.arch: {'guest/Image' (arm64) or 'guest/bzImage' (amd64), 'guest/initramfs.cpio.gz'}
+ * @param {'arm64'|'amd64'} [o.arch]
+ * @param {object} o.image                   {index, packs} or {tar, sha256} (web/builder: `make web-builder`); a tar's sha256 must be
+ *                                           BUILDER_PINS[arch].sha256 (pin.js) unless image.unpinned === true (tests, development);
+ *                                           the packs of an {index, packs} or a store hit must match the index's layer digests
+ * @param {{url: string, protocol?: 'wisp'}} o.relay  the guest's network
+ * @param {number} [o.ram]                   MiB (default 1536)
+ * @param {number} [o.cpus]                  default 2
+ * @param {{namespace: string, mib?: number}|false} o.disk  BuildKit's storage in OPFS (default 10240 MiB); false: memory
+ * @param {string|Uint8Array} o.converter    wmdpack.wasm
+ * @param {object} [o.store]                 PackStore {get, put}: the converted builder image and built packs go there
+ * @param {Function} [o.pull]                ref -> {index, packs, rawConfig} for the fast path's base images (pullImage; the fast path
+ *                                           is off without it, and a pull with no rawConfig is refused to BuildKit)
+ * @param {string[]} [o.httpRegistries]      registry hosts BuildKit reaches over plain http
+ * @param {string[]} [o.registryMirrors]    Docker Hub mirrors (host[:port], in order) BuildKit tries before docker.io; list a plain-http one
+ *                                           in httpRegistries too
+ * @param {Record<string,string>} [o.registryCAs]  host -> PEM: CAs BuildKit checks that registry's certificate against
+ * @param {Function} [o.onEvent]
+ * @param {AbortSignal} [o.signal]
+ * @param {object} [o.boot]                  extra bootWmd options (tests)
+ */
+export async function createBuilder(o) {
+  const archName = o.arch || 'arm64'
+  const arch = ARCHES[archName]
+  if (!arch) throw new TypeError(`arch ${o.arch}: arm64 or amd64`)
+  if (o.disk !== false) checkNamespace(o.disk?.namespace)
+  if (!o.relay?.url) throw new TypeError('relay: {url}: the builder pulls base images through it')
+  const fetchFn = o.fetch || globalThis.fetch.bind(globalThis)
+  const emit = ev => {
+    try {
+      o.onEvent?.(ev)
+    } catch {}
+  }
+  const ram = o.ram || 1536
+  const cpus = o.cpus || 2
+  const t0 = performance.now()
+  o.signal?.throwIfAborted()
+
+  const image = await builderImage(o.image, { converter: o.converter, platform: arch.platform, archName, fetchFn, store: o.store })
+  const digest = o.image?.tar ? o.image.sha256 : await indexDigest(image.index)
+
+  // the disk: wmd-builder-<namespace>-<arch>, or a temporary one when another tab holds it
+  let disk = null
+  if (o.disk !== false) {
+    const mib = o.disk.mib || 10240
+    const base = `wmd-builder-${o.disk.namespace}-${archName}`
+    const swept = await sweepDisks('wmd-builder-tmp-').catch(() => [])
+    if (swept.length) emit({ t: 'disk', reason: 'swept', names: swept })
+    try {
+      disk = await openDisk({ name: base, mib, onEvent: emit })
+    } catch (e) {
+      if (!(e instanceof DiskError) || e.reason !== 'locked') throw e
+      const tmp = `wmd-builder-tmp-${crypto.randomUUID().slice(0, 8)}-${archName}`
+      emit({ t: 'disk', reason: 'locked', message: `${base} is open in another tab; this builder uses ${tmp}, deleted on close` })
+      disk = await openDisk({ name: tmp, mib, onEvent: emit })
+      disk.temporary = true
+    }
+    emit({ t: 'disk', reason: disk.created ? 'new' : 'open', name: disk.name, mib: disk.mib, persisted: disk.persisted })
+  }
+
+  const env = [
+    ...(image.index.config?.Env || ['PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin']),
+    `WMD_BUILDER_DIGEST=${digest}`,
+    ...(o.httpRegistries?.length ? [`WMD_BK_HTTP=${o.httpRegistries.map(checkHost).join(' ')}`] : []),
+    ...(o.registryMirrors?.length ? [`WMD_BK_MIRRORS=${o.registryMirrors.map(checkHost).join(',')}`] : []),
+    ...(o.registryCAs && Object.keys(o.registryCAs).length ? [`WMD_BK_CA=${Object.entries(o.registryCAs).map(([h, pem]) => `${checkHost(h)}=${b64utf8(pem)}`).join(' ')}`] : []),
+  ]
+  const argv = ['/usr/local/bin/wmd-buildkitd']
+  const b = containerBundle({ args: argv, env, cwd: '/', hostname: 'buildkitsandbox', networkDisabled: false, ip: '192.168.127.2', gateway: '192.168.127.1', privileged: true })
+  const append = [...arch.console, 'rdinit=/sbin/init', 'loglevel=4', 'norandmaps', 'wmd.init', 'wmd.p9tag=wmdroot', 'wmd.control=vport', 'wmd.exit'].join(' ')
+  const args = [
+    '--machine', ...arch.machine, '--mode', 'jit', '--cpus', String(cpus), '--ram', String(ram),
+    '--kernel', `/g/${arch.kernel}`, '--initrd', '/g/guest/initramfs.cpio.gz', '--append', append,
+    '--net', String(NET_PORT), '--mac', MAC,
+    '--p9', String(P9_PORT), '--p9-tag', 'wmdroot', '--control', String(CONTROL_PORT),
+  ]
+  const services = [
+    { port: P9_PORT, kind: '9p', layers: image.packs, at: 'rootfs', files: b.files },
+    { port: CONTROL_PORT, kind: 'control', yamux: true },
+    { port: NET_PORT, kind: 'net', relay: { protocol: 'wisp', ...o.relay } },
+  ]
+  let stderr = ''
+  let slowSaid = false
+  emit({ t: 'boot', ram, cpus, arch: archName })
+  let vm
+  try {
+    vm = await bootWmd({
+      vmUrl: o.vmUrl,
+      files: o.files,
+      args,
+      ...(ram > 1536 ? { flatRam: true } : {}),
+      ...(disk ? { disk } : {}),
+      onStderr: s => {
+        stderr = (stderr + s).slice(-16384)
+        // WebKit: the engine's code pool filled, so new code waits and the guest runs slower (D-515; plan 5.10)
+        if (!slowSaid && POOL_FULL_RE.test(s)) {
+          slowSaid = true
+          emit({ t: 'slow', reason: 'webkit-code-space', message: "the browser's code space is full: new code runs in the interpreter, so this build is slower" })
+        }
+      },
+      channels: { services, collect: [{ port: P9_PORT, path: 'bundle/exitcode' }] },
+      ...(o.boot || {}),
+    })
+  } catch (e) {
+    await disk?.close().catch(() => {})
+    throw e
+  }
+  const ended = vm.exited
+  const ctl = vm.control
+  const stop = async () => {
+    try {
+      vm.stop()
+    } catch {}
+    await Promise.race([ended, new Promise(r => setTimeout(r, 10_000))])
+    await disk?.close().catch(() => {})
+    if (disk?.temporary) await deleteDisk(disk.name).catch(() => {})
+  }
+
+  // the start script's own lines on the main process's output
+  let mainOut = ''
+  let readyRes
+  let readyRej
+  const ready = new Promise((res, rej) => ((readyRes = res), (readyRej = rej)))
+  ready.catch(() => {})
+  const mainLog = logKeeper(400, 16 << 10)
+  const dec = new TextDecoder()
+  const onMain = u8 => {
+    mainOut += dec.decode(u8, { stream: true })
+    let i
+    while ((i = mainOut.indexOf('\n')) >= 0) {
+      const line = mainOut.slice(0, i)
+      mainOut = mainOut.slice(i + 1)
+      mainLog.add(line)
+      if (!line.startsWith(SAY)) continue
+      const [what, ...rest] = line.slice(SAY.length).split(' ')
+      if (what === 'ready') readyRes(rest[0])
+      else if (what === 'disk') emit({ t: 'disk', reason: rest[0], mib: Number(rest[1]) })
+      else if (what === 'tmpfs') emit({ t: 'disk', reason: 'tmpfs', mib: Number(rest[0]) })
+      else if (what === 'error') readyRej(new Error(`the builder did not start: ${rest.join(' ')}\n${mainLog.tail.slice(-3000)}`))
+    }
+  }
+  try {
+    await Promise.race([ctl.waitSession(600_000), ended.then(r => Promise.reject(new Error(`the builder machine ended before its control session: ${r.code} ${r.reason}\n${stderr.slice(-2000)}`)))])
+    const main = ctl.run(fillRunRequest({ id: MAIN_PROC_ID, args: argv, env, cwd: '/' }, { p9opts: p9MountOptions() }), { onStdout: onMain, onStderr: onMain })
+    main.exited.then(r => readyRej(new Error(`the builder's start script ended (${r.code}) before buildkitd answered\n${mainLog.tail.slice(-3000)}`)))
+    await Promise.race([ready, ended.then(r => Promise.reject(new Error(`the builder machine ended: ${r.code} ${r.reason}`))), aborted(o.signal)])
+  } catch (e) {
+    await stop()
+    throw e
+  }
+  emit({ t: 'ready', ms: Math.round(performance.now() - t0), platform: arch.platform })
+
+  let seq = 0
+  let busy = false
+  let closed = false
+  /** One process in the builder: {code, out (text, or bytes when binary), err}. */
+  const inGuest = (cmd, { stdin = null, env: xenv = [], binary = false, onStderr = null, signal = null, id = `b${++seq}` } = {}) => {
+    const chunks = []
+    let size = 0
+    let out = ''
+    let err = ''
+    const d1 = new TextDecoder()
+    const d2 = new TextDecoder()
+    const p = ctl.startExec({ id, args: cmd, env: [...env, ...xenv], cwd: '/' }, {
+      stdin: !!stdin,
+      onStdout: u8 => {
+        if (binary) {
+          chunks.push(u8.slice())
+          size += u8.length
+        } else out = (out + d1.decode(u8, { stream: true })).slice(-(1 << 20))
+      },
+      onStderr: u8 => {
+        const s = d2.decode(u8, { stream: true })
+        if (onStderr) onStderr(s)
+        else err = (err + s).slice(-(1 << 20))
+      },
+    })
+    let finished = false
+    let killTimer = null
+    let abandon = null
+    const abandoned = new Promise(res => (abandon = res))
+    // an abort sends SIGINT; a process still running 5 s later gets SIGKILL, and 2 s after that it is given up on
+    const kill = () => {
+      if (finished) return
+      ctl.kill({ id, sig: 'SIGINT' }).catch(() => {})
+      killTimer = setTimeout(() => {
+        if (finished) return
+        ctl.kill({ id, sig: 'SIGKILL' }).catch(() => {})
+        killTimer = setTimeout(() => abandon({ code: null }), 2000)
+      }, 5000)
+    }
+    if (signal) {
+      if (signal.aborted) kill()
+      else signal.addEventListener('abort', kill, { once: true })
+    }
+    return (async () => {
+      let r
+      try {
+        if (stdin) {
+          await p.writeAsync(stdin)
+          p.closeStdin()
+        }
+        r = await Promise.race([p.exited, abandoned])
+      } finally {
+        finished = true
+        clearTimeout(killTimer)
+        signal?.removeEventListener('abort', kill)
+      }
+      if (!binary) return { code: r.code ?? null, out, err }
+      const bytes = new Uint8Array(size)
+      let at = 0
+      for (const c of chunks) {
+        bytes.set(c, at)
+        at += c.length
+      }
+      return { code: r.code ?? null, out: bytes, err }
+    })()
+  }
+  const sh = (cmd, opts) => inGuest(['/bin/sh', '-c', cmd], opts)
+
+  const builder = {
+    arch: archName,
+    platform: arch.platform,
+    disk,
+    vm,
+    converter: o.converter,
+    store: o.store || null,
+    pull: o.pull || null,
+    fast: makeFast({ pull: o.pull, converter: o.converter, platform: arch.platform }),
+    inGuest,
+    sh,
+    log: () => mainLog.lines,
+    /** Free MiB and free inodes on /bk. */
+    async room() {
+      const r = await sh("df -Pm /bk | awk 'NR==2{print $4}'; df -Pi /bk | awk 'NR==2{print $4, $2}'")
+      const [mib, inodes, total] = r.out.trim().split(/\s+/).map(Number)
+      return { mib, inodes, inodesTotal: total }
+    },
+    async build(req) {
+      if (closed) throw new Error('the builder is closed')
+      if (busy) throw new Error('one build at a time')
+      busy = true
+      try {
+        return await runBuild(builder, req, emit)
+      } finally {
+        busy = false
+      }
+    },
+    /** Stops the machine and closes the disk; {keep: false} also deletes the disk and its cache. */
+    async close({ keep = true } = {}) {
+      if (closed) return
+      closed = true
+      ctl.kill({ id: MAIN_PROC_ID, sig: 'SIGTERM' }).catch(() => {})
+      await Promise.race([ended, new Promise(r => setTimeout(r, 20_000))])
+      await stop()
+      if (!keep && disk && !disk.temporary) await deleteDisk(disk.name).catch(() => {})
+    },
+    ended,
+  }
+  o.signal?.addEventListener('abort', () => builder.close(), { once: true })
+  return builder
+}
+
+const shq = s => `'${String(s).replace(/'/g, `'\\''`)}'`
+
+/** Keeps a finished build in o.store the way pullImage does: each pack under its digest, the index as JSON under image:<digest>. */
+async function keepBuilt(store, index, packs) {
+  if (!store?.put) return
+  try {
+    const layers = index?.layers || []
+    for (let i = 0; i < packs.length; i++) if (layers[i]?.pack && packs[i] instanceof Uint8Array) await store.put(layers[i].pack, packs[i])
+    await store.put(`image:sha256:${await indexDigest(index)}`, enc.encode(JSON.stringify(index)))
+  } catch {}
+}
+
+async function runBuild(builder, req, emit) {
+  const t0 = performance.now()
+  const onEvent = ev => {
+    emit(ev)
+    try {
+      req.onEvent?.(ev)
+    } catch {}
+  }
+  req.signal?.throwIfAborted()
+  // everything that can be refused is, before any work
+  if (req.tag != null) checkRef(req.tag, 'tag')
+  if (req.push) checkRef(req.push.name, 'push name')
+  const secrets = checkSecrets(req.secrets)
+  const log = logKeeper()
+  // the Dockerfile: given, or read from the context
+  let dockerfile = req.dockerfile ?? null
+  if (dockerfile == null) {
+    const df = await readFromContext(req.context, 'Dockerfile')
+    if (df == null) throw new BuildError('no Dockerfile: give dockerfile, or put a Dockerfile in the context')
+    dockerfile = new TextDecoder().decode(df)
+  }
+  const refused = refusals(dockerfile, req)
+  if (refused) throw refused
+  if (req.platform && req.platform !== builder.platform) {
+    throw new BuildRefused('platform', `this builder builds ${builder.platform}; ${req.platform} needs a builder of that arch (createBuilder({arch}))`)
+  }
+  req.signal?.throwIfAborted()
+
+  // the fast path: a Dockerfile with no RUN, built in the page (fast.js)
+  if (req.fast !== false && builder.fast) {
+    const fp = await builder.fast(dockerfile, req, onEvent)
+    req.signal?.throwIfAborted()
+    if (fp) {
+      await keepBuilt(builder.store, fp.index, fp.packs)
+      const ms = Math.round(performance.now() - t0)
+      onEvent({ t: 'done', ms, path: 'fast' })
+      return { ...fp, log: log.lines, path: 'fast', ms, cached: 0 }
+    }
+  }
+
+  const id = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`
+  const dir = `/run/ctx/${id}`
+  // req.signal and timeoutMs cover everything from here: the context, the upload, buildctl and the conversion
+  const ac = new AbortController()
+  const timer = req.timeoutMs ? setTimeout(() => ac.abort(new BuildError(`the build ran past ${req.timeoutMs} ms`, { reason: 'timeout' })), req.timeoutMs) : null
+  const onAbort = () => ac.abort(new BuildCancelled())
+  req.signal?.addEventListener('abort', onAbort, { once: true })
+  const check = () => {
+    if (ac.signal.aborted) throw ac.signal.reason
+  }
+  const diskMark = Array.isArray(builder.disk?.events) ? builder.disk.events.length : 0
+  try {
+    check()
+    const ctx = await packContext(req.context || {}, { ...(req.dockerfile != null ? { dockerfile } : {}), limits: req.limits })
+    check()
+    await ensureRoom(builder, onEvent, ac.signal)
+    check()
+    // BuildKit keeps the last context it was sent and reuses each file whose size and mtime did not change; contexts
+    // with made-up mtimes (a plain object has none) would then build with an earlier build's bytes
+    const fresh = await builder.inGuest(['buildctl', 'prune', '--filter', 'type==source.local'], { signal: ac.signal })
+    if (fresh.code !== 0) throw new BuildError(`dropping the last build's context: ${String(fresh.err || '').slice(-500)}`)
+    check()
+    const sig = { signal: ac.signal }
+    const put = await builder.inGuest(['/bin/sh', '-c', 'mkdir -p "$1/ctx" "$1/df" && /bin/tar -x -p --numeric-owner -C "$1/ctx"', 'sh', dir], { stdin: ctx.tar, ...sig })
+    check()
+    if (put.code !== 0) throw new BuildError(`sending the context: ${put.err.slice(-500)}`)
+    const dfPut = await builder.inGuest(['/bin/sh', '-c', 'cat > "$1/df/Dockerfile"', 'sh', dir], { stdin: enc.encode(dockerfile), ...sig })
+    check()
+    if (dfPut.code !== 0) throw new BuildError(`sending the Dockerfile: ${dfPut.err.slice(-500)}`)
+    // a .dockerignore in the context goes next to the Dockerfile too, where BuildKit reads it (a symlink only when it
+    // points inside the context, as the docker CLI reads it from there)
+    await builder.sh(`cd ${shq(`${dir}/ctx`)} && for f in .dockerignore Dockerfile.dockerignore; do [ -f "$f" ] || continue; t=$(readlink -f "$f") && case "$t" in "$(pwd -P)"/*) cp "$t" "../df/$f";; esac; done; true`, sig)
+    check()
+    if (req.push?.auth) {
+      const cfg = JSON.stringify({ auths: { [registryOf(req.push.name)]: { auth: b64utf8(`${req.push.auth.username}:${req.push.auth.password}`) } } })
+      const a = await builder.inGuest(['/bin/sh', '-c', 'mkdir -p "$1/auth" && umask 077 && cat > "$1/auth/config.json"', 'sh', dir], { stdin: enc.encode(cfg), ...sig })
+      check()
+      if (a.code !== 0) throw new BuildError('writing the push credentials')
+    }
+    const args = ['buildctl', 'build', '--progress=rawjson', '--frontend', 'dockerfile.v0',
+      '--local', `context=${dir}/ctx`, '--local', `dockerfile=${dir}/df`, '--opt', `platform=${builder.platform}`]
+    for (const [k, v] of Object.entries(req.args || {})) args.push('--opt', `build-arg:${k}=${v}`)
+    if (req.target) args.push('--opt', `target=${req.target}`)
+    if (req.noCache) args.push('--no-cache')
+    const xenv = []
+    for (const sec of secrets) {
+      args.push('--secret', `id=${sec.id},env=${sec.name}`)
+      xenv.push(`${sec.name}=${sec.text}`)
+    }
+    if (req.push?.auth) xenv.push(`DOCKER_CONFIG=${dir}/auth`)
+    args.push('--output', `type=docker,${req.tag ? `name=${req.tag},` : ''}dest=-`)
+    if (req.push) args.push('--output', `type=image,name=${req.push.name},push=true${req.push.insecure ? ',registry.insecure=true' : ''}`)
+    let lastStep = null
+    const errLines = [] // buildctl's own error lines (no step), not the steps' output
+    const pr = progressReader({
+      onStep: ev => {
+        if (ev.status === 'running' || ev.status === 'error') lastStep = ev.name
+        onEvent(ev)
+      },
+      onLog: (line, step) => {
+        if (!step && /^(?:error|ERROR)\b/.test(line)) errLines.push(line)
+        log.add(step ? `[${step}] ${line}` : line)
+        onEvent({ t: 'log', line, step })
+      },
+    })
+    onEvent({ t: 'build', id, files: ctx.files, bytes: ctx.bytes })
+    // the least free room /bk had during the build: a step that fills the disk fails with its own exit code, and
+    // BuildKit drops the step's files once it fails, so only a watch while it runs tells a full disk apart
+    let minMib = Infinity
+    let watching = false
+    const watch = setInterval(() => {
+      if (watching) return
+      watching = true
+      builder.room().then(x => Number.isFinite(x.mib) && (minMib = Math.min(minMib, x.mib)), () => {}).finally(() => (watching = false))
+    }, ROOM_WATCH_MS)
+    let r
+    try {
+      r = await builder.inGuest(args, { env: xenv, binary: true, onStderr: s => pr.push(s), signal: ac.signal, id: `build-${id}` })
+    } finally {
+      clearInterval(watch)
+    }
+    pr.push('\n')
+    // buildctl exited 0 before an abort landed: the build is done, and the result is returned
+    if (r.code !== 0) {
+      check()
+      const tail = log.tail
+      let reason = null
+      if (/no space left on device/i.test(errLines.join('\n')) || minMib < FULL_MIB) reason = 'no-space'
+      if (builder.disk?.events?.slice?.(diskMark).some(e => e.reason === 'quota')) reason = 'quota'
+      if (!reason && /input\/output error|read-only file system/i.test(tail)) reason = 'disk'
+      const failed = [...pr.vertexes.values()].find(v => v.error)
+      const why = failed?.error || tail.split('\n').filter(Boolean).pop() || `buildctl exited ${r.code}`
+      throw new BuildError(`the build failed${failed ? ` at ${failed.name}` : ''}: ${why.slice(0, 500)}`, { step: failed?.name || lastStep, tail, reason })
+    }
+    onEvent({ t: 'export', bytes: r.out.length })
+    const t1 = performance.now()
+    const img = await loadImageTar(r.out, { converter: builder.converter, platform: builder.platform })
+    onEvent({ t: 'convert', layers: img.packs.length, ms: Math.round(performance.now() - t1) })
+    await keepBuilt(builder.store, img.index, img.packs)
+    const cached = [...pr.vertexes.values()].filter(v => v.cached).length
+    const out = { index: img.index, packs: img.packs, name: img.name, log: log.lines, path: 'buildkit', ms: Math.round(performance.now() - t0), cached }
+    if (req.tar) out.tar = new Blob([r.out], { type: 'application/x-tar' })
+    onEvent({ t: 'done', ms: out.ms, cached, path: 'buildkit' })
+    return out
+  } finally {
+    clearTimeout(timer)
+    req.signal?.removeEventListener('abort', onAbort)
+    await builder.sh(`rm -rf ${shq(dir)}`).catch(() => {})
+  }
+}
+
+function registryOf(name) {
+  const first = String(name).split('/')[0]
+  return first.includes('.') || first.includes(':') || first === 'localhost' ? first : 'https://index.docker.io/v1/'
+}
+
+async function readFromContext(ctx, path) {
+  if (!ctx) return null
+  if (ctx instanceof Uint8Array || ctx instanceof ArrayBuffer || (typeof Blob !== 'undefined' && ctx instanceof Blob)) return readTarFile(ctx, path)
+  if (typeof ctx.read === 'function') return Promise.resolve(ctx.read(path)).catch(() => null)
+  const v = ctx[path]
+  return v == null ? null : typeof v === 'string' ? enc.encode(v) : v
+}
+
+/** Before a build: when /bk is short of space or inodes, prune BuildKit's cache and give the freed blocks back. */
+async function ensureRoom(builder, onEvent, signal) {
+  const room = await builder.room()
+  const lowInodes = room.inodesTotal && room.inodes < room.inodesTotal * 0.1
+  if (room.mib >= 1024 && !lowInodes) return room
+  onEvent({ t: 'prune', mib: room.mib, inodes: room.inodes })
+  await builder.sh('buildctl prune --keep-storage 512 >/dev/null 2>&1; fstrim /bk >/dev/null 2>&1; sync', { signal })
+  return builder.room()
+}
+
+/** createBuilder + one build + close. */
+export async function buildImage(o) {
+  const builder = await createBuilder(o)
+  try {
+    return await builder.build(o)
+  } finally {
+    await builder.close()
+  }
+}