@homeflare/alchemy 0.5.0 → 0.7.0

package/src/caddy/fake-caddy.ts

@@ -0,0 +1,160 @@
+/**
+ * A fake Caddy admin API for the tests beside it — `Bun.serve` on an ephemeral 127.0.0.1 port (or a
+ * unix socket), answering `/adapt`, `/load` and `/config/` the way caddyserver/caddy v2.11.4 does.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file, and it never forwards anywhere.
+ * ★ WHAT IS FAITHFUL, because the provider depends on it (see admin-calls.ts and digest.ts):
+ *   · `/adapt` answers the adapter's STRUCT key order (unsorted); `/config/` answers SORTED keys,
+ *     `<` escaped as `\u003c`, and a trailing newline — the differences the digest must erase.
+ *   · A refused `/load` keeps the old config. With adapter warnings, the refusal comes in a 200
+ *     whose body is the warnings followed by the error (load.go).
+ *   · The Host check (admin.go checkHost) and the Origin check when one is sent.
+ * ★ THE TOY ADAPTER. A Caddyfile here is lines; each becomes a route. Keywords steer the fake:
+ *   `SYNTAX_ERROR` fails the adapt; `PROVISION_ERROR` adapts but fails the load; a TAB anywhere is
+ *   "not formatted" (the warning real Caddy gives unformatted input); `admin <listen>`,
+ *   `admin off` and `origins <a> <b>` set the adapted `admin` block. With no site lines there are
+ *   no apps at all, as real Caddy adapts a Caddyfile of only comments or global options.
+ * ★ `listenPort` is the port Caddy BELIEVES it listens on — its Host check uses it — while the
+ *   fake really listens on an ephemeral one: a Caddy on its default :2019 behind a forward.
+ */
+export type Seen = {
+  readonly method: string;
+  readonly path: string;
+  readonly headers: Headers;
+  readonly body: string;
+};
+
+export type FakeCaddy = {
+  /** An address localCaddyAdmin() takes. */
+  readonly address: string;
+  readonly port: number;
+  readonly seen: Seen[];
+  /** The running config as a parsed object (null when empty). */
+  running: unknown;
+  /** Adapt with the toy adapter — to stage a "restart with a different file". */
+  adapt(caddyfile: string): unknown;
+  stop(): void;
+};
+
+const json = (status: number, body: unknown) =>
+  new Response(`${JSON.stringify(body)}\n`, {
+    headers: { 'content-type': 'application/json' },
+    status,
+  });
+
+/** The toy adapter: struct key order on purpose (`routes` before `listen`, `apps` before `admin`). */
+const toyAdapt = (text: string): { config?: unknown; error?: string; warnings: unknown[] } => {
+  const lines = text.split('\n').filter((line) => line.trim() !== '' && !line.startsWith('#'));
+  const at = lines.findIndex((line) => line.includes('SYNTAX_ERROR'));
+  if (at !== -1)
+    return { error: `Caddyfile:${String(at + 1)} - Error during parsing`, warnings: [] };
+  const admin: Record<string, unknown> = {};
+  const routes: unknown[] = [];
+  for (const line of lines) {
+    const [word, ...rest] = line.trim().split(/\s+/);
+    if (word === 'admin' && rest[0] === 'off') admin['disabled'] = true;
+    else if (word === 'admin') admin['listen'] = rest[0];
+    else if (word === 'origins') admin['origins'] = rest;
+    else routes.push({ match: [{ host: [word] }], handle: [{ handler: 'static', body: line }] });
+  }
+  const warnings = text.includes('\t')
+    ? [{ file: 'Caddyfile', line: 1, message: 'Caddyfile input is not formatted' }]
+    : [];
+  const config = {
+    ...(routes.length === 0
+      ? {}
+      : { apps: { http: { servers: { srv0: { routes, listen: [':443'] } } } } }),
+    ...(Object.keys(admin).length === 0 ? {} : { admin }),
+  };
+  return { config, warnings };
+};
+
+/** Go's generic re-marshal: sorted keys, `<>&` escaped. */
+const goEncode = (value: unknown): string => {
+  const sort = (v: unknown): unknown =>
+    Array.isArray(v)
+      ? v.map(sort)
+      : typeof v === 'object' && v !== null
+        ? Object.fromEntries(
+            Object.keys(v)
+              .sort()
+              .map((k) => [k, sort((v as Record<string, unknown>)[k])]),
+          )
+        : v;
+  return JSON.stringify(sort(value))
+    .replaceAll('<', '\\u003c')
+    .replaceAll('>', '\\u003e')
+    .replaceAll('&', '\\u0026');
+};
+
+export const fakeCaddy = (
+  options: { unix?: string; running?: unknown; origins?: string[]; listenPort?: number } = {},
+): FakeCaddy => {
+  const seen: Seen[] = [];
+  let port = 0;
+  const state: { running: unknown } = { running: options.running ?? null };
+  const allowedHosts = () =>
+    options.origins ??
+    ['localhost', '[::1]', '127.0.0.1'].map(
+      (host) => `${host}:${String(options.listenPort ?? port)}`,
+    );
+
+  const handle = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const body = await request.text();
+    seen.push({ body, headers: request.headers, method: request.method, path: url.pathname });
+    if (options.unix === undefined) {
+      const host = request.headers.get('host') ?? '';
+      if (!allowedHosts().includes(host)) return json(403, { error: `host not allowed: ${host}` });
+      const origin = request.headers.get('origin');
+      if (origin !== null && !allowedHosts().includes(new URL(origin).host)) {
+        return json(403, { error: `client is not allowed to access from origin '${origin}'` });
+      }
+    }
+    if (url.pathname === '/config/' && request.method === 'GET') {
+      return new Response(`${goEncode(state.running)}\n`, { status: 200 });
+    }
+    const type = request.headers.get('content-type') ?? '';
+    if (request.method !== 'POST' || type !== 'text/caddyfile')
+      return json(400, { error: 'unexpected' });
+    const adapted = toyAdapt(body);
+    if (adapted.error !== undefined) return json(400, { error: adapted.error });
+    if (url.pathname === '/adapt') {
+      const out = adapted.warnings.length > 0 ? { warnings: adapted.warnings } : {};
+      return json(200, { ...out, result: adapted.config });
+    }
+    if (url.pathname !== '/load') return json(404, { error: 'not found' });
+    const prefix = adapted.warnings.length > 0 ? JSON.stringify(adapted.warnings) : '';
+    if (body.includes('PROVISION_ERROR')) {
+      const error = JSON.stringify({
+        error: 'loading config: provision http: listen tcp :443: address already in use',
+      });
+      // ⛔ load.go: warnings written first commit a 200; the error rides after them.
+      return prefix === ''
+        ? new Response(`${error}\n`, { status: 400 })
+        : new Response(`${prefix}${error}\n`, { status: 200 });
+    }
+    state.running = JSON.parse(goEncode(adapted.config));
+    return new Response(prefix, { status: 200 });
+  };
+
+  const server =
+    options.unix === undefined
+      ? Bun.serve({ fetch: handle, hostname: '127.0.0.1', port: 0 })
+      : Bun.serve({ fetch: handle, unix: options.unix });
+  port = server.port ?? 0;
+  return {
+    adapt: (caddyfile) => toyAdapt(caddyfile).config,
+    address:
+      options.unix === undefined ? `http://127.0.0.1:${String(port)}` : `unix://${options.unix}`,
+    get running() {
+      return state.running;
+    },
+    set running(value: unknown) {
+      state.running = value;
+    },
+    port,
+    seen,
+    stop: () => void server.stop(true),
+  };
+};

package/src/caddy/guards.test.ts

@@ -0,0 +1,156 @@
+/**
+ * The pure checks: the digest's canonical form, the Caddyfile secret tripwire, and the admin-block
+ * guard. Each refusal here is one a deploy would otherwise learn about from a stranded Caddy or a
+ * token in the state store.
+ */
+import { describe, expect, test } from 'bun:test';
+import { adminProblems } from './admin-guard.ts';
+import type { CaddyAdminListener } from './admin.ts';
+import { caddyfileSecretProblems, tokensOf } from './caddyfile-tripwire.ts';
+import { canonicalConfig, configDigest, parseConfig } from './digest.ts';
+
+describe('digest', () => {
+  test('struct order (/adapt) and sorted, escaped, newline-terminated (/config/) hash the same', () => {
+    const adapted = {
+      apps: { http: { servers: { srv0: { routes: ['<a> & b'], listen: [':443'] } } } },
+    };
+    const reported =
+      '{"apps":{"http":{"servers":{"srv0":{"listen":[":443"],"routes":["\\u003ca\\u003e \\u0026 b"]}}}}}\n';
+    expect(configDigest(parseConfig(reported))).toBe(configDigest(adapted));
+  });
+
+  test('an empty config is null, and hashes as null', () => {
+    expect(parseConfig('null\n')).toBeNull();
+    expect(canonicalConfig(undefined)).toBe('null');
+  });
+
+  test('a real difference is a different digest', () => {
+    expect(configDigest({ a: [1, 2] })).not.toBe(configDigest({ a: [2, 1] }));
+  });
+});
+
+describe('tokensOf', () => {
+  test('quotes kept whole, comments dropped only at a token start', () => {
+    expect(tokensOf('header Authorization "Bearer {env.T}" # note')).toEqual([
+      'header',
+      'Authorization',
+      'Bearer {env.T}',
+    ]);
+    expect(tokensOf('respond a#b')).toEqual(['respond', 'a#b']);
+  });
+});
+
+/**
+ * ⚠️ ASSEMBLED AT RUN TIME. A literal token-shaped fixture trips the pre-commit gitleaks scan
+ *   (MEASURED 2026-09-21: its `jwt` rule flagged the first draft of this file). Joined parts keep
+ *   the shape the tripwire must catch out of the source text gitleaks reads.
+ */
+const GITHUB_TOKEN = ['ghp', 'a1B2'.repeat(9)].join('_');
+const JWT = ['eyJhbGciOiJub25lIn0', 'eyJzdWIiOiJ4In0x', 'c2lnbmF0dXJl'].join('.');
+const BCRYPT = ['', '2a', '14', 'x'.repeat(53)].join('$');
+
+describe('caddyfileSecretProblems', () => {
+  test.each([
+    ['dns provider token', 'tls {\n  dns cloudflare abcdef0123456789\n}'],
+    ['acme_dns token', 'acme_dns cloudflare abcdef0123456789'],
+    ['a secret-named subdirective', 'oauth {\n  client_secret s3cr3t\n}'],
+    [
+      'a literal Authorization header',
+      'reverse_proxy up:80 {\n  header_up Authorization "Bearer abc123"\n}',
+    ],
+    ['a GitHub token anywhere', `respond ${GITHUB_TOKEN}`],
+    ['a JWT', `header X-Id ${JWT}`],
+    ['a bcrypt hash in basic_auth', `basic_auth {\n  admin ${BCRYPT}\n}`],
+    ['a PEM private key', 'x {\n-----BEGIN EC PRIVATE KEY-----\n}'],
+    // ⛔ An adapt-time default is spliced in whenever the variable is unset: it is a literal.
+    ['a literal default for a dns token', 'dns cloudflare {$CF_API_TOKEN:abcdef0123456789}'],
+    ['a token-shaped default anywhere', `respond "{$GREETING:${GITHUB_TOKEN}}"`],
+  ])('refuses %s', (_, caddyfile) => {
+    const found = caddyfileSecretProblems(caddyfile);
+    expect(found.length).toBeGreaterThan(0);
+    expect(found.join(' ')).toContain('{env.NAME}');
+  });
+
+  test('never echoes the secret it found', () => {
+    const found = caddyfileSecretProblems('dns cloudflare abcdef0123456789').join(' ');
+    expect(found).not.toContain('abcdef0123456789');
+    expect(found).toContain('line 1');
+  });
+
+  test.each([
+    ['env placeholder', 'tls {\n  dns cloudflare {env.CF_API_TOKEN}\n}'],
+    ['file placeholder', 'client_secret {file./run/secrets/oidc}'],
+    ['adapt-time env (the name only)', 'dns cloudflare {$CF_API_TOKEN}'],
+    ['an adapt-time default that is not a secret', 'reverse_proxy {$UPSTREAM:127.0.0.1:8080}'],
+    ['a placeholder bearer', 'header_up Authorization "Bearer {env.UPSTREAM_TOKEN}"'],
+    ['a forwarded header', 'header_up Authorization {http.request.header.Authorization}'],
+    ['a block opener', 'dns cloudflare {\n  api_token {env.CF}\n}'],
+    ['a deleted header', 'header -Authorization'],
+    ['a *_file path', 'api_key_file /run/secrets/key'],
+    ['a hash from the env', 'basic_auth {\n  admin {env.ADMIN_HASH}\n}'],
+    ['an ordinary site', 'app.example.com {\n  reverse_proxy 127.0.0.1:8080\n}'],
+  ])('allows %s', (_, caddyfile) => {
+    expect(caddyfileSecretProblems(caddyfile)).toEqual([]);
+  });
+});
+
+describe('adminProblems', () => {
+  const tcp: CaddyAdminListener = { hostHeader: '127.0.0.1:2019', kind: 'tcp', port: 2019 };
+  const unix: CaddyAdminListener = { kind: 'unix', path: '/run/caddy/admin.sock' };
+  const admin = (block: object) => ({ admin: block, apps: {} });
+
+  const v6: CaddyAdminListener = { hostHeader: '[::1]:2019', kind: 'tcp', port: 2019 };
+  const named: CaddyAdminListener = { hostHeader: 'localhost:2019', kind: 'tcp', port: 2019 };
+
+  test.each([
+    [{}, tcp],
+    [{ listen: 'localhost:2019' }, tcp],
+    [{ listen: '127.0.0.1:2019', origins: ['127.0.0.1:2019'] }, tcp],
+    [{ listen: 'tcp/[::1]:2019' }, v6],
+    [{ listen: '127.0.0.1:2019' }, named],
+    [{ listen: 'unix//run/caddy/admin.sock|0660' }, unix],
+    [{ origins: ['http://127.0.0.1:2019'] }, tcp],
+  ])('allows %j', (block, transport) => {
+    expect(adminProblems(admin(block), transport)).toEqual([]);
+  });
+
+  test('no admin block at all, and an empty config, pass at Caddy’s default listener', () => {
+    expect(adminProblems({ apps: {} }, tcp)).toEqual([]);
+    expect(adminProblems(null, tcp)).toEqual([]);
+  });
+
+  /**
+   * ⛔ No `admin` address means DefaultAdminListen (localhost:2019) after the load — so a Caddy
+   *   reached anywhere else would move away from the provider (admin.go replaceLocalAdminServer).
+   */
+  test.each([
+    ['a unix socket', unix],
+    ['another port', { hostHeader: '127.0.0.1:2999', kind: 'tcp', port: 2999 } as const],
+    ['[::1] (localhost binds IPv4)', v6],
+  ])('no admin address is refused for a Caddy reached on %s', (_, transport) => {
+    expect(adminProblems({ apps: {} }, transport).join(' ')).toMatch(/declare `admin <address>`/);
+  });
+
+  test.each([
+    [{ disabled: true }, tcp, /admin off/],
+    [{ listen: ':2019' }, tcp, /not loopback/],
+    [{ listen: '0.0.0.0:2019' }, tcp, /not loopback/],
+    [{ listen: '192.0.2.5:2019' }, tcp, /not loopback/],
+    [{ listen: 'localhost:2020' }, tcp, /moves the admin API/],
+    [{ listen: 'tcp/[::1]:2019' }, tcp, /moves the admin API/],
+    [{ listen: '127.0.0.2:2019' }, tcp, /moves the admin API/],
+    [{ listen: 'localhost:2019' }, v6, /moves the admin API/],
+    [{ listen: 'unix//run/caddy/admin.sock', enforce_origin: true }, unix, /sends no Origin/],
+    [{ listen: 'unix//run/caddy/admin.sock' }, tcp, /moves the admin API/],
+    [{ listen: 'unix//run/other.sock' }, unix, /moves the admin API/],
+    [{ listen: '{env.CADDY_ADMIN}' }, tcp, /placeholder/],
+    [{ origins: ['caddy.example:2019'] }, tcp, /do not allow Host 127\.0\.0\.1:2019/],
+    [{ origins: ['https://127.0.0.1:2019'] }, tcp, /do not allow Host/],
+    [{ origins: [] }, tcp, /do not allow Host/],
+    [{}, { hostHeader: 'caddy.example:2019', kind: 'tcp', port: 2019 } as const, /default origins/],
+    [{ remote: { listen: ':2021' } }, tcp, /network-facing/],
+    [{ config: { load: { module: 'http' } } }, tcp, /pull its config/],
+  ])('refuses %j', (block, transport, reason) => {
+    expect(adminProblems(admin(block), transport).join(' ')).toMatch(reason);
+  });
+});

package/src/caddy/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Caddy for Alchemy — a running Caddy's config, declared as Caddyfile text and applied through
+ * Caddy's own admin API (`POST /load`, `GET /config/`).
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. The lifecycle,
+ *   the digest, the guards and the admin calls are internals; an `export *` would publish them.
+ * ⛔ THE ADMIN API STAYS ON LOOPBACK OR A UNIX SOCKET. It has no authentication; localCaddyAdmin()
+ *   refuses any other address, and a Caddyfile that would move or expose it is refused before load.
+ * Guide, order of file and load, `--resume` and secrets: docs/caddy.md.
+ */
+export type {
+  CaddyAdmin,
+  CaddyAdminListener,
+  CaddyAdminRequest,
+  CaddyAdminResponse,
+} from './admin.ts';
+export { CaddyAdminService, CaddyUnreachableError, caddyAdminLayer } from './admin.ts';
+export { CaddyAdminError } from './admin-calls.ts';
+export type { CaddyConfigAttributes, CaddyConfigProps } from './config.ts';
+export { CaddyConfig, CaddyConfigProvider } from './config.ts';
+export type { LocalCaddyAdminOptions } from './local-admin.ts';
+export { DEFAULT_ADMIN_ADDRESS, localCaddyAdmin } from './local-admin.ts';
+export { caddyProviders } from './providers.ts';
+export type { CaddyWithFileProps } from './with-file.ts';
+export { caddyWithFile } from './with-file.ts';

package/src/caddy/local-admin.test.ts

@@ -0,0 +1,160 @@
+/**
+ * localCaddyAdmin: which addresses it accepts, the Host and Origin it sends (Caddy checks both),
+ * the unix-socket path, and retrying only a connection nothing accepted.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CaddyUnreachableError } from './admin.ts';
+import { readRunningConfig } from './admin-calls.ts';
+import { type FakeCaddy, fakeCaddy } from './fake-caddy.ts';
+import { DEFAULT_ADMIN_ADDRESS, localCaddyAdmin, parseAdminAddress } from './local-admin.ts';
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+/** ⚠️ Short on purpose: macOS caps a socket path at 104 bytes, and node then fails EINVAL. */
+const socketPath = (label: string) => {
+  const path = join(tmpdir(), `fc-${label}-${String(process.pid)}.sock`);
+  rmSync(path, { force: true });
+  return path;
+};
+
+describe('parseAdminAddress', () => {
+  test("the default is Caddy's own default listener, over loopback TCP", () => {
+    expect(DEFAULT_ADMIN_ADDRESS).toBe('http://127.0.0.1:2019');
+    expect(parseAdminAddress(DEFAULT_ADMIN_ADDRESS).listener).toEqual({
+      hostHeader: '127.0.0.1:2019',
+      kind: 'tcp',
+      port: 2019,
+    });
+  });
+
+  test.each(['http://localhost:2019', 'http://[::1]:2019', 'http://127.0.0.2:2020'])(
+    'accepts loopback %s',
+    (address) => {
+      expect(parseAdminAddress(address).listener.kind).toBe('tcp');
+    },
+  );
+
+  test('a unix socket, which Caddy exempts from the Host check', () => {
+    expect(parseAdminAddress('unix:///run/caddy/admin.sock').listener).toEqual({
+      kind: 'unix',
+      path: '/run/caddy/admin.sock',
+    });
+  });
+
+  test.each([
+    ['http://192.0.2.10:2019', /not loopback/],
+    ['http://caddy.example.com:2019', /not loopback/],
+    ['https://127.0.0.1:2019', /only http/],
+    ['http://127.0.0.1:2019/config', /no path/],
+    ['http://user:pw@127.0.0.1:2019', /credentials/],
+    ['unix://relative.sock', /absolute/],
+    ['127.0.0.1:2019', /not a URL|only http/],
+  ])('refuses %s', (address, reason) => {
+    expect(() => parseAdminAddress(address)).toThrow(reason);
+  });
+
+  test('the Host always carries the port, as Caddy compares host:port (a default port too)', () => {
+    expect(parseAdminAddress('http://127.0.0.1').listener).toEqual({
+      hostHeader: '127.0.0.1:80',
+      kind: 'tcp',
+      port: 80,
+    });
+    expect(parseAdminAddress('http://[::1]:2019').listener).toMatchObject({
+      hostHeader: '[::1]:2019',
+    });
+  });
+
+  test('hostHeader is what Caddy checks: its port is the listener port, not the dialled one', () => {
+    const parsed = parseAdminAddress('http://127.0.0.1:12019', '127.0.0.1:2019');
+    expect(parsed.listener).toEqual({ hostHeader: '127.0.0.1:2019', kind: 'tcp', port: 2019 });
+    expect(() => parseAdminAddress('http://127.0.0.1:2019', 'no port')).toThrow(/host:port/);
+  });
+});
+
+describe('requests', () => {
+  test('over TCP: Host and Origin as the Caddy CLI sends them, so the checks pass', async () => {
+    fake = fakeCaddy();
+    const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
+    expect(await readRunningConfig(admin)).toBeNull();
+    const host = `127.0.0.1:${String(fake.port)}`;
+    expect(fake.seen[0]?.headers.get('host')).toBe(host);
+    expect(fake.seen[0]?.headers.get('origin')).toBe(`http://${host}`);
+  });
+
+  test('a narrowed `origins` needs hostHeader — without it Caddy answers 403', async () => {
+    fake = fakeCaddy({ origins: ['caddy-admin.example:2019'] });
+    const plain = localCaddyAdmin({ address: fake.address, retries: 0 });
+    await expect(readRunningConfig(plain)).rejects.toThrow(/403: host not allowed/);
+    const named = localCaddyAdmin({
+      address: fake.address,
+      hostHeader: 'caddy-admin.example:2019',
+      retries: 0,
+    });
+    expect(await readRunningConfig(named)).toBeNull();
+  });
+
+  test('a caller cannot override the Host and Origin the checks depend on', async () => {
+    fake = fakeCaddy();
+    const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
+    const headers = { Host: 'evil.example:2019', Origin: 'http://evil.example:2019' };
+    expect((await admin.request({ headers, method: 'GET', path: '/config/' })).status).toBe(200);
+    expect(fake.seen[0]?.headers.get('host')).toBe(`127.0.0.1:${String(fake.port)}`);
+  });
+
+  test('over a unix socket, with no Origin', async () => {
+    const path = socketPath('req');
+    fake = fakeCaddy({ running: { apps: {} }, unix: path });
+    const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
+    expect(await readRunningConfig(admin)).toEqual({ apps: {} });
+    expect(fake.seen[0]?.headers.has('origin')).toBe(false);
+    rmSync(path, { force: true });
+  });
+
+  test('retries a socket nobody listens on yet, then reaches the Caddy that came up', async () => {
+    const path = socketPath('late');
+    const admin = localCaddyAdmin({ address: `unix://${path}`, retries: 5, retryDelayMs: 40 });
+    const late = setTimeout(() => {
+      fake = fakeCaddy({ unix: path });
+    }, 60);
+    expect(await readRunningConfig(admin)).toBeNull();
+    clearTimeout(late);
+    rmSync(path, { force: true });
+  });
+
+  test('a connection that was ACCEPTED is never re-sent, however many retries remain', async () => {
+    // ⛔ It may have reached Caddy: re-sending a `POST /load` could apply it twice.
+    let accepted = 0;
+    const server = createServer((socket) => {
+      accepted += 1;
+      socket.on('data', () => socket.destroy());
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address() as { port: number };
+    const admin = localCaddyAdmin({
+      address: `http://127.0.0.1:${String(port)}`,
+      retries: 3,
+      retryDelayMs: 1,
+    });
+    const failure = admin.request({ body: 'x', method: 'POST', path: '/load' });
+    await expect(failure).rejects.toThrow(/Caddy admin POST \/load/);
+    await expect(failure).rejects.not.toBeInstanceOf(CaddyUnreachableError);
+    expect(accepted).toBe(1);
+    server.close();
+  });
+
+  test('gives up after the retries with CaddyUnreachableError, naming the address', async () => {
+    const path = socketPath('never');
+    const admin = localCaddyAdmin({ address: `unix://${path}`, retries: 1, retryDelayMs: 1 });
+    const failure = readRunningConfig(admin);
+    await expect(failure).rejects.toBeInstanceOf(CaddyUnreachableError);
+    await expect(failure).rejects.toThrow(/Caddy admin GET \/config\/ at unix:\/\//);
+  });
+});