redkite 0.1.6

package/src/cli/viewer.ts

@@ -0,0 +1,192 @@
+import type { Log, Task } from "../log.js";
+
+import {
+  apply,
+  elapsed,
+  emptyModel,
+  keysOf,
+  render,
+  type Model,
+  type Step,
+} from "./screen.js";
+
+// The terminal half: raw keys in, a frame out on a timer. Everything it decides
+// lives in screen.ts, so this file is only the parts a test cannot run.
+
+const FRAME_MS = 100;
+const ALTERNATE_ON = "\u001b[?1049h\u001b[?25l";
+const ALTERNATE_OFF = "\u001b[?25h\u001b[?1049l";
+const HOME = "\u001b[H";
+const CLEAR_LINE = "\u001b[K";
+const CLEAR_BELOW = "\u001b[J";
+
+// A build prints tens of thousands of lines and only the tail is ever read
+const KEPT = 2000;
+
+export type Viewer = Log & {
+  // Leaves the alternate screen and prints what happened, since nothing drawn
+  // inside it survives
+  close(): void;
+};
+
+// A pty whose size nobody set answers 0 rather than nothing, and a view one row
+// tall can only ever show the step the cursor is on
+const ROWS = 24;
+const COLUMNS = 80;
+
+const sizeOf = (stream: NodeJS.WriteStream) => ({
+  rows: stream.rows && stream.rows > 4 ? stream.rows : ROWS,
+  columns: stream.columns && stream.columns > 20 ? stream.columns : COLUMNS,
+});
+
+export type ViewerOptions = {
+  // Called on the quit key. The caller decides what asking twice means, since
+  // the same request arrives as a signal when there is no view
+  onQuit?: () => void;
+};
+
+export function createViewer(
+  stream: NodeJS.WriteStream,
+  input: NodeJS.ReadStream,
+  options: ViewerOptions = {},
+): Viewer {
+  // NO_COLOR is a standing instruction rather than a preference to re-ask
+  // about, and a terminal that took the alternate screen still may not paint
+  const colour = !process.env["NO_COLOR"] && stream.isTTY === true;
+  const size = sizeOf(stream);
+  let model = emptyModel(size.rows, size.columns, Date.now());
+  let open = true;
+
+  const draw = () => {
+    if (!open) return;
+
+    model = { ...model, now: Date.now(), ...sizeOf(stream) };
+    const rows = render(model, colour).map((row) => `${row}${CLEAR_LINE}`);
+
+    stream.write(`${HOME}${rows.join("\n")}${CLEAR_BELOW}`);
+  };
+
+  const change = (next: (current: Model) => Model) => {
+    model = next(model);
+    draw();
+  };
+
+  const timer = setInterval(draw, FRAME_MS);
+  timer.unref();
+
+  stream.write(ALTERNATE_ON);
+  if (input.isTTY) input.setRawMode(true);
+  input.resume();
+  input.setEncoding("utf8");
+
+  const say = (message: string) =>
+    change((current) => ({ ...current, messages: [...current.messages, message] }));
+
+  const onKey = (data: string) => {
+    for (const key of keysOf(data)) {
+      // Not a return: two presses in one read are two asks, and the second one
+      // is what hardens the signal the first one sent
+      if (key === "quit") quit();
+      else change((current) => apply(current, key));
+    }
+  };
+
+  input.on("data", onKey);
+  const onResize = () => draw();
+  stream.on("resize", onResize);
+
+  const close = () => {
+    if (!open) return;
+    open = false;
+
+    clearInterval(timer);
+    input.off("data", onKey);
+    stream.off("resize", onResize);
+    if (input.isTTY) input.setRawMode(false);
+    input.pause();
+
+    stream.write(ALTERNATE_OFF);
+    // The alternate screen takes every frame with it, so the run has to be
+    // written again on the screen the person keeps
+    for (const line of summary(model)) stream.write(`${line}\n`);
+  };
+
+  // What a second press means is not the view's to decide: the same key
+  // arrives as a signal when there is no view, and one answer serves both
+  const quit = () => options.onQuit?.();
+
+  process.once("exit", () => open && stream.write(ALTERNATE_OFF));
+
+  const step = (label: string): Task => {
+    let index = 0;
+
+    change((current) => {
+      index = current.steps.length;
+
+      const started: Step = {
+        label,
+        started: Date.now(),
+        state: "running",
+        lines: [],
+        // The one running is the one being read, unless the reader said no
+        expanded: !current.minimal,
+        held: false,
+        offset: 0,
+      };
+
+      return {
+        ...current,
+        steps: [...current.steps, started],
+        cursor: current.following ? index : current.cursor,
+      };
+    });
+
+    const edit = (change_: (step: Step) => Step) =>
+      change((current) => ({
+        ...current,
+        steps: current.steps.map((item, at) => (at === index ? change_(item) : item)),
+      }));
+
+    // A finished step shuts, so the list stays a list. One the reader opened by
+    // hand stays open: it is being read, and closing it would move the screen
+    const settle = (state: Step["state"], note?: string) =>
+      edit((item) => ({
+        ...item,
+        state,
+        note,
+        detail: undefined,
+        ended: Date.now(),
+        expanded: item.held,
+      }));
+
+    return {
+      detail: (message) => edit((item) => ({ ...item, detail: message })),
+      line: (message) =>
+        edit((item) => ({ ...item, lines: [...item.lines, message].slice(-KEPT) })),
+      done: (message) => settle("done", message),
+      fail: (message) => settle("failed", message),
+    };
+  };
+
+  return Object.assign(say, {
+    warn: say,
+    fail: say,
+    done: say,
+    step,
+    close,
+  });
+}
+
+// One line per step and whatever was said outside them, which is the record a
+// person scrolls back to after the deploy is over
+function summary(model: Model): string[] {
+  const rows = model.steps.map((step) => {
+    const glyph = step.state === "done" ? "✔" : step.state === "failed" ? "✘" : "·";
+    const said = step.note ? `: ${step.note}` : "";
+    const took = elapsed(step.ended ?? model.now, step.started);
+
+    return `${glyph} ${step.label}${said} (${took})`;
+  });
+
+  return [...rows, ...model.messages];
+}

package/src/config.ts

@@ -0,0 +1,90 @@
+import { assertSteps } from "./pipeline.js";
+import type { Deployment, Environment } from "./types.js";
+
+// The one selected, from the one place worth looking. A deployment that carries
+// its own overrides every file, which is what makes it an override rather than
+// a default nobody can displace
+export function environmentOf(config: Deployment, name: string) {
+  return config.environment ?? config.environments?.[name];
+}
+
+// Identity, but it pins the type so a missing health predicate fails to
+// compile. Environments are excluded rather than merely unused: each lives in
+// a redkite.<name>.config.ts of its own, and a second place to put one is a
+// second place for them to disagree
+export function defineDeployment<const T extends Deployment & { environments?: never }>(
+  config: T,
+): T {
+  assertUniqueNames(config);
+  assertOneSource(config);
+  assertRoutesResolvable(config);
+  assertDirsRelative(config);
+  assertSteps(config.steps ?? []);
+  return config;
+}
+
+// Identity, for the environment a redkite.<name>.config.ts holds. It pins the
+// type the same way defineDeployment does, so a missing subnet fails to compile
+export function defineEnvironment<const T extends Environment>(environment: T): T {
+  return environment;
+}
+
+// Cloned or already here, and the two are built differently enough that
+// guessing between them is worse than being told
+function assertOneSource(config: Deployment) {
+  for (const app of config.apps) {
+    if (app.repo && app.path) {
+      throw new Error(`${app.name} names both a repo and a path, and is built from one of them`);
+    }
+
+    if (!app.repo && !app.path) {
+      throw new Error(`${app.name} names no source, so give it a repo to clone or a path to build`);
+    }
+
+    // A clone is whatever the repository holds, so there is nothing here to
+    // narrow and an include would quietly do nothing
+    if (app.include && !app.path) {
+      throw new Error(`${app.name} says what to include, but is cloned rather than built from a path`);
+    }
+
+    if (app.include?.length === 0) {
+      throw new Error(`${app.name} includes nothing, so there would be no build context`);
+    }
+  }
+}
+
+// A dir is joined onto /app inside the image, so an absolute one would render
+// a path with two slashes and a climbing one would leave the checkout
+function assertDirsRelative(config: Deployment) {
+  for (const app of config.apps) {
+    const dir = app.dir;
+    if (dir === undefined) continue;
+
+    if (!dir || dir.startsWith("/") || dir.endsWith("/")) {
+      throw new Error(`dir for ${app.name} must be a path inside the repository`);
+    }
+
+    if (dir.split("/").includes("..")) {
+      throw new Error(`dir for ${app.name} must not climb out of the repository`);
+    }
+  }
+}
+
+function assertUniqueNames(config: Deployment) {
+  const names = [...config.apps, ...config.services].map((item) => item.name);
+  const duplicate = names.find((name, i) => names.indexOf(name) !== i);
+  if (duplicate) throw new Error(`Duplicate name in deployment: ${duplicate}`);
+}
+
+// Two apps on the same route means one of them is unreachable, and which one
+// depends on nginx location precedence rather than on anything written here
+function assertRoutesResolvable(config: Deployment) {
+  const routes = config.apps.map((app) => app.route);
+  const duplicate = routes.find((route, i) => routes.indexOf(route) !== i);
+  if (duplicate) throw new Error(`Two apps share the route ${duplicate}`);
+
+  for (const app of config.apps) {
+    if (app.route.startsWith("/")) continue;
+    throw new Error(`Route for ${app.name} must start with a slash`);
+  }
+}

package/src/deploy.ts

@@ -0,0 +1,409 @@
+import { build, type BuildContext, type BuildResult } from "./build.js";
+import { assertCheckable, runChecks } from "./checks.js";
+import { environmentOf } from "./config.js";
+import { Docker } from "./docker.js";
+import { healthcheck, type HealthDeps } from "./health.js";
+import type { Host } from "./host.js";
+import { localHost } from "./localHost.js";
+import { silent, type Log } from "./log.js";
+import {
+  defineStep,
+  merge,
+  runPipeline,
+  type AnyStep,
+  type Built,
+  type BuiltApp,
+  type Context,
+  type Finished,
+  type Plan,
+  type Prepared,
+  type Released,
+  type Run,
+  type Start,
+} from "./pipeline.js";
+import { readEnv, readRef, type SecretStores } from "./secrets/refs.js";
+import { ensureService } from "./services/ensure.js";
+import { plannedServices } from "./services/planned.js";
+import { topologyFor, type AppTopology, type Topology } from "./topology.js";
+import type { AppSpec, Deployment } from "./types.js";
+
+// The runs redkite offers, and the steps it supplies to them. A deploy is
+// blue-green: bring the host up, build everything, move addresses, check,
+// revert or stop. A verify stops after the build and runs what the apps declare
+// instead of swapping, which is the same host and the same images without the
+// half of it that touches what is serving.
+//
+// Nothing here is privileged. Each of these is an ordinary step at an ordinary
+// point, and a deployment that registers its own at the same point replaces it.
+
+export type DeployOptions = {
+  config: Deployment;
+  environment: string;
+  // The machine the containers run on, and which now builds them too
+  host: Host;
+  // One store per provider named by a ref in the config
+  secrets: SecretStores;
+  // How the probe waits between attempts. Absent means a real wait, which is
+  // what everything but a test wants
+  health?: Omit<HealthDeps, "probe">;
+  log?: Log;
+  // Prints what each build wrote, line by line as it runs
+  verbose?: boolean;
+  // Stops the run. Whatever command is in flight is killed, and the pipeline
+  // unwinds through its own failure path rather than through an exit
+  signal?: AbortSignal;
+};
+
+export async function deploy(options: DeployOptions): Promise<Finished> {
+  return await start("deploy", options);
+}
+
+// The same host, the same services and the same images, stopping where a deploy
+// would start moving addresses. What runs instead is what each app declares
+export async function verify(options: DeployOptions): Promise<Finished> {
+  return await start("verify", options);
+}
+
+async function start(run: Run, options: DeployOptions): Promise<Finished> {
+  const log = options.log ?? silent;
+
+  const setting: Omit<Context, "task"> = {
+    config: options.config,
+    environment: options.environment,
+    topology: topologyFor(options.config, options.environment),
+    host: options.host,
+    docker: new Docker(options.host),
+    secrets: options.secrets,
+    log,
+    run,
+  };
+
+  const steps = merge(supplied(options), options.config.steps ?? []);
+  return await runPipeline(run, steps, setting, options.signal);
+}
+
+// Every step redkite supplies, in the order the phases name. A run walks the
+// phases it has, so the ones it does not are never ordered in
+function supplied(options: DeployOptions): AnyStep[] {
+  return [
+    defineStep("setup", prepare),
+    defineStep("build", (input, context) =>
+      compile(input, context, options.verbose ?? false, options.signal),
+    ),
+    defineStep("verify", runChecks, assertCheckable),
+    defineStep(
+      "swap",
+      (input, context) => release(input, context, options.health ?? { sleep: wait }),
+      assertPublishable,
+    ),
+    defineStep("cleanup", finish),
+  ];
+}
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// A deploy publishes the proxy on a port, and an environment written for verify
+// alone has no reason to name one. Checked before the run so the mistake lands
+// before a build rather than on a proxy nobody outside can reach
+function assertPublishable(plan: Plan) {
+  if (environmentOf(plan.config, plan.environment)?.publicPort) return;
+
+  throw new Error(
+    `${plan.environment} names no publicPort, so a deploy has nothing to publish ` +
+      "the proxy on. Only a verify run goes without one",
+  );
+}
+
+// The network and the services, which outlive a run and are only built when
+// they are missing. This used to overlap the builds, and now costs the round
+// trips it takes rather than nothing, which is what buys a setup step a host
+// it can rely on
+async function prepare(input: Start, context: Context): Promise<Prepared> {
+  const { docker, topology } = context;
+
+  await docker.network.create(topology.network, topology.cidr);
+  const services = await ensureServices(context);
+
+  return { ...input, network: topology.network, services };
+}
+
+// Every image is built before anything is disturbed. A build failure has to
+// leave the running deployment exactly as it was, which is why this is a step
+// of its own rather than the first half of the swap
+async function compile(
+  input: Prepared,
+  context: Context,
+  verbose: boolean,
+  signal?: AbortSignal,
+): Promise<Built> {
+  // One checkout directory for every app, opened here so the build step owns
+  // its lifetime rather than the process
+  const here = buildsHere(context) ? await localHost({ signal }) : undefined;
+
+  try {
+    return { ...input, apps: (await buildAll(context, verbose, here)).map(describe) };
+  } finally {
+    await here?.close?.();
+  }
+}
+
+// Building here and deploying here are the same daemon, so shipping would be a
+// save and a load of an image that never moved. An app built from a path on
+// this machine has no say in it: the source is here, so the build is too
+function buildsHere(context: Context) {
+  const environment = environmentOf(context.config, context.environment);
+  if (!environment?.host?.bastion) return false;
+
+  return environment.buildOn === "local" || context.config.apps.some((app) => app.path);
+}
+
+async function release(
+  input: Built,
+  context: Context,
+  health: Omit<HealthDeps, "probe">,
+): Promise<Released> {
+  const { docker, task, topology } = context;
+  const apps = context.config.apps.map((app) => appOf(topology, app.name));
+
+  // Keyed by name rather than by index: appOf resolves the topology, and two
+  // lists walked in step is a bug waiting for someone to reorder one
+  const environments = new Map(
+    context.config.apps.map((app) => [app.name, app.environment ?? {}]),
+  );
+
+  task.detail("retiring the running containers");
+  await Promise.all(apps.map((app) => retire(docker, topology, app)));
+
+  task.detail("creating the new ones");
+
+  await Promise.all(
+    apps.map((app) =>
+      create(docker, topology, app, environments.get(app.name)),
+    ),
+  );
+
+  task.detail("starting them");
+  await Promise.all(apps.map((app) => docker.container.start(app.container)));
+
+  // One unhealthy app reverts all of them. A half-swapped deployment is the
+  // one state nothing downstream knows how to reason about
+  if (!(await checkAll(context, health))) {
+    context.log.fail("Health checks failed, reverting");
+    await Promise.all(apps.map((app) => revert(docker, topology, app)));
+
+    return {
+      ...input,
+      ok: false,
+      released: [],
+      reverted: apps.map((app) => app.container),
+      checked: [],
+    };
+  }
+
+  return {
+    ...input,
+    ok: true,
+    released: apps.map((app) => app.container),
+    reverted: [],
+    checked: [],
+  };
+}
+
+// A build leaves its image on the host rather than sending one, so without this
+// every run adds a runtime image and a builder to a disk nobody is watching
+async function finish(input: Released, context: Context): Promise<Finished> {
+  // What would be removed is what is serving, and the images are what a retry
+  // would be built from
+  if (!input.ok) return { ...input, removed: [], reclaimed: [] };
+
+  const { docker, topology } = context;
+  const apps = context.config.apps.map((app) => appOf(topology, app.name));
+
+  const removed = await Promise.all(apps.map((app) => cleanup(docker, app)));
+  const reclaimed = await Promise.all(input.apps.map((app) => reclaim(docker, app)));
+
+  return { ...input, removed: removed.flat(), reclaimed: reclaimed.flat() };
+}
+
+function describe({ app, result }: Built0): BuiltApp {
+  return {
+    name: app.name,
+    container: result.tag.split(":")[0] ?? app.name,
+    release: result.release,
+    fingerprint: result.fingerprint,
+    cached: result.cached,
+    builderTag: result.builderTag,
+  };
+}
+
+async function checkAll(context: Context, health: Omit<HealthDeps, "probe">) {
+  const { docker, log, topology } = context;
+
+  const results = await Promise.all(
+    context.config.apps.map(async (app) => {
+      const target = appOf(topology, app.name);
+      const deps: HealthDeps = {
+        ...health,
+        probe: async (container, url) => {
+          const result = await docker.run(`exec ${container} curl -s ${url}`);
+          return { code: result.code, output: result.stdout };
+        },
+        log,
+      };
+
+      return await healthcheck(target.container, target.port, app.health, deps);
+    }),
+  );
+
+  return !results.includes(false);
+}
+
+// The proxy is one of these, derived rather than listed. What each should be
+// is worked out in one place, so a plan reports drift against the same shape a
+// deploy converges to
+async function ensureServices(context: Context) {
+  const planned = plannedServices(context.config, context.topology, context.run);
+
+  return await Promise.all(
+    planned.map(async (item) => {
+      await ensureService(item.spec, item.service, {
+        ...context,
+        files: item.files,
+        publish: item.publish,
+      });
+
+      return item.service.container;
+    }),
+  );
+}
+
+type Built0 = { app: AppSpec; result: BuildResult };
+
+async function buildAll(
+  context: Context,
+  verbose: boolean,
+  here?: Host,
+): Promise<Built0[]> {
+  const { config, log, topology } = context;
+  const environment = environmentOf(config, context.environment);
+
+  if (!environment) throw new Error(`Unknown environment ${context.environment}`);
+
+  return await Promise.all(
+    config.apps.map(async (app) => {
+      const task = log.step(`Building ${app.name}`);
+
+      try {
+        const buildContext: BuildContext = {
+          host: here ?? context.host,
+          docker: here ? new Docker(here) : context.docker,
+          deliver: here && { host: context.host, docker: context.docker },
+          env: await readEnv(app.secrets, context.secrets),
+          files: await resolveFiles(app, context.secrets),
+          branch: environment.branch,
+          environment: context.environment,
+          detail: task.detail,
+          output: task.line,
+        };
+
+        const result = await build(app, appOf(topology, app.name), buildContext);
+        task.done(`${result.release.slice(0, 7)}${result.cached ? " (held)" : ""}`);
+
+        return { app, result };
+      } catch (error) {
+        task.fail(`${app.name} failed to build`);
+        throw error;
+      }
+    }),
+  );
+}
+
+async function resolveFiles(app: AppSpec, stores: SecretStores) {
+  const entries = await Promise.all(
+    Object.entries(app.files ?? {}).map(
+      async ([path, ref]) => [path, await readRef(ref, stores)] as const,
+    ),
+  );
+
+  return Object.fromEntries(entries);
+}
+
+// Move the running container out of the way without stopping it, so it keeps
+// answering on the retired address while the new one starts
+async function retire(docker: Docker, topology: Topology, app: AppTopology) {
+  await docker.container.stop(app.retired);
+  await docker.container.remove(app.retired);
+  await docker.network.reconnect(topology.network, app.container, app.retiredAddress);
+  await docker.container.rename(app.container, app.retired);
+}
+
+async function create(
+  docker: Docker,
+  topology: Topology,
+  app: AppTopology,
+  environment: Record<string, string> = {},
+) {
+  const builder = docker.container
+    .builder()
+    .name(app.container)
+    .image(app.container)
+    .network(topology.network)
+    .ip(app.currentAddress)
+    .restart("unless-stopped");
+
+  for (const [host, ip] of Object.entries(topology.extraHosts)) {
+    // An app resolving its own name to the live address would loop
+    if (host === app.container || host === app.retired) continue;
+    builder.extraHost(host, ip);
+  }
+
+  for (const volume of app.volumes) builder.volume(volume.volume, volume.mountPath);
+  for (const [name, value] of Object.entries(environment)) builder.env(name, value);
+
+  await builder.create();
+}
+
+// Put the retired container back on the live address and its original name
+async function revert(docker: Docker, topology: Topology, app: AppTopology) {
+  await docker.container.stop(app.container);
+  await docker.container.rename(app.container, app.failed);
+  await docker.network.reconnect(topology.network, app.retired, app.currentAddress);
+  await docker.container.rename(app.retired, app.container);
+  await docker.container.start(app.container);
+}
+
+async function cleanup(docker: Docker, app: AppTopology) {
+  const removed: string[] = [];
+
+  for (const name of [app.retired, app.failed]) {
+    await docker.container.stop(name);
+    if (await docker.container.remove(name)) removed.push(name);
+  }
+
+  return removed;
+}
+
+// Every version of this app's images except the one that was just released,
+// including the builder a step before the swap ran in
+async function reclaim(docker: Docker, app: BuiltApp) {
+  const version = `${app.release}-${app.fingerprint}`;
+  const reclaimed: string[] = [];
+
+  for (const repository of [app.container, `${app.container}-builder`]) {
+    for (const held of await docker.image.versionsOf(repository)) {
+      if (held === `${repository}:${version}`) continue;
+
+      await docker.image.remove(held);
+      reclaimed.push(held);
+    }
+  }
+
+  return reclaimed;
+}
+
+function appOf(topology: Topology, name: string) {
+  const app = topology.apps.find((item) => item.name === name);
+  if (app) return app;
+
+  throw new Error(`No topology for app ${name}`);
+}