@homeflare/alchemy 0.37.2 → 0.37.3

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),
+      }),
+    ),
+  );

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

@@ -0,0 +1,162 @@
+/** Notification lifecycles through the real SDK and upstream Alchemy test harness. */
+import { afterEach, beforeEach, expect, test as unit } from 'bun:test';
+import * as Test from 'alchemy/Test/Bun';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import {
+  ProxmoxNotificationMatcher,
+  ProxmoxNotificationMatcherProvider,
+} from './notification-matcher.ts';
+import {
+  ProxmoxNotificationTarget,
+  ProxmoxNotificationTargetProvider,
+} from './notification-target.ts';
+import { readMatcher } from './notification-matcher-distilled.ts';
+import { readTarget } from './notification-target-distilled.ts';
+
+const fake = fakeNotify();
+let saved: [string, string | undefined][] = [];
+beforeEach(() => {
+  saved = Object.entries(process.env).filter(([key]) => /^(BAO|VAULT)_/.test(key));
+  for (const [key] of saved) delete process.env[key];
+  process.env['BAO_ADDR'] = 'http://bao.invalid';
+  fake.objects.clear();
+  fake.secrets.clear();
+  fake.calls.length = 0;
+});
+afterEach(() => {
+  for (const key of Object.keys(process.env))
+    if (/^(BAO|VAULT)_/.test(key)) delete process.env[key];
+  for (const [key, value] of saved) process.env[key] = value;
+});
+const { test } = Test.make({
+  adopt: true,
+  dev: false,
+  sidecar: false,
+  stage: 'test',
+  providers: Layer.mergeAll(
+    ProxmoxNotificationTargetProvider(),
+    ProxmoxNotificationMatcherProvider(),
+  ).pipe(Layer.provideMerge(fake.layer)),
+});
+const target = (clear = false) =>
+  ProxmoxNotificationTarget('mail', {
+    target: FAKE_TARGET,
+    type: 'sendmail',
+    name: 'mail',
+    mailto: clear ? [] : ['a@example.com', 'b@example.com'],
+    'mailto-user': ['root@pam'],
+  });
+const matcher = (clear = false) =>
+  ProxmoxNotificationMatcher('route', {
+    target: FAKE_TARGET,
+    name: 'route',
+    targets: ['mail'],
+    'match-field': clear ? [] : ['exact:type=prune,sync', 'regex:hostname=^node'],
+  });
+const stack = (clear = false) =>
+  Effect.gen(function* () {
+    yield* target(clear);
+    yield* matcher(clear);
+  });
+const existing = () => {
+  fake.objects.set('cluster/notifications/endpoints/sendmail/mail', {
+    name: 'mail',
+    mailto: ['b@example.com', 'a@example.com'],
+    'mailto-user': ['root@pam'],
+  });
+  fake.objects.set('cluster/notifications/matchers/route', {
+    name: 'route',
+    target: ['mail'],
+    'match-field': ['exact:type=prune,sync', 'regex:hostname=^node'],
+  });
+};
+const actions = (plan: { resources: Record<string, { action: string }> }) =>
+  Object.values(plan.resources)
+    .map((row) => row.action)
+    .sort();
+
+test.provider('matching target and matcher adopt with zero writes and redeploy noop', (scratch) =>
+  Effect.gen(function* () {
+    existing();
+    yield* scratch.deploy(stack());
+    expect(fake.writes()).toEqual([]);
+    expect(actions(yield* scratch.plan(stack()))).toEqual(['noop', 'noop']);
+  }),
+);
+test.provider('new rows send repeated arrays and preserve commas inside rules', (scratch) =>
+  Effect.gen(function* () {
+    yield* scratch.deploy(stack());
+    expect(fake.objects.get('cluster/notifications/matchers/route')?.['match-field']).toEqual([
+      'exact:type=prune,sync',
+      'regex:hostname=^node',
+    ]);
+    expect(fake.objects.get('cluster/notifications/endpoints/sendmail/mail')?.['mailto']).toEqual([
+      'a@example.com',
+      'b@example.com',
+    ]);
+    expect(actions(yield* scratch.plan(stack()))).toEqual(['noop', 'noop']);
+  }),
+);
+test.provider('empty recipient and rule arrays clear explicitly and settle to noop', (scratch) =>
+  Effect.gen(function* () {
+    existing();
+    yield* scratch.deploy(stack());
+    yield* scratch.deploy(stack(true));
+    expect(fake.objects.get('cluster/notifications/endpoints/sendmail/mail')).not.toHaveProperty(
+      'mailto',
+    );
+    expect(fake.objects.get('cluster/notifications/matchers/route')).not.toHaveProperty(
+      'match-field',
+    );
+    expect(actions(yield* scratch.plan(stack(true)))).toEqual(['noop', 'noop']);
+  }),
+);
+for (const status of [200, 400, 401, 403, 500]) {
+  unit(`malformed or refused HTTP ${status} cannot become absence`, async () => {
+    const broken = fakePve(() => Response.json({ data: null, message: 'refused' }, { status }));
+    await withoutBao(async () => {
+      const targetRead = readTarget({ target: FAKE_TARGET, name: 'mail', type: 'sendmail' });
+      const matcherRead = readMatcher({ target: FAKE_TARGET, name: 'route', targets: ['mail'] });
+      expect(
+        (await Effect.runPromise(Effect.exit(targetRead).pipe(Effect.provide(broken.layer))))._tag,
+      ).toBe('Failure');
+      expect(
+        (await Effect.runPromise(Effect.exit(matcherRead).pipe(Effect.provide(broken.layer))))._tag,
+      ).toBe('Failure');
+    });
+    expect(broken.writes()).toEqual([]);
+  });
+}
+
+test.provider('same-name endpoint type changes replace delete-first', (scratch) =>
+  Effect.gen(function* () {
+    const hook = ProxmoxNotificationTarget('endpoint', {
+      target: FAKE_TARGET,
+      name: 'pager',
+      type: 'webhook',
+      url: 'https://pager.example.com',
+      method: 'post',
+      header: ['name=X-One,value=b25l', 'name=X-Two,value=dHdv'],
+    });
+    const mail = ProxmoxNotificationTarget('endpoint', {
+      target: FAKE_TARGET,
+      name: 'pager',
+      type: 'sendmail',
+      'mailto-user': ['root@pam'],
+    });
+    yield* scratch.deploy(hook);
+    expect(fake.objects.get('cluster/notifications/endpoints/webhook/pager')?.['header']).toEqual([
+      'name=X-One,value=b25l',
+      'name=X-Two,value=dHdv',
+    ]);
+    yield* scratch.deploy(mail);
+    expect(fake.writes()).toEqual([
+      'POST cluster/notifications/endpoints/webhook',
+      'DELETE cluster/notifications/endpoints/webhook/pager',
+      'POST cluster/notifications/endpoints/sendmail',
+    ]);
+  }),
+);

package/src/proxmox/notification-matcher-distilled.ts

@@ -0,0 +1,60 @@
+/** PVE 9.2.11 matchers through distilled; 404 is measured absence, other failures propagate. */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import * as Effect from 'effect/Effect';
+import type { NotificationMatcherProps } from './notification-matcher.ts';
+import {
+  matcherAttributes,
+  matcherCreateForm,
+  matcherUpdateForm,
+} from './notification-matcher-form.ts';
+import { runPve } from './distilled-pve.ts';
+import { notificationRequest, notificationResponse } from './notification-sdk-input.ts';
+
+export const readMatcher = (props: NotificationMatcherProps) =>
+  runPve(
+    props.target,
+    'read',
+    false,
+    cluster.getClusterNotificationMatcher({ name: props.name }),
+  ).pipe(
+    Effect.flatMap(notificationResponse(cluster.GetClusterNotificationMatcherResponse)),
+    Effect.map((live) =>
+      matcherAttributes(
+        {
+          ...live,
+          'invert-match': live.invert_match,
+          'match-calendar': live.match_calendar,
+          'match-field': live.match_field,
+          'match-severity': live.match_severity,
+        },
+        props.name,
+      ),
+    ),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+export const createMatcher = (props: NotificationMatcherProps) =>
+  Effect.gen(function* () {
+    const input = yield* notificationRequest(
+      cluster.CreateClusterNotificationMatcherRequest,
+      matcherCreateForm(props),
+    );
+    yield* runPve(props.target, 'provision', true, cluster.createClusterNotificationMatcher(input));
+  });
+
+export const updateMatcher = (props: NotificationMatcherProps) =>
+  Effect.gen(function* () {
+    const input = yield* notificationRequest(cluster.PutClusterNotificationMatcherRequest, {
+      ...matcherUpdateForm(props),
+      name: props.name,
+    });
+    yield* runPve(props.target, 'provision', true, cluster.putClusterNotificationMatcher(input));
+  });
+
+export const deleteMatcher = (props: NotificationMatcherProps) =>
+  runPve(
+    props.target,
+    'provision',
+    true,
+    cluster.deleteClusterNotificationMatcher({ name: props.name }),
+  ).pipe(Effect.catchTag('NotFound', () => Effect.void));

package/src/proxmox/notification-matcher-lifecycle.ts

@@ -0,0 +1,71 @@
+/** A matching PVE matcher adoption writes nothing; unreadable is never treated as absent. */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { NotificationMatcherProps as Props } from './notification-matcher.ts';
+import {
+  type NotificationMatcherAttributes as Attributes,
+  matcherCreateForm,
+  matcherMatches,
+  matcherUpdateForm,
+} from './notification-matcher-form.ts';
+import { guardForm } from './constraint-guard.ts';
+import {
+  createMatcher,
+  deleteMatcher,
+  readMatcher,
+  updateMatcher,
+} from './notification-matcher-distilled.ts';
+
+const guard = (props: Props, create: boolean) =>
+  guardForm('pve:POST /cluster/notifications/matchers', matcherCreateForm(props), create).pipe(
+    Effect.andThen(
+      guardForm('pve:PUT /cluster/notifications/matchers/{name}', matcherUpdateForm(props), false),
+    ),
+  );
+
+export const matcherHandlers = {
+  /** Built-ins and human-created matchers are not auto-enrolled; adoption is explicit. */
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: Props }) =>
+    Effect.gen(function* () {
+      const live = yield* readMatcher(olds);
+      yield* guard(olds, live === undefined);
+      return live;
+    }),
+  diff: ({
+    news,
+    olds,
+    output,
+  }: {
+    news: Input<Props>;
+    olds: Props;
+    output: Attributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      if (olds.name !== news.name) return { action: 'replace' } as const;
+      yield* guard(news, output === undefined);
+      if (output === undefined) return undefined;
+      const live = yield* readMatcher(news);
+      if (live === undefined) {
+        yield* guard(news, true);
+        return { action: 'update' } as const;
+      }
+      return { action: matcherMatches(live, news) ? 'noop' : 'update' } as const;
+    }),
+  reconcile: ({ news }: { news: Props }) =>
+    Effect.gen(function* () {
+      const live = yield* readMatcher(news);
+      yield* guard(news, live === undefined);
+      if (live === undefined) yield* createMatcher(news);
+      else if (!matcherMatches(live, news)) yield* updateMatcher(news);
+      const after = yield* readMatcher(news);
+      if (after === undefined)
+        return yield* Effect.die(
+          new Error(`Notification matcher ${news.name}: write returned but read-back is absent.`),
+        );
+      return after;
+    }),
+  delete: ({ olds }: { olds: Props }) => deleteMatcher(olds),
+};

package/src/proxmox/notification-matcher.ts

@@ -24,22 +24,19 @@
  *   ⛔ `Mapping.Use` IS NOT ENOUGH, though the COLLECTION GET accepts it: the per-object read this
  *     family makes lists only Audit and Modify (pve-manager API2/Cluster/Notifications.pm
  *     `get_matcher`, read at HEAD 2026-09-22 — corrected here; PR 95 said Use sufficed).
- *   ⛔ A MISSING READ PRIVILEGE LOOKS LIKE "ABSENT", not like a 403 — see the same file. For
- *     `default-matcher` that turns an adoption into a planned CREATE that PVE refuses as a
- *     duplicate: the noop below needs a read lease holding Mapping.Audit.
+ *   ⛔ THE OLD HAND CLIENT FOLDED A MISSING READ PRIVILEGE INTO "ABSENT", planning a duplicate
+ *     create. The distilled read now catches only NotFound: a refused read fails the plan.
+ *     The noop still requires a read lease holding Mapping.Audit.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import {
-  type NotificationMatcherAttributes,
-  type NotificationMatcherFields,
-  matcherAttributes,
-  matcherCreateForm,
-  matcherMatches,
-  matcherUpdateForm,
+import type {
+  NotificationMatcherAttributes,
+  NotificationMatcherFields,
 } from './notification-matcher-form.ts';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { matcherHandlers } from './notification-matcher-lifecycle.ts';
 
 export interface NotificationMatcherProps extends NotificationMatcherFields, WithTarget {}
 
@@ -60,22 +57,8 @@ export const ProxmoxNotificationMatcher = Resource<ProxmoxNotificationMatcher>(
   'Proxmox.NotificationMatcher',
 );
 
-const handlers = pveHandlers<NotificationMatcherProps, NotificationMatcherAttributes>({
-  attributes: (live, props) => matcherAttributes(live, props.name),
-  collection: () => 'cluster/notifications/matchers',
-  createForm: matcherCreateForm,
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: {
-    create: 'pve:POST /cluster/notifications/matchers',
-    update: 'pve:PUT /cluster/notifications/matchers/{name}',
-  },
-  matches: matcherMatches,
-  path: (props) => `cluster/notifications/matchers/${props.name}`,
-  updateForm: matcherUpdateForm,
-});
-
 export const ProxmoxNotificationMatcherProvider = () =>
   Provider.effect(
     ProxmoxNotificationMatcher,
-    Effect.succeed(ProxmoxNotificationMatcher.Provider.of(handlers)),
+    Effect.succeed(ProxmoxNotificationMatcher.Provider.of(matcherHandlers)),
   );