@homeflare/alchemy 0.6.0 → 0.8.0

package/src/caddy/config-adopt.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Ownership with no state — decision 2026-09-21: CaddyConfig never adopts silently. The adoption
+ * probe (`read` with no output) and the apply of a create the engine never probed must agree on
+ * what is claimable: the declared config itself, or a Caddy serving nothing. Anything else is
+ * `Unowned` at plan time and refused at apply, unless the deploy runs with `--adopt` — and state
+ * lends authority only over the Caddy it was applied to.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { AdoptPolicy, Unowned } from 'alchemy/AdoptPolicy';
+import { AlchemyContext } from 'alchemy/AlchemyContext';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { type CaddyAdmin, CaddyUnreachableError, caddyAdminLayer } from './admin.ts';
+import { CaddyConfig, CaddyConfigProvider } from './config.ts';
+import { probeLive, reconcileConfig } from './config-lifecycle.ts';
+import { configDigest } from './digest.ts';
+import { type FakeCaddy, fakeDefaultCaddy } from './fake-caddy.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+/** A config someone else loaded: it serves a site, and it is not what the stack declares. */
+const FOREIGN = { apps: { http: { servers: { legacy: { listen: [':80'] } } } } };
+const ids = { fqn: 'stack/caddy', id: 'caddy', instanceId: 'i-1' };
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+const setup = (running?: unknown) => {
+  const made = fakeDefaultCaddy(running);
+  fake = made.caddy;
+  return made;
+};
+
+/** A Caddy already running the declared config — as one started from caddyWithFile's file is. */
+const runningDeclared = () => {
+  const made = setup();
+  made.caddy.running = made.caddy.adapt(SITE);
+  return made;
+};
+
+const loads = (caddy: FakeCaddy) => caddy.seen.filter((call) => call.path === '/load');
+
+describe('the probe: read with no state', () => {
+  test('a Caddy already running the declared config is ours — adopting it changes nothing', async () => {
+    const { admin, caddy } = runningDeclared();
+    const probe = await probeLive(admin, SITE);
+    expect(probe).toMatchObject({ attributes: { configSha256: configDigest(caddy.adapt(SITE)) } });
+    expect(probe?.ours).toBe(true);
+    expect(loads(caddy)).toHaveLength(0);
+  });
+
+  test('a Caddy running any other config is not ours', async () => {
+    const { admin } = setup(FOREIGN);
+    const probe = await probeLive(admin, SITE, '/usr/local/etc/Caddyfile');
+    expect(probe?.ours).toBe(false);
+    expect(probe?.unchecked).toBeUndefined();
+    expect(probe?.attributes).toEqual({
+      configSha256: configDigest(FOREIGN),
+      endpoint: fake?.address ?? '',
+      sourceFile: '/usr/local/etc/Caddyfile',
+    });
+  });
+
+  test.each([
+    ['no config at all', null],
+    ['only an admin block', { admin: { listen: 'localhost:2019' } }],
+  ])('a Caddy serving nothing (%s) reads as absent: a create', async (_, running) => {
+    const { admin } = setup(running);
+    expect(await probeLive(admin, SITE)).toBeUndefined();
+  });
+
+  test.each([
+    ['does not adapt', 'SYNTAX_ERROR', /Error during parsing/],
+    ['is not plain text (a stripped Output)', undefined, /not plain text/],
+  ])('a declaration that %s is not ours — and never fails the read', async (_, text, reason) => {
+    // ⛔ The engine replays this read with an interrupted create's props: a throw here would fail
+    //   every later plan, the one carrying the fix included.
+    const { admin } = setup(FOREIGN);
+    const probe = await probeLive(admin, text);
+    expect(probe?.ours).toBe(false);
+    expect(probe?.unchecked).toMatch(reason);
+  });
+
+  test('Caddy vanishing mid-probe stays "no Caddy", never "not ours"', async () => {
+    const { admin } = setup(FOREIGN);
+    const flaky: CaddyAdmin = {
+      ...admin,
+      request: (call) =>
+        call.path === '/adapt'
+          ? Promise.reject(new CaddyUnreachableError('gone'))
+          : admin.request(call),
+    };
+    await expect(probeLive(flaky, SITE)).rejects.toThrow('gone');
+  });
+});
+
+/** A create the engine never probed, or state from another endpoint (config.ts decides which). */
+describe('the apply without authority over the running config', () => {
+  test('without authority, a config the stack cannot claim is refused before any load', async () => {
+    const { admin, caddy } = setup(FOREIGN);
+    await expect(reconcileConfig(admin, { caddyfile: SITE }, { takeOver: false })).rejects.toThrow(
+      /which this stack did not load.*Deploy with --adopt/,
+    );
+    expect(loads(caddy)).toHaveLength(0);
+    expect(caddy.running).toEqual(FOREIGN);
+  });
+
+  test('the declared config already running is taken as it is — no load', async () => {
+    const { admin, caddy } = runningDeclared();
+    const applied = await reconcileConfig(admin, { caddyfile: SITE }, { takeOver: false });
+    expect(applied.loaded).toBe(false);
+    expect(loads(caddy)).toHaveLength(0);
+  });
+
+  test('a Caddy serving nothing is loaded — there is nothing to take over', async () => {
+    const { admin, caddy } = setup();
+    const applied = await reconcileConfig(admin, { caddyfile: SITE }, { takeOver: false });
+    expect(applied.loaded).toBe(true);
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+
+  test('the config the state last stored is known — the same Caddy at a new endpoint', async () => {
+    const { admin } = setup(FOREIGN);
+    const authority = { stored: configDigest(FOREIGN), takeOver: false };
+    expect((await reconcileConfig(admin, { caddyfile: SITE }, authority)).loaded).toBe(true);
+  });
+
+  test('with authority, the foreign config is replaced', async () => {
+    const { admin, caddy } = setup(FOREIGN);
+    const applied = await reconcileConfig(admin, { caddyfile: SITE }, { takeOver: true });
+    expect(applied.loaded).toBe(true);
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+});
+
+type Deploy = { readonly adopt?: boolean; readonly contextAdopt?: boolean };
+
+/** The provider over `admin`, run under the services a deploy provides (the CLI's `--adopt`). */
+const withProvider = <A>(
+  admin: CaddyAdmin,
+  deploy: Deploy,
+  use: (p: Effect.Success<typeof CaddyConfig.Provider>) => Effect.Effect<A, unknown>,
+) => {
+  let program = Effect.gen(function* () {
+    return yield* use(yield* CaddyConfig.Provider);
+  }).pipe(Effect.provide(CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin)))));
+  if (deploy.adopt !== undefined) {
+    program = program.pipe(Effect.provideService(AdoptPolicy, deploy.adopt));
+  }
+  if (deploy.contextAdopt !== undefined) {
+    const context = { adopt: deploy.contextAdopt, dev: false, dotAlchemy: '.alchemy' };
+    program = program.pipe(Effect.provideService(AlchemyContext, context));
+  }
+  return Effect.runPromise(program);
+};
+
+const read = (admin: CaddyAdmin, caddyfile: unknown, output?: object) =>
+  withProvider(admin, {}, (provider) => {
+    if (provider.read === undefined) throw new Error('provider has no read handler');
+    return provider.read({ ...ids, olds: { caddyfile } as never, output: output as never });
+  });
+
+/** Apply, then check that exactly the expected loads reached Caddy — or none, and why. */
+const expectApply = async (applying: Promise<unknown>, caddy: FakeCaddy, loaded: boolean) => {
+  if (loaded) await applying;
+  else await expect(applying).rejects.toThrow(/Deploy with --adopt/);
+  expect(loads(caddy)).toHaveLength(loaded ? 1 : 0);
+};
+
+const reconcile = (admin: CaddyAdmin, deploy: Deploy, output?: object) =>
+  withProvider(admin, deploy, (provider) =>
+    provider.reconcile({
+      ...ids,
+      bindings: [] as never,
+      news: { caddyfile: SITE },
+      olds: undefined,
+      output: output as never,
+      session: undefined as never,
+    }),
+  );
+
+describe('CaddyConfigProvider', () => {
+  test('read: Unowned with no state, plain with state, plain when it is the declared config', async () => {
+    const { admin, caddy } = setup(FOREIGN);
+    const probe = await read(admin, SITE);
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ configSha256: configDigest(FOREIGN) });
+    const owned = await read(admin, SITE, { configSha256: 'stored', endpoint: caddy.address });
+    expect(owned).toBeDefined();
+    expect(Unowned.is(owned)).toBe(false);
+    caddy.running = caddy.adapt(SITE);
+    const same = await read(admin, SITE);
+    expect(same).toBeDefined();
+    expect(Unowned.is(same)).toBe(false);
+  });
+
+  test('read with no state: nothing served is a create; an unreadable declaration is Unowned', async () => {
+    expect(await read(setup().admin, SITE)).toBeUndefined();
+    fake?.stop();
+    const { admin } = setup(FOREIGN);
+    expect(Unowned.is(await read(admin, 'SYNTAX_ERROR'))).toBe(true);
+    expect(Unowned.is(await read(admin, {}))).toBe(true);
+  });
+
+  test.each([
+    ['no adopt setting at all', {}, false],
+    ['AdoptPolicy off', { adopt: false }, false],
+    ['--adopt (AdoptPolicy)', { adopt: true }, true],
+    ['--adopt reaching only AlchemyContext', { contextAdopt: true }, true],
+    ['AdoptPolicy off over AlchemyContext on', { adopt: false, contextAdopt: true }, false],
+  ] as const)('reconcile with no state, %s', async (_, deploy, loaded) => {
+    const { admin, caddy } = setup(FOREIGN);
+    await expectApply(reconcile(admin, deploy), caddy, loaded);
+  });
+
+  test('reconcile with state for this Caddy loads over anything, without --adopt', async () => {
+    // ★ An update correcting drift (a hand edit since the stored digest), or an adopted create.
+    const { admin, caddy } = setup(FOREIGN);
+    const output = { configSha256: 'before-a-hand-edit', endpoint: caddy.address };
+    await expectApply(reconcile(admin, {}, output), caddy, true);
+  });
+
+  test.each([
+    ['a config it never stored, without --adopt', 'stored-elsewhere', {}, false],
+    ['a config it never stored, with --adopt', 'stored-elsewhere', { adopt: true }, true],
+    ['the config it last stored (the same Caddy, renamed)', configDigest(FOREIGN), {}, true],
+  ] as const)('reconcile with state from another endpoint: %s', async (_, sha, deploy, loaded) => {
+    // ⛔ State vouches for the Caddy it was applied to — not for whatever the transport now reaches.
+    const { admin, caddy } = setup(FOREIGN);
+    const output = { configSha256: sha, endpoint: 'unix:///run/elsewhere.sock' };
+    await expectApply(reconcile(admin, deploy, output), caddy, loaded);
+  });
+});

package/src/caddy/config-form.ts

@@ -0,0 +1,64 @@
+/**
+ * CaddyConfig's props, attributes and validation — the pure half of the provider.
+ *
+ * ⛔ `caddyfile` IS NEVER A SECRET. Alchemy stores props unencrypted, so the whole Caddyfile sits in
+ *   the state store and in every plan diff. Secrets reach Caddy as runtime placeholders
+ *   (`{env.NAME}`, `{file./path}`) resolved from files a secret renderer writes — see
+ *   caddyfile-tripwire.ts, which refuses the obvious literals.
+ */
+import { caddyfileSecretProblems } from './caddyfile-tripwire.ts';
+
+export interface CaddyConfigProps {
+  /**
+   * The whole Caddyfile. Applied with `POST /load` (Content-Type `text/caddyfile`); it REPLACES the
+   * running config. ⛔ Never a secret. ⚠️ `import` paths resolve against Caddy's working directory
+   * (the API adapts with no file name), so keep them absolute.
+   */
+  caddyfile: string;
+  /**
+   * The file Caddy was started with (`caddy run --config <this>`), when the same Caddyfile is also
+   * written there — `caddyWithFile()` sets it from its HostFile. Sent as
+   * `Caddy-Config-Source-File` so a load keeps Caddy's SIGUSR1 reload-from-file working.
+   */
+  sourceFile?: string;
+}
+
+export interface CaddyConfigAttributes {
+  /**
+   * SHA-256 of the ADAPTED JSON Caddy reported after the last apply (digest.ts canonical form) —
+   * never the config itself. Drift is the live config hashing to anything else.
+   */
+  configSha256: string;
+  /** The admin endpoint the config was applied through (no credential; the API has none). */
+  endpoint: string;
+  /** The `sourceFile` prop as applied. */
+  sourceFile?: string;
+}
+
+const absoluteNormalised = (path: string): boolean =>
+  path.startsWith('/') &&
+  !path.endsWith('/') &&
+  !path.includes('\x00') &&
+  !path
+    .split('/')
+    .slice(1)
+    .some((part) => part === '' || part === '.' || part === '..');
+
+export const configProblems = (props: CaddyConfigProps): string[] => {
+  const found: string[] = [];
+  /**
+   * ⛔ AN EMPTY CADDYFILE IS NOT "NOTHING TO DO". It adapts to a config with no apps, and loading
+   *   it stops every server Caddy runs — every site down, on a templating bug that rendered ''.
+   *   Emptying Caddy is a deliberate act for a person at the admin API, not a declaration.
+   *   Text that is not empty but serves nothing (only comments, only global options) is caught
+   *   after `/adapt`, where it shows as no apps (config-lifecycle.ts servesNothing).
+   */
+  if (props.caddyfile.trim() === '') {
+    found.push('caddyfile is empty — loading it would stop every site Caddy serves');
+  }
+  if (props.sourceFile !== undefined && !absoluteNormalised(props.sourceFile)) {
+    found.push('sourceFile must be an absolute, normalised path');
+  }
+  found.push(...caddyfileSecretProblems(props.caddyfile));
+  return found;
+};

package/src/caddy/config-lifecycle.test.ts

@@ -0,0 +1,196 @@
+/**
+ * CaddyConfig's lifecycle against the fake admin API (fake-caddy.ts): apply, a refused config
+ * rolled back, drift, and the refusals that must happen before anything is sent.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import type { CaddyAdmin } from './admin.ts';
+import { type FakeCaddy, fakeDefaultCaddy } from './fake-caddy.ts';
+import { configDigest } from './digest.ts';
+import { diffConfig, readLive, reconcileConfig } from './config-lifecycle.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+const OTHER = 'www.example.com respond <hello> & bye';
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+/** A Caddy on its default :2019 (fake-caddy.ts fakeDefaultCaddy), stopped after each test. */
+const setup = (running?: unknown) => {
+  const made = fakeDefaultCaddy(running);
+  fake = made.caddy;
+  return made;
+};
+
+/** ★ These are the resource's own applies (it has state); config-adopt.test.ts covers a create. */
+const OWNED = { takeOver: true } as const;
+
+const loads = (caddy: FakeCaddy) => caddy.seen.filter((call) => call.path === '/load');
+
+describe('apply', () => {
+  test('loads the Caddyfile, reads it back, and stores the digest Caddy reports', async () => {
+    const { admin, caddy } = setup();
+    const applied = await reconcileConfig(admin, { caddyfile: OTHER }, OWNED);
+    expect(applied.loaded).toBe(true);
+    // ★ The fake's /config/ is sorted and escaped differently from /adapt; the digests still agree.
+    expect(applied.attributes.configSha256).toBe(configDigest(caddy.adapt(OTHER)));
+    expect(applied.attributes.endpoint).toBe(caddy.address);
+    const [load] = loads(caddy);
+    expect(load?.headers.get('content-type')).toBe('text/caddyfile');
+    expect(load?.body).toBe(OTHER);
+  });
+
+  test('a Caddy already running this config is not reloaded', async () => {
+    const { admin, caddy } = setup();
+    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    const again = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    expect(again.loaded).toBe(false);
+    expect(loads(caddy)).toHaveLength(1);
+  });
+
+  test('sourceFile rides as the headers `caddy reload` sends, and lands in the attributes', async () => {
+    const { admin, caddy } = setup();
+    const path = '/usr/local/etc/Caddyfile';
+    const applied = await reconcileConfig(admin, { caddyfile: SITE, sourceFile: path }, OWNED);
+    expect(loads(caddy)[0]?.headers.get('caddy-config-source-file')).toBe(path);
+    expect(loads(caddy)[0]?.headers.get('caddy-config-source-adapter')).toBe('caddyfile');
+    expect(applied.attributes.sourceFile).toBe(path);
+  });
+
+  test('adapter warnings are returned, not refused', async () => {
+    const { admin } = setup();
+    const applied = await reconcileConfig(admin, { caddyfile: `${SITE}\t` }, OWNED);
+    expect(applied.warnings).toEqual(['Caddyfile:1: Caddyfile input is not formatted']);
+  });
+});
+
+describe('a config Caddy refuses', () => {
+  test('surfaces Caddy’s reason and confirms the previous config is still running', async () => {
+    const { admin, caddy } = setup();
+    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    const before = caddy.running;
+    await expect(
+      reconcileConfig(admin, { caddyfile: `${SITE}\nPROVISION_ERROR` }, OWNED),
+    ).rejects.toThrow(/address already in use.*kept the previous config/);
+    expect(caddy.running).toEqual(before);
+  });
+
+  test('a refusal that came back as a 200 (warnings first) is still a refusal', async () => {
+    const { admin, caddy } = setup();
+    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    await expect(
+      reconcileConfig(admin, { caddyfile: `${SITE}\t\nPROVISION_ERROR` }, OWNED),
+    ).rejects.toThrow(/→ 200: loading config.*error in a 200 body.*kept the previous/);
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+
+  test('a load answered 200 that Caddy did not apply fails the deploy (the read-back)', async () => {
+    const { admin, caddy } = setup();
+    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    // ⚠️ A concurrent writer, or a 200 that carried no change: state must not record OTHER.
+    const swallowing: CaddyAdmin = {
+      ...admin,
+      request: (call) =>
+        call.path === '/load' ? Promise.resolve({ body: '', status: 200 }) : admin.request(call),
+    };
+    await expect(reconcileConfig(swallowing, { caddyfile: OTHER }, OWNED)).rejects.toThrow(
+      /after the load Caddy runs config \w+, not the \w+ this Caddyfile adapts to/,
+    );
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+
+  test('a Caddyfile that does not adapt is refused before any load', async () => {
+    const { admin, caddy } = setup();
+    await expect(reconcileConfig(admin, { caddyfile: 'SYNTAX_ERROR' }, OWNED)).rejects.toThrow(
+      /\/adapt → 400: Caddyfile:1 - Error during parsing/,
+    );
+    expect(loads(caddy)).toHaveLength(0);
+  });
+});
+
+describe('refused before anything is sent', () => {
+  test.each([
+    ['a literal token', 'example.com {\n  dns cloudflare abcdef0123456789\n}'],
+    ['an empty Caddyfile', '  \n'],
+  ])('%s', async (_, caddyfile) => {
+    const { admin, caddy } = setup();
+    await expect(reconcileConfig(admin, { caddyfile }, OWNED)).rejects.toThrow(
+      /Caddy\.Config at http/,
+    );
+    expect(caddy.seen).toHaveLength(0);
+  });
+
+  test.each([
+    ['only a comment', '# the template rendered nothing'],
+    ['only global options', 'admin localhost:2019'],
+  ])('a Caddyfile of %s adapts to no apps, and is never loaded', async (_, caddyfile) => {
+    const { admin, caddy } = setup();
+    await expect(reconcileConfig(admin, { caddyfile }, OWNED)).rejects.toThrow(/adapts to no apps/);
+    expect(loads(caddy)).toHaveLength(0);
+  });
+
+  test('a Caddyfile that would turn the admin API off is never loaded', async () => {
+    const { admin, caddy } = setup();
+    await expect(
+      reconcileConfig(admin, { caddyfile: `admin off\n${SITE}` }, OWNED),
+    ).rejects.toThrow(/admin off/);
+    expect(loads(caddy)).toHaveLength(0);
+  });
+});
+
+describe('drift', () => {
+  const applied = async () => {
+    const { admin, caddy } = setup();
+    const { attributes } = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    return { admin, attributes, caddy };
+  };
+
+  test('converged: declared, live and stored agree → noop', async () => {
+    const { admin, attributes } = await applied();
+    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'noop' });
+  });
+
+  test('a changed declaration → update', async () => {
+    const { admin, attributes } = await applied();
+    expect(await diffConfig(admin, { caddyfile: OTHER }, attributes)).toEqual({ action: 'update' });
+  });
+
+  test('a hand edit through the API → update, and the apply puts the declaration back', async () => {
+    const { admin, attributes, caddy } = await applied();
+    caddy.running = { apps: { http: { servers: {} } } };
+    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'update' });
+    const again = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    expect(again.attributes.configSha256).toBe(attributes.configSha256);
+  });
+
+  test('a restart with a different file → update', async () => {
+    const { admin, attributes, caddy } = await applied();
+    caddy.running = JSON.parse(JSON.stringify(caddy.adapt(OTHER))) as unknown;
+    expect((await readLive(admin)).configSha256).not.toBe(attributes.configSha256);
+    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'update' });
+  });
+
+  test('state that lags the live config → update, so the stored digest is refreshed', async () => {
+    const { admin, attributes } = await applied();
+    const stale = { ...attributes, configSha256: configDigest({ apps: { before: true } }) };
+    expect(await diffConfig(admin, { caddyfile: SITE }, stale)).toEqual({ action: 'update' });
+  });
+
+  test('the transport now reaches Caddy at another endpoint → update (load there)', async () => {
+    const { admin, attributes } = await applied();
+    const moved = { ...attributes, endpoint: 'unix:///run/caddy/admin.sock' };
+    expect(await diffConfig(admin, { caddyfile: SITE }, moved)).toEqual({ action: 'update' });
+  });
+
+  test('a new sourceFile → update, so state records the file this config mirrors', async () => {
+    const { admin, attributes } = await applied();
+    const diff = await diffConfig(
+      admin,
+      { caddyfile: SITE, sourceFile: '/etc/Caddyfile' },
+      attributes,
+    );
+    expect(diff).toEqual({ action: 'update' });
+  });
+});