@homeflare/alchemy 0.5.0 → 0.7.0

package/src/caddy/local-admin.ts

@@ -0,0 +1,189 @@
+/**
+ * The real CaddyAdmin: this machine's Caddy, over loopback TCP or a unix socket.
+ *
+ * ★ node:http, NOT fetch. MEASURED 2026-09-21 on bun 1.4.0 and node 26.7.0: node:http sends a Host
+ *   override and dials a unix socket on BOTH runtimes, while node's fetch silently drops a `Host`
+ *   header (it sent the URL's host) and only Bun's fetch has a `unix` option. The published dist
+ *   loads under node too (launchd's local-runner.ts makes the same call for the same reason).
+ * ⛔ LOOPBACK OR A UNIX SOCKET, NOTHING ELSE. The admin API is unauthenticated plaintext; an
+ *   address off this machine means it is reachable from the network, which decision 23 forbids.
+ *   Reaching another host's Caddy means forwarding its socket or port to here (SSH), never
+ *   exposing :2019.
+ * ★ HOST AND ORIGIN, AS CADDY's OWN CLI SENDS THEM (cmd/commandfuncs.go AdminAPIRequest): over
+ *   TCP, `Host` and `Origin: http://<host>`; over a socket, `Host: 127.0.0.1` and no Origin, because
+ *   Caddy skips the Host check on unix listeners (admin.go allowedOrigins). MEASURED against the
+ *   mini's Caddy 2.11.4: any other Host gets 403 `host not allowed`, a forwarded port included —
+ *   hence `hostHeader`.
+ */
+import { request as httpRequest } from 'node:http';
+import {
+  type CaddyAdmin,
+  type CaddyAdminListener,
+  type CaddyAdminResponse,
+  CaddyUnreachableError,
+} from './admin.ts';
+
+export type LocalCaddyAdminOptions = {
+  /**
+   * `http://<loopback>:<port>` or `unix:///absolute/path.sock`.
+   * @default 'http://127.0.0.1:2019' — Caddy's default admin listener (`localhost:2019`).
+   */
+  readonly address?: string;
+  /**
+   * The Host (and Origin) to send over TCP, when it is not the address's own: the Caddyfile
+   * narrowed `admin { origins … }`, or the port is an SSH forward of the real one (Caddy checks
+   * the Host against ITS port, not yours). Form `host:port`.
+   */
+  readonly hostHeader?: string;
+  /**
+   * Abort an exchange after this long. @default 60_000
+   * ⚠️ A `shutdown_delay` in the Caddyfile makes `/load` block that long (caddyhttp app.go Stop);
+   *   a timeout then fails the deploy while Caddy goes on to apply — the next plan converges.
+   */
+  readonly timeoutMs?: number;
+  /**
+   * Retries when the connection is REFUSED (nothing listening yet — a Caddy launchd job that was
+   * bootstrapped a moment ago). Only refusals: those never reached Caddy, so re-sending a
+   * `POST /load` cannot apply it twice. @default 2
+   */
+  readonly retries?: number;
+  /** @default 500 */
+  readonly retryDelayMs?: number;
+};
+
+export const DEFAULT_ADMIN_ADDRESS = 'http://127.0.0.1:2019';
+
+type Target =
+  | { readonly kind: 'tcp'; readonly host: string; readonly port: number }
+  | { readonly kind: 'unix'; readonly socketPath: string };
+
+const UNIX = 'unix://';
+const HOST_PORT = /^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\]):\d{1,5}$/;
+
+const refuse = (address: string, why: string): Error =>
+  new Error(`Caddy admin address ${JSON.stringify(address)}: ${why}`);
+
+const isLoopback = (hostname: string): boolean =>
+  hostname === 'localhost' || hostname === '[::1]' || /^127(?:\.\d{1,3}){3}$/.test(hostname);
+
+/** The dial target and listener for an address, or a refusal naming what is wrong with it. */
+export const parseAdminAddress = (
+  address: string,
+  hostHeader?: string,
+): { target: Target; listener: CaddyAdminListener } => {
+  if (hostHeader !== undefined && !HOST_PORT.test(hostHeader)) {
+    throw refuse(address, `hostHeader ${JSON.stringify(hostHeader)} must be host:port`);
+  }
+  if (address.startsWith(UNIX)) {
+    const socketPath = address.slice(UNIX.length);
+    if (!socketPath.startsWith('/')) throw refuse(address, 'the socket path must be absolute');
+    return { listener: { kind: 'unix', path: socketPath }, target: { kind: 'unix', socketPath } };
+  }
+  let url: URL;
+  try {
+    url = new URL(address);
+  } catch {
+    throw refuse(address, 'not a URL (http://127.0.0.1:2019 or unix:///path)');
+  }
+  // ⛔ Caddy's local admin endpoint is plaintext by design; its TLS one (`admin.remote`, mTLS on
+  //   :2021) is a different, network-facing API this transport deliberately does not speak.
+  if (url.protocol !== 'http:') throw refuse(address, 'only http:// (loopback) or unix://');
+  if (!isLoopback(url.hostname)) {
+    throw refuse(address, 'not loopback — the admin API is unauthenticated; forward it to here');
+  }
+  if (url.pathname !== '/' || url.search !== '' || url.username !== '') {
+    throw refuse(address, 'no path, query or credentials — the API lives at the root');
+  }
+  const port = url.port === '' ? 80 : Number(url.port);
+  // ⚠️ NOT `url.host`: WHATWG URL drops a default port (`http://127.0.0.1:80` has host
+  //   `127.0.0.1`), and Caddy compares the Host against `host:port` (admin.go allowedOrigins), so
+  //   a portless Host is a 403 on every call. The Caddy CLI always sends the port (JoinHostPort).
+  const host = hostHeader ?? `${url.hostname}:${String(port)}`;
+  return {
+    listener: {
+      hostHeader: host,
+      kind: 'tcp',
+      port: Number(host.slice(host.lastIndexOf(':') + 1)),
+    },
+    // ★ `hostname` keeps IPv6 brackets; node:http wants them off.
+    target: { host: url.hostname.replace(/^\[(.*)\]$/, '$1'), kind: 'tcp', port },
+  };
+};
+
+const code = (cause: unknown): string | undefined =>
+  typeof cause === 'object' && cause !== null && 'code' in cause
+    ? String((cause as { code: unknown }).code)
+    : undefined;
+
+/** Nothing accepted the connection: refused TCP, or no socket file yet. The request never left. */
+const neverConnected = (cause: unknown): boolean =>
+  code(cause) === 'ECONNREFUSED' || code(cause) === 'ENOENT';
+
+const exchange = (
+  target: Target,
+  method: string,
+  path: string,
+  headers: Record<string, string>,
+  body: string | undefined,
+  timeoutMs: number,
+): Promise<CaddyAdminResponse> =>
+  new Promise((resolve, reject) => {
+    const bytes = body === undefined ? undefined : Buffer.from(body, 'utf8');
+    const request = httpRequest(
+      {
+        ...(target.kind === 'tcp'
+          ? { host: target.host, port: target.port }
+          : { socketPath: target.socketPath }),
+        headers: bytes === undefined ? headers : { ...headers, 'Content-Length': bytes.length },
+        method,
+        path,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        const chunks: Buffer[] = [];
+        response.on('data', (chunk: Buffer) => chunks.push(chunk));
+        response.on('error', reject);
+        response.on('end', () =>
+          resolve({
+            body: Buffer.concat(chunks).toString('utf8'),
+            status: response.statusCode ?? 0,
+          }),
+        );
+      },
+    );
+    request.on('timeout', () => request.destroy(new Error(`no answer in ${String(timeoutMs)} ms`)));
+    request.on('error', reject);
+    request.end(bytes);
+  });
+
+export const localCaddyAdmin = (options: LocalCaddyAdminOptions = {}): CaddyAdmin => {
+  const address = options.address ?? DEFAULT_ADMIN_ADDRESS;
+  const { listener, target } = parseAdminAddress(address, options.hostHeader);
+  const timeoutMs = options.timeoutMs ?? 60_000;
+  const retries = options.retries ?? 2;
+  const delay = options.retryDelayMs ?? 500;
+  const fixed: Record<string, string> =
+    listener.kind === 'tcp'
+      ? { Host: listener.hostHeader, Origin: `http://${listener.hostHeader}` }
+      : { Host: '127.0.0.1' };
+  return {
+    endpoint: address,
+    listener,
+    request: async ({ body, headers, method, path }) => {
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          // oxlint-disable-next-line no-await-in-loop -- sequential by design: retry after a wait
+          return await exchange(target, method, path, { ...headers, ...fixed }, body, timeoutMs);
+        } catch (cause) {
+          if (!neverConnected(cause) || attempt >= retries) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            const message = `Caddy admin ${method} ${path} at ${address}: ${reason}`;
+            throw neverConnected(cause) ? new CaddyUnreachableError(message) : new Error(message);
+          }
+          // oxlint-disable-next-line no-await-in-loop -- the wait between attempts
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    },
+  };
+};

package/src/caddy/providers.test.ts

@@ -0,0 +1,244 @@
+/**
+ * The Alchemy wiring: the provider built as a Layer over a fake admin API, its handlers called the
+ * way the engine calls them; caddyWithFile's registration; and the barrel, the public API.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Output from 'alchemy/Output';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { caddyAdminLayer } from './admin.ts';
+import { CaddyConfig, CaddyConfigProvider } from './config.ts';
+import { type FakeCaddy, fakeCaddy } from './fake-caddy.ts';
+import * as barrel from './index.ts';
+import { localCaddyAdmin } from './local-admin.ts';
+import { caddyWithFile } from './with-file.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+const ids = { fqn: 'stack/caddy', id: 'caddy', instanceId: 'i-1' };
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+/** A handler the provider must define; a missing one fails the test by name. */
+const handler = <F>(name: string, fn: F | undefined): F => {
+  if (fn === undefined) throw new Error(`provider has no ${name} handler`);
+  return fn;
+};
+
+const withProvider = <A>(
+  use: (p: Effect.Success<typeof CaddyConfig.Provider>) => Effect.Effect<A, unknown>,
+  address?: string,
+) => {
+  // ★ A Caddy on its default :2019 behind a forward, as in config-lifecycle.test.ts.
+  fake =
+    address === undefined
+      ? fakeCaddy({ listenPort: 2019, running: { apps: { legacy: true } } })
+      : undefined;
+  const admin = localCaddyAdmin({
+    address: address ?? (fake as FakeCaddy).address,
+    hostHeader: '127.0.0.1:2019',
+    retries: 0,
+  });
+  return Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* use(yield* CaddyConfig.Provider);
+    }).pipe(Effect.provide(CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin))))),
+  );
+};
+
+describe('CaddyConfigProvider', () => {
+  test('read with no state ADOPTS: plain attributes of the live config, never Unowned', async () => {
+    const probe = await withProvider((provider) =>
+      handler('read', provider.read)({ ...ids, olds: { caddyfile: SITE }, output: undefined }),
+    );
+    expect(Unowned.is(probe)).toBe(false);
+    expect(probe).toMatchObject({ endpoint: fake?.address });
+  });
+
+  test('reconcile applies; delete then sends nothing at all', async () => {
+    await withProvider((provider) =>
+      Effect.gen(function* () {
+        yield* provider.reconcile({
+          ...ids,
+          bindings: [] as never,
+          news: { caddyfile: SITE },
+          olds: undefined,
+          output: undefined,
+          session: undefined as never,
+        });
+        const before = fake?.seen.length;
+        const output = yield* handler(
+          'read',
+          provider.read,
+        )({
+          ...ids,
+          olds: { caddyfile: SITE },
+          output: undefined,
+        });
+        yield* provider.delete({ ...ids, olds: { caddyfile: SITE }, output } as never);
+        // ★ Only the read above talked to Caddy: delete never unloads, never stops.
+        expect(fake?.seen.length).toBe((before ?? 0) + 1);
+      }),
+    );
+  });
+
+  test('diff defers to the engine with no prior output', async () => {
+    const diff = await withProvider((provider) =>
+      handler(
+        'diff',
+        provider.diff,
+      )({
+        ...ids,
+        news: { caddyfile: SITE },
+        olds: { caddyfile: SITE },
+        output: undefined,
+      } as never),
+    );
+    expect(diff).toBeUndefined();
+  });
+
+  test('an unresolved sourceFile still validates the Caddyfile at plan time', async () => {
+    const pending = Effect.succeed('/usr/local/etc/Caddyfile');
+    const output = { configSha256: 'x', endpoint: 'y' };
+    const ok = await withProvider((provider) =>
+      handler(
+        'diff',
+        provider.diff,
+      )({
+        ...ids,
+        news: { caddyfile: SITE, sourceFile: pending },
+        olds: { caddyfile: SITE },
+        output,
+      } as never),
+    );
+    expect(ok).toEqual({ action: 'update' });
+    const bad = withProvider((provider) =>
+      handler(
+        'diff',
+        provider.diff,
+      )({
+        ...ids,
+        news: { caddyfile: 'SYNTAX_ERROR', sourceFile: pending },
+        olds: { caddyfile: SITE },
+        output,
+      } as never),
+    );
+    await expect(bad).rejects.toThrow(/Error during parsing/);
+  });
+});
+
+describe('a Caddy that is down', () => {
+  /** A loopback port that just closed: connecting is refused, nothing is listening. */
+  const closedPort = () => {
+    const server = Bun.serve({ fetch: () => new Response(), hostname: '127.0.0.1', port: 0 });
+    const address = `http://127.0.0.1:${String(server.port)}`;
+    server.stop(true);
+    return address;
+  };
+  const output = { configSha256: 'x', endpoint: 'y' };
+
+  test('does not fail the plan: read finds nothing to adopt, diff plans an update', async () => {
+    const address = closedPort();
+    const probe = await withProvider(
+      (provider) =>
+        handler('read', provider.read)({ ...ids, olds: { caddyfile: SITE }, output: undefined }),
+      address,
+    );
+    expect(probe).toBeUndefined();
+    const diff = await withProvider(
+      (provider) =>
+        handler(
+          'diff',
+          provider.diff,
+        )({ ...ids, news: { caddyfile: SITE }, olds: { caddyfile: SITE }, output } as never),
+      address,
+    );
+    expect(diff).toEqual({ action: 'update' });
+  });
+
+  test('but the apply, which needs Caddy, fails loudly', async () => {
+    const applying = withProvider(
+      (provider) =>
+        provider.reconcile({
+          ...ids,
+          bindings: [] as never,
+          news: { caddyfile: SITE },
+          olds: undefined,
+          output: undefined,
+          session: undefined as never,
+        }),
+      closedPort(),
+    );
+    await expect(applying).rejects.toThrow(/Caddy admin POST \/adapt at http:\/\/127\.0\.0\.1/);
+  });
+
+  test('a bad Caddyfile still fails the plan when Caddy IS up (only unreachability is forgiven)', async () => {
+    const bad = withProvider((provider) =>
+      handler(
+        'diff',
+        provider.diff,
+      )({
+        ...ids,
+        news: { caddyfile: 'SYNTAX_ERROR' },
+        olds: { caddyfile: SITE },
+        output,
+      } as never),
+    );
+    await expect(bad).rejects.toThrow(/Error during parsing/);
+  });
+});
+
+describe('caddyWithFile', () => {
+  const stack = () => ({ actions: {}, bindings: {}, name: 'test', resources: {}, stage: 'test' });
+
+  test('declares the HostFile (retained) and a CaddyConfig ordered after it', async () => {
+    const spec = stack();
+    const { config, file } = await Effect.runPromise(
+      caddyWithFile('caddy', { caddyfile: SITE, path: '/usr/local/etc/Caddyfile' }).pipe(
+        Effect.provideService(Stack, spec as never),
+      ) as Effect.Effect<{ config: unknown; file: unknown }>,
+    );
+    expect(Object.keys(spec.resources).sort()).toEqual(['caddy', 'caddy-file']);
+    const target = config as { Props: { sourceFile: unknown }; RemovalPolicy: string };
+    // ★ An Output of the HostFile, not the literal path: that edge is what writes the file first.
+    expect(Output.isExpr(target.Props.sourceFile)).toBe(true);
+    expect(target.RemovalPolicy).toBe('retain');
+    expect((file as { RemovalPolicy: string }).RemovalPolicy).toBe('retain');
+  });
+
+  test('a literal secret is refused before the HostFile — and its content prop — exist', async () => {
+    const spec = stack();
+    const failure = Effect.runPromise(
+      Effect.flip(
+        caddyWithFile('caddy', {
+          caddyfile: 'dns cloudflare abcdef0123456789',
+          path: '/etc/Caddyfile',
+        }),
+      ).pipe(Effect.provideService(Stack, spec as never)) as Effect.Effect<Error>,
+    );
+    expect((await failure).message).toMatch(/caddyWithFile caddy: line 1/);
+    expect(spec.resources).toEqual({});
+  });
+});
+
+describe('the barrel', () => {
+  test('exports the public API and not the internals', () => {
+    expect(Object.keys(barrel).sort()).toEqual([
+      'CaddyAdminError',
+      'CaddyAdminService',
+      'CaddyConfig',
+      'CaddyConfigProvider',
+      'CaddyUnreachableError',
+      'DEFAULT_ADMIN_ADDRESS',
+      'caddyAdminLayer',
+      'caddyProviders',
+      'caddyWithFile',
+      'localCaddyAdmin',
+    ]);
+  });
+});

package/src/caddy/providers.ts

@@ -0,0 +1,17 @@
+/**
+ * The Caddy provider with its admin transport, as a single layer for a host stack.
+ *
+ *     Layer.mergeAll(caddyProviders(), launchdProviders(), …the stack's other providers)
+ *
+ * ★ launchdProviders() TOO when the stack uses caddyWithFile(): the file is a launchd-subpath
+ *   HostFile, written through that subpath's HostRunner.
+ * ⚠️ The default is localCaddyAdmin(): `http://127.0.0.1:2019`, Caddy's default admin listener.
+ *   Pass another CaddyAdmin for a unix socket, a narrowed `admin { origins }`, or an SSH forward.
+ */
+import * as Layer from 'effect/Layer';
+import { type CaddyAdmin, caddyAdminLayer } from './admin.ts';
+import { CaddyConfigProvider } from './config.ts';
+import { localCaddyAdmin } from './local-admin.ts';
+
+export const caddyProviders = (admin: CaddyAdmin = localCaddyAdmin()) =>
+  CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin)));

package/src/caddy/with-file.ts

@@ -0,0 +1,62 @@
+/**
+ * `caddyWithFile` — one Caddyfile, applied to the running Caddy AND written to the file Caddy
+ * starts from, so a restart keeps it (decision 23: "the file also lands on disk").
+ *
+ * ★ REUSES launchd's HostFile, NOT A SECOND FILE WRITER. The file is an ordinary `Host.File`
+ *   (atomic write, digest diff, symlink refusal, `--adopt` for a file already there); the config is
+ *   a `Caddy.Config` whose `sourceFile` is that HostFile's `path` Output — which is what orders them.
+ *
+ * ⛔ THE ORDER IS FILE, THEN `/load`. The dependency makes Alchemy write the file first, and it is the
+ *   only order that bootstraps: a new host's Caddy launchd job starts from the file, before any
+ *   admin API exists to load into. Its cost, and what bounds it:
+ *   · A Caddyfile that does not ADAPT never reaches disk once the config has state: CaddyConfig's
+ *     diff adapts it at PLAN time and fails the plan. (On the very first deploy the file's path is
+ *     still an Output, Alchemy skips the adoption probe, and the check runs at apply instead.)
+ *   · A Caddyfile that adapts but that Caddy then REFUSES (a port in use, a missing cert file) is
+ *     on disk when `/load` fails. Caddy keeps serving the old config, the deploy fails with Caddy's
+ *     reason — and a RESTART before the fix would load the refused file. Fix and redeploy, or run
+ *     Caddy with `--resume` (docs/caddy.md): it restarts from `autosave.json`, the last config Caddy
+ *     ACCEPTED, and the file is only the first-boot fallback.
+ * ⛔ SECRETS ARE REFUSED HERE, AT DECLARATION, before the HostFile exists: its `content` is a prop
+ *   too, and would carry a literal into state even if the CaddyConfig then refused it.
+ * ★ BOTH RETAIN. Removing this from a stack must not delete the file a restart needs.
+ */
+import * as Effect from 'effect/Effect';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import { HostFile } from '../launchd/host-file.ts';
+import { CaddyConfig } from './config.ts';
+import { configProblems } from './config-form.ts';
+
+export interface CaddyWithFileProps {
+  /** The whole Caddyfile. ⛔ Never a secret — use `{env.NAME}` / `{file./path}` placeholders. */
+  readonly caddyfile: string;
+  /** Absolute path Caddy is started with: `caddy run --config <path> --adapter caddyfile`. */
+  readonly path: string;
+  /** @default 0o644 */
+  readonly mode?: number;
+  readonly owner?: string | number;
+  readonly group?: string | number;
+}
+
+/**
+ * Declare the file (`<id>-file`) and the config (`<id>`). Provide `launchdProviders()` for the
+ * file and `caddyProviders()` for the config.
+ *
+ *     const { config, file } = yield* caddyWithFile('caddy', { caddyfile, path: '/usr/local/etc/Caddyfile' });
+ */
+export const caddyWithFile = (id: string, props: CaddyWithFileProps) =>
+  Effect.gen(function* () {
+    const found = configProblems({ caddyfile: props.caddyfile, sourceFile: props.path });
+    if (found.length > 0) {
+      return yield* Effect.fail(new Error(`caddyWithFile ${id}: ${found.join('; ')}`));
+    }
+    const file = yield* HostFile(`${id}-file`, {
+      content: props.caddyfile,
+      mode: props.mode ?? 0o644,
+      path: props.path,
+      ...(props.owner === undefined ? {} : { owner: props.owner }),
+      ...(props.group === undefined ? {} : { group: props.group }),
+    }).pipe(RemovalPolicy.retain());
+    const config = yield* CaddyConfig(id, { caddyfile: props.caddyfile, sourceFile: file.path });
+    return { config, file };
+  });