redkite 0.1.7 → 0.1.8

package/src/plugins/bitwarden.ts

@@ -0,0 +1,57 @@
+import { definePlugin, type OpenContext, type Plugin } from "../plugin.js";
+import { bitwardenStore } from "../secrets/store.js";
+import type { SecretRef } from "../types.js";
+
+// Redkite's own vault, and a plugin like any other: a deployment that does not
+// register it cannot resolve a bitwarden ref, and says so before it builds.
+
+// The one variable a vault needs when the session was obtained elsewhere. A CI
+// job that unlocked once and reuses it across several deploys is the case
+const KEY = "BW_KEY";
+
+export type BitwardenOptions = {
+  // Whether this vault answers secret refs, and what unlocks it. true reads
+  // BW_KEY, and falls back to the api credentials when that is not set. A
+  // string is the session itself, for a config that names its own variable.
+  // false registers the plugin without a store, for a deployment that has
+  // stopped reading from it but has not yet taken the refs out
+  secrets?: boolean | string;
+};
+
+function vault(options: BitwardenOptions = {}): Plugin {
+  const secrets = options.secrets ?? true;
+  if (secrets === false) return definePlugin({ name: "bitwarden" });
+
+  return definePlugin({
+    name: "bitwarden",
+    stores: { bitwarden: async (context) => await open(secrets, context) },
+  });
+}
+
+async function open(secrets: true | string, context: OpenContext) {
+  const session = typeof secrets === "string" ? secrets : process.env[KEY];
+  if (session) return await bitwardenStore({ session, detail: context.detail });
+
+  return await bitwardenStore({
+    detail: context.detail,
+    clientId: required("BW_CLIENT_ID"),
+    clientSecret: required("BW_CLIENT_SECRET"),
+    password: required("BW_PASSWORD"),
+  });
+}
+
+function required(name: string) {
+  const value = process.env[name];
+  if (value) return value;
+
+  throw new Error(
+    `Neither ${KEY} nor ${name} is set, and this deployment reads its environment from Bitwarden`,
+  );
+}
+
+// The plugin is what a deployment registers; the item is what an app points at.
+// Both are named bitwarden because both are the same vault, and the id is a
+// pointer rather than a secret, so it belongs in the config
+export const bitwarden = Object.assign(vault, {
+  item: (id: string): SecretRef => ({ provider: "bitwarden", id }),
+});

package/src/plugins/digitalOcean.ts

@@ -0,0 +1,111 @@
+import type { Step } from "../pipeline.js";
+import { definePlugin, type Plugin } from "../plugin.js";
+
+import { slug, snapshotName, tokenFrom, type SnapshotPoint } from "./snapshot.js";
+
+// A snapshot of the disk a database sits on, taken before anything migrates it.
+//
+// DigitalOcean's managed databases have no endpoint that takes one on demand:
+// their backups are automatic and the API only lists them. So what this
+// snapshots is the block storage volume redkite's own postgres service keeps
+// its data on, or the droplet when the database is the whole machine. A volume
+// snapshot of a running Postgres is crash consistent rather than clean, which
+// Postgres is built to survive: it replays the log on the way back up.
+
+const API = "https://api.digitalocean.com/v2";
+
+// Injected for the same reason the ssh runner is: what this builds is asserted
+// on rather than trusted
+export type Request = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body: string },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+export type DigitalOceanSnapshotOptions = {
+  // The block storage volume the data lives on, by id
+  volume?: string;
+  // Or the droplet, by id, for a database that is the whole machine
+  droplet?: number;
+  // Goes in front of the snapshot's name, which carries the environment and
+  // the minute after it
+  name?: string;
+  // Environment variable the API token is read from, never the token itself:
+  // a config is committed and a token is not
+  tokenFrom?: string;
+  request?: Request;
+};
+
+const TOKEN = "DIGITALOCEAN_TOKEN";
+
+export function digitalOceanSnapshot(options: DigitalOceanSnapshotOptions): Plugin {
+  assertOneTarget(options);
+
+  return definePlugin({
+    name: `digitalocean-snapshot-${slug(options.volume ?? String(options.droplet ?? ""))}`,
+    steps: [snapshotStep(options)],
+  });
+}
+
+function snapshotStep(options: DigitalOceanSnapshotOptions): Step<SnapshotPoint> {
+  const target = options.volume ?? String(options.droplet ?? "");
+  const send = options.request ?? ((url, init) => fetch(url, init));
+  const variable = options.tokenFrom ?? TOKEN;
+
+  return {
+    point: `swap:before:snapshot-${slug(target)}`,
+    check: (plan) => tokenFrom(variable, plan),
+
+    run: async (input, context) => {
+      const name = snapshotName(options.name ?? target, context.environment, new Date());
+      context.task.detail(`snapshotting ${target} as ${name}`);
+
+      const token = tokenFrom(variable, {
+        config: context.config,
+        environment: context.environment,
+      });
+
+      const answer = await send(urlFor(options), {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(bodyFor(options, name)),
+      });
+
+      if (!answer.ok) {
+        throw new Error(
+          `DigitalOcean refused the snapshot of ${target} (${answer.status}): ${await answer.text()}`,
+        );
+      }
+
+      return input;
+    },
+  };
+}
+
+function urlFor(options: DigitalOceanSnapshotOptions) {
+  if (options.volume) return `${API}/volumes/${options.volume}/snapshots`;
+  return `${API}/droplets/${options.droplet}/actions`;
+}
+
+// A volume takes a snapshot, a droplet is asked to perform one. Two endpoints
+// with two shapes, which is why the target is not one field
+function bodyFor(options: DigitalOceanSnapshotOptions, name: string) {
+  if (options.volume) return { name };
+  return { type: "snapshot", name };
+}
+
+// Checked where the plugin is written rather than where it runs, so the config
+// fails to load. The token cannot be: a plan reads the config without one
+function assertOneTarget(options: DigitalOceanSnapshotOptions) {
+  if (options.volume && options.droplet !== undefined) {
+    throw new Error(
+      "digitalOceanSnapshot names both a volume and a droplet, and they are different disks",
+    );
+  }
+
+  if (!options.volume && options.droplet === undefined) {
+    throw new Error("digitalOceanSnapshot names no volume or droplet to snapshot");
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,4 @@
+export * from "./bitwarden.js";
+export * from "./digitalOcean.js";
+export * from "./rds.js";
+export * from "./snapshot.js";

package/src/plugins/rds.ts

@@ -0,0 +1,126 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import type { Step } from "../pipeline.js";
+import { definePlugin, type Plugin } from "../plugin.js";
+
+import { slug, snapshotName, type SnapshotPoint } from "./snapshot.js";
+
+// A snapshot of a managed Postgres or MySQL, taken before anything migrates it.
+// Through the AWS CLI rather than the REST API: signing a request by hand is a
+// page of crypto that nothing here could check, and every runner already has
+// the CLI with the credentials the job was given.
+
+const run = promisify(execFile);
+
+// Injected so the argv this builds is asserted on rather than trusted
+export type Aws = (args: string[]) => Promise<{ stdout: string }>;
+
+export type RdsSnapshotOptions = {
+  // The instance to snapshot, or the cluster for Aurora. One of them
+  instance?: string;
+  cluster?: string;
+  // Goes in front of the snapshot's name, which carries the environment and
+  // the minute after it
+  name?: string;
+  region?: string;
+  // Waits for the snapshot to finish rather than only to start. RDS captures
+  // the data when it begins, so this is about learning it worked rather than
+  // about the restore point, and it can take a very long time
+  wait?: boolean;
+  aws?: Aws;
+};
+
+export function rdsSnapshot(options: RdsSnapshotOptions): Plugin {
+  assertOneTarget(options);
+  const target = slug(options.instance ?? options.cluster ?? "");
+
+  return definePlugin({
+    name: `rds-snapshot-${target}`,
+    steps: [snapshotStep(options)],
+  });
+}
+
+function snapshotStep(options: RdsSnapshotOptions): Step<SnapshotPoint> {
+  const target = options.instance ?? options.cluster ?? "";
+  const aws = options.aws ?? ((args: string[]) => run("aws", args));
+
+  return {
+    point: `swap:before:snapshot-${slug(target)}`,
+
+    run: async (input, context) => {
+      const identifier = snapshotName(options.name ?? target, context.environment, new Date());
+      context.task.detail(`snapshotting ${target} as ${identifier}`);
+
+      await aws(create(options, identifier));
+
+      // The data is captured when it begins, so this is not what makes the
+      // restore point good. It is what turns a snapshot that silently failed
+      // into a deploy that stops before the migration
+      if (options.wait) {
+        context.task.detail(`waiting for ${identifier}`);
+        await aws(ready(options, identifier));
+      }
+
+      return input;
+    },
+  };
+}
+
+function create(options: RdsSnapshotOptions, identifier: string) {
+  const region = options.region ? ["--region", options.region] : [];
+
+  if (options.cluster) {
+    return [
+      "rds",
+      "create-db-cluster-snapshot",
+      "--db-cluster-identifier",
+      options.cluster,
+      "--db-cluster-snapshot-identifier",
+      identifier,
+      ...region,
+    ];
+  }
+
+  return [
+    "rds",
+    "create-db-snapshot",
+    "--db-instance-identifier",
+    options.instance ?? "",
+    "--db-snapshot-identifier",
+    identifier,
+    ...region,
+  ];
+}
+
+function ready(options: RdsSnapshotOptions, identifier: string) {
+  const region = options.region ? ["--region", options.region] : [];
+
+  if (options.cluster) {
+    return [
+      "rds",
+      "wait",
+      "db-cluster-snapshot-available",
+      "--db-cluster-snapshot-identifier",
+      identifier,
+      ...region,
+    ];
+  }
+
+  return ["rds", "wait", "db-snapshot-available", "--db-snapshot-identifier", identifier, ...region];
+}
+
+// An instance and a cluster are different API calls against different things,
+// and guessing which was meant is worse than being told. Checked where the
+// plugin is written rather than where it runs, so the config fails to load
+function assertOneTarget(options: RdsSnapshotOptions) {
+  if (options.instance && options.cluster) {
+    throw new Error(
+      "rdsSnapshot names both an instance and a cluster, and they are different databases",
+    );
+  }
+
+  if (!options.instance && !options.cluster) {
+    throw new Error("rdsSnapshot names no instance or cluster to snapshot");
+  }
+}

package/src/plugins/snapshot.ts

@@ -0,0 +1,44 @@
+import type { Plan } from "../pipeline.js";
+
+// What the two snapshot plugins share. A snapshot is a control-plane call
+// rather than anything the deploy host does, so it runs where the credentials
+// are, which is the process running redkite.
+
+// Hung before the swap and before any migration, so the thing being protected
+// from is still ahead of it. Steps run in the order the config lists them, so a
+// snapshot has to be written above the migrate it guards
+export type SnapshotPoint = `swap:before:${string}`;
+
+// Letters, digits and single hyphens, which is the intersection of what RDS
+// accepts as a snapshot identifier and what a point may be named
+export function slug(value: string) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+}
+
+// Sortable, second-resolution, and legal in every identifier below. Two
+// snapshots in one second would collide, and two deploys in one second is not
+// a thing a swap can do
+export function stamp(now: Date) {
+  return now.toISOString().replace(/[-:T]/g, "").slice(0, 14);
+}
+
+// Names the deploy it was taken for. A snapshot nobody can place is one nobody
+// will dare restore
+export function snapshotName(prefix: string, environment: string, now: Date) {
+  return slug(`${prefix}-${environment}-${stamp(now)}`);
+}
+
+// Read before the run starts, so a missing token is a config that fails while
+// the host is untouched rather than a deploy that stops with the swap ahead
+export function tokenFrom(name: string, plan: Plan) {
+  const value = process.env[name];
+  if (value) return value;
+
+  throw new Error(
+    `${name} is not set, and ${plan.config.project} snapshots its database before swapping`,
+  );
+}

package/src/presets/nodeApp.ts

@@ -1,4 +1,4 @@
-import type { BuildSpec, CarryPath, SourcemapSpec } from "../types.js";
+import type { BuildSpec, CarryPath } from "../types.js";
 
 type NodeAppOptions = {
   builder?: string;
@@ -12,7 +12,6 @@ type NodeAppOptions = {
   carry?: CarryPath[];
   submodules?: boolean;
   caches?: string[];
-  sourcemaps?: SourcemapSpec;
 };
 
 export function nodeApp(options: NodeAppOptions): BuildSpec {
@@ -41,6 +40,5 @@ export function nodeApp(options: NodeAppOptions): BuildSpec {
     aptPackages: ["git"],
     runtimePackages: ["curl"],
     runtimeSteps: [],
-    sourcemaps: options.sourcemaps,
   };
 }

package/src/recover.ts

@@ -0,0 +1,90 @@
+import { revert } from "./deploy.js";
+import { Docker } from "./docker.js";
+import { finalHost, type Host } from "./host.js";
+import { silent, type Log } from "./log.js";
+import { topologyFor, type Topology } from "./topology.js";
+import type { Deployment } from "./types.js";
+
+// Undoing a run that did not finish, from a process that is not it. A cancelled
+// job is killed rather than asked, so nothing it was holding survives to tidy
+// up: what the host is left in has to be readable from the host alone.
+
+export type RecoverOptions = {
+  config: Deployment;
+  environment: string;
+  host: Host;
+  log?: Log;
+};
+
+export type RolledBack = {
+  // Apps put back on the live address they were serving from
+  restored: string[];
+  // Apps that were already where they belong, which is most runs
+  untouched: string[];
+};
+
+// A retired container is the whole signal. One exists between the swap and the
+// cleanup that removes it, so finding one means a run moved an address and did
+// not get to say whether that worked
+export async function rollback(options: RecoverOptions): Promise<RolledBack> {
+  const { log, topology, docker } = opened(options);
+
+  const restored: string[] = [];
+  const untouched: string[] = [];
+
+  for (const app of topology.apps) {
+    if (!(await docker.container.exists(app.retired))) {
+      untouched.push(app.container);
+      continue;
+    }
+
+    log(`Putting ${app.container} back`);
+    await revert(docker, topology, app);
+    restored.push(app.container);
+  }
+
+  return { restored, untouched };
+}
+
+export type TakenDown = {
+  stopped: string[];
+};
+
+// Stopped rather than removed, so the next run adopts them where it left off.
+// For an environment that exists to be built against rather than served from,
+// which is the one a cancelled job should not leave running
+export async function down(options: RecoverOptions): Promise<TakenDown> {
+  const { log, topology, docker } = opened(options);
+  const stopped: string[] = [];
+
+  for (const name of every(topology)) {
+    if (!(await docker.container.isRunning(name))) continue;
+
+    log(`Stopping ${name}`);
+    await docker.container.stop(name);
+    stopped.push(name);
+  }
+
+  return { stopped };
+}
+
+// Everything this environment named, whether or not it was ever created. The
+// proxy is derived rather than listed, so it would be missed by walking the
+// config alone
+function every(topology: Topology) {
+  return [
+    ...topology.apps.flatMap((app) => [app.container, app.retired, app.failed]),
+    ...topology.services.map((service) => service.container),
+    topology.router.container,
+  ];
+}
+
+// Both of these exist because something was stopped, so neither may be refused
+// by that same stop
+function opened(options: RecoverOptions) {
+  return {
+    log: options.log ?? silent,
+    topology: topologyFor(options.config, options.environment),
+    docker: new Docker(finalHost(options.host)),
+  };
+}

package/src/secrets/store.ts

@@ -16,12 +16,11 @@ import type { SecretStore } from "./refs.js";
 
 const run = promisify(execFile);
 
+// A session the caller already holds, or what it takes to obtain one. Both
+// spellings in one object would be a pair of credentials nobody can tell apart
 export type BitwardenCredentials = {
-  clientId: string;
-  clientSecret: string;
-  password: string;
   detail?: (message: string) => void;
-};
+} & ({ session: string } | { clientId: string; clientSecret: string; password: string });
 
 // Used when bw is not already on PATH. Pinned, because an unpinned CLI is a
 // different program on a machine that has never run a deploy before
@@ -53,22 +52,7 @@ export async function bitwardenStore(
       maxBuffer: 32 * 1024 * 1024,
     });
 
-  detail("unlocking the vault");
-
-  // Already logged in is not an error, the session is what matters
-  await bw(["login", "--apikey"], {
-    BW_CLIENTID: credentials.clientId,
-    BW_CLIENTSECRET: credentials.clientSecret,
-  }).catch(() => undefined);
-
-  const unlocked = await bw(["unlock", "--passwordenv", "BW_PASSWORD", "--raw"], {
-    BW_PASSWORD: credentials.password,
-  }).catch((error: unknown) => {
-    throw new Error(`Could not unlock the Bitwarden vault: ${messageOf(error)}`);
-  });
-
-  const session = unlocked.stdout.trim();
-  if (!session) throw new Error("Bitwarden unlocked without a session");
+  const session = await unlock(bw, credentials, detail);
 
   // An item added since the last deploy is not in the local vault otherwise,
   // and bw get answers "not found" rather than fetching it
@@ -97,6 +81,41 @@ export async function bitwardenStore(
   };
 }
 
+type Bw = (args: string[], env?: Record<string, string>) => Promise<{ stdout: string }>;
+
+// A session handed in is one nobody had to obtain, which is the whole of what
+// a key in the environment buys: no api credentials, no master password, and
+// two fewer round trips before the first item is read
+async function unlock(
+  bw: Bw,
+  credentials: BitwardenCredentials,
+  detail: (message: string) => void,
+) {
+  if ("session" in credentials) {
+    detail("using the session it was given");
+    return credentials.session;
+  }
+
+  detail("unlocking the vault");
+
+  // Already logged in is not an error, the session is what matters
+  await bw(["login", "--apikey"], {
+    BW_CLIENTID: credentials.clientId,
+    BW_CLIENTSECRET: credentials.clientSecret,
+  }).catch(() => undefined);
+
+  const unlocked = await bw(["unlock", "--passwordenv", "BW_PASSWORD", "--raw"], {
+    BW_PASSWORD: credentials.password,
+  }).catch((error: unknown) => {
+    throw new Error(`Could not unlock the Bitwarden vault: ${messageOf(error)}`);
+  });
+
+  const session = unlocked.stdout.trim();
+  if (session) return session;
+
+  throw new Error("Bitwarden unlocked without a session");
+}
+
 type Cli = { file: string; prefix: string[] };
 
 // A machine with the CLI installed pays nothing. One without it installs the

package/src/sshHost.ts

@@ -3,6 +3,7 @@ import { dirname } from "node:path";
 
 import type { Host, OnLine, Result } from "./host.js";
 import { quote, spawnCollect } from "./shell.js";
+import type { HostKeys } from "./types.js";
 
 // The deploy host, reached over ssh. The agent is forwarded rather than a key,
 // there is nothing to forward, and the agent travels with the connection so the
@@ -23,23 +24,40 @@ export type SshOptions = {
   shell?: Shell;
   directory?: string;
   cache?: string;
+  // How the host's key is checked. Defaults to accept-new
+  hostKeys?: HostKeys;
   // Aborting kills the ssh client. The command it was carrying keeps running on
   // the other machine, which is what stop is for
   signal?: AbortSignal;
 };
 
+// What ssh calls each of them. accept-new is the default rather than no: a
+// deploy hands over a vault's contents, and the last thing it should do that
+// to is a machine that answered to the address and nothing else
+const CHECKING: Record<HostKeys, string> = {
+  "accept-new": "accept-new",
+  strict: "yes",
+  off: "no",
+};
+
 // One TCP connection and one authentication for the whole deploy. Without it
 // every command pays a handshake, which is most of what a command costs
-const MULTIPLEX = [
-  "-o",
-  "ControlMaster=auto",
-  "-o",
-  "ControlPersist=60s",
-  "-o",
-  "StrictHostKeyChecking=no",
-  // The host clones from GitHub on our behalf rather than us shipping a tree
-  "-A",
-];
+function multiplex(hostKeys: HostKeys = "accept-new") {
+  return [
+    "-o",
+    "ControlMaster=auto",
+    "-o",
+    "ControlPersist=60s",
+    "-o",
+    `StrictHostKeyChecking=${CHECKING[hostKeys]}`,
+    // Never a prompt. Unknown under strict is a refusal with a reason, and a
+    // question nobody is there to answer is a deploy that hangs
+    "-o",
+    "BatchMode=yes",
+    // The host clones from GitHub on our behalf rather than us shipping a tree
+    "-A",
+  ];
+}
 
 export async function sshHost(bastion: string, options: SshOptions = {}): Promise<Host> {
   const control = `/tmp/redkite-${randomUUID().slice(0, 8)}.control`;
@@ -57,8 +75,10 @@ export async function sshHost(bastion: string, options: SshOptions = {}): Promis
     options.shell ??
     ((command: string) => spawnCollect("sh", ["-c", command], { signal }));
 
+  const flags = multiplex(options.hostKeys);
+
   const argv = (command: string) => [
-    ...MULTIPLEX,
+    ...flags,
     "-o",
     `ControlPath=${control}`,
     bastion,
@@ -111,6 +131,10 @@ export async function sshHost(bastion: string, options: SshOptions = {}): Promis
     pipe: async (local, remote) =>
       await shell(`${local} | ssh ${argv(remote).map(quote).join(" ")}`),
 
+    // Runs on the connection that is already open, and without the signal that
+    // killed whatever made it necessary
+    final: async (command) => await final(argv(command)),
+
     // Signalled where they are running, not here. Killing the client would
     // leave the build going with nothing left able to reach it
     stop: async (name) => {

package/src/steps.ts

@@ -1,4 +1,5 @@
 import { environmentOf } from "./config.js";
+import { envFlags } from "./environment.js";
 import type { Built, Plan, Step } from "./pipeline.js";
 import type { Topology } from "./topology.js";
 import type { AppSpec, StepNetwork } from "./types.js";
@@ -48,10 +49,16 @@ export function migrate(options: MigrateOptions): Step<`swap:before:${string}`>
       const image = builderOf(input, options.app);
       context.task.detail(`${options.app}: ${options.command}`);
 
+      // Nothing from the vault is in the image, so a migration reads its
+      // database url from the environment it is given rather than from a file
+      // the build left behind
+      const app = context.config.apps.find((item) => item.name === options.app);
+
       await context.docker.runOrThrow(
         [
           "run --rm",
           ...attachment(options.network ?? "host", context.topology),
+          ...(app ? await envFlags(app, context) : []),
           "--workdir /app",
           image,
           ...command,
@@ -90,12 +97,6 @@ export function builderOf(input: Built, name: string) {
   throw new Error(`${name} has no builder image, so nothing can be run in it`);
 }
 
-type SentryOptions = { stripFromImage: string };
-
-export function sentry(options: SentryOptions) {
-  return { provider: "sentry" as const, stripFromImage: options.stripFromImage };
-}
-
 export function routeOf(app: AppSpec) {
   return app.route;
 }