@homeflare/distilled-proxmox-backup 0.2.0 → 0.3.1

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);

package/src/services/access.ts

@@ -189,14 +189,9 @@ export const DeleteAccessTfaRequest = /*@__PURE__*/ S.suspend(() =>
   S.Struct({
     userid: S.String.pipe(T.Label()),
     id: S.String.pipe(T.Label()),
-    password: S.optional(S.String),
+    password: S.optional(S.String.pipe(T.Query())),
   }).pipe(
-    T.Http({
-      method: "DELETE",
-      uri: "/access/tfa/{userid}/{id}",
-      code: 200,
-      contentType: "form-urlencoded",
-    }),
+    T.Http({ method: "DELETE", uri: "/access/tfa/{userid}/{id}", code: 200 }),
   ),
 ).annotate({
   identifier: "DeleteAccessTfaRequest",
@@ -233,14 +228,9 @@ export interface DeleteAccessUserRequest {
 export const DeleteAccessUserRequest = /*@__PURE__*/ S.suspend(() =>
   S.Struct({
     userid: S.String.pipe(T.Label()),
-    digest: S.optional(S.String),
+    digest: S.optional(S.String.pipe(T.Query())),
   }).pipe(
-    T.Http({
-      method: "DELETE",
-      uri: "/access/users/{userid}",
-      code: 200,
-      contentType: "form-urlencoded",
-    }),
+    T.Http({ method: "DELETE", uri: "/access/users/{userid}", code: 200 }),
   ),
 ).annotate({
   identifier: "DeleteAccessUserRequest",
@@ -263,13 +253,12 @@ export const DeleteAccessUserTokenRequest = /*@__PURE__*/ S.suspend(() =>
   S.Struct({
     userid: S.String.pipe(T.Label()),
     token_name: S.String.pipe(T.Label()),
-    digest: S.optional(S.String),
+    digest: S.optional(S.String.pipe(T.Query())),
   }).pipe(
     T.Http({
       method: "DELETE",
       uri: "/access/users/{userid}/token/{token-name}",
       code: 200,
-      contentType: "form-urlencoded",
     }),
   ),
 ).annotate({

package/src/services/admin.ts

@@ -324,18 +324,19 @@ export interface DeleteAdminDatastoreGroupsRequest {
 export const DeleteAdminDatastoreGroupsRequest = /*@__PURE__*/ S.suspend(() =>
   S.Struct({
     store: S.String.pipe(T.Label()),
-    backup_id: S.String.pipe(T.Body("backup-id")),
+    backup_id: S.String.pipe(T.Query("backup-id")),
     backup_type: DeleteAdminDatastoreGroupsRequestBackupType.pipe(
-      T.Body("backup-type"),
+      T.Query("backup-type"),
     ),
-    error_on_protected: S.optional(S.String.pipe(T.Body("error-on-protected"))),
-    ns: S.optional(S.String),
+    error_on_protected: S.optional(
+      S.String.pipe(T.Query("error-on-protected")),
+    ),
+    ns: S.optional(S.String.pipe(T.Query())),
   }).pipe(
     T.Http({
       method: "DELETE",
       uri: "/admin/datastore/{store}/groups",
       code: 200,
-      contentType: "form-urlencoded",
     }),
   ),
 ).annotate({
@@ -372,17 +373,16 @@ export const DeleteAdminDatastoreNamespaceRequest = /*@__PURE__*/ S.suspend(
   () =>
     S.Struct({
       store: S.String.pipe(T.Label()),
-      delete_groups: S.optional(S.String.pipe(T.Body("delete-groups"))),
+      delete_groups: S.optional(S.String.pipe(T.Query("delete-groups"))),
       error_on_protected: S.optional(
-        S.String.pipe(T.Body("error-on-protected")),
+        S.String.pipe(T.Query("error-on-protected")),
       ),
-      ns: S.String,
+      ns: S.String.pipe(T.Query()),
     }).pipe(
       T.Http({
         method: "DELETE",
         uri: "/admin/datastore/{store}/namespace",
         code: 200,
-        contentType: "form-urlencoded",
       }),
     ),
 ).annotate({
@@ -417,18 +417,17 @@ export const DeleteAdminDatastoreSnapshotsRequest = /*@__PURE__*/ S.suspend(
   () =>
     S.Struct({
       store: S.String.pipe(T.Label()),
-      backup_id: S.String.pipe(T.Body("backup-id")),
-      backup_time: S.String.pipe(T.Body("backup-time")),
+      backup_id: S.String.pipe(T.Query("backup-id")),
+      backup_time: S.String.pipe(T.Query("backup-time")),
       backup_type: DeleteAdminDatastoreSnapshotsRequestBackupType.pipe(
-        T.Body("backup-type"),
+        T.Query("backup-type"),
       ),
-      ns: S.optional(S.String),
+      ns: S.optional(S.String.pipe(T.Query())),
     }).pipe(
       T.Http({
         method: "DELETE",
         uri: "/admin/datastore/{store}/snapshots",
         code: 200,
-        contentType: "form-urlencoded",
       }),
     ),
 ).annotate({