redkite 0.1.6

package/src/health.ts

@@ -0,0 +1,83 @@
+import { silent, type Log } from "./log.js";
+import type { HealthSpec } from "./types.js";
+
+const RETRIES = 10;
+// Ceiling for the backoff, not a fixed wait
+const INTERVAL_MS = 5000;
+// The first probe is free, a container that is already up answers it
+const DELAY_MS = 0;
+const FIRST_BACKOFF_MS = 250;
+
+export type Probe = (
+  container: string,
+  url: string,
+) => Promise<{ code: number; output: string }>;
+
+export type HealthDeps = {
+  probe: Probe;
+  sleep: (ms: number) => Promise<void>;
+  log?: Log;
+};
+
+// One loop for every app. The two copies it replaces had already drifted: the
+// frontend never incremented its counter on a failed predicate, so a container
+// that answered but never became healthy span until the deploy was killed.
+export async function healthcheck(
+  container: string,
+  port: number,
+  spec: HealthSpec,
+  deps: HealthDeps,
+): Promise<boolean> {
+  const retries = spec.retries ?? RETRIES;
+  const ceiling = spec.intervalMs ?? INTERVAL_MS;
+  const log = deps.log ?? silent;
+  const delay = spec.delayMs ?? DELAY_MS;
+
+  if (delay > 0) await deps.sleep(delay);
+
+  let backoff = FIRST_BACKOFF_MS;
+
+  for (let attempt = 1; attempt <= retries; attempt += 1) {
+    const url = `localhost:${port}${spec.path}`;
+    const { code, output } = await deps.probe(container, url);
+
+    if (code === 0 && passes(spec, output, log, container)) {
+      log.done(`${container} is healthy`);
+      return true;
+    }
+
+    if (attempt === retries) break;
+
+    // Doubling from a quarter second means a container that starts quickly
+    // costs almost nothing, and one that does not still gets the same budget
+    await deps.sleep(backoff);
+    backoff = Math.min(backoff * 2, ceiling);
+  }
+
+  log.fail(`${container} failed its health check after ${retries} attempts`);
+  return false;
+}
+
+// A body that parses but fails the predicate is a retry, not a verdict. The
+// container may still be warming up, and the caller has a retry budget for it
+function passes(
+  spec: HealthSpec,
+  output: string,
+  log: Log,
+  container: string,
+) {
+  let body: unknown;
+
+  try {
+    body = JSON.parse(output);
+  } catch {
+    log.warn(`${container} returned a body that is not JSON: ${output}`);
+    return false;
+  }
+
+  if (typeof body !== "object" || body === null) return false;
+  if (spec.expect(body as Record<string, unknown>)) return true;
+
+  log.warn(`${container} is not healthy yet: ${output}`);
+  return false;
+}

package/src/host.ts

@@ -0,0 +1,54 @@
+// The machine the containers run on. Every command a deploy issues goes through
+// this, so the rest of the library is exercised against a recorder rather than
+// against a host. Two implementations: one over ssh, one on this machine.
+
+export type Result = { code: number; stdout: string; stderr: string };
+
+// Called per line while a command runs, for the ones long enough that the person
+// watching needs to know what they are waiting for
+export type OnLine = (line: string) => void;
+
+export type Host = {
+  // A shell command, run where the containers are. The shell is what lets a
+  // caller redirect, chain, and quote, which several of them do
+  sh(command: string, onLine?: OnLine): Promise<Result>;
+  // Writes contents to a file there, answering with the path it landed at.
+  // Parent directories are created, so a name may contain slashes
+  write(name: string, contents: string): Promise<string>;
+  // Scratch space this host hands out, removed when the deploy closes
+  readonly directory: string;
+  // Survives a deploy: the git mirrors and the checkouts built from them
+  readonly cache: string;
+  // Streams one command's output into another's input, the near side local and
+  // the far side here. Shipping an image is the only caller
+  pipe(local: string, remote: string, onLine?: OnLine): Promise<Result>;
+  // Signals everything this host started and answers with how many are still
+  // running. Zero is the only answer that means nothing was left behind
+  stop(signal: "TERM" | "KILL"): Promise<number>;
+  close?(): Promise<void>;
+};
+
+// A streamed command keeps this many lines, so a build that prints tens of
+// megabytes still fits in the error a failure reports
+const TAIL = 200;
+
+export function tail(lines: string[]) {
+  return lines.slice(-TAIL).join("\n");
+}
+
+// Splits a chunked stream into lines, holding the partial last one back
+export function lineReader(onLine: OnLine) {
+  let rest = "";
+
+  return {
+    push(chunk: string) {
+      const parts = (rest + chunk).split("\n");
+      rest = parts.pop() ?? "";
+      for (const line of parts) onLine(line);
+    },
+    flush() {
+      if (rest) onLine(rest);
+      rest = "";
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from "./build.js";
+export * from "./config.js";
+export * from "./deploy.js";
+export * from "./docker.js";
+export * from "./dockerfile.js";
+export * from "./health.js";
+export * from "./host.js";
+export * from "./layout.js";
+export * from "./localHost.js";
+export * from "./log.js";
+export * from "./nginx.js";
+export * from "./pipeline.js";
+export * from "./presets/index.js";
+export * from "./secrets/bitwarden.js";
+export * from "./secrets/refs.js";
+export * from "./secrets/store.js";
+export * from "./shell.js";
+export * from "./services/ensure.js";
+export * from "./services/index.js";
+export * from "./services/planned.js";
+export * from "./source.js";
+export * from "./sshHost.js";
+export * from "./steps.js";
+export * from "./topology.js";
+export * from "./types.js";

package/src/layout.ts

@@ -0,0 +1,41 @@
+// Where a cache is mounted and where a carried directory lands. The renderer
+// and the topology have to agree on these, and a second copy of them is a
+// drift waiting to happen.
+
+// A package manager's own cache is global; everything else is a path inside the
+// project. Both managers are listed because a preset does not know which the
+// repository uses, and mounting the wrong one is a cache that never hits
+export function mountFor(name: string, dir?: string) {
+  if (name === "yarn") return "/root/.yarn";
+  if (name === "npm") return "/root/.npm";
+  // A workspace resolves one lockfile at the repository root and hoists there
+  if (name === "modules") return "/app/node_modules";
+  // An app that installs against its own manifest puts them beside it instead.
+  // Both are mounted, because only the install command knows which it does, and
+  // mounting the wrong one alone is a cache that never hits
+  if (name === "app-modules") return `${appRoot(dir)}/node_modules`;
+  if (name === "next-app") return rootedAt("/app/.next/cache", dir);
+  return rootedAt(`/app/.cache/${name}`, dir);
+}
+
+// Where the app itself sits. The whole repository is copied to /app, and dir is
+// the app's own place in it
+export function appRoot(dir?: string) {
+  return dir ? `/app/${dir}` : "/app";
+}
+
+// A path under /app belongs to the app, so it moves with it. Bare /app is the
+// repository itself and stays: that is what a build shipping its whole tree copies
+export function rootedAt(path: string, dir?: string) {
+  if (!dir || !path.startsWith("/app/")) return path;
+  return `${appRoot(dir)}/${path.slice("/app/".length)}`;
+}
+
+// A directory inside the output root moves with it, because the output becomes
+// /app in the runtime. Anything else keeps the position it had in the builder:
+// flattening it to a basename is what put Next's static assets at /app/static,
+// where the server looks for them under .next and answers 404
+export function destinationFor(path: string, output: string) {
+  if (path.startsWith(`${output}/`)) return `/app/${path.slice(output.length + 1)}`;
+  return path;
+}

package/src/localHost.ts

@@ -0,0 +1,50 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import type { Host } from "./host.js";
+import { signalEverything, spawnCollect } from "./shell.js";
+
+// The same Host without a network in the way, for an environment that names no
+// bastion. Deploying to this machine and deploying to another one differ in
+// nothing but which of these the CLI constructs.
+
+export type LocalOptions = { cache?: string; signal?: AbortSignal };
+
+export async function localHost(options: LocalOptions = {}): Promise<Host> {
+  const directory = await mkdtemp(join(tmpdir(), "redkite-"));
+  const cache = options.cache ?? join(homedir(), ".cache", "redkite");
+
+  await mkdir(cache, { recursive: true });
+
+  return {
+    directory,
+    cache,
+    sh: async (command, onLine) =>
+      await spawnCollect("sh", ["-c", command], { onLine, signal: options.signal }),
+
+    write: async (name, contents) => {
+      const path = join(directory, name);
+
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, contents, { mode: 0o600 });
+
+      return path;
+    },
+
+    // Both ends are this machine, so the pipe is one shell away
+    pipe: async (local, remote, onLine) =>
+      await spawnCollect("sh", ["-c", `${local} | ${remote}`], {
+        onLine,
+        signal: options.signal,
+      }),
+
+    // The build is a grandchild of the shell that was spawned, and every child
+    // is a process group leader, so one signal reaches the whole tree
+    stop: async (name) => signalEverything(name === "KILL" ? "SIGKILL" : "SIGTERM"),
+
+    close: async () => {
+      await rm(directory, { recursive: true, force: true });
+    },
+  };
+}

package/src/log.ts

@@ -0,0 +1,38 @@
+// The shape progress is reported through. The library only knows this much, so
+// a deploy driven from somewhere without a terminal supplies its own.
+
+// Work that is still running. Announced when it starts, because the thing worth
+// knowing during a four minute build is which step is the four minutes
+export type Task = {
+  // What the step is doing right now, replacing whatever it said before
+  detail(message: string): void;
+  // A line the step produced, kept under it. detail replaces, this appends,
+  // and a build's own output is the reason there are two
+  line(message: string): void;
+  done(message?: string): void;
+  fail(message: string): void;
+};
+
+export type Log = ((message: string) => void) & {
+  // Something the run survived, but that the person should know happened
+  warn(message: string): void;
+  // The reason a deploy is about to stop, or did
+  fail(message: string): void;
+  // A step reaching the state it was waiting for
+  done(message: string): void;
+  step(label: string): Task;
+};
+
+const NOTHING: Task = {
+  detail: () => {},
+  line: () => {},
+  done: () => {},
+  fail: () => {},
+};
+
+export const silent: Log = Object.assign(() => {}, {
+  warn: () => {},
+  fail: () => {},
+  done: () => {},
+  step: () => NOTHING,
+});

package/src/nginx.ts

@@ -0,0 +1,63 @@
+import type { AppTopology, Topology } from "./topology.js";
+
+// The nginx configuration is a function of the app list. Header policy is set
+// here once rather than per location, which is what let the two blocks drift
+// apart and lose X-Forwarded-For on one of them.
+
+const FORWARDING = [
+  "proxy_set_header Host $http_host;",
+  "proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;",
+  "proxy_set_header X-Forwarded-Host $http_host;",
+  "proxy_set_header X-Forwarded-Proto $scheme;",
+];
+
+const FAILOVER = [
+  "proxy_connect_timeout 2s;",
+  "proxy_read_timeout 30s;",
+  "proxy_next_upstream error timeout http_502 http_503;",
+  "proxy_next_upstream_tries 2;",
+];
+
+// The port the proxy listens on inside its container. The published port maps
+// onto this one, so both sides have to agree and only one of them may say it
+export const LISTEN_PORT = 3000;
+
+export function renderNginx(topology: Topology, maxBodySize?: string) {
+
+  const upstreams = topology.apps.map((app) => upstream(app)).join("\n\n");
+  // Longest route first, so "/api/" is not shadowed by the "/" catch-all
+  const ordered = [...topology.apps].sort((a, b) => b.route.length - a.route.length);
+  const locations = ordered.map((app) => location(app)).join("\n\n");
+
+  return `resolver 127.0.0.1 valid=5s;
+
+${upstreams}
+
+server {
+    listen ${LISTEN_PORT};
+    merge_slashes off;
+
+    client_max_body_size ${maxBodySize ?? "1M"};
+
+${locations}
+}
+`;
+}
+
+function upstream(app: AppTopology) {
+  return `upstream ${app.name} {
+    server ${app.container}:${app.port} max_fails=1 fail_timeout=2s;
+    server ${app.retired}:${app.port} backup;
+}`;
+}
+
+function location(app: AppTopology) {
+  // A trailing slash on proxy_pass strips the location prefix. The catch-all
+  // must not carry one, a mounted route must
+  const target = app.route === "/" ? `http://${app.name}` : `http://${app.name}/`;
+  const body = [`proxy_pass ${target};`, ...FAILOVER, ...FORWARDING];
+
+  return `    location ${app.route} {
+${body.map((line) => `        ${line}`).join("\n")}
+    }`;
+}

package/src/pipeline.ts

@@ -0,0 +1,335 @@
+import type { Docker } from "./docker.js";
+import type { Host } from "./host.js";
+import type { Log, Task } from "./log.js";
+import type { SecretStores } from "./secrets/refs.js";
+import type { Topology } from "./topology.js";
+import type { Deployment } from "./types.js";
+
+// Capistrano's shape: work addressed by where it runs rather than by who calls
+// it, so a plugin or a config adds a step without any file here knowing it
+// exists. A run is a list of steps, each handed what the one before it answered
+// with. Redkite's own four are ordinary members of that list.
+
+// Every phase redkite supplies a step for. Each is also the name of the point
+// that step sits at. No run walks all of them: swap and verify are alternatives
+export const PHASES = ["setup", "build", "verify", "swap", "cleanup"] as const;
+export type Phase = (typeof PHASES)[number];
+
+// The phases each command walks, in the order it walks them. A phase left out
+// is not run, and a step hung on one of its slots never fires
+export const RUNS = {
+  deploy: ["setup", "build", "swap", "cleanup"],
+  verify: ["setup", "build", "verify", "cleanup"],
+} as const satisfies Record<string, readonly Phase[]>;
+
+export type Run = keyof typeof RUNS;
+
+// Everything before the phase's own step, the phase's own slot, everything after
+export const SLOTS = ["before", "main", "after"] as const;
+export type Slot = (typeof SLOTS)[number];
+
+// Where a step runs. The bare phase is the point redkite's own step sits at, and a
+// deployment that puts its own step there replaces it: nothing about redkite's
+// four makes them harder to displace than any other step
+export type Point = Phase | `${Phase}:${string}`;
+
+// Every point but the four redkite's own steps sit at. A hook is handed and
+// answers with one value, which is what lets a helper be written over all of
+// them at once
+export type Hook = Exclude<Point, Phase>;
+
+// What a run has done so far. Each phase adds to what it was handed rather than
+// replacing it, so a step late in the pipeline reads everything above it
+
+export type Start = {
+  environment: string;
+};
+
+export type Prepared = Start & {
+  network: string;
+  // Every service's container, whether this run created it or adopted one
+  services: string[];
+};
+
+export type BuiltApp = {
+  name: string;
+  container: string;
+  release: string;
+  fingerprint: string;
+  // The host already held this image, and nothing was rebuilt
+  cached: boolean;
+  // The image a step hung before the swap runs in, holding the app's own
+  // toolchain rather than only what it compiled to
+  builderTag: string;
+};
+
+export type Built = Prepared & {
+  apps: BuiltApp[];
+};
+
+export type Released = Built & {
+  // False when an app failed its health check and every app was put back, or
+  // when a check the verify step ran said the build does not work
+  ok: boolean;
+  released: string[];
+  reverted: string[];
+  // Apps whose checks ran. A deploy runs none, so only a verify fills this,
+  // and the two runs answer with one shape so a step after either reads it
+  checked: string[];
+};
+
+export type Finished = Released & {
+  removed: string[];
+  reclaimed: string[];
+};
+
+// Everything a step is given besides the value: what is being deployed, and the
+// machine it is being deployed to
+export type Context = {
+  config: Deployment;
+  environment: string;
+  // Which run this is. A step that behaves differently in one is rare, but the
+  // service set does: nothing serves in a verify, so it has no proxy
+  run: Run;
+  topology: Topology;
+  host: Host;
+  docker: Docker;
+  secrets: SecretStores;
+  log: Log;
+  // The progress row this step already has. A step says what it is doing
+  // through this rather than opening a second one beside it
+  task: Task;
+};
+
+// What a phase's step is handed, and what it answers with. The two together are
+// the only reason a step can be typed by where it runs
+type PhaseInput = {
+  setup: Start;
+  build: Prepared;
+  verify: Built;
+  swap: Built;
+  cleanup: Released;
+};
+
+type PhaseOutput = {
+  setup: Prepared;
+  build: Built;
+  verify: Released;
+  swap: Released;
+  cleanup: Finished;
+};
+
+type PhaseOf<P extends Point> = P extends Phase
+  ? P
+  : P extends `${infer F extends Phase}:${string}`
+    ? F
+    : never;
+
+// A phase's own step is what moves a run from one value to the next. Everything
+// hung around it is handed what that side of it produced, so a step is typed by
+// where it runs and never has to say what it takes
+export type InputAt<P extends Point> = P extends Phase
+  ? PhaseInput[P]
+  : P extends `${string}:before:${string}`
+    ? PhaseInput[PhaseOf<P>]
+    : PhaseOutput[PhaseOf<P>];
+
+export type OutputAt<P extends Point> = P extends Phase
+  ? PhaseOutput[P]
+  : P extends `${string}:before:${string}`
+    ? PhaseInput[PhaseOf<P>]
+    : PhaseOutput[PhaseOf<P>];
+
+// What a step can know before a run starts: nothing has happened yet, so this
+// is the config as written and the environment it was asked for
+export type Plan = {
+  config: Deployment;
+  environment: string;
+};
+
+// A property rather than a method, because a method's parameter is checked
+// bivariantly: declared as one, a step could narrow its input to a value the
+// slot it runs in has not produced yet
+export type Step<P extends Point = Point> = {
+  point: P;
+  // Run before the first step, so a step that cannot possibly work says so
+  // while the host is still untouched rather than half way through a swap
+  check?: (plan: Plan) => void;
+  run: (input: InputAt<P>, context: Context) => OutputAt<P> | Promise<OutputAt<P>>;
+};
+
+// Erased for storage. A list assembled from a config cannot carry each step's
+// own input type, and `never` is what every one of them accepts
+export type AnyStep = {
+  point: Point;
+  check?: (plan: Plan) => void;
+  run: (input: never, context: Context) => unknown;
+};
+
+// Identity, but it pins the point so a typo fails to compile and the input is
+// inferred from where the step runs rather than annotated
+export function defineStep<const P extends Point>(
+  point: P,
+  run: Step<P>["run"],
+  check?: Step<P>["check"],
+): Step<P> {
+  return { point, run, check };
+}
+
+// A step at the same point as one redkite supplies replaces it, in the place redkite
+// had it. That is the whole of turning one of redkite's four off: put something
+// there that does less, or nothing
+export function merge(supplied: AnyStep[], added: AnyStep[]): AnyStep[] {
+  const overrides = new Map(added.map((step) => [step.point, step]));
+  const claimed = new Set(supplied.map((step) => step.point));
+
+  return [
+    ...supplied.map((step) => overrides.get(step.point) ?? step),
+    ...added.filter((step) => !claimed.has(step.point)),
+  ];
+}
+
+// Stopping between steps, rather than in the middle of one. A step is the unit
+// that leaves the host in a state the next deploy can read
+export class Aborted extends Error {
+  constructor(point: string) {
+    super(`Stopped before ${point}`);
+    this.name = "Aborted";
+  }
+}
+
+export async function runPipeline(
+  run: Run,
+  steps: AnyStep[],
+  setting: Omit<Context, "task">,
+  signal?: AbortSignal,
+): Promise<Finished> {
+  const ordered = sequence(steps, RUNS[run]);
+  const plan: Plan = { config: setting.config, environment: setting.environment };
+
+  // Every check before any step, so a run that is going to fail on a config
+  // mistake fails before it has created a network or built an image. Nothing
+  // wraps what a check throws: it is about the config, and the config is what
+  // the reader has in front of them
+  for (const step of ordered) step.check?.(plan);
+
+  // Every step is handed what the one before it answered with, so the whole run
+  // is a fold over one list. Running part of it at once is a change here alone
+  let value: unknown = { environment: setting.environment } satisfies Start;
+
+  for (const step of ordered) {
+    if (signal?.aborted) throw new Aborted(step.point);
+
+    const task = setting.log.step(step.point);
+
+    // A step declares what it takes and answers with through its point, and a
+    // list assembled from a config cannot carry that through. The declared
+    // types are the contract, and this is the one place they are taken on trust
+    const run = step.run as (input: unknown, context: Context) => unknown;
+
+    try {
+      value = await run(value, { ...setting, task });
+      task.done();
+    } catch (error) {
+      // One step throwing ends the run. Everything after it was written
+      // assuming the steps before did what they said they would
+      task.fail(`${step.point} failed`);
+      throw new Error(`Step ${step.point} failed`, { cause: error });
+    }
+  }
+
+  // Every run ends at cleanup, and a step there answers with a Finished or does
+  // not compile
+  return value as Finished;
+}
+
+// The order a run walks: for each of its phases, everything before it, the
+// phase's own slot, then everything after. Redkite's own step leads its slot
+// because merge keeps the supplied list first
+export function sequence(
+  steps: AnyStep[],
+  phases: readonly Phase[] = RUNS.deploy,
+): AnyStep[] {
+  const ordered: AnyStep[] = [];
+
+  for (const phase of phases) {
+    for (const slot of SLOTS) {
+      ordered.push(...steps.filter((step) => runsAt(step, phase, slot)));
+    }
+  }
+
+  return ordered;
+}
+
+function runsAt(step: AnyStep, phase: Phase, slot: Slot) {
+  const address = addressOf(step.point);
+  return address.phase === phase && address.slot === slot;
+}
+
+export type Address = { phase: Phase; slot: Slot; name: string };
+
+// The names everything else in redkite derives, so a step reads like the container
+// and cache keys beside it
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+// Points a config may still be written against, and what they became
+const RENAMED: Record<string, Phase> = { deploy: "swap" };
+
+export function addressOf(point: string): Address {
+  const parts = point.split(":");
+  const phase = parts[0];
+
+  const renamed = phase ? RENAMED[phase] : undefined;
+  if (renamed) {
+    throw new Error(`${point} names the phase ${phase}, which is now ${renamed}`);
+  }
+
+  if (!phase || !isPhase(phase)) {
+    throw new Error(`${point} names no phase, expected one of ${PHASES.join(", ")}`);
+  }
+
+  // The point redkite's own step sits at, and the one a deployment claims to
+  // replace it
+  if (parts.length === 1) return { phase, slot: "main", name: phase };
+
+  if (parts.length === 2) return { phase, slot: "main", name: named(point, parts[1]) };
+
+  if (parts.length !== 3) {
+    throw new Error(
+      `${point} is not a point, expected ${phase}, ${phase}:… or ${phase}:before|after:…`,
+    );
+  }
+
+  const slot = parts[1];
+  if (slot !== "before" && slot !== "after") {
+    throw new Error(`${point} names no slot, expected ${phase}:before:… or ${phase}:after:…`);
+  }
+
+  return { phase, slot, name: named(point, parts[2]) };
+}
+
+// Checked where the config is defined rather than where it runs, so a typo or a
+// collision is a config that fails to load rather than a deploy that stops half
+// way through with the host already changed
+export function assertSteps(steps: AnyStep[]) {
+  const seen = new Set<string>();
+
+  for (const step of steps) {
+    addressOf(step.point);
+
+    if (seen.has(step.point)) {
+      throw new Error(`Two steps share the point ${step.point}`);
+    }
+
+    seen.add(step.point);
+  }
+}
+
+function named(point: string, name: string | undefined) {
+  if (name && NAME.test(name)) return name;
+  throw new Error(`${point} needs a kebab-case name`);
+}
+
+function isPhase(value: string): value is Phase {
+  return (PHASES as readonly string[]).includes(value);
+}