redkite 0.1.6

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+import type { AnyStep } from "./pipeline.js";
+export type Environment = {
+    buildOn?: "host" | "local";
+    branch: string;
+    subnet: string;
+    publicPort?: number;
+    host?: DeployHost;
+    extraHosts?: Record<string, string>;
+};
+export type StepNetwork = "host" | "deployment" | "none" | {
+    named: string;
+};
+export type DeployHost = {
+    bastion: string;
+    socket?: string;
+};
+export type SecretRef = {
+    provider: string;
+    id: string;
+};
+export type SecretRefs = SecretRef | SecretRef[];
+export type ServiceSpec = {
+    name: string;
+    image: string;
+    alias?: string;
+    restart?: "always" | "unless-stopped";
+    files?: Record<string, string>;
+    environment?: Record<string, string>;
+    secrets?: SecretRefs;
+    address?: number;
+    volumes?: Record<string, string>;
+};
+export type CarryPath = string | {
+    path: string;
+    optional: true;
+};
+export type BuildSpec = {
+    preset: string;
+    builderImage: string;
+    runtimeImage: string;
+    dependencies?: {
+        files: string[];
+        step: string;
+        stripScripts?: string[];
+    };
+    steps: string[];
+    output: string;
+    carry: CarryPath[];
+    keepsLayout?: boolean;
+    entrypoint: string[];
+    caches: string[];
+    submodules: boolean;
+    aptPackages: string[];
+    runtimePackages: string[];
+    runtimeSteps: string[];
+    sourcemaps?: SourcemapSpec;
+};
+export type SourcemapSpec = {
+    provider: "sentry";
+    stripFromImage: string;
+};
+export type VerifySpec = {
+    steps: string[];
+    network?: StepNetwork;
+    environment?: Record<string, string>;
+};
+export type HealthSpec = {
+    path: string;
+    expect: (body: Record<string, unknown>) => boolean;
+    retries?: number;
+    intervalMs?: number;
+    delayMs?: number;
+};
+export type AppSpec = {
+    name: string;
+    repo?: string;
+    path?: string;
+    include?: string[];
+    route: string;
+    port: number;
+    secrets?: SecretRefs;
+    dir?: string;
+    build: BuildSpec;
+    health: HealthSpec;
+    verify?: VerifySpec;
+    volumes?: Record<string, string>;
+    environment?: Record<string, string>;
+    files?: Record<string, SecretRef>;
+};
+export type Deployment = {
+    project: string;
+    environment?: Environment;
+    environments?: Record<string, Environment>;
+    maxBodySize?: string;
+    proxyImage?: string;
+    services: ServiceSpec[];
+    apps: AppSpec[];
+    steps?: AnyStep[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "redkite",
+  "version": "0.1.6",
+  "description": "Blue-green Docker deployment from one config file, over ssh. No engine, no agent, no dependencies.",
+  "keywords": [
+    "deploy",
+    "deployment",
+    "blue-green",
+    "zero-downtime",
+    "docker",
+    "buildkit",
+    "nginx",
+    "ssh",
+    "ci",
+    "cd"
+  ],
+  "license": "MIT",
+  "author": "Joao Kdouk <contato@kdouk.com>",
+  "homepage": "https://github.com/JVKdouk/RedKite#readme",
+  "repository": {
+    "url": "git+https://github.com/JVKdouk/RedKite",
+    "type": "git"
+  },
+  "bugs": {
+    "url": "https://github.com/JVKdouk/RedKite/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "redkite": "./bin/redkite.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc --project tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "bench": "tsx bench/index.ts",
+    "plan": "node bin/redkite.mjs plan --config examples/acme/redkite.config.ts",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run check && npm test && node scripts/verifyRelease.mjs"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "5.9.3"
+  }
+}

package/src/build.ts

@@ -0,0 +1,236 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+
+import type { Docker } from "./docker.js";
+import { BUILDER_STAGE, renderDockerfile, renderDockerignore } from "./dockerfile.js";
+import type { Host } from "./host.js";
+import { prepareSource } from "./source.js";
+import type { AppTopology } from "./topology.js";
+import type { AppSpec } from "./types.js";
+
+// One build. The host clones the repository, renders the pipeline as a
+// Dockerfile, and hands it to the BuildKit inside the daemon that will run the
+// container, so the image is finished where it is needed and never moves.
+
+export type BuildContext = {
+  host: Host;
+  docker: Docker;
+  // Set when the image is built somewhere other than where it will run. The
+  // build goes to the daemon above, and what it produced is streamed to this one
+  deliver?: { host: Host; docker: Docker };
+  // Contents of the .env the image ships with
+  env: string;
+  // Container path to the contents that land there
+  files: Record<string, string>;
+  branch: string;
+  environment: string;
+  detail?: (message: string) => void;
+  // Prints what the build itself wrote, line by line as it runs
+  output?: (line: string) => void;
+};
+
+// Bumped when the pipeline changes shape without the config changing. The tag
+// below is what tells a host it already holds an image, and a host that trusts
+// the commit alone serves the last pipeline's output forever
+const PIPELINE = "4";
+
+export type BuildResult = {
+  release: string;
+  // Everything that shaped the image, not just the commit it was built from
+  fingerprint: string;
+  // Versioned name the image carries, which is what the next deploy recognises
+  tag: string;
+  // The builder stage, kept as an image of its own. The runtime image holds
+  // only what the app compiled to, so this is the one place a step can run the
+  // app's own toolchain
+  builderTag: string;
+  // True when the host already held this exact image and nothing was rebuilt
+  cached: boolean;
+};
+
+export async function build(
+  app: AppSpec,
+  topology: AppTopology,
+  context: BuildContext,
+): Promise<BuildResult> {
+  const { host, docker } = context;
+  const spec = app.build;
+  const detail = context.detail ?? (() => {});
+
+  const source = await prepareSource(host, {
+    name: topology.container,
+    repo: app.repo,
+    // Already absolute when the CLI loaded the config, because a path is read
+    // against the deployment file rather than wherever this was run
+    path: app.path && resolve(app.path),
+    include: app.include,
+    branch: context.branch,
+    submodules: spec.submodules,
+    detail,
+  });
+
+  const release = source.release;
+  const fingerprint = fingerprintOf(app, context, release);
+  const tag = `${topology.container}:${release}-${fingerprint}`;
+  // Always, rather than where something remembered to ask for it. It costs the
+  // export of layers the runtime build produced anyway, and a flag that has to
+  // be set before a step can run is a flag that will be missing
+  const builderTag = `${topology.container}-builder:${release}-${fingerprint}`;
+
+  // Asked of the daemon that will run the container, not the one that builds.
+  // An image this machine holds and the host does not is one still to be sent
+  const runner = context.deliver?.docker ?? docker;
+
+  // The whole build is skipped, not just a transfer. Nothing about this commit,
+  // this pipeline or these secrets differs from the image already sitting there
+  if (await held(runner, tag, builderTag)) {
+    detail(`already built at ${release.slice(0, 7)}`);
+    await runner.image.retag(tag, topology.container);
+
+    return { release, fingerprint, tag, builderTag, cached: true };
+  }
+
+  const secrets = await writeSecrets(app, context, fingerprint);
+
+  const dockerfile = await host.write(
+    `${app.name}.Dockerfile`,
+    renderDockerfile(spec, {
+      caches: topology.caches,
+      port: topology.port,
+      release,
+      environment: context.environment,
+      envSecret: secrets.env.id,
+      fileSecrets: Object.fromEntries(
+        secrets.files.map((file) => [file.path, file.id]),
+      ),
+      dir: app.dir,
+    }),
+  );
+
+  // BuildKit reads this beside the Dockerfile rather than inside the context,
+  // which is what lets the checkout stay a checkout: the repository keeps its
+  // own .dockerignore, and .git never enters the build
+  await host.write(
+    `${app.name}.Dockerfile.dockerignore`,
+    renderDockerignore(app.include),
+  );
+
+  const invocation = {
+    context: source.tree,
+    dockerfile,
+    secrets: Object.fromEntries(
+      [secrets.env, ...secrets.files].map((secret) => [secret.id, secret.src]),
+    ),
+  };
+
+  detail(`building ${release.slice(0, 7)}`);
+  await docker.image.build(
+    { ...invocation, tags: [tag, topology.container] },
+    watch(detail, context.output),
+  );
+
+  // Every layer of this was just built, so it costs the export alone
+  detail("keeping the builder");
+  await docker.image.build(
+    { ...invocation, tags: [builderTag], target: BUILDER_STAGE },
+    watch(detail, context.output),
+  );
+
+  await ship(context, [tag, topology.container, builderTag], detail);
+
+  return { release, fingerprint, tag, builderTag, cached: false };
+}
+
+// One stream, rather than a tarball written here, copied, and read there. The
+// tags travel inside the archive, so nothing has to be named again on arrival
+async function ship(
+  context: BuildContext,
+  tags: (string | undefined)[],
+  detail: (message: string) => void,
+) {
+  const deliver = context.deliver;
+  if (!deliver) return;
+
+  const named = tags.filter((tag) => tag !== undefined);
+  detail(`shipping ${named.length} images`);
+
+  const result = await deliver.host.pipe(
+    `docker save ${named.join(" ")}`,
+    "docker load",
+    context.output,
+  );
+
+  if (result.code !== 0) {
+    throw new Error(`Could not ship the image: ${result.stderr || result.stdout}`);
+  }
+
+  await deliver.docker.track((state) => {
+    for (const tag of named) state.images.add(tag);
+  });
+}
+
+async function held(docker: Docker, tag: string, builderTag: string) {
+  if (!(await docker.image.exists(tag))) return false;
+
+  // A runtime image without the builder that produced it would run the
+  // migration from whatever release happened to be tagged last
+  return await docker.image.exists(builderTag);
+}
+
+// Named by the id BuildKit mounts it under, holding where it sits on the host
+type Secret = { id: string; src: string };
+
+// And, for a credential, where it has to land in the image
+type FileSecret = Secret & { path: string };
+
+// The fingerprint is part of every id, because a secret mount is not part of a
+// layer's cache key. Without it a changed environment file is answered with the
+// image that was built from the old one
+async function writeSecrets(
+  app: AppSpec,
+  context: BuildContext,
+  fingerprint: string,
+): Promise<{ env: Secret; files: FileSecret[] }> {
+  const env = {
+    id: `${app.name}-env-${fingerprint}`,
+    src: await context.host.write(`${app.name}.env`, context.env),
+  };
+
+  const files = await Promise.all(
+    Object.entries(context.files).map(async ([path, contents], index) => ({
+      path,
+      id: `${app.name}-file-${index}-${fingerprint}`,
+      // Named by index, so a container path with slashes in it stays one file
+      src: await context.host.write(`${app.name}.file.${index}`, contents),
+    })),
+  );
+
+  return { env, files };
+}
+
+// BuildKit names the step it is on in its own progress output, which is a
+// better line to show than anything this file could invent
+const STEP = /^#\d+ \[[^\]]*\] (.+)$/;
+
+function watch(detail: (message: string) => void, output?: (line: string) => void) {
+  return (line: string) => {
+    output?.(line);
+
+    const step = STEP.exec(line)?.[1];
+    if (step) detail(step);
+  };
+}
+
+// The commit is one input of several. The pipeline, the environment file and
+// any credential baked in as a file all change the image without touching it
+function fingerprintOf(app: AppSpec, context: BuildContext, release: string) {
+  return createHash("sha256")
+    .update(PIPELINE)
+    .update(release)
+    .update(app.dir ?? "")
+    .update(JSON.stringify(app.build))
+    .update(context.env)
+    .update(JSON.stringify(Object.entries(context.files).sort()))
+    .digest("hex")
+    .slice(0, 12);
+}

package/src/checks.ts

@@ -0,0 +1,65 @@
+import { appRoot } from "./layout.js";
+import type { Built, Context, Plan, Released } from "./pipeline.js";
+import { quote } from "./shell.js";
+import { attachment, builderOf } from "./steps.js";
+import type { AppSpec, VerifySpec } from "./types.js";
+
+// What redkite's verify step runs. An app declares the commands that decide
+// whether its build works, and this is the whole of putting them somewhere they
+// can reach the services the deployment brought up.
+//
+// The image is the builder rather than the runtime one. The runtime image holds
+// the compiled output and nothing that compiled it, so the test runner is not
+// in there, and installing one at check time would test a different tree.
+
+export async function runChecks(input: Built, context: Context): Promise<Released> {
+  const checked: string[] = [];
+
+  for (const app of context.config.apps) {
+    if (!app.verify) continue;
+
+    await checkApp(app, app.verify, input, context);
+    checked.push(app.name);
+  }
+
+  // Anything that got here passed: a failing command throws. The lists a swap
+  // fills stay empty, because a verify run moves no addresses
+  return { ...input, ok: true, released: [], reverted: [], checked };
+}
+
+async function checkApp(app: AppSpec, spec: VerifySpec, input: Built, context: Context) {
+  const flags = [
+    "run --rm",
+    ...attachment(spec.network ?? "deployment", context.topology),
+    `--workdir ${appRoot(app.dir)}`,
+    ...settings({ ...app.environment, ...spec.environment }),
+    builderOf(input, app.name),
+  ];
+
+  // In order and one at a time. The first is usually what brings the database
+  // to the schema the rest expect, so running them together would race
+  for (const command of spec.steps) {
+    context.task.detail(`${app.name}: ${command}`);
+
+    await context.docker.runOrThrow(
+      [...flags, "sh -c", quote(command)].join(" "),
+      `${app.name} failed ${command}`,
+      context.task.line,
+    );
+  }
+}
+
+function settings(environment: Record<string, string>) {
+  return Object.entries(environment).map(([name, value]) => `-e ${name}=${quote(value)}`);
+}
+
+// Checked before the run starts, so asking for a verify that would check
+// nothing fails without having created a network or built an image
+export function assertCheckable(plan: Plan) {
+  if (plan.config.apps.some((app) => app.verify)) return;
+
+  throw new Error(
+    "No app declares verify, so this run would check nothing. " +
+      "An app is verified by giving it verify: { steps: [...] }",
+  );
+}

package/src/cli/agent.ts

@@ -0,0 +1,28 @@
+import { execFileSync } from "node:child_process";
+
+// Cloning private repositories and opening the tunnel both go through the
+// agent, so a deploy without one fails halfway rather than at the start
+
+// A plain writer rather than a Log, because this runs before the view opens:
+// ssh-add may ask for a passphrase, and it cannot ask through a screen
+// something else is drawing
+export function requireAgent(warn: (message: string) => void) {
+  const existing = process.env["SSH_AUTH_SOCK"];
+  if (existing) return existing;
+
+  warn("No SSH agent, starting one");
+
+  const output = execFileSync("ssh-agent", ["-s"], { encoding: "utf8" });
+  const socket = output.match(/SSH_AUTH_SOCK=([^;]+);/)?.[1];
+  const pid = output.match(/SSH_AGENT_PID=([^;]+);/)?.[1];
+
+  if (!socket) throw new Error("ssh-agent did not report a socket");
+
+  process.env["SSH_AUTH_SOCK"] = socket;
+  if (pid) process.env["SSH_AGENT_PID"] = pid;
+
+  // Inherits stdio so a passphrase prompt reaches the person running this
+  execFileSync("ssh-add", [], { stdio: "inherit" });
+
+  return socket;
+}