@homeflare/distilled-proxmox-backup 0.3.0 → 0.3.1

package/package.json

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

package/src/errors.ts

@@ -37,12 +37,8 @@ export {
   API_ERRORS,
 } from "@distilled.cloud/core/errors";
 // `export { X } from "mod"` (above) is a RE-EXPORT ONLY — it creates no local
-// binding for `X`, so `BadRequest` needs its own `import type` to be usable
-// in this file's own `DefaultErrors` union below.
-import type {
-  BadRequest,
-  DefaultErrors as CoreDefaultErrors,
-} from "@distilled.cloud/core/errors";
+// binding for `X`, so the API error tuple needs a type import for its union below.
+import type { API_ERRORS } from "@distilled.cloud/core/errors";
 
 import * as Schema from "effect/Schema";
 import * as Category from "@distilled.cloud/core/category";
@@ -115,12 +111,12 @@ export class ProxmoxBackupTaskFailed extends Schema.TaggedError<ProxmoxBackupTas
 export type ClientErrors = UnknownProxmoxBackupError | ProxmoxBackupParseError;
 
 /**
- * Default Proxmox Backup Server operation errors: the shared HTTP status
- * errors from core, PBS's global parameter-verification failure, plus the
- * client-level fallback/decode errors.
+ * Every status class the protocol's HTTP_STATUS_MAP may return, plus PBS failures.
+ * Core's DefaultErrors is only its infrastructure subset; using that here hid mapped
+ * NotFound/Forbidden/Conflict from the typed operation union, so a legitimate catchTag
+ * could not compile even though that exact error was returned at runtime.
  */
 export type DefaultErrors =
-  | CoreDefaultErrors
-  | BadRequest
+  | InstanceType<(typeof API_ERRORS)[number]>
   | ParameterVerificationFailed
   | ClientErrors;

package/src/missing-resource.test.ts

@@ -0,0 +1,98 @@
+/** Read-only PBS wire measurements, 2026-09-24: missing config items use plain-text 400. */
+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 { ProxmoxBackupOpContext } from "./protocol.ts";
+import * as Retry from "./retry.ts";
+import * as config from "./services/config.ts";
+
+const testCredentials = credentials({
+  tokenId: "backup@pbs!test",
+  secret: "test-secret",
+  baseUrl: "https://pbs.test:8007",
+});
+const failure = (
+  op: Effect.Effect<unknown, unknown, ProxmoxBackupOpContext>,
+  status: number,
+  body: string,
+) =>
+  Effect.runPromise(
+    op.pipe(
+      Retry.none,
+      Effect.provide(
+        Layer.mergeAll(
+          testCredentials,
+          Layer.succeed(
+            HttpClient.HttpClient,
+            HttpClient.make((request) =>
+              Effect.succeed(
+                HttpClientResponse.fromWeb(
+                  request,
+                  new Response(body, { status }),
+                ),
+              ),
+            ),
+          ),
+        ),
+      ),
+      Effect.flip,
+    ),
+  );
+const absent = "hf-absent-sdk-0924";
+const cases = [
+  {
+    op: config.getConfigDatastore({ name: absent }),
+    kind: "datastore",
+    tag: "DatastoreNotFound",
+  },
+  {
+    op: config.getConfigPrune({ id: absent }),
+    kind: "prune",
+    tag: "PruneJobNotFound",
+  },
+  {
+    op: config.getConfigSync({ id: absent }),
+    kind: "sync",
+    tag: "SyncJobNotFound",
+  },
+  {
+    op: config.getConfigVerify({ id: absent }),
+    kind: "verification",
+    tag: "VerifyJobNotFound",
+  },
+] as const;
+
+describe("PBS resource absence", () => {
+  for (const { op, kind, tag } of cases) {
+    test(`${kind}: exact measured 400 is a typed missing resource`, async () => {
+      expect(
+        await failure(op, 400, `no such ${kind} '${absent}'`),
+      ).toMatchObject({ _tag: tag });
+    });
+    test(`${kind}: a different status, kind or extended error is not absence`, async () => {
+      for (const [status, body] of [
+        [403, `no such ${kind} '${absent}'`],
+        [500, `no such ${kind} '${absent}'`],
+        [400, "no such unrelated 'id'"],
+        [400, `no such ${kind} '${absent}': configuration unreadable`],
+        [400, "parameter verification failed"],
+      ] as const) {
+        expect(await failure(op, status, body)).not.toMatchObject({
+          _tag: tag,
+        });
+      }
+    });
+  }
+  test("missing text is scoped to the named GET operation", async () => {
+    expect(
+      await failure(
+        config.listConfigDatastore({}),
+        400,
+        `no such datastore '${absent}'`,
+      ),
+    ).not.toMatchObject({ _tag: "DatastoreNotFound" });
+  });
+});

package/src/protocol-boundaries.test.ts

@@ -0,0 +1,60 @@
+/** The PBS adapter preserves core's decoded-value and nested-form contracts. */
+import { expect, test } from "bun:test";
+import * as API from "@distilled.cloud/core/api";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import { withPbsCodecs } from "./protocol-codecs.ts";
+
+const request = HttpClientRequest.post("https://pbs.test/config").pipe(
+  HttpClientRequest.bodyUrlParams([
+    ["target[0]", "mail"],
+    ["target[1]", "hook"],
+    ["nested[targets][0]", "keep"],
+    ["scalar", "a,b"],
+  ]),
+);
+const base = Layer.succeed(
+  API.Protocol,
+  API.Protocol.of({
+    encode: () => Effect.succeed(request),
+    decode: () => Effect.succeed(42),
+  }),
+);
+const protocol = withPbsCodecs(base);
+
+test("only top-level indexed form lists change", async () => {
+  const encoded = await Effect.runPromise(
+    Effect.gen(function* () {
+      const adapter = yield* API.Protocol;
+      return yield* adapter.encode({
+        input: {},
+        inputAst: Schema.Unknown.ast,
+        config: {},
+      });
+    }).pipe(Effect.provide(protocol)),
+  );
+  expect(encoded.body._tag).toBe("Uint8Array");
+  if (encoded.body._tag !== "Uint8Array") return;
+  const form = new URLSearchParams(new TextDecoder().decode(encoded.body.body));
+  expect(form.getAll("target")).toEqual(["mail", "hook"]);
+  expect(form.get("nested[targets][0]")).toBe("keep");
+  expect(form.get("scalar")).toBe("a,b");
+});
+
+test("core-decoded output is validated on the Type side without decoding twice", async () => {
+  const result = await Effect.runPromise(
+    Effect.gen(function* () {
+      const adapter = yield* API.Protocol;
+      return yield* adapter.decode({
+        response: HttpClientResponse.fromWeb(request, new Response("42")),
+        outputAst: Schema.NumberFromString.ast,
+        config: { output: Schema.NumberFromString },
+        errors: [],
+      });
+    }).pipe(Effect.provide(protocol)),
+  );
+  expect(result).toBe(42);
+});

package/src/protocol-codecs.test.ts

@@ -0,0 +1,112 @@
+import { 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 type { HttpClientRequest } from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import { credentials } from "./credentials.ts";
+import * as Retry from "./retry.ts";
+import {
+  getConfigNotificationMatcher,
+  putConfigNotificationMatcher,
+} from "./services/config.ts";
+
+const credential = credentials({
+  baseUrl: "https://pbs.test:8007",
+  tokenId: "test@pbs!fake",
+  secret: "fake-not-real",
+});
+
+const fakePbs = (body: unknown, see?: (request: HttpClientRequest) => void) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.sync(() => {
+        see?.(request);
+        return HttpClientResponse.fromWeb(
+          request,
+          Response.json({ data: body }),
+        );
+      }),
+    ),
+  );
+
+test("PBS arrays use repeated keys and Unit data:null remains a successful write", async () => {
+  let pairs: [string, string][] = [];
+  const client = fakePbs(null, (request) => {
+    expect(request.body._tag).toBe("Uint8Array");
+    if (request.body._tag === "Uint8Array") {
+      pairs = [
+        ...new URLSearchParams(new TextDecoder().decode(request.body.body)),
+      ];
+    }
+  });
+  await Effect.runPromise(
+    putConfigNotificationMatcher({
+      name: "pager",
+      target: ["mail-to-root", "hook"],
+      delete: ["match-field", "match-calendar"],
+    }).pipe(Retry.none, Effect.provide(Layer.mergeAll(client, credential))),
+  );
+  expect(pairs.filter(([key]) => key === "target")).toEqual([
+    ["target", "mail-to-root"],
+    ["target", "hook"],
+  ]);
+  expect(pairs.filter(([key]) => key === "delete")).toEqual([
+    ["delete", "match-field"],
+    ["delete", "match-calendar"],
+  ]);
+});
+
+for (const body of [null, { comment: "secret-like-text-must-not-appear" }]) {
+  test("incomplete resource output fails without exposing response contents", async () => {
+    const error = await Effect.runPromise(
+      getConfigNotificationMatcher({ name: "pager" }).pipe(
+        Retry.none,
+        Effect.flip,
+        Effect.provide(Layer.mergeAll(fakePbs(body), credential)),
+      ),
+    );
+    expect(error).toMatchObject({ _tag: "ProxmoxBackupParseError" });
+    expect(JSON.stringify(error)).not.toContain(
+      "secret-like-text-must-not-appear",
+    );
+  });
+}
+
+test("valid resource output preserves fields omitted from the vendor schema", async () => {
+  const result = await Effect.runPromise(
+    getConfigNotificationMatcher({ name: "pager" }).pipe(
+      Retry.none,
+      Effect.provide(
+        Layer.mergeAll(
+          fakePbs({ name: "pager", future_field: "keep-me" }),
+          credential,
+        ),
+      ),
+    ),
+  );
+  expect(result).toMatchObject({ name: "pager", future_field: "keep-me" });
+});
+
+test("mapped NotFound is in the operation's typed union, including a plain-text response", async () => {
+  const client = Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          new Response("matcher 'pager' not found", { status: 404 }),
+        ),
+      ),
+    ),
+  );
+  const result = await Effect.runPromise(
+    getConfigNotificationMatcher({ name: "pager" }).pipe(
+      Retry.none,
+      Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+      Effect.provide(Layer.mergeAll(client, credential)),
+    ),
+  );
+  expect(result).toBeUndefined();
+});

package/src/protocol-codecs.ts

@@ -0,0 +1,75 @@
+/**
+ * PBS 4.2.6-1's form arrays and successful response validation.
+ *
+ * The vendor's array parameters are repeated keys (`target=a&target=b`), not the Stripe
+ * bracket-index encoding used by core's generic REST builder. Measured against the PBS
+ * notification provider's existing protocol fixtures, 2026-09-24: indexed headers/secrets
+ * disappear from its read-back, and matchers perpetually drift. Preserve core path/auth/key
+ * mapping and adapt only its top-level indexed form fields at this vendor boundary.
+ */
+import * as API from "@distilled.cloud/core/api";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import { ProxmoxBackupParseError } from "./errors.ts";
+
+const repeatedFormKeys = (request: HttpClientRequest.HttpClientRequest) => {
+  if (
+    request.body._tag !== "Uint8Array" ||
+    request.body.contentType !== "application/x-www-form-urlencoded"
+  )
+    return request;
+  const fields = new URLSearchParams(
+    new TextDecoder().decode(request.body.body),
+  );
+  const repeated: [string, string][] = [];
+  for (const [key, value] of fields) {
+    repeated.push([key.replace(/^([^\[\]]+)\[\d+\]$/, "$1"), value]);
+  }
+  return HttpClientRequest.bodyUrlParams(request, repeated);
+};
+
+/**
+ * Core REST decode maps wire keys but does not validate required fields. In particular,
+ * PBS data:null unwrapped to {} used to look like a real resource to a caller. Validate
+ * with the operation's generated schema: Unit operations still accept {}, while a GET
+ * missing its required name/id fails. Preserve the mapped payload after validation: vendor
+ * fields absent from the published schema must not silently disappear. Core has already
+ * decoded the payload, so validate the schema's Type side instead of re-decoding transforms.
+ * Keep server data out of the parse error: notification responses can contain header
+ * credentials, and a schema diagnostic can reproduce them.
+ */
+export const withPbsCodecs = (
+  base: Layer.Layer<API.Protocol>,
+): Layer.Layer<API.Protocol> =>
+  Layer.effect(
+    API.Protocol,
+    Effect.gen(function* () {
+      const protocol = yield* API.Protocol;
+      return API.Protocol.of({
+        encode: (args) =>
+          protocol.encode(args).pipe(Effect.map(repeatedFormKeys)),
+        decode: (args) =>
+          protocol.decode(args).pipe(
+            Effect.flatMap((body) =>
+              args.config.output === undefined
+                ? Effect.succeed(body)
+                : (Schema.decodeUnknownEffect(
+                    Schema.toType(args.config.output),
+                  )(body).pipe(
+                    Effect.as(body),
+                    Effect.mapError(
+                      () =>
+                        new ProxmoxBackupParseError({
+                          body: undefined,
+                          cause:
+                            "Response does not match the operation's declared output schema",
+                        }),
+                    ),
+                  ) as Effect.Effect<unknown>),
+            ),
+          ),
+      });
+    }),
+  ).pipe(Layer.provide(base));

package/src/protocol-raw-root.test.ts

@@ -0,0 +1,84 @@
+import { 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 { ProxmoxBackupOpContext } from "./protocol.ts";
+import * as Retry from "./retry.ts";
+import {
+  deleteConfigDatastore,
+  getConfigAcmeTos,
+  listConfigDatastore,
+} from "./services/config.ts";
+
+const run = <A, E>(
+  operation: Effect.Effect<A, E, ProxmoxBackupOpContext>,
+  data: unknown,
+) =>
+  Effect.runPromise(
+    operation.pipe(
+      Retry.none,
+      Effect.provide(
+        Layer.mergeAll(
+          credentials({
+            baseUrl: "https://pbs.test:8007",
+            tokenId: "test@pbs!fake",
+            secret: "fake-not-real",
+          }),
+          Layer.succeed(
+            HttpClient.HttpClient,
+            HttpClient.make((request) =>
+              Effect.succeed(
+                HttpClientResponse.fromWeb(request, Response.json({ data })),
+              ),
+            ),
+          ),
+        ),
+      ),
+    ),
+  );
+
+test("raw-root string responses retain task IDs and ACME terms URLs", async () => {
+  const upid =
+    "UPID:pbs:00000001:00000002:00000003:delete-datastore:test:root@pam:";
+  expect(await run(deleteConfigDatastore({ name: "test" }), upid)).toBe(upid);
+  const url = "https://acme.test/terms";
+  expect(await run(getConfigAcmeTos({}), url)).toBe(url);
+});
+
+test("raw-root lists retain empty lists, map wire keys, and preserve extra fields", async () => {
+  expect(await run(listConfigDatastore({}), [])).toEqual([]);
+  const expected = [
+    { name: "test", path: "/backup/test", keep_last: 2, future_field: "keep" },
+  ];
+  expect(
+    await run(listConfigDatastore({}), [
+      {
+        name: "test",
+        path: "/backup/test",
+        "keep-last": 2,
+        future_field: "keep",
+      },
+    ]),
+  ).toEqual(expected);
+});
+
+// These operations are not Unit responses: null must not become a valid empty object.
+for (const data of [null, {}]) {
+  test(`raw-root operations reject ${JSON.stringify(data)} instead of accepting missing output`, async () => {
+    const operations: Effect.Effect<
+      unknown,
+      unknown,
+      ProxmoxBackupOpContext
+    >[] = [
+      deleteConfigDatastore({ name: "test" }),
+      getConfigAcmeTos({}),
+      listConfigDatastore({}),
+    ];
+    for (const operation of operations) {
+      const error = await run(Effect.flip(operation), data);
+      expect(error).toMatchObject({ _tag: "ProxmoxBackupParseError" });
+    }
+  });
+}

package/src/protocol.ts

@@ -89,6 +89,7 @@ import {
   type RestErrorEnvelope,
 } from "@distilled.cloud/core/protocol-rest";
 import { Credentials, type Config } from "./credentials.ts";
+import { withPbsCodecs } from "./protocol-codecs.ts";
 import {
   ParameterVerificationFailed,
   UnknownProxmoxBackupError,
@@ -132,65 +133,68 @@ const PROXMOX_BACKUP_STATUS_MAP: Record<number, new (args: any) => unknown> = {
 };
 delete (PROXMOX_BACKUP_STATUS_MAP as Record<number, unknown>)[400];
 
-export const ProxmoxBackupProtocol: Layer.Layer<API.Protocol> =
-  makeRestProtocol<Config>({
-    credentials: Effect.gen(function* () {
-      const resolve = yield* Credentials;
-      return yield* resolve;
-    }),
-    baseUrl: (creds) => creds.apiBaseUrl,
-    headers: (creds) => ({
-      // ⛔ COLON, NOT `=` — see the module header's Authentication section.
-      Authorization: `PBSAPIToken=${creds.tokenId}:${Redacted.value(creds.secret)}`,
-      Accept: "application/json",
-    }),
-    errorEnvelope,
-    statusMap: PROXMOX_BACKUP_STATUS_MAP,
-    // Unwrap PBS'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".
-    transformResponse: (body) => {
+const baseProtocol: Layer.Layer<API.Protocol> = makeRestProtocol<Config>({
+  credentials: Effect.gen(function* () {
+    const resolve = yield* Credentials;
+    return yield* resolve;
+  }),
+  baseUrl: (creds) => creds.apiBaseUrl,
+  headers: (creds) => ({
+    // ⛔ COLON, NOT `=` — see the module header's Authentication section.
+    Authorization: `PBSAPIToken=${creds.tokenId}:${Redacted.value(creds.secret)}`,
+    Accept: "application/json",
+  }),
+  errorEnvelope,
+  statusMap: PROXMOX_BACKUP_STATUS_MAP,
+  // Unwrap PBS'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".
+  transformResponse: (body) => {
+    if (
+      body !== null &&
+      typeof body === "object" &&
+      "data" in (body as Record<string, unknown>)
+    ) {
+      return (body as Record<string, unknown>).data ?? {};
+    }
+    return body;
+  },
+  // Reached for a 400 (see PROXMOX_BACKUP_STATUS_MAP above) or a status
+  // with no core mapping at all. `body` is the FULL parsed failure
+  // envelope, so this is where PBS's per-field `errors` object is read.
+  //
+  // ⛔ A BARE 400 WITHOUT THE `errors` OBJECT MUST NOT FALL INTO
+  //   `UnknownProxmoxBackupError` — same retry-amplification hazard
+  //   PVE's identical comment explains (`ServerError` is retried
+  //   automatically; a malformed request is permanent). `BadRequest`
+  //   (`Category.withBadRequestError`, not retryable) is the honest
+  //   answer for "PBS said 400 and gave no further structure".
+  unknownError: ({ status, message, body }) => {
+    const b =
+      body !== null && typeof body === "object"
+        ? (body as Record<string, unknown>)
+        : undefined;
+    const fieldErrors = b?.errors;
+    if (status === 400) {
       if (
-        body !== null &&
-        typeof body === "object" &&
-        "data" in (body as Record<string, unknown>)
+        fieldErrors !== null &&
+        typeof fieldErrors === "object" &&
+        !Array.isArray(fieldErrors)
       ) {
-        return (body as Record<string, unknown>).data ?? {};
-      }
-      return body;
-    },
-    // Reached for a 400 (see PROXMOX_BACKUP_STATUS_MAP above) or a status
-    // with no core mapping at all. `body` is the FULL parsed failure
-    // envelope, so this is where PBS's per-field `errors` object is read.
-    //
-    // ⛔ A BARE 400 WITHOUT THE `errors` OBJECT MUST NOT FALL INTO
-    //   `UnknownProxmoxBackupError` — same retry-amplification hazard
-    //   PVE's identical comment explains (`ServerError` is retried
-    //   automatically; a malformed request is permanent). `BadRequest`
-    //   (`Category.withBadRequestError`, not retryable) is the honest
-    //   answer for "PBS said 400 and gave no further structure".
-    unknownError: ({ status, message, body }) => {
-      const b =
-        body !== null && typeof body === "object"
-          ? (body as Record<string, unknown>)
-          : undefined;
-      const fieldErrors = b?.errors;
-      if (status === 400) {
-        if (
-          fieldErrors !== null &&
-          typeof fieldErrors === "object" &&
-          !Array.isArray(fieldErrors)
-        ) {
-          const errors: Record<string, string> = {};
-          for (const [k, v] of Object.entries(
-            fieldErrors as Record<string, unknown>,
-          )) {
-            if (typeof v === "string") errors[k] = v;
-          }
-          return new ParameterVerificationFailed({ message, errors });
+        const errors: Record<string, string> = {};
+        for (const [k, v] of Object.entries(
+          fieldErrors as Record<string, unknown>,
+        )) {
+          if (typeof v === "string") errors[k] = v;
         }
-        return new BadRequest({ message });
+        return new ParameterVerificationFailed({ message, errors });
       }
-      return new UnknownProxmoxBackupError({ status, message, body });
-    },
-  });
+      return new BadRequest({ message });
+    }
+    return new UnknownProxmoxBackupError({ status, message, body });
+  },
+});
+
+/** PBS-specific form encoding and schema validation wrap core without changing other vendors. */
+export const ProxmoxBackupProtocol: Layer.Layer<API.Protocol> =
+  withPbsCodecs(baseProtocol);