@homeflare/distilled-proxmox-backup 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @distilled.cloud/proxmox-backup — Proxmox Backup Server API SDK for
+ * Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy
+ * models in `.generated-specs` (written by `scripts/convert.ts` from PBS's
+ * own `apidoc.js`, mirrored under `specs/`). Everything else in this
+ * folder is hand-written.
+ *
+ * One module per PBS top-level path segment — `access`, `admin`, `backup`,
+ * `config`, `nodes`, `ping`, `pull`, `push`, `reader`, `root`, `status`,
+ * `tape`, `version` — the same split the vendor's own api-viewer uses
+ * (measured on the pinned schema; see `scripts/convert.ts`'s header for
+ * per-bucket endpoint counts).
+ *
+ * @example
+ * ```ts
+ * import * as ProxmoxBackup from "@distilled.cloud/proxmox-backup";
+ *
+ * const status = yield* ProxmoxBackup.Services.nodes.getNodeTaskStatus({
+ *   node: "pbs1",
+ *   upid: "UPID:pbs1:00001234:...",
+ * });
+ * ```
+ */
+export * from "./credentials.ts";
+export * from "./errors.ts";
+export * as T from "./traits.ts";
+export { ProxmoxBackupProtocol, type ProxmoxBackupOpError, type ProxmoxBackupOpContext, } from "./protocol.ts";
+export * as Retry from "./retry.ts";
+export * as Services from "./services/index.ts";
+export { awaitTask, type TaskRef, type AwaitTaskOptions } from "./task.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,OAAO,KAAK,CAAC,MAAM,aAAa,CAAC;AACjC,OAAO,EACL,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,KAAK,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @distilled.cloud/proxmox-backup — Proxmox Backup Server API SDK for
+ * Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy
+ * models in `.generated-specs` (written by `scripts/convert.ts` from PBS's
+ * own `apidoc.js`, mirrored under `specs/`). Everything else in this
+ * folder is hand-written.
+ *
+ * One module per PBS top-level path segment — `access`, `admin`, `backup`,
+ * `config`, `nodes`, `ping`, `pull`, `push`, `reader`, `root`, `status`,
+ * `tape`, `version` — the same split the vendor's own api-viewer uses
+ * (measured on the pinned schema; see `scripts/convert.ts`'s header for
+ * per-bucket endpoint counts).
+ *
+ * @example
+ * ```ts
+ * import * as ProxmoxBackup from "@distilled.cloud/proxmox-backup";
+ *
+ * const status = yield* ProxmoxBackup.Services.nodes.getNodeTaskStatus({
+ *   node: "pbs1",
+ *   upid: "UPID:pbs1:00001234:...",
+ * });
+ * ```
+ */
+export * from "./credentials.js";
+export * from "./errors.js";
+export * as T from "./traits.js";
+export { ProxmoxBackupProtocol, } from "./protocol.js";
+export * as Retry from "./retry.js";
+export * as Services from "./services/index.js";
+export { awaitTask } from "./task.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,OAAO,KAAK,CAAC,MAAM,aAAa,CAAC;AACjC,OAAO,EACL,qBAAqB,GAGtB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAuC,MAAM,WAAW,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,19 @@
+import type * as Layer from "effect/Layer";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type * as API from "@distilled.cloud/core/api";
+import { type ConfigError } from "@distilled.cloud/core/errors";
+import { Credentials } from "./credentials.ts";
+import { type DefaultErrors } from "./errors.ts";
+/**
+ * Error channel shared by every generated Proxmox Backup Server operation.
+ * Generated service files annotate operations with
+ * `API.OperationMethod<I, O, ProxmoxBackupOpError, ProxmoxBackupOpContext>`
+ * explicitly so the compiler never infers these back out of the schema
+ * generics.
+ */
+export type ProxmoxBackupOpError = DefaultErrors | ConfigError | HttpClientError.HttpClientError;
+/** Context (requirements) shared by every generated Proxmox Backup Server operation. */
+export type ProxmoxBackupOpContext = Credentials | HttpClient.HttpClient;
+export declare const ProxmoxBackupProtocol: Layer.Layer<API.Protocol>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AA4EA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AACnE,OAAO,KAAK,KAAK,eAAe,MAAM,sCAAsC,CAAC;AAC7E,OAAO,KAAK,KAAK,GAAG,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAKtC,OAAO,EAAE,WAAW,EAAe,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC5B,aAAa,GACb,WAAW,GACX,eAAe,CAAC,eAAe,CAAC;AAEpC,wFAAwF;AACxF,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,UAAU,CAAC,UAAU,CAAC;AAwBzE,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CA6DxD,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,158 @@
+/**
+ * ProxmoxBackupProtocol — the shared bearer-REST protocol instantiated for
+ * Proxmox Backup Server. Hand-written; `@distilled.cloud/core` is never
+ * changed for a provider's own quirks — they all live here.
+ *
+ * Ported from `packages/proxmox/src/protocol.ts` in this same distilled
+ * clone. Three of PVE's "THREE 200-TRAPS" carry forward; the fourth
+ * (cluster-forwarding 595) does not exist for PBS — see `src/errors.ts`'s
+ * header. Each trap below cites what was actually checked against the
+ * pinned schema (`~/.cache/homeflare/schemas/proxmox/
+ * pbs_4.2.6-1_apidoc.js`), versus what is carried by same-vendor
+ * architecture and NOT independently measured (this build makes no live
+ * PBS calls).
+ *
+ * ## The envelope
+ *
+ * Every PBS response is wrapped `{"data": …}`, the same as PVE.
+ * ⚠️ NOT independently measured live (no PBS credential exists to call
+ * with). Asserted, not just assumed: `taslabs-net/homeflare-kit`'s
+ * `packages/alchemy/src/proxmox/credentials.ts` documents PVE and PBS
+ * sharing ONE http client specifically BECAUSE "Proxmox Backup Server
+ * speaks the same `/api2/json` paths, wraps every answer in the same
+ * `{"data": …}` envelope" — also written before that repo had a live PBS
+ * credential, so this is the same vendor-architecture inference stated
+ * independently in two places, not two confirmations of one live check.
+ * `transformResponse` below unwraps it before `core/protocol-rest`'s
+ * schema-driven decode ever sees a payload, exactly as PVE's does.
+ *
+ * ## Authentication
+ *
+ * The API-token scheme: `Authorization: PBSAPIToken=<user>@<realm>!
+ * <tokenid>:<secret>` — MEASURED DIFFERENT FROM PVE: a colon separator,
+ * not `=`, and a `PBSAPIToken` prefix, not `PVEAPIToken`. See
+ * `src/credentials.ts`'s header for the two independent citations (kit
+ * `credentials.ts` and `pbs-prune-job.ts`) and their shared caveat
+ * (reasoned from PBS's documented scheme, not a live call either).
+ *
+ * ## THE TRAPS CARRIED FROM PVE (measured against the pinned schema)
+ *
+ * (a) **Async POST/PUT/DELETE answer 200 with a UPID and can fail later.**
+ *     CONFIRMED IN SCHEMA: the pinned file's `pattern` for UPID-shaped
+ *     strings appears 44 times, and `GET /nodes/{node}/tasks/{upid}/status`
+ *     exists (measured: `grep -n 'tasks/{upid}/status'` finds it at line
+ *     25814) — the identical path shape PVE's own `awaitTask` polls.
+ *     Handled with real code: `src/task.ts`'s `awaitTask`, unchanged in
+ *     its `"OK"` exact-equality logic from PVE's (see that file's header
+ *     for why `"OK (warnings)"` must not match a prefix/substring check).
+ *
+ * (b) **Some PUTs answer 200 `{"data":null}` even when nothing changed.**
+ *     CONFIRMED IN SCHEMA: e.g. `PUT /access/acl` and `PUT /access/
+ *     password` both declare `"returns": {"type": "null"}` (measured,
+ *     among 53 total PUT endpoints in the pinned schema) — the same
+ *     declared-null-return signature PVE's update endpoints carry. THIS IS
+ *     NOT SOMETHING A PROTOCOL LAYER CAN DETECT OR FIX; documented here so
+ *     it travels with the protocol.
+ *
+ * (c) **Permission-filtered lists return 200 + `[]` instead of 403.**
+ *     CONFIRMED IN SCHEMA: `GET /access/acl`'s own `permissions.description`
+ *     reads "Returns all ACLs if user has Sys.Audit on '/access/acl', or
+ *     just the ACLs containing the user's API tokens" (measured, line 32
+ *     of the pinned file) — the identical conditional-visibility-by-token
+ *     phrasing the PVE package's header cites for this trap, not a guess
+ *     by analogy. Also undetectable here for the same reason as (b).
+ *
+ * ## NOT carried: cluster-forwarding 595
+ *
+ * See `src/errors.ts`'s header — the pinned schema has zero `proxyto`
+ * occurrences. PBS is not a cluster product.
+ *
+ * ## Self-signed TLS
+ *
+ * Same as PVE: explicitly not handled here or anywhere in this package —
+ * the `HttpClient.HttpClient` layer the caller provides owns that
+ * decision.
+ */
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { BadRequest, HTTP_STATUS_MAP, } from "@distilled.cloud/core/errors";
+import { makeRestProtocol, } from "@distilled.cloud/core/protocol-rest";
+import { Credentials } from "./credentials.js";
+import { ParameterVerificationFailed, UnknownProxmoxBackupError, } from "./errors.js";
+/**
+ * PBS's failure envelope is `{"data": null, "message": "...", "errors"?:
+ * {…}}` — see PVE's identical `errorEnvelope` for why `message` alone is
+ * read here (the `errors` sub-object is read straight from the body in
+ * `unknownError` below, never here).
+ */
+const errorEnvelope = (body) => {
+    if (body === null || typeof body !== "object")
+        return undefined;
+    const b = body;
+    return { message: typeof b.message === "string" ? b.message : undefined };
+};
+/**
+ * `HTTP_STATUS_MAP` minus 400 — same reasoning as PVE's copy: PBS's 400 is
+ * specifically the parameter-verification failure, and the generic
+ * `BadRequest` would throw away the per-field `errors` object.
+ */
+const PROXMOX_BACKUP_STATUS_MAP = {
+    ...HTTP_STATUS_MAP,
+};
+delete PROXMOX_BACKUP_STATUS_MAP[400];
+export const ProxmoxBackupProtocol = makeRestProtocol({
+    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) {
+            return body.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
+            : undefined;
+        const fieldErrors = b?.errors;
+        if (status === 400) {
+            if (fieldErrors !== null &&
+                typeof fieldErrors === "object" &&
+                !Array.isArray(fieldErrors)) {
+                const errors = {};
+                for (const [k, v] of Object.entries(fieldErrors)) {
+                    if (typeof v === "string")
+                        errors[k] = v;
+                }
+                return new ParameterVerificationFailed({ message, errors });
+            }
+            return new BadRequest({ message });
+        }
+        return new UnknownProxmoxBackupError({ status, message, body });
+    },
+});
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.test.d.ts.map

package/dist/protocol.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.test.d.ts","sourceRoot":"","sources":["../src/protocol.test.ts"],"names":[],"mappings":""}

package/dist/protocol.test.js

@@ -0,0 +1,75 @@
+/**
+ * Ported from `packages/proxmox/src/protocol.test.ts` in this same
+ * distilled clone — same bug class, same shape: a bare 400 (no `errors`
+ * object) must decode to the non-retryable `BadRequest`, never the
+ * `Category.withServerError`-tagged `UnknownProxmoxBackupError`. See
+ * `protocol.ts`'s `unknownError` and `errors.ts`'s module header.
+ *
+ * Adds one test PVE's file does not need: the auth header itself, because
+ * that is the one thing measurably different between the two packages
+ * (`PBSAPIToken=<id>:<secret>`, colon separator — see `credentials.ts`'s
+ * header) and a wrong separator fails SILENTLY AS A 401 with no other
+ * symptom, per that same header's citation of the kit's own warning. All
+ * of this runs against a fake `HttpClient` — no live PBS host is
+ * contacted anywhere in this file.
+ */
+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.js";
+import { BadRequest, ParameterVerificationFailed, UnknownProxmoxBackupError, } from "./errors.js";
+import * as Retry from "./retry.js";
+import { getVersion } from "./services/version.js";
+const testCredentials = credentials({
+    tokenId: "backup@pbs!test",
+    secret: "test-secret",
+    baseUrl: "https://pbs.test:8007",
+});
+const fakePbs = (status, body) => Layer.succeed(HttpClient.HttpClient, HttpClient.make((request) => Effect.sync(() => HttpClientResponse.fromWeb(request, new Response(JSON.stringify(body), { status })))));
+const call = (status, body) => Effect.runPromise(getVersion({}).pipe(Retry.none, Effect.provide(Layer.mergeAll(fakePbs(status, body), testCredentials)), Effect.flip));
+describe("protocol.ts error decoding", () => {
+    test("a bare 400 (no `errors` object) is BadRequest, never UnknownProxmoxBackupError", async () => {
+        const error = await call(400, { data: null, message: "invalid parameter" });
+        expect(error).toBeInstanceOf(BadRequest);
+        expect(error).not.toBeInstanceOf(UnknownProxmoxBackupError);
+        expect(error).toMatchObject({ message: "invalid parameter" });
+    });
+    test("a 400 with an `errors` object is ParameterVerificationFailed, carrying the per-field messages", async () => {
+        const error = await call(400, {
+            data: null,
+            message: "parameter verification failed",
+            errors: { comment: "value may only be 128 characters long" },
+        });
+        expect(error).toBeInstanceOf(ParameterVerificationFailed);
+        expect(error).toMatchObject({
+            message: "parameter verification failed",
+            errors: { comment: "value may only be 128 characters long" },
+        });
+    });
+    test("a genuinely unmapped, non-5xx status still falls back to UnknownProxmoxBackupError", async () => {
+        const error = await call(418, { data: null, message: "weird" });
+        expect(error).toBeInstanceOf(UnknownProxmoxBackupError);
+    });
+    test('the {"data": ...} envelope is unwrapped before decode', async () => {
+        const result = await Effect.runPromise(getVersion({}).pipe(Effect.provide(Layer.mergeAll(fakePbs(200, {
+            data: { version: "4.2.6", release: "4.2", repoid: "abc123" },
+        }), testCredentials))));
+        expect(result).toMatchObject({ version: "4.2.6", release: "4.2" });
+    });
+});
+describe("credentials.ts auth header", () => {
+    test("Authorization is PBSAPIToken=<id>:<secret> — colon, never `=` like PVE's PVEAPIToken", async () => {
+        let seenAuth;
+        const capturing = Layer.succeed(HttpClient.HttpClient, HttpClient.make((request) => Effect.sync(() => {
+            seenAuth = request.headers["authorization"];
+            return HttpClientResponse.fromWeb(request, new Response(JSON.stringify({
+                data: { version: "4.2.6", release: "4.2", repoid: "abc" },
+            }), { status: 200 }));
+        })));
+        await Effect.runPromise(getVersion({}).pipe(Effect.provide(Layer.mergeAll(capturing, testCredentials))));
+        expect(seenAuth).toBe("PBSAPIToken=backup@pbs!test:test-secret");
+    });
+});
+//# sourceMappingURL=protocol.test.js.map

package/dist/protocol.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.test.js","sourceRoot":"","sources":["../src/protocol.test.ts"],"names":[],"mappings":"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"}

package/dist/retry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Proxmox Backup Server retry surface — a veneer over
+ * `@distilled.cloud/core/retry`. Copied unchanged from
+ * `packages/proxmox/src/retry.ts` (no vendor-specific logic; only the
+ * Context.Service tag name below is package-local).
+ *
+ * The `Retry` service tag is threaded into every generated operation via
+ * `API.make({ retry: Retry })`, so a caller-installed policy applies to all
+ * Proxmox Backup Server calls below it and core's `makeDefault` is the
+ * fallback when none is provided.
+ *
+ * @example
+ * ```ts
+ * import * as ProxmoxBackup from "@distilled.cloud/proxmox-backup";
+ *
+ * myEffect.pipe(ProxmoxBackup.Retry.transient);
+ * ```
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Retries from "@distilled.cloud/core/retry";
+export type Options = Retries.Options;
+export type Factory = Retries.Factory;
+export type Policy = Retries.Policy;
+declare const Retry_base: Context.ServiceClass<Retry, "ProxmoxBackupRetry", Retries.Policy>;
+/** Context tag for configuring retry behavior of Proxmox Backup Server API calls. */
+export declare class Retry extends Retry_base {
+}
+/** Provides a custom retry policy to every Proxmox Backup Server API call below it. */
+export declare const policy: {
+    (options: Options): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Retry>>;
+    (factory: Factory): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Retry>>;
+};
+/** Disables all automatic retries. */
+export declare const none: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Retry>>;
+/**
+ * The default retry policy (core's): transient/throttling/retryable errors,
+ * capped exponential backoff with jitter, server `retryAfter` hints honored
+ * with precedence.
+ */
+export declare const makeDefault: Factory;
+export declare const jittered: <Error, Env>(self: import("effect/Schedule").Schedule<unknown, unknown, Error, Env>) => import("effect/Schedule").Schedule<unknown, unknown, Error, Env>;
+export declare const capped: (max: import("effect/Duration").Duration) => <Error, Env>(self: import("effect/Schedule").Schedule<unknown, unknown, Error, Env>) => import("effect/Schedule").Schedule<unknown, unknown, Error, Env>;
+/** Retry options that retry all throttling errors indefinitely. */
+export declare const throttlingOptions: Options;
+/** Retries all throttling errors indefinitely (honoring server hints). */
+export declare const throttling: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Retry>>;
+/** Retry options that retry all transient errors indefinitely. */
+export declare const transientOptions: Options;
+/** Retries all transient errors indefinitely (honoring server hints). */
+export declare const transient: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Retry>>;
+export {};
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAC;AAEvD,MAAM,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;AACtC,MAAM,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;AACtC,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;;AAEpC,qFAAqF;AACrF,qBAAa,KAAM,SAAQ,UAE1B;CAAG;AAEJ,uFAAuF;AACvF,eAAO,MAAM,MAAM,EAAE;IACnB,CACE,OAAO,EAAE,OAAO,GACf,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IAC5C,CACE,OAAO,EAAE,OAAO,GACf,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;CAEU,CAAC;AAEzD,sCAAsC;AACtC,eAAO,MAAM,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAEzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,OAA6B,CAAC;AAExD,eAAO,MAAM,QAAQ,0JAAmB,CAAC;AACzC,eAAO,MAAM,MAAM,uMAAiB,CAAC;AAErC,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,EAAE,OAAmC,CAAC;AAEpE,0EAA0E;AAC1E,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAqC,CAAC;AAEhF,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,EAAE,OAAkC,CAAC;AAElE,yEAAyE;AACzE,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAoC,CAAC"}

package/dist/retry.js

@@ -0,0 +1,46 @@
+/**
+ * Proxmox Backup Server retry surface — a veneer over
+ * `@distilled.cloud/core/retry`. Copied unchanged from
+ * `packages/proxmox/src/retry.ts` (no vendor-specific logic; only the
+ * Context.Service tag name below is package-local).
+ *
+ * The `Retry` service tag is threaded into every generated operation via
+ * `API.make({ retry: Retry })`, so a caller-installed policy applies to all
+ * Proxmox Backup Server calls below it and core's `makeDefault` is the
+ * fallback when none is provided.
+ *
+ * @example
+ * ```ts
+ * import * as ProxmoxBackup from "@distilled.cloud/proxmox-backup";
+ *
+ * myEffect.pipe(ProxmoxBackup.Retry.transient);
+ * ```
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Retries from "@distilled.cloud/core/retry";
+/** Context tag for configuring retry behavior of Proxmox Backup Server API calls. */
+export class Retry extends Context.Service()("ProxmoxBackupRetry") {
+}
+/** Provides a custom retry policy to every Proxmox Backup Server API call below it. */
+export const policy = (optionsOrFactory) => Effect.provide(Layer.succeed(Retry, optionsOrFactory));
+/** Disables all automatic retries. */
+export const none = Effect.provide(Layer.succeed(Retry, { while: () => false }));
+/**
+ * The default retry policy (core's): transient/throttling/retryable errors,
+ * capped exponential backoff with jitter, server `retryAfter` hints honored
+ * with precedence.
+ */
+export const makeDefault = Retries.makeDefault;
+export const jittered = Retries.jittered;
+export const capped = Retries.capped;
+/** Retry options that retry all throttling errors indefinitely. */
+export const throttlingOptions = Retries.throttlingOptions;
+/** Retries all throttling errors indefinitely (honoring server hints). */
+export const throttling = policy(Retries.throttlingFactory);
+/** Retry options that retry all transient errors indefinitely. */
+export const transientOptions = Retries.transientOptions;
+/** Retries all transient errors indefinitely (honoring server hints). */
+export const transient = policy(Retries.transientFactory);
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAC;AAMvD,qFAAqF;AACrF,MAAM,OAAO,KAAM,SAAQ,OAAO,CAAC,OAAO,EAAiB,CACzD,oBAAoB,CACrB;CAAG;AAEJ,uFAAuF;AACvF,MAAM,CAAC,MAAM,MAAM,GAWf,CAAC,gBAAmC,EAAE,EAAE,CAC1C,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAEzD,sCAAsC;AACtC,MAAM,CAAC,MAAM,IAAI,GAE6B,MAAM,CAAC,OAAO,CAC1D,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,CAC7C,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAY,OAAO,CAAC,WAAW,CAAC;AAExD,MAAM,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACzC,MAAM,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AAErC,mEAAmE;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,CAAC,iBAAiB,CAAC;AAEpE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,UAAU,GAEuB,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhF,kEAAkE;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAY,OAAO,CAAC,gBAAgB,CAAC;AAElE,yEAAyE;AACzE,MAAM,CAAC,MAAM,SAAS,GAEwB,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC"}