mirab 0.0.0-stage → 0.2.0

package/src/runner/define.ts

@@ -0,0 +1,187 @@
+// What a CI runner declares: `defineRunner(...)`. mirab runs each job in a
+// fresh VM and throws it away; a forge adapter (woreda's `github()`, later
+// gild, GitLab, Forgejo) says how to register for one job and what to run in
+// the VM. Nothing here knows any particular forge.
+import { z } from 'zod'
+
+/** The guests a runner can run. */
+export const RUNNER_PLATFORMS = ['linux-x64', 'linux-arm64'] as const
+export type RunnerPlatform = (typeof RUNNER_PLATFORMS)[number]
+
+/** Every runner carries `mirab-<os>-<arch>` (e.g. `mirab-linux-arm64`), so a
+ *  job asks for a fresh VM of a platform with one label. */
+export const platformLabel = (platform: RunnerPlatform) => `mirab-${platform}`
+
+/** One command in the VM. Steps run as the unprivileged `runner` user unless
+ *  `asRoot` (then the step is responsible for dropping to it, with RUNNER_SETPRIV). */
+export interface RunnerStep {
+  argv: string[]
+  env?: Record<string, string>
+  asRoot?: boolean
+}
+
+/** A file put into the VM before the job's steps. `secret` files are never
+ *  logged; they should live on tmpfs (/run) and be removed once read. */
+export interface RunnerFile {
+  path: string
+  mode: number
+  content: string
+  secret?: boolean
+}
+
+/** A one-time credential for exactly one job. Every value in `secret` is
+ *  redacted from mirab's logs and never written to the host's disk. */
+export interface RunnerTicket {
+  name: string
+  secret: Record<string, string>
+  meta?: Record<string, string>
+}
+
+/** What a forge adapter provides. */
+export interface Forge {
+  name: string
+  /** Host side: register one runner called `name` for one job. */
+  ticket(req: {
+    name: string
+    labels: string[]
+    platform: RunnerPlatform
+  }): Promise<RunnerTicket>
+  guest: {
+    /** Baked into the runner image as root, in the build VM. `key` names
+     *  exactly what is installed (e.g. a version and checksum): a new key is
+     *  a new image. Called again at most daily, to notice new releases. */
+    install(
+      platform: RunnerPlatform,
+    ): Promise<{ key: string; steps: RunnerStep[] }>
+    /** Hosts the image build may reach for `install`. */
+    buildEgress: string[]
+    /** One job: files put first, then the steps in order; the last one is
+     *  the runner, which takes one job and exits. */
+    job(ticket: RunnerTicket): {
+      files: RunnerFile[]
+      steps: RunnerStep[]
+      env: Record<string, string>
+    }
+    /** True for the runner's output line that says a job has started: the
+     *  job timer (timeoutMinutes) starts there, not at boot. */
+    started(line: string): boolean
+  }
+  /** Delete this host's registrations named `prefix*` that aren't in `live`. */
+  reconcile(prefix: string, live: string[]): Promise<void>
+}
+
+/** The toolsets a runner image can carry. */
+export const TOOLSETS = ['rust', 'node', 'go'] as const
+
+const NAME = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/
+const LABEL = /^[A-Za-z0-9._-]{1,64}$/
+const PACKAGE = /^[a-z0-9][a-z0-9+.-]*$/
+
+const forgeSchema = z.custom<Forge>(
+  (f) =>
+    !!f &&
+    typeof f === 'object' &&
+    typeof (f as Forge).name === 'string' &&
+    typeof (f as Forge).ticket === 'function' &&
+    typeof (f as Forge).reconcile === 'function' &&
+    typeof (f as Forge).guest?.job === 'function' &&
+    typeof (f as Forge).guest?.install === 'function' &&
+    typeof (f as Forge).guest?.started === 'function' &&
+    Array.isArray((f as Forge).guest?.buildEgress),
+  'forge is an adapter object (ticket, reconcile, guest.install/job/started/buildEgress)',
+)
+
+export const runnerSchema = z.strictObject({
+  /** Unique on its host; registrations are `<host>-<name>-<random>`. */
+  name: z
+    .string()
+    .regex(
+      NAME,
+      'name is [a-z0-9-], up to 40 characters, no leading or trailing -',
+    ),
+  forge: forgeSchema,
+  /** Extra labels, after `platformLabel`'s, passed to the adapter as they are. */
+  labels: z.array(z.string().regex(LABEL)).max(32).default([]),
+  image: z
+    .strictObject({
+      /** Pinned versions: rust `1.91.0` or `1.91`; node `24` or `24.21.0`; go `1.25` or `1.25.3`. */
+      tools: z
+        .strictObject({
+          rust: z
+            .string()
+            .regex(/^\d+\.\d+(\.\d+)?$/)
+            .optional(),
+          node: z
+            .string()
+            .regex(/^\d+(\.\d+){0,2}$/)
+            .optional(),
+          go: z
+            .string()
+            .regex(/^\d+\.\d+(\.\d+)?$/)
+            .optional(),
+        })
+        .default({}),
+      /** apt package names. */
+      packages: z
+        .array(z.string().regex(PACKAGE, 'an apt package name'))
+        .default([]),
+    })
+    .default({ tools: {}, packages: [] }),
+  vm: z
+    .strictObject({
+      vcpus: z.number().int().min(1).max(64).default(2),
+      memoryMiB: z.number().int().min(1024).default(3072),
+      /** The job's disk; caps what one job can use of the host's. */
+      diskGiB: z.number().int().min(8).max(1024).default(30),
+    })
+    .default({ vcpus: 2, memoryMiB: 3072, diskGiB: 30 }),
+  pool: z
+    .strictObject({
+      /** VMs kept booted and registered, waiting for a job (0 or 1 in phase 1). */
+      warm: z.number().int().min(0).max(1).default(1),
+      /** VMs at once on this host (1 until VM-to-VM isolation is proven). */
+      max: z.number().int().min(1).max(1).default(1),
+      /** A slot nobody gave a job ends after this, and registers again. */
+      idleHours: z.number().positive().max(72).default(12),
+    })
+    .default({ warm: 1, max: 1, idleHours: 12 }),
+  /** One job's hard limit, from the moment it starts; the VM is killed after. */
+  timeoutMinutes: z
+    .number()
+    .int()
+    .min(1)
+    .max(24 * 60)
+    .default(90),
+})
+
+export type RunnerDefinition = z.infer<typeof runnerSchema>
+export type RunnerInput = z.input<typeof runnerSchema>
+
+export function defineRunner(input: RunnerInput): RunnerDefinition {
+  const parsed = runnerSchema.safeParse(input)
+  if (!parsed.success)
+    throw new Error(
+      `defineRunner: ${parsed.error.issues.map((i) => `${i.path.join('.') || 'runner'}: ${i.message}`).join('; ')}`,
+    )
+  return Object.freeze(parsed.data)
+}
+
+/** The unprivileged user every job step runs as (created in the runner image). */
+export const RUNNER_USER = { name: 'runner', uid: 1001, home: '/home/runner' }
+
+/** Prefix that drops a root command to the runner user, keeping its env. */
+export const RUNNER_SETPRIV = [
+  'setpriv',
+  `--reuid=${RUNNER_USER.uid}`,
+  `--regid=${RUNNER_USER.uid}`,
+  '--init-groups',
+]
+
+/** The guest platform a VM on this host runs. */
+export function hostRunnerPlatform(
+  arch: string = process.arch,
+): RunnerPlatform {
+  if (arch === 'arm64') return 'linux-arm64'
+  if (arch === 'x64') return 'linux-x64'
+  throw new Error(`no runner guest for ${arch} hosts`)
+}

package/src/runner/image.ts

@@ -0,0 +1,239 @@
+// A runner's image: the base, grown to the job's disk size, plus the runner
+// user, apt packages, toolsets and the forge's runner, built once in a VM
+// whose only way out is the station (to the hosts the recipe needs) and cached
+// under the hash of all of it. Every job boots a copy-on-write clone of it.
+import { mkdir, readFile, rm, utimes } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  BUILD_ENV,
+  GROW_ROOT_FS,
+  UBUNTU_MIRRORS,
+  baseId,
+  bootForBuild,
+  keep,
+  recipeKey,
+  run,
+} from '../images'
+import type { VmConfig } from '../isolation'
+import {
+  RUNNER_USER,
+  hostRunnerPlatform,
+  type RunnerDefinition,
+  type RunnerPlatform,
+  type RunnerStep,
+} from './define'
+import {
+  RUST_HOME,
+  TOOL_CACHE,
+  resolveTools,
+  toolEnv,
+  toolSteps,
+  type Fetcher,
+  type ResolvedTool,
+} from './toolsets'
+
+/** Bump when the build recipe below changes in a way that needs new images. */
+const RECIPE_VERSION = 1
+
+export const runnerImagesDir = (configDir: string) =>
+  join(configDir, 'runner-images')
+
+export interface RunnerImageMeta {
+  key: string
+  platform: RunnerPlatform
+  forge: { name: string; key: string }
+  tools: ResolvedTool[]
+  packages: string[]
+  diskGiB: number
+  /** The toolsets' env, and PATH entries to put first, for every job. */
+  env: Record<string, string>
+  path: string[]
+  builtAt: string
+}
+
+export interface RunnerImage {
+  rootfs: string
+  meta: RunnerImageMeta
+}
+
+export interface RunnerRecipe {
+  platform: RunnerPlatform
+  forge: { name: string; key: string; steps: RunnerStep[]; egress: string[] }
+  tools: ResolvedTool[]
+  packages: string[]
+  diskGiB: number
+}
+
+/** Everything that decides an image, resolved: the key is the hash of it. */
+export async function runnerRecipe(
+  def: RunnerDefinition,
+  o: { platform?: RunnerPlatform; fetch?: Fetcher } = {},
+): Promise<RunnerRecipe> {
+  const platform = o.platform ?? hostRunnerPlatform()
+  const install = await def.forge.guest.install(platform)
+  return {
+    platform,
+    forge: {
+      name: def.forge.name,
+      key: install.key,
+      steps: install.steps,
+      egress: def.forge.guest.buildEgress,
+    },
+    tools: await resolveTools(def.image.tools, platform, o.fetch),
+    packages: [...new Set(def.image.packages)].sort(),
+    diskGiB: def.vm.diskGiB,
+  }
+}
+
+export function runnerImageKey(base: string, r: RunnerRecipe) {
+  return recipeKey(base, {
+    v: RECIPE_VERSION,
+    platform: r.platform,
+    forge: { name: r.forge.name, key: r.forge.key },
+    tools: r.tools.map((t) => ({
+      tool: t.tool,
+      version: t.version,
+      sha256: t.sha256,
+    })),
+    packages: r.packages,
+    diskGiB: r.diskGiB,
+  })
+}
+
+/** The build, as root in the build VM, in order. */
+export function buildSteps(r: RunnerRecipe): RunnerStep[] {
+  const u = RUNNER_USER
+  return [
+    { argv: ['sh', '-c', GROW_ROOT_FS] },
+    { argv: ['apt-get', 'update'] },
+    {
+      argv: [
+        'apt-get',
+        'install',
+        '-y',
+        '--no-install-recommends',
+        ...new Set(['sudo', ...r.packages]),
+      ],
+    },
+    // The base writes /etc/passwd and /etc/group itself; useradd adds the
+    // runner (and its group, and a shadow entry sudo's PAM wants). sudo by a
+    // sudoers file, not a sudo group the base doesn't have.
+    {
+      argv: [
+        'sh',
+        '-euc',
+        [
+          `useradd -m -d ${u.home} -u ${u.uid} -U -s /bin/bash ${u.name}`,
+          `printf '%s\\n' '${u.name} ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/${u.name}`,
+          `chmod 0440 /etc/sudoers.d/${u.name}`,
+          `mkdir -p ${u.home}/tmp ${TOOL_CACHE}`,
+        ].join(' && '),
+      ],
+    },
+    ...toolSteps(r.tools, r.platform),
+    ...r.forge.steps,
+    {
+      argv: [
+        'sh',
+        '-euc',
+        [
+          `chown -R ${u.uid}:${u.uid} ${u.home} ${TOOL_CACHE}`,
+          r.tools.some((t) => t.tool === 'rust')
+            ? `chown -R ${u.uid}:${u.uid} ${RUST_HOME}`
+            : 'true',
+          'apt-get clean',
+          'rm -rf /var/lib/apt/lists/*',
+        ].join(' && '),
+      ],
+    },
+  ]
+}
+
+/** The cached image for `r`, if it was built on this base. */
+export async function cachedRunnerImage(
+  configDir: string,
+  key: string,
+): Promise<RunnerImage | undefined> {
+  const dir = join(runnerImagesDir(configDir), key)
+  try {
+    const meta = JSON.parse(
+      await readFile(join(dir, 'meta.json'), 'utf8'),
+    ) as RunnerImageMeta
+    if (meta.key !== key) return undefined
+    return { rootfs: join(dir, 'rootfs.ext4'), meta }
+  } catch {
+    return undefined
+  }
+}
+
+/** The runner's image: from the cache, or built now (a few minutes). */
+export async function runnerImage(o: {
+  configDir: string
+  vm: VmConfig
+  recipe: RunnerRecipe
+  log?: (line: string) => void
+}): Promise<RunnerImage> {
+  const r = o.recipe
+  const base = await baseId(o.vm.rootfs)
+  const key = runnerImageKey(base, r)
+  const hit = await cachedRunnerImage(o.configDir, key)
+  if (hit) {
+    const now = new Date()
+    await utimes(
+      join(runnerImagesDir(o.configDir), key, 'meta.json'),
+      now,
+      now,
+    ).catch(() => {})
+    return hit
+  }
+  o.log?.(
+    `building runner image ${key.slice(0, 12)}: ${r.forge.name} ${r.forge.key}` +
+      (r.tools.length
+        ? `, ${r.tools.map((t) => `${t.tool} ${t.version}`).join(', ')}`
+        : '') +
+      (r.packages.length ? `, apt: ${r.packages.join(' ')}` : ''),
+  )
+  const dir = join(runnerImagesDir(o.configDir), key)
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  const allow = [
+    ...new Set([
+      ...UBUNTU_MIRRORS,
+      ...r.tools.flatMap((t) => t.hosts),
+      ...r.forge.egress,
+    ]),
+  ]
+  const { iso, cleanup } = await bootForBuild({
+    configDir: o.configDir,
+    // A Rust toolchain unpacks in memory-hungry steps; the build VM is short-lived.
+    vm: { ...o.vm, memoryMiB: Math.max(o.vm.memoryMiB, 2048) },
+    rootfs: o.vm.rootfs,
+    key,
+    allow,
+    rootGiB: r.diskGiB,
+    log: o.log,
+  })
+  try {
+    for (const step of buildSteps(r))
+      await run(iso, step.argv, o.log, { ...BUILD_ENV, ...step.env })
+    const { env, path } = toolEnv(r.tools, r.platform)
+    const meta: RunnerImageMeta = {
+      key,
+      platform: r.platform,
+      forge: { name: r.forge.name, key: r.forge.key },
+      tools: r.tools,
+      packages: r.packages,
+      diskGiB: r.diskGiB,
+      env,
+      path,
+      builtAt: new Date().toISOString(),
+    }
+    await keep(iso, dir, meta, { previous: false })
+    return { rootfs: join(dir, 'rootfs.ext4'), meta }
+  } catch (e) {
+    await iso.close().catch(() => {})
+    await rm(dir, { recursive: true, force: true })
+    throw e
+  } finally {
+    await cleanup()
+  }
+}

package/src/runner/index.ts

@@ -0,0 +1,37 @@
+// What a host that serves runners imports (woreda): the VM side of runners.
+// A runner definition itself imports only `defineRunner` from 'mirab'.
+export * from './define'
+export {
+  buildSteps,
+  cachedRunnerImage,
+  runnerImage,
+  runnerImageKey,
+  runnerImagesDir,
+  runnerRecipe,
+} from './image'
+export type { RunnerImage, RunnerImageMeta, RunnerRecipe } from './image'
+export {
+  admission,
+  hostLabel,
+  jobEnv,
+  redact,
+  runnersDir,
+  serveRunners,
+  startRunnerVm,
+  stepArgv,
+} from './serve'
+export type {
+  RunnerState,
+  ServeDeps,
+  ServeOptions,
+  SlotPhase,
+  SlotState,
+} from './serve'
+export { resolveTools, TOOL_CACHE } from './toolsets'
+/** The VM this host runs runners on: the published guest image (fetched on
+ *  first use) and the backend's settings from <config dir>/isolation.json. */
+export { requireVm as runnerHostVm } from '../isolation'
+/** This copy's package version: with the commit a package pins mirab at, it
+ *  names that commit's canary (`<version>-canary-<sha7>`) for runnerHostVm. */
+export { MIRAB_VERSION } from '../isolation/image'
+export type { ResolvedTool } from './toolsets'