@homeflare/alchemy 0.37.2 → 0.37.4

package/src/proxmox/distilled-pbs.test.ts

@@ -0,0 +1,87 @@
+/** The real PBS SDK protocol: correct credentials, bounded attempts, and no implicit re-send. */
+import { expect, test } from 'bun:test';
+import * as config from '@distilled.cloud/proxmox-backup/config';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { PbsTarget, PveCredential } from './credentials.ts';
+import { runPbsWith } from './distilled-pbs.ts';
+
+const TARGET: PbsTarget = { api: 'https://pbs.invalid:8007', mount: 'pbs-test', scheme: 'pbs' };
+const CREDENTIAL: PveCredential = {
+  leaseSeconds: 300,
+  secret: 'fake-secret-not-real',
+  tokenId: 'test@pbs!fake',
+};
+
+const transport = (answer: (request: Request) => Response | Promise<Response>) => {
+  const stub = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) =>
+    Promise.resolve(
+      answer(
+        input instanceof Request ? new Request(input, init) : new Request(String(input), init),
+      ),
+    );
+  return FetchHttpClient.layer.pipe(
+    Layer.provideMerge(
+      Layer.succeed(
+        FetchHttpClient.Fetch,
+        Object.assign(stub, { preconnect: globalThis.fetch.preconnect }),
+      ),
+    ),
+  );
+};
+
+test('the PBS SDK builds its own colon-separated authorization and normalizes the API root', async () => {
+  let called = false;
+  const layer = transport((request) => {
+    called = true;
+    expect(request.url).toBe(
+      'https://pbs.invalid:8007/api2/json/config/notifications/matchers/pager',
+    );
+    expect(request.headers.get('authorization')).toBe(
+      'PBSAPIToken=test@pbs!fake:fake-secret-not-real',
+    );
+    return Response.json({ data: { name: 'pager', target: ['mail-to-root'] } });
+  });
+  const row = await Effect.runPromise(
+    runPbsWith(TARGET, CREDENTIAL, config.getConfigNotificationMatcher({ name: 'pager' })).pipe(
+      Effect.provide(layer),
+    ),
+  );
+  expect(called).toBe(true);
+  expect(row.target).toEqual(['mail-to-root']);
+});
+
+test('a typed HTTP failure is returned once, without the SDK default retry', async () => {
+  let calls = 0;
+  const layer = transport(() => {
+    calls += 1;
+    return Response.json({ message: 'unavailable' }, { status: 503 });
+  });
+  const error = await Effect.runPromise(
+    runPbsWith(TARGET, CREDENTIAL, config.deleteConfigNotificationMatcher({ name: 'pager' })).pipe(
+      Effect.flip,
+      Effect.provide(layer),
+    ),
+  );
+  expect(error).toMatchObject({ _tag: 'ServiceUnavailable' });
+  expect(calls).toBe(1);
+});
+
+test('a sent write that never answers is bounded and never repeated', async () => {
+  let calls = 0;
+  const layer = transport(() => {
+    calls += 1;
+    return new Promise<Response>(() => {});
+  });
+  const error = await Effect.runPromise(
+    runPbsWith(
+      TARGET,
+      CREDENTIAL,
+      config.deleteConfigNotificationMatcher({ name: 'pager' }),
+      '20 millis',
+    ).pipe(Effect.flip, Effect.provide(layer)),
+  );
+  expect(error).toMatchObject({ _tag: 'TimeoutError' });
+  expect(calls).toBe(1);
+});

package/src/proxmox/distilled-pbs.ts

@@ -0,0 +1,50 @@
+/**
+ * PBS 4.2.6-1 operations through the distilled SDK, with the existing OpenBao leases.
+ *
+ * ⛔ PBS IS A SINGLE HOST, NOT A PVE CLUSTER. Its Credentials layer supplies the
+ *   `PBSAPIToken=id:secret` scheme; running a PBS operation through runPve would send PVE's
+ *   different header. Nothing here invents another host or retries a possibly completed write.
+ * ★ Retry.none also disables distilled's default transient-error retries within that host.
+ *   MEMBER_TIMEOUT bounds the one attempt, just as it bounds each PVE member attempt.
+ */
+import { credentials } from '@distilled.cloud/proxmox-backup/Credentials';
+import type { ProxmoxBackupOpContext } from '@distilled.cloud/proxmox-backup/Protocol';
+import * as Retry from '@distilled.cloud/proxmox-backup/Retry';
+import type * as Cause from 'effect/Cause';
+import type * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { PveCredentialDenied } from './credential-errors.ts';
+import type { PbsTarget, PveCredential, PveRole } from './credentials.ts';
+import { leased } from './lease-cache.ts';
+import { MEMBER_TIMEOUT } from './members.ts';
+
+/** An already-held lease, also used by offline protocol tests. Production uses the default bound. */
+export const runPbsWith = <A, E>(
+  target: PbsTarget,
+  credential: PveCredential,
+  op: Effect.Effect<A, E, ProxmoxBackupOpContext>,
+  timeout: Duration.Input = MEMBER_TIMEOUT,
+): Effect.Effect<A, E | Cause.TimeoutError, HttpClient.HttpClient> =>
+  op.pipe(
+    Retry.none,
+    Effect.provide(
+      credentials({
+        baseUrl: target.api,
+        secret: credential.secret,
+        tokenId: credential.tokenId,
+      }),
+    ),
+    Effect.timeout(timeout),
+  );
+
+/** Preserve lease sharing and expose credential refusal and SDK error tags unchanged. */
+export const runPbs = <A, E>(
+  target: PbsTarget,
+  role: PveRole,
+  op: Effect.Effect<A, E, ProxmoxBackupOpContext>,
+): Effect.Effect<A, E | Cause.TimeoutError | PveCredentialDenied | Error, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const credential = yield* leased(target, role);
+    return yield* runPbsWith(target, credential, op);
+  });

package/src/proxmox/fake-pbs-jobs.ts

@@ -0,0 +1,99 @@
+/** Test-only PBS 4.2.6-1 wire fixture. Every HTTP request is intercepted; no live credentials. */
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { PbsTarget } from './credentials.ts';
+
+export const PBS_JOBS_TARGET: PbsTarget = {
+  api: 'https://pbs.test:8007/api2/json',
+  mount: 'pbs-test',
+  scheme: 'pbs',
+};
+
+const sections: Record<string, string> = {
+  datastore: 'datastore',
+  prune: 'prune',
+  sync: 'sync',
+  verify: 'verification',
+};
+const numbers =
+  /^(keep-(daily|hourly|last|monthly|weekly|yearly)|max-depth|outdated-after|transfer-last)$/;
+const booleans = /^(disable|ignore-verified|remove-vanished|verified-only|verify-new)$/;
+
+type Write = { method: string; path: string; form: Record<string, string> };
+
+export const fakePbsJobs = () => {
+  const rows = new Map<string, Record<string, unknown>>();
+  const writes: Write[] = [];
+  const calls: { method: string; path: string }[] = [];
+  let failure: { status: number; body: unknown } | undefined;
+  let deleteFailure: { status: number; body: unknown } | undefined;
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      return Response.json({
+        data: { secret: 'fake-secret-not-real', token_id: 'test@pbs!fake' },
+        lease_duration: 0,
+      });
+    }
+    const path = decodeURIComponent(url.pathname.replace('/api2/json/', ''));
+    calls.push({ method: request.method, path });
+    if (request.method === 'GET' && failure !== undefined) {
+      return Response.json(failure.body, { status: failure.status });
+    }
+    const parts = path.split('/');
+    const family = parts[1] ?? '';
+    const id = parts[2] ?? '';
+    const row = rows.get(path);
+    if (request.method === 'GET') {
+      // ★ Measured live 2026-09-24: these four missing sections are plain-text HTTP400.
+      return row === undefined
+        ? new Response(`no such ${sections[family]} '${id}'`, { status: 400 })
+        : Response.json({ data: row });
+    }
+    const form = Object.fromEntries(new URLSearchParams(await request.text()));
+    writes.push({ method: request.method, path, form });
+    if (request.method === 'DELETE') {
+      if (deleteFailure !== undefined) {
+        return Response.json(deleteFailure.body, { status: deleteFailure.status });
+      }
+      rows.delete(path);
+      return Response.json({ data: family === 'datastore' ? 'UPID:fake:delete' : null });
+    }
+    const key = request.method === 'POST' ? `${path}/${form['id'] ?? form['name']}` : path;
+    const after = { ...rows.get(key) };
+    for (const [name, value] of Object.entries(form)) {
+      after[name] = numbers.test(name)
+        ? Number(value)
+        : booleans.test(name)
+          ? value === '1'
+          : value;
+    }
+    rows.set(key, after);
+    // ★ Pinned schema: create datastore is Unit/null; DELETE alone yields a UPID.
+    return Response.json({ data: null });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    rows,
+    writes,
+    calls,
+    failRead: (status: number, body: unknown) => {
+      failure = { status, body };
+    },
+    failDelete: (status: number, body: unknown) => {
+      deleteFailure = { status, body };
+    },
+    reset: () => {
+      rows.clear();
+      calls.length = 0;
+      writes.length = 0;
+      failure = undefined;
+      deleteFailure = undefined;
+    },
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};

package/src/proxmox/fake-pbs-notify.ts

@@ -83,7 +83,10 @@ export const fakeNotify = (
     const { deletes, fields } = body(call);
     if (call.method === 'GET') {
       const object = objects.get(path);
-      return object === undefined ? undefined : withSecretsBlanked(path, object, secrets);
+      // SDK reads require the resource shape: data:null is malformed, not evidence of absence.
+      return object === undefined
+        ? Response.json({ message: 'not found' }, { status: 404 })
+        : withSecretsBlanked(path, object, secrets);
     }
     if (call.method === 'DELETE') {
       objects.delete(path);

package/src/proxmox/fake-pve.ts

@@ -35,7 +35,7 @@ export interface PveCall {
   readonly pairs: readonly (readonly [string, string])[];
 }
 
-/** Answers one call with its `data`; `undefined` is PVE's `{"data": null}`. */
+/** Answers with `data`, or an explicit Response for SDK error fixtures; undefined is data:null. */
 export type PveAnswer = (call: PveCall) => unknown;
 
 export interface FakePve {
@@ -69,7 +69,8 @@ export const fakePve = (answer: PveAnswer): FakePve => {
       path,
     };
     calls.push(call);
-    return Response.json({ data: answer(call) ?? null });
+    const value = answer(call);
+    return value instanceof Response ? value : Response.json({ data: value ?? null });
   };
   // ⚠️ `typeof fetch` carries `preconnect` on bun's lib — client.test.ts has the note.
   const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });

package/src/proxmox/live-core-fixtures.ts

@@ -0,0 +1,126 @@
+/** Test-only declarations and vendor-shaped responses for the three migrated PVE families. */
+import type * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { type FakeEngine, engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxBackupJob, ProxmoxBackupJobProvider } from './backup-job.ts';
+import { deleteBackupJob, readBackupJob } from './backup-job-distilled.ts';
+import { FAKE_TARGET, type FakePve } from './fake-pve.ts';
+import { ProxmoxMetricServer, ProxmoxMetricServerProvider } from './metric-server.ts';
+import { deleteMetricServer, readMetricServer } from './metric-server-distilled.ts';
+import { ProxmoxPool, ProxmoxPoolProvider, deletePool, readPool } from './pool.ts';
+
+export const poolProps = { poolid: 'lab', comment: 'managed', target: FAKE_TARGET };
+export const backupProps = {
+  id: 'nightly',
+  schedule: '02:00',
+  vmid: [103, 101],
+  'prune-backups': 'keep-weekly=4,keep-daily=7',
+  target: FAKE_TARGET,
+};
+export const metricProps = {
+  id: 'metrics',
+  type: 'influxdb' as const,
+  server: 'metrics.test',
+  port: 8086,
+  target: FAKE_TARGET,
+};
+
+export interface CoreCase {
+  name: string;
+  path: string;
+  declare: () => Effect.Effect<unknown, never, unknown>;
+  engine: (fake: FakePve) => FakeEngine;
+  read: () => Effect.Effect<unknown, unknown, HttpClient.HttpClient>;
+  remove: () => Effect.Effect<unknown, unknown, HttpClient.HttpClient>;
+  live: Record<string, unknown>;
+  drift: Record<string, unknown>;
+  missing: () => Response;
+  createPath: string;
+  /** Actual form fields, including defaults, without SDK identifier spelling leaking onto wire. */
+  createForm: Record<string, string>;
+}
+export const coreCases: CoreCase[] = [
+  {
+    name: 'Pool',
+    path: 'pools/lab',
+    createPath: 'pools',
+    declare: () => ProxmoxPool('row', poolProps),
+    engine: (fake) => engineOver(ProxmoxPoolProvider().pipe(Layer.provideMerge(fake.layer))),
+    read: () => readPool(poolProps),
+    remove: () => deletePool(poolProps),
+    live: { comment: 'managed', members: [] },
+    drift: { comment: 'old', members: [] },
+    missing: () =>
+      Response.json({ message: "pool 'lab' does not exist\n", data: null }, { status: 500 }),
+    createForm: { poolid: 'lab', comment: 'managed' },
+  },
+  {
+    name: 'BackupJob',
+    path: 'cluster/backup/nightly',
+    createPath: 'cluster/backup',
+    declare: () => ProxmoxBackupJob('row', backupProps),
+    engine: (fake) => engineOver(ProxmoxBackupJobProvider().pipe(Layer.provideMerge(fake.layer))),
+    read: () => readBackupJob(backupProps),
+    remove: () => deleteBackupJob(backupProps),
+    live: {
+      id: 'nightly',
+      schedule: '02:00',
+      vmid: '101,103',
+      'next-run': 987654,
+      'prune-backups': { 'keep-daily': 7, 'keep-weekly': 4 },
+      compress: 'zstd',
+      mailto: 'operator.invalid',
+    },
+    drift: {
+      id: 'nightly',
+      schedule: '03:00',
+      vmid: '101,103',
+      'prune-backups': { 'keep-daily': 7, 'keep-weekly': 4 },
+    },
+    missing: () =>
+      Response.json(
+        {
+          message: 'Parameter verification failed.\n',
+          errors: { id: "No such job 'nightly'" },
+          data: null,
+        },
+        { status: 400 },
+      ),
+    createForm: {
+      id: 'nightly',
+      schedule: '02:00',
+      vmid: '101,103',
+      all: '0',
+      enabled: '1',
+      mode: 'snapshot',
+      'notification-mode': 'auto',
+      'repeat-missed': '0',
+      'prune-backups': 'keep-weekly=4,keep-daily=7',
+    },
+  },
+  {
+    name: 'MetricServer',
+    path: 'cluster/metrics/server/metrics',
+    createPath: 'cluster/metrics/server/metrics',
+    declare: () => ProxmoxMetricServer('row', metricProps),
+    engine: (fake) =>
+      engineOver(ProxmoxMetricServerProvider().pipe(Layer.provideMerge(fake.layer))),
+    read: () => readMetricServer(metricProps),
+    remove: () => deleteMetricServer(metricProps),
+    live: { type: 'influxdb', server: 'metrics.test', port: 8086, token: 'fake-not-a-secret' },
+    drift: { type: 'influxdb', server: 'old.test', port: 8086, token: 'fake-not-a-secret' },
+    missing: () =>
+      Response.json(
+        { message: "status server entry 'metrics' does not exist\n", data: null },
+        { status: 500 },
+      ),
+    createForm: {
+      type: 'influxdb',
+      server: 'metrics.test',
+      port: '8086',
+      disable: '0',
+      'verify-certificate': '1',
+    },
+  },
+];

package/src/proxmox/live-core-lifecycle.test.ts

@@ -0,0 +1,115 @@
+/** Real Alchemy Plan/Apply and distilled requests; fixtures never reach a real host. */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import { fakePve, withoutBao } from './fake-pve.ts';
+import { coreCases } from './live-core-fixtures.ts';
+
+for (const entry of coreCases) {
+  describe(`distilled ${entry.name}`, () => {
+    test('adoption, subsequent plan and apply have zero writes', async () => {
+      const fake = fakePve(() => entry.live);
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        expect((await engine.verify(entry.declare(), { all: true })).rows).toEqual([
+          expect.objectContaining({ diff: 'noop', ok: true }),
+        ]);
+        expect(await engine.deploy(entry.declare())).toEqual({ row: 'adopted' });
+        expect((await engine.verify(entry.declare(), { all: true })).rows).toEqual([
+          expect.objectContaining({ diff: 'noop', ok: true }),
+        ]);
+        await engine.deploy(entry.declare());
+        expect(engine.stored()).not.toContain('fake-not-a-secret');
+      });
+      expect(fake.writes()).toEqual([]);
+    });
+
+    test('genuine absence creates once, then reads and converges', async () => {
+      let exists = false;
+      const fake = fakePve((call) => {
+        if (call.method === 'GET') return exists ? entry.live : entry.missing();
+        exists = true;
+        return null;
+      });
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        await engine.deploy(entry.declare());
+        expect((await engine.verify(entry.declare(), { all: true })).rows[0]).toMatchObject({
+          diff: 'noop',
+        });
+      });
+      expect(fake.writes()).toEqual([`POST ${entry.createPath}`]);
+      expect(fake.calls.find((call) => call.method === 'POST')?.form).toEqual(entry.createForm);
+    });
+
+    test('live drift produces exactly one PUT and preserves omitted fields', async () => {
+      let live = entry.drift;
+      const fake = fakePve((call) => {
+        if (call.method === 'GET') return live;
+        live = entry.live;
+        return null;
+      });
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        expect((await engine.verify(entry.declare(), { all: true })).rows[0]).toMatchObject({
+          diff: 'update',
+        });
+        await engine.deploy(entry.declare());
+        expect((await engine.verify(entry.declare(), { all: true })).rows[0]).toMatchObject({
+          diff: 'noop',
+        });
+      });
+      expect(fake.writes()).toEqual([`PUT ${entry.path}`]);
+      const form = fake.calls.find((call) => call.method === 'PUT')?.form;
+      expect(form).not.toHaveProperty('token');
+      expect(form).not.toHaveProperty('otel-headers');
+      expect(form).not.toHaveProperty('compress');
+      expect(form).not.toHaveProperty('mailto');
+      if (entry.name === 'BackupJob') expect(form).not.toHaveProperty('delete');
+      if (entry.name === 'MetricServer') {
+        expect(form?.['delete']).toBe(
+          'api-path-prefix,bucket,influxdbproto,max-body-size,mtu,organization,timeout',
+        );
+        expect(form).not.toHaveProperty('id');
+        expect(form).not.toHaveProperty('type');
+      }
+    });
+
+    for (const status of [401, 403, 500]) {
+      test(`${status} read failure stops cold adoption and confirmed drift before writes`, async () => {
+        let fail = true;
+        const fake = fakePve(() =>
+          fail
+            ? Response.json({ data: null, message: 'unrelated failure' }, { status })
+            : entry.live,
+        );
+        await withoutBao(async () => {
+          const engine = entry.engine(fake);
+          await expect(engine.deploy(entry.declare())).rejects.toBeDefined();
+          fail = false;
+          await engine.deploy(entry.declare());
+          fail = true;
+          await expect(engine.drift(entry.declare())).rejects.toBeDefined();
+          await expect(engine.deploy(entry.declare())).rejects.toBeDefined();
+        });
+        expect(fake.writes()).toEqual([]);
+      });
+    }
+
+    test('delete failure retains the engine state and propagates', async () => {
+      let failing = false;
+      const fake = fakePve(() =>
+        failing
+          ? Response.json({ data: null, message: 'permission denied' }, { status: 403 })
+          : entry.live,
+      );
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        await engine.deploy(entry.declare().pipe(RemovalPolicy.destroy()));
+        failing = true;
+        await expect(engine.deploy(Effect.void)).rejects.toBeDefined();
+        expect(engine.stored()).toContain('row');
+      });
+    });
+  });
+}