@critical-labs/qa-conductor 0.0.0-stage → 0.3.0

package/lib/adapters/exposure-tailscale.mjs

@@ -0,0 +1,136 @@
+// tailscale serve Exposure adapter: publishes the conductor's mounts on this
+// host's tailscaled through the tailscale CLI, and reports drift.
+//
+// It only ever adds or replaces handlers at the (port, path) pairs it is
+// given. `serve --bg --https=P --set-path=/qa T` sits beside an existing /
+// handler on P, and re-running a / handler keeps /qa (tailscaled 1.98.5), so
+// another app's 8444 / and the harness's /qa can share a port. It never runs
+// `serve reset` or `off`, so it never removes a handler: one an old origin
+// left stays until the operator removes it, and one that shadows a mount is
+// reported as drift, never rewritten.
+//
+// Every command goes through the injected execFileFn (makeExecFileFn from
+// ./exec in production), so it is tested against recorded status JSON with
+// no tailscaled. The platform constructs it; the core never does.
+
+const SERVE_STATUS = ['serve', 'status', '--json']
+
+// A Mount this adapter can pass to the CLI: an argument that can't be read
+// as a flag, and a port and path serve accepts.
+function assertMounts(mounts) {
+  if (!Array.isArray(mounts)) throw new Error('tailscale exposure: mounts must be an array')
+  for (const m of mounts) {
+    const ok = m != null &&
+      Number.isInteger(m.port) && m.port >= 1 && m.port <= 65535 &&
+      typeof m.path === 'string' && /^\/\S*$/.test(m.path) &&
+      typeof m.target === 'string' && /^https?:\/\/\S+$/.test(m.target)
+    if (!ok) throw new Error(`tailscale exposure: not a mount: ${JSON.stringify(m)}`)
+  }
+}
+
+const sameTarget = (a, b) => a.replace(/\/$/, '') === b.replace(/\/$/, '')
+const proxyOf = handler => (typeof handler?.Proxy === 'string' ? handler.Proxy : null)
+const snippet = text => JSON.stringify(text.length > 200 ? `${text.slice(0, 200)}…` : text)
+
+export function createTailscaleExposure({ execFileFn, bin = 'tailscale', socket = null, timeoutMs = 30_000 } = {}) {
+  if (typeof execFileFn !== 'function') throw new TypeError('createTailscaleExposure needs execFileFn (makeExecFileFn() from ./exec)')
+  if (typeof bin !== 'string' || !bin) throw new TypeError(`createTailscaleExposure: bin must be the tailscale CLI's path or name, got ${JSON.stringify(bin)}`)
+  if (socket !== null && (typeof socket !== 'string' || !socket)) throw new TypeError(`createTailscaleExposure: socket must be a path or null, got ${JSON.stringify(socket)}`)
+  if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError(`createTailscaleExposure: timeoutMs must be a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`)
+  }
+  // --socket is a global flag, so it goes before the subcommand. The timeout
+  // keeps a hung CLI from holding a reconcile pass forever.
+  const run = async args => {
+    const result = await execFileFn(bin, [...(socket ? [`--socket=${socket}`] : []), ...args], { timeout: timeoutMs })
+    return String(result?.stdout ?? '')
+  }
+
+  // The serve config. With none, the CLI prints {} (1.98.5); empty output and
+  // a JSON null mean the same.
+  async function status() {
+    const out = (await run(SERVE_STATUS)).trim()
+    if (!out) return {}
+    let st
+    try { st = JSON.parse(out) } catch {
+      throw new Error(`tailscale serve status --json printed something that is not JSON: ${snippet(out)}`)
+    }
+    if (st === null) return {}
+    if (typeof st !== 'object' || Array.isArray(st)) throw new Error(`tailscale serve status --json printed JSON that is not a JSON object: ${snippet(out)}`)
+    return st
+  }
+
+  // What tailscaled serves for a mount, from the status JSON:
+  // - `actual`: the proxy target served over https at the mount's own
+  //   (port, path), or null;
+  // - `shadows`: the other handlers on that Web key that take some of the
+  //   mount's requests and don't proxy to its target, each as
+  //   `<path> -> <proxy>` or `<path> (not a proxy)`. tailscaled hands a
+  //   request to the deepest handler path that holds it, trying `<dir>/`
+  //   before `<dir>` (getServeHandler in ipn/ipnlocal/serve.go). So `/qa/`
+  //   or `/qa/api` beside the harness's `/qa` takes harness requests, and
+  //   any other path on a pane's port takes pane requests.
+  // The Web key is the mount's own host:port, else the first key on that port
+  // (a mount host that is a short MagicDNS name, say).
+  function served(st, { host, port, path, target }) {
+    if (st.TCP?.[String(port)]?.HTTPS !== true) return { actual: null, shadows: [] }
+    const keys = Object.keys(st.Web ?? {})
+    const exact = `${host}:${port}`.toLowerCase()
+    const key = keys.find(k => k.toLowerCase() === exact) ?? keys.find(k => k.endsWith(`:${port}`))
+    const handlers = (key === undefined ? undefined : st.Web[key]?.Handlers) ?? {}
+    const under = path.endsWith('/') ? path : `${path}/`
+    const shadows = []
+    for (const [p, handler] of Object.entries(handlers)) {
+      if (p === path || !p.startsWith(under)) continue
+      const proxy = proxyOf(handler)
+      if (proxy !== null && sameTarget(proxy, target)) continue
+      shadows.push(proxy === null ? `${p} (not a proxy)` : `${p} -> ${proxy}`)
+    }
+    return { actual: Object.hasOwn(handlers, path) ? proxyOf(handlers[path]) : null, shadows }
+  }
+
+  const inPlace = (actual, mount) => actual !== null && sameTarget(actual, mount.target)
+
+  // A mount drifts when its own handler is missing or points elsewhere
+  // (`actual` is that handler's target, or null), and once more for each
+  // handler that shadows it (`actual` names that handler).
+  async function check(mounts) {
+    assertMounts(mounts)
+    const st = await status()
+    const drift = []
+    for (const mount of mounts) {
+      const { actual, shadows } = served(st, mount)
+      if (!inPlace(actual, mount)) drift.push({ mount, actual })
+      for (const shadow of shadows) drift.push({ mount, actual: shadow })
+    }
+    return { ok: drift.length === 0, drift }
+  }
+
+  // Writes each mount whose own handler drifted, and only those: a handler
+  // that shadows a mount isn't the conductor's, so it is reported and left
+  // alone. One that fails doesn't stop the rest, so a port another listener
+  // holds can't keep the others down. Then it rejects, naming each failure,
+  // and the error's `added` lists the mounts that were written.
+  async function ensure(mounts) {
+    assertMounts(mounts)
+    const st = await status()
+    const added = []
+    const failed = []
+    for (const mount of mounts.filter(m => !inPlace(served(st, m).actual, m))) {
+      const args = ['serve', '--bg', `--https=${mount.port}`, ...(mount.path === '/' ? [] : [`--set-path=${mount.path}`]), mount.target]
+      try {
+        await run(args)
+        added.push(mount)
+      } catch (err) {
+        failed.push({ mount, err })
+      }
+    }
+    if (failed.length) {
+      const lines = failed.map(({ mount, err }) => `could not mount ${mount.port}${mount.path} -> ${mount.target}: ${err?.message ?? err}`)
+      throw Object.assign(new AggregateError(failed.map(f => f.err), lines.join('\n')), { added })
+    }
+    return { added, ok: mounts.filter(m => !added.includes(m)) }
+  }
+
+  return { check, ensure }
+}

package/lib/adapters/provisioner-docker.mjs

@@ -0,0 +1,116 @@
+// Docker Provisioner adapter: the built-in Provisioner for docker-sibling
+// deployments.
+//
+// It owns everything docker: the pane pg containers, the shared network, the
+// app containers, registry auth, the one-shot migrate run, the pane env files
+// (mode 0600, under workDir), the startup orphan sweep and the failure log
+// tails. The conductor core never touches docker. A managed-Postgres or
+// process-based deployment provides a peer provisioner; the core and the other
+// four seams are identical either way.
+//
+// Single-service per pane: each pane runs its services as `qa-app-<role>`
+// with one env file; multi-service docker panes are a follow-up when a
+// consumer needs them.
+//
+// Effects are injected (docker wrappers, fsx) so this is unit-tested against a
+// recording docker mock with no real containers.
+
+import { renderEnv } from '../session.mjs'
+
+export function createDockerProvisioner({
+  docker,
+  fsx,
+  // directory the pane env files are written to (must be readable by the
+  // docker daemon's `--env-file` path resolution, i.e. the conductor's cwd view)
+  workDir,
+  network = 'qa-session',
+  postgres = { user: 'qa', password: 'qa', db: 'postgres' },
+  // per-role loopback host ports the app container publishes on
+  hostPorts = { base: 3111, pr: 3112 },
+  // registry credentials: log in before pulls, relogin on pull retry
+  registry = null,
+}) {
+  const ensureOpts = registry ? { relogin: () => docker.login(registry.user, registry.token) } : {}
+  const login = async () => {
+    if (registry) await docker.login(registry.user, registry.token)
+  }
+  const pgName = role => `qa-pg-${role}`
+  const appName = role => `qa-app-${role}`
+  const envFile = role => `${workDir}/.env.qa-${role}`
+  // The env carries prod-derived secrets: owner-only, and scrubbed on teardown.
+  const writeEnv = async (role, env) => {
+    const path = envFile(role)
+    await fsx.writeFile(path, renderEnv(env ?? {}), { mode: 0o600 })
+    return path
+  }
+
+  return {
+    network,
+
+    async provisionDatabase({ paneRef, databases }) {
+      await docker.createNetwork(network).catch(() => {}) // idempotent; shared across panes
+      const pg = pgName(paneRef.role)
+      await docker.runPg(pg, network)
+      await docker.waitHealthyPg(pg, {})
+      for (const d of databases) await docker.createDatabase(pg, d)
+      const dsn = `postgresql://${postgres.user}:${postgres.password}@${pg}:5432`
+      // query handle = docker-exec psql; the topology stays inside this adapter.
+      // query takes an optional {database} so adapters can target a specific
+      // logical DB (homefree's magic_links lives in `idp`, not the admin DB).
+      const db = { dsn, query: (sql, { database } = {}) => docker.psql(pg, database ?? postgres.db, sql) }
+      return { dsn, db }
+    },
+
+    async reserveServices({ paneRef, services }) {
+      // Docker host ports are deterministic per role, so reservation is pure:
+      // assign the loopback url/port without starting anything.
+      const port = hostPorts[paneRef.role]
+      const out = {}
+      for (const name of Object.keys(services)) out[name] = { url: `http://127.0.0.1:${port}`, port }
+      return out
+    },
+
+    // One-shot migration: run the migrate image on the pane network with the
+    // same env the app will get. Pulls explicitly (retry + relogin) so a
+    // transient registry hiccup can't half-fail a docker run.
+    async runMigrate({ paneRef, migrate, env }) {
+      await login()
+      await docker.ensureImage(migrate.image, ensureOpts)
+      const file = await writeEnv(paneRef.role, env.app ?? Object.values(env)[0])
+      await docker.runMigrate(migrate.image, network, file)
+    },
+
+    async launchServices({ paneRef, services, env, reserved }) {
+      await login()
+      for (const [name, image] of Object.entries(services)) {
+        await docker.ensureImage(image, ensureOpts)
+        const file = await writeEnv(paneRef.role, env[name])
+        await docker.runApp(appName(paneRef.role), image, network, file, reserved[name].port)
+      }
+    },
+
+    async waitHealthy({ services }) {
+      for (const svc of Object.values(services)) if (svc.port) await docker.waitHealthyApp(svc.port, {})
+    },
+
+    // Failure triage: the app container once it exists, the pg container before.
+    async logs({ paneRef, stage, lines = 40 }) {
+      const container = stage === 'starting' ? appName(paneRef.role) : pgName(paneRef.role)
+      return docker.logsTail(container, lines)
+    },
+
+    // Startup: remove labelled orphans (and the network) from a previous run.
+    async sweep() {
+      await docker.sweepQaContainers()
+      await docker.rmNetwork(network)
+    },
+
+    async teardown({ paneRef }) {
+      await docker.rmForce([appName(paneRef.role), pgName(paneRef.role)])
+      // Shared across panes; removal succeeds once the last pane is gone and
+      // is tolerated (rmNetwork swallows already-gone/in-use) otherwise.
+      await docker.rmNetwork(network)
+      await fsx.unlink(envFile(paneRef.role)).catch(() => {})
+    },
+  }
+}