@homeflare/alchemy 0.37.1 → 0.37.3

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

@@ -0,0 +1,190 @@
+/** Vendor-specific failures and normalization at the actual distilled HTTP boundary. */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { readBackupJob } from './backup-job-distilled.ts';
+import { ProxmoxBackupJob, ProxmoxBackupJobProvider } from './backup-job.ts';
+import { fakePve, withoutBao } from './fake-pve.ts';
+import { backupProps, coreCases, metricProps } from './live-core-fixtures.ts';
+import { deleteMetricServer, readMetricServer } from './metric-server-distilled.ts';
+import { ProxmoxMetricServer, ProxmoxMetricServerProvider } from './metric-server.ts';
+
+for (const entry of coreCases) {
+  describe(`${entry.name} wire`, () => {
+    test('only the typed missing signal returns undefined', async () => {
+      const fake = fakePve(entry.missing);
+      await withoutBao(async () => {
+        expect(
+          await Effect.runPromise(entry.read().pipe(Effect.provide(fake.layer))),
+        ).toBeUndefined();
+      });
+      expect(fake.writes()).toEqual([]);
+    });
+    test('deleting an already missing object succeeds', async () => {
+      const fake = fakePve(entry.missing);
+      await withoutBao(async () => {
+        await Effect.runPromise(entry.remove().pipe(Effect.provide(fake.layer)));
+      });
+      expect(fake.writes()).toEqual(entry.name === 'MetricServer' ? [] : [`DELETE ${entry.path}`]);
+    });
+    for (const [status, tag] of [
+      [401, 'Unauthorized'],
+      [403, 'Forbidden'],
+      [500, 'InternalServerError'],
+    ] as const) {
+      test(`${status} remains typed ${tag}`, async () => {
+        const fake = fakePve(() =>
+          Response.json({ message: 'unrelated failure', data: null }, { status }),
+        );
+        await withoutBao(async () => {
+          expect(
+            await Effect.runPromise(entry.read().pipe(Effect.flip, Effect.provide(fake.layer))),
+          ).toMatchObject({ _tag: tag });
+        });
+        expect(fake.writes()).toEqual([]);
+      });
+    }
+    if (entry.name !== 'MetricServer') {
+      test('a successful null payload fails the generated response schema', async () => {
+        const fake = fakePve(() => null);
+        await withoutBao(async () => {
+          expect(
+            await Effect.runPromise(entry.read().pipe(Effect.flip, Effect.provide(fake.layer))),
+          ).toMatchObject({ _tag: 'ProxmoxParseError', body: undefined });
+          await expect(entry.engine(fake).deploy(entry.declare())).rejects.toBeDefined();
+        });
+        expect(fake.writes()).toEqual([]);
+      });
+    }
+  });
+}
+
+test('BackupJob keeps genuine validation failure distinct from a missing id', async () => {
+  const fake = fakePve(() =>
+    Response.json(
+      {
+        data: null,
+        message: 'Parameter verification failed.\n',
+        errors: { id: "No such job 'nightly'", schedule: 'invalid calendar expression' },
+      },
+      { status: 400 },
+    ),
+  );
+  await withoutBao(async () => {
+    expect(
+      await Effect.runPromise(
+        readBackupJob(backupProps).pipe(Effect.flip, Effect.provide(fake.layer)),
+      ),
+    ).toMatchObject({ _tag: 'ParameterVerificationFailed' });
+  });
+  expect(fake.writes()).toEqual([]);
+});
+
+for (const expanded of [false, true]) {
+  test(`BackupJob canonicalizes retention and fleecing (${expanded ? 'expanded objects' : 'legacy strings'})`, async () => {
+    const fake = fakePve(() => ({
+      id: backupProps.id,
+      schedule: backupProps.schedule,
+      'prune-backups': expanded
+        ? { 'keep-weekly': 4, 'keep-daily': 7 }
+        : 'keep-weekly=4,keep-daily=7',
+      fleecing: expanded ? { enabled: 1, storage: 'fast' } : 'enabled=1,storage=fast',
+      'next-run': 123456,
+      'notes-template': '{{guestname}}',
+      'repeat-missed': 1,
+      'notification-mode': 'notification-system',
+    }));
+    await withoutBao(async () => {
+      expect(
+        await Effect.runPromise(readBackupJob(backupProps).pipe(Effect.provide(fake.layer))),
+      ).toMatchObject({
+        'prune-backups': 'keep-daily=7,keep-weekly=4',
+        fleecing: 'enabled=1,storage=fast',
+        'next-run': 123456,
+        'notes-template': '{{guestname}}',
+        'repeat-missed': true,
+        'notification-mode': 'notification-system',
+      });
+      const props = {
+        ...backupProps,
+        vmid: undefined,
+        fleecing: 'enabled=1,storage=fast',
+        'notes-template': '{{guestname}}',
+        'repeat-missed': true,
+        'notification-mode': 'notification-system' as const,
+      };
+      const { vmid: _omitted, ...declared } = props;
+      const engine = engineOver(ProxmoxBackupJobProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect((await engine.verify(ProxmoxBackupJob('row', declared))).rows[0]).toMatchObject({
+        diff: 'noop',
+      });
+      await engine.deploy(ProxmoxBackupJob('row', declared));
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+}
+
+test('MetricServer rejects a malformed non-object without leaking its payload', async () => {
+  const fake = fakePve(() => 'fixture-secret-value');
+  await withoutBao(async () => {
+    const error = await Effect.runPromise(
+      readMetricServer(metricProps).pipe(Effect.flip, Effect.provide(fake.layer)),
+    );
+    expect(error).toMatchObject({ _tag: 'ProxmoxParseError', body: undefined });
+    expect(JSON.stringify(error)).not.toContain('fixture-secret-value');
+  });
+  expect(fake.writes()).toEqual([]);
+});
+
+test('MetricServer delete race propagates an unclassified vendor refusal', async () => {
+  const fake = fakePve((call) =>
+    call.method === 'GET'
+      ? { type: 'influxdb', server: 'metrics.test', port: 8086 }
+      : Response.json({ data: null, message: 'unable to read plugin type' }, { status: 500 }),
+  );
+  await withoutBao(async () => {
+    expect(
+      await Effect.runPromise(
+        deleteMetricServer(metricProps).pipe(Effect.flip, Effect.provide(fake.layer)),
+      ),
+    ).toMatchObject({ _tag: 'InternalServerError' });
+  });
+  expect(fake.writes()).toEqual(['DELETE cluster/metrics/server/metrics']);
+});
+
+test('MetricServer OTEL updates preserve plugin-specific wire names and secrets', async () => {
+  const props = {
+    ...metricProps,
+    type: 'opentelemetry' as const,
+    'otel-protocol': 'http' as const,
+    'otel-path': '/ingest',
+    'otel-compression': 'none' as const,
+    'otel-timeout': 7,
+    'otel-max-body-size': 2048,
+    'otel-verify-ssl': false,
+  };
+  const fake = fakePve(() => ({
+    type: 'opentelemetry',
+    server: 'old.test',
+    port: 8086,
+    'otel-headers': 'fixture-secret-value',
+  }));
+  await withoutBao(async () => {
+    const engine = engineOver(ProxmoxMetricServerProvider().pipe(Layer.provideMerge(fake.layer)));
+    await engine.deploy(ProxmoxMetricServer('row', props));
+    expect(engine.stored()).not.toContain('fixture-secret-value');
+  });
+  expect(fake.writes()).toEqual(['PUT cluster/metrics/server/metrics']);
+  expect(fake.calls.find((call) => call.method === 'PUT')?.form).toEqual({
+    server: 'metrics.test',
+    port: '8086',
+    disable: '0',
+    'otel-protocol': 'http',
+    'otel-path': '/ingest',
+    'otel-compression': 'none',
+    'otel-timeout': '7',
+    'otel-max-body-size': '2048',
+    'otel-verify-ssl': '0',
+  });
+});

package/src/proxmox/metric-server-config.ts

@@ -0,0 +1,87 @@
+/** Pure existing forms, normalization and equality, shared by plan and SDK lifecycle. */
+import type { MetricServerAttributes, MetricServerProps } from './metric-server.ts';
+import type { PveSpec } from './resource-spec.ts';
+import { UNSET, createBody, update } from './metric-server-form.ts';
+import { otelAttributes, otelMatches } from './metric-server-otel.ts';
+import { bool, int, text } from './values.ts';
+
+/**
+ * The type-specific half of `matches`.
+ *
+ * ⛔ ONLY FIELDS THIS TYPE ACTUALLY SENDS ARE COMPARED. `verify-certificate` is not in graphite's
+ *   option set and `path` is not in influxdb's, so neither is ever sent to the wrong plugin — and
+ *   diffing one anyway would report an update that the PUT it triggers cannot satisfy, forever.
+ *   `mtu` and `timeout` are compared for graphite and influxdb only, because the opentelemetry
+ *   plugin has neither and `optional` never sends them to it.
+ */
+const matchesType = (attributes: MetricServerAttributes, props: MetricServerProps): boolean => {
+  if (props.type === 'opentelemetry') return otelMatches(attributes, props);
+  const socket =
+    attributes.mtu === (props.mtu ?? UNSET) && attributes.timeout === (props.timeout ?? UNSET);
+  if (props.type === 'graphite') return socket && attributes.path === (props.path ?? '');
+  return (
+    socket &&
+    attributes.influxdbproto === (props.influxdbproto ?? '') &&
+    attributes.organization === (props.organization ?? '') &&
+    attributes.bucket === (props.bucket ?? '') &&
+    attributes['api-path-prefix'] === (props['api-path-prefix'] ?? '') &&
+    attributes['max-body-size'] === (props['max-body-size'] ?? UNSET) &&
+    attributes['verify-certificate'] === (props['verify-certificate'] !== false)
+  );
+};
+
+export const metricServerSpec = {
+  attributes: (live, props) => {
+    /**
+     * ⛔ A SERVER OF ANOTHER TYPE IS ANOTHER OBJECT, AND "ABSENT" IS THE HONEST ANSWER. `type`
+     *   cannot be changed by a PUT, so reporting the foreign section as missing makes reconcile
+     *   POST instead and PVE refuses because the id is taken — a loud, accurate error rather than a
+     *   PUT pushing influxdb fields at a graphite section. An older PVE that omits `type` from the
+     *   read falls through and is trusted.
+     */
+    const liveType = text(live['type']);
+    if (liveType !== '' && liveType !== props.type) return undefined;
+    return {
+      ...otelAttributes(live),
+      'api-path-prefix': text(live['api-path-prefix']),
+      bucket: text(live['bucket']),
+      disable: bool(live['disable'], false),
+      id: props.id,
+      influxdbproto: text(live['influxdbproto']),
+      'max-body-size': int(live['max-body-size'], UNSET),
+      mtu: int(live['mtu'], UNSET),
+      organization: text(live['organization']),
+      path: text(live['path']),
+      port: int(live['port'], 0),
+      server: text(live['server']),
+      timeout: int(live['timeout'], UNSET),
+      type: props.type,
+      'verify-certificate': bool(live['verify-certificate'], true),
+    };
+  },
+  /** ⛔ THE SAME STRING AS `path`, DELIBERATELY — see the ⛔ in the header. */
+  collection: (props) => `cluster/metrics/server/${props.id}`,
+  /** ⚠️ `type` IS REQUIRED ON CREATE; `id` IS NOT SENT, because the id is the path. */
+  createForm: createBody,
+  /**
+   * The vendor rules both forms are checked against at plan time — resource-spec.ts.
+   * ⚠️ POST AND PUT ARE THE SAME PATH HERE, and they are still two different tables: only the
+   *   POST marks `type` required, and only the PUT accepts `delete` and `digest`.
+   */
+  endpoint: {
+    create: 'pve:POST /cluster/metrics/server/{id}',
+    update: 'pve:PUT /cluster/metrics/server/{id}',
+  },
+  /**
+   * ⛔ `id` and `type` are absent: one is the key the object was read by, the other is refused
+   *   rather than updated. Everything type-specific is `matchesType`'s, above.
+   */
+  matches: (attributes, props) =>
+    attributes.server === props.server &&
+    attributes.port === props.port &&
+    attributes.disable === (props.disable === true) &&
+    matchesType(attributes, props),
+  path: (props) => `cluster/metrics/server/${props.id}`,
+  /** The form and its clear-list, from the one table in metric-server-form.ts. */
+  updateForm: update,
+} satisfies PveSpec<MetricServerProps, MetricServerAttributes>;

package/src/proxmox/metric-server-distilled.ts

@@ -0,0 +1,81 @@
+/** Metric-server SDK transport; pve-manager 9.2.11, no change to managed/secret fields. */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import { ProxmoxParseError } from '@distilled.cloud/proxmox/Errors';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { asForm } from './distilled-guard.ts';
+import { runPve } from './distilled-pve.ts';
+import { metricServerSpec } from './metric-server-config.ts';
+import type { MetricServerProps } from './metric-server.ts';
+
+/**
+ * The vendor intentionally leaves this plugin-dependent response unstructured in its
+ * schema. Decode only the object envelope, then use the existing per-plugin normalization.
+ * A malformed response fails without including header credentials in a schema diagnostic.
+ */
+export const readMetricServerRow = (props: MetricServerProps) =>
+  runPve(props.target, 'read', false, cluster.getClusterMetricsServer({ id: props.id })).pipe(
+    Effect.flatMap((body) =>
+      Schema.decodeUnknownEffect(Schema.Record(Schema.String, Schema.Unknown))(body).pipe(
+        Effect.mapError(
+          () =>
+            new ProxmoxParseError({
+              body: undefined,
+              cause: 'Metric server response must be an object',
+            }),
+        ),
+      ),
+    ),
+    Effect.catchTag('MetricServerNotFound', () => Effect.succeed(undefined)),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+export const readMetricServer = (props: MetricServerProps) =>
+  readMetricServerRow(props).pipe(
+    Effect.map((row) => (row === undefined ? undefined : metricServerSpec.attributes(row, props))),
+  );
+
+/** Map only the existing form's declared keys; token and otel-headers never enter this map. */
+export const metricServerRequest = (
+  props: MetricServerProps,
+  form: Record<string, string>,
+): cluster.PutClusterMetricsServerRequest => ({
+  ...asForm({
+    api_path_prefix: form['api-path-prefix'],
+    bucket: form['bucket'],
+    delete: form['delete'],
+    disable: form['disable'],
+    influxdbproto: form['influxdbproto'],
+    max_body_size: form['max-body-size'],
+    mtu: form['mtu'],
+    organization: form['organization'],
+    otel_compression: form['otel-compression'],
+    otel_max_body_size: form['otel-max-body-size'],
+    otel_path: form['otel-path'],
+    otel_protocol: form['otel-protocol'],
+    otel_timeout: form['otel-timeout'],
+    otel_verify_ssl: form['otel-verify-ssl'],
+    path: form['path'],
+    timeout: form['timeout'],
+    verify_certificate: form['verify-certificate'],
+  } satisfies { [K in keyof cluster.PutClusterMetricsServerRequest]?: string | undefined }),
+  id: props.id,
+  port: String(props.port),
+  server: props.server,
+});
+
+/**
+ * Vendor DELETE dereferences the plugin without an absent-row check (MetricServer.pm:293).
+ * A typed GET miss therefore skips DELETE. A race or any other SDK error still propagates;
+ * never reinterpret an arbitrary 500 from deleting an invalid section as success.
+ */
+export const deleteMetricServer = (props: MetricServerProps) =>
+  Effect.gen(function* () {
+    if ((yield* readMetricServerRow(props)) === undefined) return;
+    yield* runPve(
+      props.target,
+      'provision',
+      true,
+      cluster.deleteClusterMetricsServer({ id: props.id }),
+    );
+  });

package/src/proxmox/metric-server.ts

@@ -29,17 +29,25 @@
  *   cluster-wide config write. A separate role for metric writes is the narrower answer.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import { runPve } from './distilled-pve.ts';
+import { specGuards } from './resource-guard.ts';
+import { formToSend } from './update-guard.ts';
+import { metricServerSpec } from './metric-server-config.ts';
+import {
+  deleteMetricServer,
+  metricServerRequest,
+  readMetricServer,
+} from './metric-server-distilled.ts';
+
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { UNSET, createBody, update } from './metric-server-form.ts';
 import {
   type MetricServerOtelAttributes,
   type MetricServerOtelProps,
-  otelAttributes,
-  otelMatches,
 } from './metric-server-otel.ts';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool, int, text } from './values.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
 
 /**
  * PVE's status plugins. Which one a server is decides which fields it will even accept.
@@ -130,88 +138,7 @@ export interface ProxmoxMetricServer extends Resource<
 export const ProxmoxMetricServer = Resource<ProxmoxMetricServer>('Proxmox.MetricServer');
 
 /**
- * The type-specific half of `matches`.
- *
- * ⛔ ONLY FIELDS THIS TYPE ACTUALLY SENDS ARE COMPARED. `verify-certificate` is not in graphite's
- *   option set and `path` is not in influxdb's, so neither is ever sent to the wrong plugin — and
- *   diffing one anyway would report an update that the PUT it triggers cannot satisfy, forever.
- *   `mtu` and `timeout` are compared for graphite and influxdb only, because the opentelemetry
- *   plugin has neither and `optional` never sends them to it.
- */
-const matchesType = (attributes: MetricServerAttributes, props: MetricServerProps): boolean => {
-  if (props.type === 'opentelemetry') return otelMatches(attributes, props);
-  const socket =
-    attributes.mtu === (props.mtu ?? UNSET) && attributes.timeout === (props.timeout ?? UNSET);
-  if (props.type === 'graphite') return socket && attributes.path === (props.path ?? '');
-  return (
-    socket &&
-    attributes.influxdbproto === (props.influxdbproto ?? '') &&
-    attributes.organization === (props.organization ?? '') &&
-    attributes.bucket === (props.bucket ?? '') &&
-    attributes['api-path-prefix'] === (props['api-path-prefix'] ?? '') &&
-    attributes['max-body-size'] === (props['max-body-size'] ?? UNSET) &&
-    attributes['verify-certificate'] === (props['verify-certificate'] !== false)
-  );
-};
-
-const handlers = pveHandlers<MetricServerProps, MetricServerAttributes>({
-  attributes: (live, props) => {
-    /**
-     * ⛔ A SERVER OF ANOTHER TYPE IS ANOTHER OBJECT, AND "ABSENT" IS THE HONEST ANSWER. `type`
-     *   cannot be changed by a PUT, so reporting the foreign section as missing makes reconcile
-     *   POST instead and PVE refuses because the id is taken — a loud, accurate error rather than a
-     *   PUT pushing influxdb fields at a graphite section. An older PVE that omits `type` from the
-     *   read falls through and is trusted.
-     */
-    const liveType = text(live['type']);
-    if (liveType !== '' && liveType !== props.type) return undefined;
-    return {
-      ...otelAttributes(live),
-      'api-path-prefix': text(live['api-path-prefix']),
-      bucket: text(live['bucket']),
-      disable: bool(live['disable'], false),
-      id: props.id,
-      influxdbproto: text(live['influxdbproto']),
-      'max-body-size': int(live['max-body-size'], UNSET),
-      mtu: int(live['mtu'], UNSET),
-      organization: text(live['organization']),
-      path: text(live['path']),
-      port: int(live['port'], 0),
-      server: text(live['server']),
-      timeout: int(live['timeout'], UNSET),
-      type: props.type,
-      'verify-certificate': bool(live['verify-certificate'], true),
-    };
-  },
-  /** ⛔ THE SAME STRING AS `path`, DELIBERATELY — see the ⛔ in the header. */
-  collection: (props) => `cluster/metrics/server/${props.id}`,
-  /** ⚠️ `type` IS REQUIRED ON CREATE; `id` IS NOT SENT, because the id is the path. */
-  createForm: createBody,
-  /**
-   * The vendor rules both forms are checked against at plan time — resource-spec.ts.
-   * ⚠️ POST AND PUT ARE THE SAME PATH HERE, and they are still two different tables: only the
-   *   POST marks `type` required, and only the PUT accepts `delete` and `digest`.
-   */
-  endpoint: {
-    create: 'pve:POST /cluster/metrics/server/{id}',
-    update: 'pve:PUT /cluster/metrics/server/{id}',
-  },
-  /**
-   * ⛔ `id` and `type` are absent: one is the key the object was read by, the other is refused
-   *   rather than updated. Everything type-specific is `matchesType`'s, above.
-   */
-  matches: (attributes, props) =>
-    attributes.server === props.server &&
-    attributes.port === props.port &&
-    attributes.disable === (props.disable === true) &&
-    matchesType(attributes, props),
-  path: (props) => `cluster/metrics/server/${props.id}`,
-  /** The form and its clear-list, from the one table in metric-server-form.ts. */
-  updateForm: update,
-});
-
-/**
- * ⛔ THE EMPTY `list` FROM `pveHandlers` EARNS ITS KEEP HERE. `GET cluster/metrics/server` answers
+ * ⛔ THE EMPTY `list` KEEPS ADOPTION EXPLICIT. `GET cluster/metrics/server` answers
  *   with every target the cluster already ships to, including the one somebody configured by hand
  *   years ago; adopting that is how a later `alchemy destroy` silences a graph nobody declared.
  * ⚠️ AND NOTHING BRAKES THIS DESTROY. A pool refuses while it holds guests, a container while it
@@ -219,5 +146,67 @@ const handlers = pveHandlers<MetricServerProps, MetricServerAttributes>({
  *   interval, and no guest or task is affected. The plan diff is the only warning anyone gets —
  *   the top of this file again, this time caused by a deploy.
  */
+const { guardCreate, guardUpdate } = specGuards(metricServerSpec);
+
+/** SDK lifecycle walked against pve-manager 9.2.11; failed reads never imply create. */
 export const ProxmoxMetricServerProvider = () =>
-  Provider.effect(ProxmoxMetricServer, Effect.succeed(ProxmoxMetricServer.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxMetricServer,
+    Effect.succeed(
+      ProxmoxMetricServer.Provider.of({
+        list: () => Effect.succeed([]),
+        read: ({ olds }) => readMetricServer(olds),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardCreate(news, output === undefined);
+          yield* guardUpdate(news);
+          if (output === undefined) return undefined;
+          const live = yield* readMetricServer(news);
+          if (live === undefined) {
+            yield* guardCreate(news, true);
+            return { action: 'update' } as const;
+          }
+          return { action: metricServerSpec.matches(live, news) ? 'noop' : 'update' } as const;
+        }),
+        reconcile: Effect.fn(function* ({ news }) {
+          const live = yield* readMetricServer(news);
+          yield* guardCreate(news, live === undefined);
+          yield* guardUpdate(news);
+          if (live === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              cluster.updateClusterMetricsServer({
+                ...metricServerRequest(news, metricServerSpec.createForm(news)),
+                type: news.type,
+              }),
+            );
+          } else {
+            const form = formToSend(
+              metricServerSpec.matches,
+              live,
+              news,
+              metricServerSpec.updateForm(news),
+            );
+            if (form !== undefined)
+              yield* runPve(
+                news.target,
+                'provision',
+                true,
+                cluster.putClusterMetricsServer(metricServerRequest(news, form)),
+              );
+          }
+          const after = yield* readMetricServer(news);
+          if (after === undefined)
+            return yield* Effect.fail(
+              new Error(
+                `${metricServerSpec.path(news)}: write returned success but the resource is still absent`,
+              ),
+            );
+          return after;
+        }),
+        delete: ({ olds }) => deleteMetricServer(olds),
+      }),
+    ),
+  );