redkite 0.1.9 → 0.1.10

package/src/index.ts

@@ -9,18 +9,19 @@ 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 "./plugin.js";
 export * from "./plugins/index.js";
 export * from "./recover.js";
 export * from "./presets/index.js";
+export * from "./secrets/manager.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 "./services/proxy.js";
 export * from "./source.js";
 export * from "./sshHost.js";
 export * from "./steps.js";

package/src/log.ts

@@ -14,6 +14,9 @@ export type Task = {
 };
 
 export type Log = ((message: string) => void) & {
+  // Every point the run will walk, said once before the first of them starts.
+  // A view that knows the whole list can show what has not begun
+  plan?(points: 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
@@ -31,6 +34,7 @@ const NOTHING: Task = {
 };
 
 export const silent: Log = Object.assign(() => {}, {
+  plan: () => {},
   warn: () => {},
   fail: () => {},
   done: () => {},

package/src/pipeline.ts

@@ -207,6 +207,10 @@ export async function runPipeline(
   const ordered = sequence(steps, RUNS[run]);
   const plan: Plan = { config: setting.config, environment: setting.environment };
 
+  // What the run will walk, said before any of it does. Nothing depends on it
+  // being heard: a log without a view has nothing to do with the list
+  setting.log.plan?.(ordered.map((step) => step.point));
+
   // 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

package/src/plugins/bitwarden.ts

@@ -1,26 +1,34 @@
 import { definePlugin, type OpenContext, type Plugin } from "../plugin.js";
+import { secretsManagerStore } from "../secrets/manager.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.
+//
+// Bitwarden is two services rather than one. Secrets Manager holds secrets for
+// machines and opens with an access token, which is what a deploy wants. The
+// password manager holds a person's vault and wants a session obtained by
+// unlocking it. The ids are different, the CLIs are different, and giving one
+// service's credential to the other is how a deploy ends up waiting on a
+// password prompt nobody can see.
 
-// 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
+// The one variable either side reads, so a job sets one thing whichever it is
 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
+  // Which Bitwarden this deployment reads, and what opens it.
+  //
+  // true, the default, is Secrets Manager: BW_KEY is the access token. A
+  // string is that token given directly, for a config naming its own variable.
+  //
+  // false is the password manager: BW_KEY is a session from bw unlock --raw,
+  // and without one the api credentials obtain one.
   secrets?: boolean | string;
 };
 
 function vault(options: BitwardenOptions = {}): Plugin {
   const secrets = options.secrets ?? true;
-  if (secrets === false) return definePlugin({ name: "bitwarden" });
 
   return definePlugin({
     name: "bitwarden",
@@ -28,8 +36,26 @@ function vault(options: BitwardenOptions = {}): Plugin {
   });
 }
 
-async function open(secrets: true | string, context: OpenContext) {
-  const session = typeof secrets === "string" ? secrets : process.env[KEY];
+async function open(secrets: boolean | string, context: OpenContext) {
+  if (secrets === false) return await passwords(context);
+
+  const token = typeof secrets === "string" ? secrets : process.env[KEY];
+
+  if (!token) {
+    throw new Error(
+      `${KEY} is not set, and this deployment reads from Bitwarden Secrets ` +
+        "Manager. It is an access token, not a password. A deployment reading " +
+        "the password manager instead says bitwarden({ secrets: false })",
+    );
+  }
+
+  return await secretsManagerStore({ token, detail: context.detail });
+}
+
+// The personal vault. A session skips the login and the unlock, which is two
+// fewer round trips and the only way a job without a master password gets in
+async function passwords(context: OpenContext) {
+  const session = process.env[KEY];
   if (session) return await bitwardenStore({ session, detail: context.detail });
 
   return await bitwardenStore({
@@ -45,7 +71,8 @@ function required(name: string) {
   if (value) return value;
 
   throw new Error(
-    `Neither ${KEY} nor ${name} is set, and this deployment reads its environment from Bitwarden`,
+    `Neither ${KEY} nor ${name} is set, and this deployment reads its ` +
+      "environment from the Bitwarden password manager",
   );
 }
 

package/src/presets/nextApp.ts

@@ -57,10 +57,11 @@ export function nextApp(options: NextAppOptions = {}): BuildSpec {
       // whatever the repository put there, and plenty of apps have none
       carry: ["/app/.next/static", { path: "/app/public", optional: true }],
       entrypoint: start("node server.js"),
-      // app-modules is what makes the build fast: node_modules on a mount
-      // rather than in a layer, which the standalone tree makes safe by
-      // carrying its own copy of everything the server reaches
-      caches: ["yarn", "npm", "modules", "app-modules", "next-app"],
+      // next-app is Next's own build cache, which only ever makes a build
+      // slower when it is dropped. node_modules is not here for the same
+      // reason it is not in nodeApp: a dropped mount and a kept layer is a
+      // build that cannot find what the manifest lists
+      caches: ["yarn", "npm", "next-app"],
     }),
     preset: "nextApp",
     // The standalone tree traces from the workspace root, so an app in a

package/src/presets/nodeApp.ts

@@ -31,13 +31,22 @@ export function nodeApp(options: NodeAppOptions): BuildSpec {
     output: options.output,
     carry: options.carry ?? [],
     entrypoint: options.entrypoint,
-    // Not the app's own node_modules: a step after the build runs in this image
-    // without the mounts, and a migration that cannot find prisma is what a
-    // cache mount instead of a layer looks like from the outside
-    caches: options.caches ?? ["yarn", "npm", "modules"],
+    // The package manager's own cache, and nothing else. node_modules used to
+    // be a mount too, and BuildKit drops a cache mount whenever it likes while
+    // keeping the layer that filled it: the install then does not re-run and
+    // the modules are simply gone. What that looks like is a build saying it
+    // cannot find a dependency the manifest plainly lists.
+    //
+    // Installed into the layer instead, they are there for every step below,
+    // for a migration run in this image afterwards, and for a check. The
+    // manager's cache still makes the install itself fast
+    caches: options.caches ?? ["yarn", "npm"],
     submodules: options.submodules ?? false,
-    // The checkout arrives complete, so this is what a build step itself needs
-    aptPackages: ["git"],
+    // The checkout arrives complete, so this is what a build step itself needs.
+    // openssh-client is for the dependencies it resolves rather than the
+    // repository: a git+ssh entry in a manifest is fetched during the install,
+    // and git cannot do that without an ssh to run
+    aptPackages: ["git", "openssh-client"],
     runtimePackages: ["curl"],
     runtimeSteps: [],
   };

package/src/secrets/manager.ts

@@ -0,0 +1,172 @@
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync } from "node:fs";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { SecretStore } from "./refs.js";
+
+// Bitwarden Secrets Manager, which is not the password manager: different
+// service, different CLI, different credential. An access token opens a set of
+// projects rather than a personal vault, which is what a deploy wants, and it
+// is the whole of the authentication: nothing to log in to and nothing to
+// unlock, so there is no session to obtain or lose.
+
+// Not an npm package. The password manager's CLI is one and redkite installs
+// it with npm; this one is a released binary, and the only thing on npm under
+// its name belongs to somebody else entirely. Pinned for the same reason the
+// other is: an unpinned CLI is a different program on a machine that has never
+// run a deploy before
+const VERSION = "2.1.0";
+const RELEASES = "https://github.com/bitwarden/sdk-sm/releases/download";
+const CLIS = join(homedir(), ".cache", "redkite", "cli");
+
+// What the release calls each platform. Anything not here has to bring its own
+const TARGETS: Record<string, string> = {
+  "linux-x64": "x86_64-unknown-linux-gnu",
+  "linux-arm64": "aarch64-unknown-linux-gnu",
+  "darwin-x64": "x86_64-apple-darwin",
+  "darwin-arm64": "aarch64-apple-darwin",
+  "win32-x64": "x86_64-pc-windows-msvc",
+  "win32-arm64": "aarch64-pc-windows-msvc",
+};
+
+export type ManagerCredentials = {
+  // The access token, which is the only credential this service has
+  token: string;
+  detail?: (message: string) => void;
+  // Injected so the argv this builds is asserted on rather than trusted
+  bws?: Bws;
+};
+
+export type Bws = (args: string[], env: Record<string, string>) => Promise<string>;
+
+export async function secretsManagerStore(
+  credentials: ManagerCredentials,
+): Promise<SecretStore> {
+  const detail = credentials.detail ?? (() => {});
+  const bws = credentials.bws ?? (await resolve(detail));
+
+  // Fetched once each. A second read of the same item during a deploy is the
+  // same answer, and this avoids a process per call site
+  const cache = new Map<string, Promise<string>>();
+
+  const fetch = async (id: string) => {
+    detail(`reading ${id.slice(0, 8)}`);
+
+    const answer = await bws(["secret", "get", id, "--output", "json"], {
+      BWS_ACCESS_TOKEN: credentials.token,
+    }).catch((error: unknown) => {
+      throw new Error(`Could not read ${id} from Bitwarden Secrets Manager: ${messageOf(error)}`);
+    });
+
+    return valueOf(answer, id);
+  };
+
+  return {
+    read: async (id) => {
+      const pending = cache.get(id) ?? fetch(id);
+      cache.set(id, pending);
+      return await pending;
+    },
+  };
+}
+
+// The secret's value, which is the whole of what a ref points at. Everything
+// else the call answers with is about the item rather than in it
+function valueOf(answer: string, id: string) {
+  try {
+    const parsed = JSON.parse(answer) as { value?: unknown };
+    if (typeof parsed.value === "string") return parsed.value;
+  } catch {
+    // Falls through to the same refusal as a shape without a value
+  }
+
+  throw new Error(`Bitwarden Secrets Manager answered for ${id} without a value`);
+}
+
+async function resolve(detail: (message: string) => void): Promise<Bws> {
+  const file = await binary(detail);
+  return async (args, env) => await run(file, args, env);
+}
+
+async function binary(detail: (message: string) => void) {
+  const override = process.env["REDKITE_BWS_BIN"];
+  if (override) return override;
+
+  const onPath = await run("bws", ["--version"], {}).then(
+    () => true,
+    () => false,
+  );
+
+  if (onPath) return "bws";
+
+  const directory = join(CLIS, `bws-${VERSION}`);
+  const installed = join(directory, process.platform === "win32" ? "bws.exe" : "bws");
+  if (existsSync(installed)) return installed;
+
+  return await install(directory, installed, detail);
+}
+
+// Downloaded once per machine per pinned version, the way the other CLI is
+// installed once. The archive is a zip with one file in it, and unzip is the
+// one thing on every platform that reads one
+async function install(directory: string, installed: string, detail: (m: string) => void) {
+  const target = TARGETS[`${process.platform}-${process.arch}`];
+
+  if (!target) {
+    throw new Error(
+      `Bitwarden publishes no bws for ${process.platform}-${process.arch}. ` +
+        "Install it yourself and point REDKITE_BWS_BIN at it",
+    );
+  }
+
+  const url = `${RELEASES}/bws-v${VERSION}/bws-${target}-${VERSION}.zip`;
+  detail(`installing bws ${VERSION}, once for this machine`);
+
+  await mkdir(directory, { recursive: true });
+  const archive = join(directory, "bws.zip");
+
+  const answer = await globalThis.fetch(url);
+  if (!answer.ok) throw new Error(`Could not download bws from ${url}: ${answer.status}`);
+
+  await writeFile(archive, Buffer.from(await answer.arrayBuffer()));
+  await run("unzip", ["-o", "-q", archive, "-d", directory], {}).catch((error: unknown) => {
+    throw new Error(`Could not unpack bws: ${messageOf(error)}`);
+  });
+
+  await rm(archive, { force: true });
+
+  // The zip carries no mode anything trusts, so it arrives unrunnable
+  chmodSync(installed, 0o755);
+
+  return installed;
+}
+
+// Nothing on stdin, and the output kept exactly as it came. The same reasoning
+// as the password manager's runner: a question nobody can answer is a deploy
+// that waits for ever
+function run(file: string, args: string[], env: Record<string, string>) {
+  return new Promise<string>((resolve_, reject) => {
+    const child = spawn(file, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk: Buffer) => (stdout += chunk.toString()));
+    child.stderr.on("data", (chunk: Buffer) => (stderr += chunk.toString()));
+    child.on("error", reject);
+
+    child.on("close", (code) => {
+      if (code === 0) return resolve_(stdout);
+      reject(new Error(stderr.trim() || stdout.trim() || `${file} exited ${code}`));
+    });
+  });
+}
+
+function messageOf(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/secrets/store.ts

@@ -1,9 +1,8 @@
-import { execFile } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { promisify } from "node:util";
 
 import type { SecretStore } from "./refs.js";
 
@@ -14,7 +13,32 @@ import type { SecretStore } from "./refs.js";
 // purely as a sandbox, which meant installing several thousand packages on
 // every deploy to read three items.
 
-const run = promisify(execFile);
+// Nothing on stdin, ever. Both CLIs ask for a password when they decide the
+// vault is locked, and a question put down a pipe nobody writes to is a deploy
+// that waits for ever rather than one that fails.
+//
+// The output is kept exactly as it came: a secret is a file's contents, and a
+// key that lost its last newline is a key some parsers refuse
+function run(file: string, args: string[], env: Record<string, string> = {}) {
+  return new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
+    const child = spawn(file, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk: Buffer) => (stdout += chunk.toString()));
+    child.stderr.on("data", (chunk: Buffer) => (stderr += chunk.toString()));
+    child.on("error", reject);
+
+    child.on("close", (code) => {
+      if (code === 0) return resolve({ stdout, stderr });
+      reject(new Error(stderr.trim() || stdout.trim() || `${file} exited ${code}`));
+    });
+  });
+}
 
 // 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
@@ -44,25 +68,32 @@ export async function bitwardenStore(
 
   const bw = async (args: string[], env: Record<string, string> = {}) =>
     await run(command.file, [...command.prefix, ...args], {
-      env: {
-        ...process.env,
-        BITWARDENCLI_APPDATA_DIR: appdata,
-        ...env,
-      },
-      maxBuffer: 32 * 1024 * 1024,
+      BITWARDENCLI_APPDATA_DIR: appdata,
+      ...env,
     });
 
   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
-  await bw(["sync"], { BW_SESSION: session }).catch(() => undefined);
+  // and bw get answers "not found" rather than fetching it. This is also what
+  // proves a session handed in still works: without it the first read is what
+  // finds out, and by then a build is waiting on the answer
+  await bw(["sync"], { BW_SESSION: session }).catch((error: unknown) => {
+    if (!("session" in credentials)) return undefined;
+
+    throw new Error(
+      `The session it was given does not open this vault: ${messageOf(error)}. ` +
+        "Obtain one with bw unlock --raw, or unset it and let the api credentials do it",
+    );
+  });
 
   // Fetched once each. A second read of the same item during a deploy is the
   // same answer, and this avoids a process per call site
   const cache = new Map<string, Promise<string>>();
 
   const fetch = async (id: string) => {
+    detail(`reading ${id.slice(0, 8)}`);
+
     const item = await bw(["get", "notes", id, "--raw"], {
       BW_SESSION: session,
     }).catch((error: unknown) => {
@@ -145,11 +176,15 @@ async function install(detail: (message: string) => void) {
   detail(`installing ${CLI}, once for this machine`);
   await mkdir(directory, { recursive: true });
 
-  await run(
-    "npm",
-    ["install", "--prefix", directory, "--no-save", "--no-audit", "--no-fund", CLI],
-    { maxBuffer: 32 * 1024 * 1024 },
-  ).catch((error: unknown) => {
+  await run("npm", [
+    "install",
+    "--prefix",
+    directory,
+    "--no-save",
+    "--no-audit",
+    "--no-fund",
+    CLI,
+  ]).catch((error: unknown) => {
     throw new Error(`Could not install ${CLI}: ${messageOf(error)}`);
   });
 

package/src/services/ensure.ts

@@ -1,7 +1,7 @@
 import { SPEC_LABEL, type Docker } from "../docker.js";
 import type { Host } from "../host.js";
 import type { Log } from "../log.js";
-import { LISTEN_PORT } from "../nginx.js";
+import { LISTEN_PORT } from "./proxy.js";
 import { readEnv, type SecretStores } from "../secrets/refs.js";
 import type { ServiceTopology, Topology } from "../topology.js";
 import type { ServiceSpec } from "../types.js";

package/src/services/index.ts

@@ -1,4 +1,16 @@
-import type { SecretRefs, ServiceSpec } from "../types.js";
+import type { ProxySpec, SecretRefs, ServiceSpec } from "../types.js";
+
+// Not something a deployment lists. Apps carry routes, routes need something
+// to resolve them, and this says what that something is rather than that it
+// exists. A service by this name is refused: there is already one
+export function nginx(options: ProxySpec = {}): ProxySpec {
+  return {
+    image: options.image ?? "nginx:stable",
+    maxBodySize: options.maxBodySize ?? "1M",
+    server: options.server ?? [],
+    location: options.location ?? [],
+  };
+}
 
 type RedisOptions = {
   image?: string;

package/src/services/planned.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 
 import type { Docker } from "../docker.js";
-import { LISTEN_PORT, renderNginx } from "../nginx.js";
+import { LISTEN_PORT, proxyService, renderProxy } from "./proxy.js";
 import type { Run } from "../pipeline.js";
 import type { ServiceTopology, Topology } from "../topology.js";
 import type { Deployment, ServiceSpec } from "../types.js";
@@ -36,10 +36,10 @@ export function plannedServices(
   if (run === "verify") return rest;
 
   const proxy: PlannedService = {
-    spec: router(config),
+    spec: proxyService(config),
     service: topology.router,
     files: {
-      "/etc/nginx/conf.d/default.conf": renderNginx(topology, config.maxBodySize),
+      "/etc/nginx/conf.d/default.conf": renderProxy(topology, config.proxy),
     },
     publish: topology.publicPort,
   };
@@ -47,16 +47,6 @@ export function plannedServices(
   return [proxy, ...rest];
 }
 
-// Not something a deployment lists. Apps carry routes, routes need a proxy to
-// resolve them, and the one that renders them is this
-export function router(config: Deployment): ServiceSpec {
-  return {
-    name: "nginx",
-    image: config.proxyImage ?? "nginx:stable",
-    restart: "always",
-  };
-}
-
 // Everything a recreate would change, and nothing a deploy resolves. Secrets
 // are named by their refs rather than their values: whether the config is the
 // one running is a question a plan should answer without unlocking a vault

package/src/services/proxy.ts

@@ -0,0 +1,126 @@
+import type { AppTopology, Topology } from "../topology.js";
+import type { Deployment, ProxySpec, ServiceSpec } from "../types.js";
+
+// The proxy every route is resolved by: what it is, and the configuration it
+// runs. Both halves here, because a deployment does not list this service and
+// the only thing that decides either is the app list.
+//
+// Header policy is set 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;
+
+// What the derived proxy is called. A service by this name would be a second
+// container claiming the first one's, so the config surface refuses it
+export const PROXY = "nginx";
+
+// Not something a deployment lists. Apps carry routes, routes need something
+// to resolve them, and this says what that something is
+export function proxyService(config: Deployment): ServiceSpec {
+  return {
+    name: PROXY,
+    image: config.proxy?.image ?? "nginx:stable",
+    restart: "always",
+  };
+}
+
+export function renderProxy(topology: Topology, proxy: ProxySpec = {}) {
+  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, proxy.location ?? [])).join("\n\n");
+
+  assertNotDerived(proxy.server ?? []);
+
+  const server = settled([
+    `merge_slashes off;`,
+    `client_max_body_size ${proxy.maxBodySize ?? "1M"};`,
+    ...(proxy.server ?? []),
+  ]);
+
+  return `resolver 127.0.0.1 valid=5s;
+
+${upstreams}
+
+server {
+    listen ${LISTEN_PORT};
+${indented(server, 4)}
+${locations}
+}
+`;
+}
+
+// nginx refuses a second proxy_read_timeout but expects several
+// proxy_set_header, so what identifies a line is the directive and, for the
+// ones that carry a name, the name after it
+const NAMED = new Set(["add_header", "proxy_set_header", "proxy_hide_header", "set"]);
+
+function directive(line: string) {
+  const [name = "", argument = ""] = line.trim().split(/\s+/);
+  return NAMED.has(name) ? `${name} ${argument}` : name;
+}
+
+// The last of each wins. A line written by hand replaces the one redkite would
+// have put there rather than repeating it, which nginx would refuse outright
+function settled(lines: string[]) {
+  const kept = new Map<string, string>();
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    kept.set(directive(line), line.trim());
+  }
+
+  return [...kept.values()];
+}
+
+// The published port maps onto this one, so both sides have to agree and only
+// one of them may say it
+function assertNotDerived(lines: string[]) {
+  const listening = lines.find((line) => directive(line) === "listen");
+  if (!listening) return;
+
+  throw new Error(
+    `The proxy's server block says ${listening.trim()}, and the port it listens ` +
+      "on inside its container is what publicPort is published onto",
+  );
+}
+
+function indented(lines: string[], by: number) {
+  return lines.map((line) => " ".repeat(by) + line).join("\n");
+}
+
+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, added: string[]) {
+  // 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}/`;
+
+  // Last, so one of these replaces what redkite set rather than repeating it
+  const body = settled([`proxy_pass ${target};`, ...FAILOVER, ...FORWARDING, ...added]);
+
+  return `    location ${app.route} {
+${indented(body, 8)}
+    }`;
+}