@homeflare/distilled-proxmox 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/distilled-proxmox",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Interim npm home for @distilled.cloud/proxmox — see docs/distilled-interim.md. Not published upstream yet; the kit aliases @distilled.cloud/proxmox onto this package until it is.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/distilled-proxmox#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/network-changes.test.ts

@@ -0,0 +1,60 @@
+/**
+ * The interfaces diff is a sibling of `data`. Generic unwrapping must not drop it,
+ * and a response without that sibling must still unwrap.
+ */
+import { describe, expect, test } from "bun:test";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import { credentials } from "./credentials.ts";
+import type { ProxmoxOpContext } from "./protocol.ts";
+import * as Retry from "./retry.ts";
+import { getNodeTime, listNodeNetwork } from "./services/nodes.ts";
+
+const creds = credentials({
+  tokenId: "root@pam!test",
+  secret: "test-secret",
+  baseUrl: "https://pve.test:8006",
+});
+
+const http = (body: unknown) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.succeed(
+        HttpClientResponse.fromWeb(request, Response.json(body, { status: 200 })),
+      ),
+    ),
+  );
+
+const run = <A, E>(op: Effect.Effect<A, E, ProxmoxOpContext>, body: unknown) =>
+  Effect.runPromise(op.pipe(Retry.none, Effect.provide(Layer.mergeAll(http(body), creds))));
+
+describe("network changes sibling", () => {
+  test("a staged interfaces diff survives beside data", async () => {
+    const changes = "--- a\n+++ b\n+wpa-psk secret-value\n";
+    const live = await run(
+      listNodeNetwork({ node: "pve1" }),
+      { data: [{ iface: "vmbr0", type: "bridge" }], changes },
+    );
+    expect(live).toEqual({
+      data: [{ iface: "vmbr0", type: "bridge" }],
+      changes,
+    });
+  });
+
+  test("no changes sibling still unwraps to the interface list", async () => {
+    const live = await run(listNodeNetwork({ node: "pve1" }), {
+      data: [{ iface: "vmbr0", type: "bridge" }],
+    });
+    expect(live).toEqual([{ iface: "vmbr0", type: "bridge" }]);
+  });
+
+  test("another operation still unwraps data and ignores no sibling", async () => {
+    const live = await run(getNodeTime({ node: "pve1" }), {
+      data: { time: 1_700_000_000 },
+    });
+    expect(live).toMatchObject({ time: 1_700_000_000 });
+  });
+});

package/src/not-found-errors.test.ts

@@ -27,6 +27,13 @@ import {
   deleteNodeCephFs,
   getNodeCephPoolStatus,
 } from "./services/nodes.ts";
+import {
+  deleteClusterHaResource,
+  getClusterHaResource,
+  getClusterHaRule,
+  HaResourceNotFound,
+  HaRuleNotFound,
+} from "./services/cluster.ts";
 import { getStorage, StorageNotFound } from "./services/storage.ts";
 
 const testCredentials = credentials({
@@ -101,6 +108,37 @@ describe("WI-3 typed not-found errors decode from PVE's real wire shape", () =>
     expect(error).toBeInstanceOf(CephPoolNotFound);
   });
 
+  test("a missing HA resource's 500 decodes to HaResourceNotFound", async () => {
+    const error = await flipped(getClusterHaResource({ sid: "ct:101" }), 500, {
+      message: "no such resource 'ct:101'\n",
+    });
+    expect(error).toBeInstanceOf(HaResourceNotFound);
+  });
+
+  test("deleting an unmanaged HA resource's 500 decodes to HaResourceNotFound", async () => {
+    const error = await flipped(
+      deleteClusterHaResource({ sid: "vm:100" }),
+      500,
+      { message: "cannot delete service 'vm:100', not HA managed!\n" },
+    );
+    expect(error).toBeInstanceOf(HaResourceNotFound);
+  });
+
+  test("a missing HA rule's 500 decodes to HaRuleNotFound", async () => {
+    const error = await flipped(getClusterHaRule({ rule: "keep-apart" }), 500, {
+      message: "no such ha rule 'keep-apart'\n",
+    });
+    expect(error).toBeInstanceOf(HaRuleNotFound);
+  });
+
+  test("a nearby HA sentence does not become absence", async () => {
+    const error = await flipped(getClusterHaResource({ sid: "ct:101" }), 500, {
+      message:
+        "service 'ct:101' in error state, must be disabled and fixed first\n",
+    });
+    expect(error).not.toBeInstanceOf(HaResourceNotFound);
+  });
+
   test("a missing Ceph filesystem's 500 (on destroy) decodes to CephFsNotFound", async () => {
     const error = await flipped(
       deleteNodeCephFs({ node: "n2", name: "ghost-fs" }),

package/src/protocol.ts

@@ -174,13 +174,22 @@ export const ProxmoxProtocol: Layer.Layer<API.Protocol> = withPveFormArrays(
     // Unwrap PVE's `{"data": …}` envelope BEFORE the schema-driven decode —
     // see the module header. `data` is `null`/absent for a Unit-output
     // operation; `?? {}` is core's own convention for "no body".
+    // ⛔ `changes` is a sibling, not a field of `data`. PVE/HTTPServer.pm copies
+    //   `$rpcenv->get_result_attrib('changes')` beside `data`. Network.pm sets
+    //   that attrib to the interfaces diff. Dropping it makes a pending reload
+    //   invisible. Only a string sibling is preserved; every other envelope
+    //   still unwraps. The network list schema is the union that can decode it.
     transformResponse: (body) => {
       if (
         body !== null &&
         typeof body === "object" &&
         "data" in (body as Record<string, unknown>)
       ) {
-        return (body as Record<string, unknown>).data ?? {};
+        const record = body as Record<string, unknown>;
+        if (typeof record.changes === "string") {
+          return { changes: record.changes, data: record.data ?? [] };
+        }
+        return record.data ?? {};
       }
       return body;
     },

package/src/qemu-config-absence.test.ts

@@ -0,0 +1,75 @@
+/**
+ * QEMU absence is the config-file sentence from AbstractConfig, not every 500.
+ * qemu-server Qemu.pm routes GET/PUT through `{vmid}/config` and DELETE through `{vmid}`.
+ */
+import { describe, expect, test } from "bun:test";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import { credentials } from "./credentials.ts";
+import type { ProxmoxOpContext } from "./protocol.ts";
+import * as Retry from "./retry.ts";
+import { deleteNodeQemu, getNodeQemuConfig } from "./services/nodes.ts";
+
+const call = <A, E>(
+  op: Effect.Effect<A, E, ProxmoxOpContext>,
+  status: number,
+  body: unknown,
+) =>
+  Effect.runPromise(
+    op.pipe(
+      Retry.none,
+      Effect.provide(
+        credentials({
+          baseUrl: "https://pve.test:8006",
+          tokenId: "test@pve!test",
+          secret: "fake",
+        }),
+      ),
+      Effect.provide(
+        Layer.succeed(
+          HttpClient.HttpClient,
+          HttpClient.make((request) =>
+            Effect.succeed(
+              HttpClientResponse.fromWeb(
+                request,
+                Response.json(body, { status }),
+              ),
+            ),
+          ),
+        ),
+      ),
+      Effect.flip,
+    ),
+  );
+
+const missing = {
+  data: null,
+  message: "Configuration file 'nodes/pve1/qemu-server/150.conf' does not exist\n",
+};
+
+describe("QEMU config absence", () => {
+  test("config GET and guest DELETE share the missing-file tag", async () => {
+    expect(
+      await call(getNodeQemuConfig({ node: "pve1", vmid: "150" }), 500, missing),
+    ).toMatchObject({ _tag: "QemuConfigNotFound" });
+    expect(
+      await call(deleteNodeQemu({ node: "pve1", vmid: "150" }), 500, missing),
+    ).toMatchObject({ _tag: "QemuConfigNotFound" });
+  });
+
+  test("a container path, a running guest, and a bare 500 stay unrelated", async () => {
+    for (const message of [
+      "Configuration file 'nodes/pve1/lxc/150.conf' does not exist\n",
+      "VM 150 is running - destroy failed\n",
+      "unrelated failure",
+    ]) {
+      const error = await call(getNodeQemuConfig({ node: "pve1", vmid: "150" }), 500, {
+        data: null,
+        message,
+      });
+      expect(error).toMatchObject({ _tag: "InternalServerError" });
+    }
+  });
+});

package/src/services/cluster.ts

@@ -33,6 +33,32 @@ export class FirewallAliasNotFound
     [{ status: 400, message: { matches: "^no such alias$" } }],
   ) {}
 
+/** The HA resource does not exist. pve-ha-manager 5.2.5, 28c31e4124ab2440753e7bf843c4dba97637aed8, PVE/API2/HA/Resources.pm:27 (GET, via the read method at line 179) raises no such resource '<sid>', and line 320 (DELETE) raises cannot delete service '<sid>', not HA managed. Both are wire 500. PUT does not raise either sentence and is not attached. */
+export class HaResourceNotFound
+  extends /*@__PURE__*/ T.applyErrorMatchers(
+    /*@__PURE__*/ S.TaggedError<HaResourceNotFound>()("HaResourceNotFound", {
+      message: S.String,
+    }).pipe(C.withBadRequestError),
+    [
+      { status: 500, message: { matches: "^no such resource '[^']+'\\n?$" } },
+      {
+        status: 500,
+        message: {
+          matches: "^cannot delete service '[^']+', not HA managed!\\n?$",
+        },
+      },
+    ],
+  ) {}
+
+/** The HA rule does not exist. pve-ha-manager 5.2.5, 28c31e4124ab2440753e7bf843c4dba97637aed8, PVE/API2/HA/Rules.pm:25 (GET, via the read method at line 247) raises no such ha rule '<ruleid>' as a wire 500. DELETE removes the id with no absence check and is not attached. PUT of a missing rule raises a different sentence and is not this tag. */
+export class HaRuleNotFound
+  extends /*@__PURE__*/ T.applyErrorMatchers(
+    /*@__PURE__*/ S.TaggedError<HaRuleNotFound>()("HaRuleNotFound", {
+      message: S.String,
+    }).pipe(C.withBadRequestError),
+    [{ status: 500, message: { matches: "^no such ha rule '[^']+'\\n?$" } }],
+  ) {}
+
 /** The metrics server does not exist. pve-manager 9.2.11, f6997e698c7933ea8e62319e2bf1bf7262daa56a, PVE/API2/Cluster/MetricServer.pm:136 throws status server entry '<id>' does not exist on GET, and line 228 throws no such server '<id>' on PUT. Both are wire 500. DELETE dereferences the plugin config without an explicit absence check and is not declared to return this tag. */
 export class MetricServerNotFound
   extends /*@__PURE__*/ T.applyErrorMatchers(
@@ -15366,7 +15392,7 @@ export const deleteClusterHaGroup: API.OperationMethod<
   retry: Retry.Retry,
 }));
 
-export type DeleteClusterHaResourceError = ProxmoxOpError;
+export type DeleteClusterHaResourceError = HaResourceNotFound | ProxmoxOpError;
 /** Delete resource configuration. (root-privileged endpoint) */
 export const deleteClusterHaResource: API.OperationMethod<
   DeleteClusterHaResourceRequest,
@@ -15376,7 +15402,7 @@ export const deleteClusterHaResource: API.OperationMethod<
 > = /*@__PURE__*/ API.make(() => ({
   input: DeleteClusterHaResourceRequest,
   output: DeleteClusterHaResourceResponse,
-  errors: [],
+  errors: [HaResourceNotFound],
   protocol: ProxmoxProtocol,
   retry: Retry.Retry,
 }));
@@ -16107,7 +16133,7 @@ export const getClusterHaGroup: API.OperationMethod<
   retry: Retry.Retry,
 }));
 
-export type GetClusterHaResourceError = ProxmoxOpError;
+export type GetClusterHaResourceError = HaResourceNotFound | ProxmoxOpError;
 /** Read resource configuration. */
 export const getClusterHaResource: API.OperationMethod<
   GetClusterHaResourceRequest,
@@ -16117,12 +16143,12 @@ export const getClusterHaResource: API.OperationMethod<
 > = /*@__PURE__*/ API.make(() => ({
   input: GetClusterHaResourceRequest,
   output: GetClusterHaResourceResponse,
-  errors: [],
+  errors: [HaResourceNotFound],
   protocol: ProxmoxProtocol,
   retry: Retry.Retry,
 }));
 
-export type GetClusterHaRuleError = ProxmoxOpError;
+export type GetClusterHaRuleError = HaRuleNotFound | ProxmoxOpError;
 /** Read HA rule. */
 export const getClusterHaRule: API.OperationMethod<
   GetClusterHaRuleRequest,
@@ -16132,7 +16158,7 @@ export const getClusterHaRule: API.OperationMethod<
 > = /*@__PURE__*/ API.make(() => ({
   input: GetClusterHaRuleRequest,
   output: GetClusterHaRuleResponse,
-  errors: [],
+  errors: [HaRuleNotFound],
   protocol: ProxmoxProtocol,
   retry: Retry.Retry,
 }));

package/src/services/nodes.ts

@@ -67,6 +67,23 @@ export class LxcConfigNotFound
     ],
   ) {}
 
+/** qemu-server PVE/API2/Qemu.pm vm_config GET and destroy_vm both call QemuConfig->load_config. pve-guest-common AbstractConfig.pm load_config dies when the cfs file is missing: Configuration file '$cfspath' does not exist. QemuConfig's path is nodes/$node/qemu-server/$vmid.conf, HTTP 500. A missing file on this node is not a free cluster-wide vmid. */
+export class QemuConfigNotFound
+  extends /*@__PURE__*/ T.applyErrorMatchers(
+    /*@__PURE__*/ S.TaggedError<QemuConfigNotFound>()("QemuConfigNotFound", {
+      message: S.String,
+    }).pipe(C.withBadRequestError),
+    [
+      {
+        status: 500,
+        message: {
+          matches:
+            "^Configuration file 'nodes/[^/']+/qemu-server/[0-9]+\\.conf' does not exist\\n?$",
+        },
+      },
+    ],
+  ) {}
+
 /** pve-manager 9.2.11, PVE/API2/Network.pm. GET (network_config) and PUT (update_network) both raise HTTP 400 with exactly errors.iface = interface does not exist -- verified against the live n2 source on 2026-09-25. DELETE (delete_network) raises it too but is left untyped: no generated deleteNodeNetwork2 caller exists yet. Only the exact sole-field detail is normalized for operation matching; all other validation errors remain ParameterVerificationFailed. Attached to GET and PUT. */
 export class NetworkInterfaceNotFound
   extends /*@__PURE__*/ T.applyErrorMatchers(
@@ -12574,9 +12591,28 @@ export const ListNodeNetworkResponseBodyList = /*@__PURE__*/ S.Array(
   ListNodeNetworkResponseBodyItem,
 ) as any as S.Schema<ListNodeNetworkResponseBodyList>;
 
-export type ListNodeNetworkResponse = ListNodeNetworkResponseBodyList;
+/** Present only when PVE staged an interfaces diff. The string can contain secrets. */
+export interface ListNodeNetworkPendingResponse {
+  data: ListNodeNetworkResponseBodyList;
+  changes: string;
+}
+export const ListNodeNetworkPendingResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    data: ListNodeNetworkResponseBodyList,
+    changes: S.String,
+  }),
+).annotate({
+  identifier: "ListNodeNetworkPendingResponse",
+}) as any as S.Schema<ListNodeNetworkPendingResponse>;
+
+export type ListNodeNetworkResponse =
+  | ListNodeNetworkResponseBodyList
+  | ListNodeNetworkPendingResponse;
 export const ListNodeNetworkResponse = /*@__PURE__*/ S.suspend(() =>
-  ListNodeNetworkResponseBodyList.pipe(T.RawResponseRoot()),
+  S.Union([
+    ListNodeNetworkResponseBodyList.pipe(T.RawResponseRoot()),
+    ListNodeNetworkPendingResponse,
+  ]),
 ).annotate({
   identifier: "ListNodeNetworkResponse",
 }) as any as S.Schema<ListNodeNetworkResponse>;
@@ -21547,7 +21583,7 @@ export const deleteNodeNetwork2: API.OperationMethod<
   retry: Retry.Retry,
 }));
 
-export type DeleteNodeQemuError = ProxmoxOpError;
+export type DeleteNodeQemuError = QemuConfigNotFound | ProxmoxOpError;
 /** Destroy the VM and all used/owned volumes. Removes any VM specific permissions and firewall rules (root-privileged endpoint) */
 export const deleteNodeQemu: API.OperationMethod<
   DeleteNodeQemuRequest,
@@ -21557,7 +21593,7 @@ export const deleteNodeQemu: API.OperationMethod<
 > = /*@__PURE__*/ API.make(() => ({
   input: DeleteNodeQemuRequest,
   output: DeleteNodeQemuResponse,
-  errors: [],
+  errors: [QemuConfigNotFound],
   protocol: ProxmoxProtocol,
   retry: Retry.Retry,
 }));
@@ -22566,7 +22602,7 @@ export const getNodeQemuCloudinitDump: API.OperationMethod<
   retry: Retry.Retry,
 }));
 
-export type GetNodeQemuConfigError = ProxmoxOpError;
+export type GetNodeQemuConfigError = QemuConfigNotFound | ProxmoxOpError;
 /** Get the virtual machine configuration with pending configuration changes applied. Set the 'current' parameter to get the current configuration instead. */
 export const getNodeQemuConfig: API.OperationMethod<
   GetNodeQemuConfigRequest,
@@ -22576,7 +22612,7 @@ export const getNodeQemuConfig: API.OperationMethod<
 > = /*@__PURE__*/ API.make(() => ({
   input: GetNodeQemuConfigRequest,
   output: GetNodeQemuConfigResponse,
-  errors: [],
+  errors: [QemuConfigNotFound],
   protocol: ProxmoxProtocol,
   retry: Retry.Retry,
 }));