@homeflare/distilled-proxmox 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @distilled.cloud/proxmox — Proxmox VE API SDK for Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy models
+ * in `.generated-specs` (written by `scripts/convert.ts` from PVE's own
+ * `apidata.js`, mirrored under `specs/`). Everything else in this folder is
+ * hand-written.
+ *
+ * One module per PVE top-level path segment — `access`, `cluster`,
+ * `nodes`, `pools`, `storage`, `version` — the same split the vendor's own
+ * api-viewer uses.
+ *
+ * @example
+ * ```ts
+ * import * as Proxmox from "@distilled.cloud/proxmox";
+ *
+ * const status = yield* Proxmox.Services.nodes.getNodeTaskStatus({
+ *   node: "pve1",
+ *   upid: "UPID:pve1:00001234:...",
+ * });
+ * ```
+ */
+export * from "./credentials.ts";
+export * from "./errors.ts";
+export * as T from "./traits.ts";
+export { ProxmoxProtocol, type ProxmoxOpError, type ProxmoxOpContext, } 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;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,OAAO,KAAK,CAAC,MAAM,aAAa,CAAC;AACjC,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,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,30 @@
+/**
+ * @distilled.cloud/proxmox — Proxmox VE API SDK for Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy models
+ * in `.generated-specs` (written by `scripts/convert.ts` from PVE's own
+ * `apidata.js`, mirrored under `specs/`). Everything else in this folder is
+ * hand-written.
+ *
+ * One module per PVE top-level path segment — `access`, `cluster`,
+ * `nodes`, `pools`, `storage`, `version` — the same split the vendor's own
+ * api-viewer uses.
+ *
+ * @example
+ * ```ts
+ * import * as Proxmox from "@distilled.cloud/proxmox";
+ *
+ * const status = yield* Proxmox.Services.nodes.getNodeTaskStatus({
+ *   node: "pve1",
+ *   upid: "UPID:pve1:00001234:...",
+ * });
+ * ```
+ */
+export * from "./credentials.js";
+export * from "./errors.js";
+export * as T from "./traits.js";
+export { ProxmoxProtocol, } 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;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,OAAO,KAAK,CAAC,MAAM,aAAa,CAAC;AACjC,OAAO,EACL,eAAe,GAGhB,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,18 @@
+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 operation. Generated
+ * service files annotate operations with `API.OperationMethod<I, O,
+ * ProxmoxOpError, ProxmoxOpContext>` explicitly so the compiler never
+ * infers these back out of the schema generics.
+ */
+export type ProxmoxOpError = DefaultErrors | ConfigError | HttpClientError.HttpClientError;
+/** Context (requirements) shared by every generated Proxmox operation. */
+export type ProxmoxOpContext = Credentials | HttpClient.HttpClient;
+export declare const ProxmoxProtocol: 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":"AAkEA,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;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,WAAW,GACX,eAAe,CAAC,eAAe,CAAC;AAEpC,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,UAAU,CAAC,UAAU,CAAC;AA6BnE,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CA2ElD,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,167 @@
+/**
+ * ProxmoxProtocol — the shared bearer-REST protocol instantiated for
+ * Proxmox VE. Hand-written; `@distilled.cloud/core` is never changed for a
+ * provider's own quirks — they all live here.
+ *
+ * ## The envelope
+ *
+ * Every PVE response — success AND failure — is wrapped `{"data": …}`
+ * (measured, and already relied on by `packages/alchemy/src/proxmox/
+ * client.ts` in `taslabs-net/homeflare-kit`: "EVERY PVE ANSWER IS WRAPPED
+ * IN `{"data": ...}`, errors included — a failed call can still be HTTP
+ * 200 with `{"data": null}`"). `transformResponse` below unwraps it before
+ * `core/protocol-rest`'s schema-driven decode ever sees a payload, so a
+ * generated operation's output type is the PAYLOAD, not the envelope.
+ *
+ * ## Authentication
+ *
+ * The API-token scheme: `Authorization: PVEAPIToken=<user>@<realm>!
+ * <tokenid>=<secret>` (no `Bearer`, and the token id is embedded in the
+ * header value itself, not just the credential).
+ *
+ * ## THE THREE 200-TRAPS
+ *
+ * (a) **Async POST/PUT/DELETE answer 200 with a UPID and can fail later.**
+ *     PVE hands back a bare task id string (`"UPID:node:...);"`) for any
+ *     long-running action — a VM start, a backup, a storage scan — and the
+ *     200 means "the task was QUEUED", not "the task succeeded". Handled
+ *     with real code: `src/task.ts`'s `awaitTask`, which polls
+ *     `GetNodeTaskStatus` (this package's own generated operation) until
+ *     `exitstatus` is present, then fails with the typed
+ *     `ProxmoxTaskFailed` unless it is EXACTLY `"OK"` — PVE also answers
+ *     `"OK (warnings)"`, which is not a bare-prefix match on purpose (see
+ *     that file).
+ *
+ * (b) **Some PUTs answer 200 `{"data":null}` even when nothing changed.**
+ *     PVE's update handlers commonly return `null` unconditionally on
+ *     success, whether or not any field actually differed from what was
+ *     already stored — there is no wire signal that distinguishes "applied"
+ *     from "already exactly this". THIS IS NOT SOMETHING A PROTOCOL LAYER
+ *     CAN DETECT OR FIX — it is a statement about business semantics no
+ *     amount of parsing recovers. Documented here so it travels with the
+ *     protocol rather than being rediscovered per resource: an update
+ *     operation's caller (a future kit `Resource`) MUST read the value back
+ *     with a follow-up GET rather than trust a 200 as proof anything
+ *     changed.
+ *
+ * (c) **Permission-filtered lists return 200 + `[]` instead of 403.** A
+ *     list endpoint called with a token that has no visibility into any
+ *     member of the collection answers an EMPTY array, not a permission
+ *     error — indistinguishable, on the wire, from "the collection is
+ *     genuinely empty". Also undetectable here for the same reason as (b):
+ *     documented so a caller treats an empty list from a narrowly-scoped
+ *     token as "unknown", never as "confirmed absent".
+ *
+ * ## Self-signed TLS
+ *
+ * A fresh PVE node serves its own self-signed certificate. This is
+ * EXPLICITLY NOT handled here, or anywhere in this package: the custom
+ * CA / certificate trust decision belongs to the `HttpClient.HttpClient`
+ * layer the CALLER provides (Effect's platform HTTP client layers take a
+ * `NodeHttpClient.layerConfig` / custom `Agent` for this), never to a
+ * distilled protocol module, which only ever builds and decodes requests
+ * against whatever transport it is handed. Wiring a custom CA at the
+ * `HttpClient` layer is a caller decision to prototype and own.
+ */
+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, UnknownProxmoxError, } from "./errors.js";
+/**
+ * PVE's failure envelope is `{"data": null, "message": "...", "errors"?:
+ * {…}}` — `message` is the only field every failure carries (the `errors`
+ * sub-object, PVE's parameter-verification detail, is read straight from
+ * the body in `unknownError` below, not here — `RestErrorEnvelope` has no
+ * room for a nested object and `errorEnvelope` only feeds per-op typed-error
+ * MATCHING, never the classes themselves).
+ */
+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: PVE's 400 is not one shape (a generic
+ * "bad request" some other providers mean by it) — it is SPECIFICALLY the
+ * parameter-verification failure, and answering it with the generic
+ * `BadRequest` would throw away the per-field `errors` object the vendor
+ * always attaches. Dropping the entry here is what lets a 400 fall through
+ * to `unknownError`, which reads that object.
+ */
+const PROXMOX_STATUS_MAP = {
+    ...HTTP_STATUS_MAP,
+};
+delete PROXMOX_STATUS_MAP[400];
+export const ProxmoxProtocol = makeRestProtocol({
+    // Resolved on the CALLING fiber per request (the layer is memoized per
+    // process); the Credentials service holds an effect, so a token rotated
+    // between calls is picked up without rebuilding the layer.
+    credentials: Effect.gen(function* () {
+        const resolve = yield* Credentials;
+        return yield* resolve;
+    }),
+    baseUrl: (creds) => creds.apiBaseUrl,
+    headers: (creds) => ({
+        Authorization: `PVEAPIToken=${creds.tokenId}=${Redacted.value(creds.secret)}`,
+        Accept: "application/json",
+    }),
+    errorEnvelope,
+    statusMap: PROXMOX_STATUS_MAP,
+    // 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".
+    transformResponse: (body) => {
+        if (body !== null &&
+            typeof body === "object" &&
+            "data" in body) {
+            return body.data ?? {};
+        }
+        return body;
+    },
+    // Reached for a 400 (see PROXMOX_STATUS_MAP above), an operation-declared
+    // typed error that didn't match (`ClusterNodeUnreachable`'s 595 — see
+    // `patches/nodes/task-polling.json` — when the status is right but the
+    // matcher's other fields aren't), or a status with no core mapping at
+    // all. `body` is the FULL parsed failure envelope (unlike
+    // `errorEnvelope`, which only ever sees `{code?, message?}`), so this is
+    // where PVE's per-field `errors` object is actually read.
+    //
+    // ⛔ A BARE 400 WITHOUT THE `errors` OBJECT MUST NOT FALL INTO
+    //   `UnknownProxmoxError`. That class is `.pipe(Category.withServerError)`
+    //   (matching every other provider's Unknown*Error fallback here), and
+    //   `ServerError` is one of the categories `core/category.ts`'s
+    //   `isTransientError` retries AUTOMATICALLY — with no caller opt-in —
+    //   via `makeDefault` (`core/api.ts`: `Option.isSome(opt) ? opt.value :
+    //   makeDefault` when no retry policy is in context). A malformed
+    //   request is permanent; retrying it up to `makeDefault`'s cap before
+    //   finally surfacing would silently multiply every truly-bad call by
+    //   several attempts and several seconds of backoff for no chance of a
+    //   different outcome. `BadRequest` (`Category.withBadRequestError`,
+    //   not retryable) is the honest answer for "PVE said 400 and gave no
+    //   further structure" — `UnknownProxmoxError` stays for statuses this
+    //   package genuinely has no mapping for at all (never 400).
+    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 UnknownProxmoxError({ 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,64 @@
+/**
+ * Proves the exact bug an adversarial review of this package caught and
+ * this file exists to stop recurring: a bare PVE 400 (no `errors` object)
+ * must decode to the non-retryable `BadRequest`, never the
+ * `Category.withServerError`-tagged `UnknownProxmoxError` — core's default
+ * retry policy treats `ServerError` as transient, so the wrong class would
+ * have silently retried a permanent, caller-caused failure several times
+ * before surfacing it. See `protocol.ts`'s `unknownError` and
+ * `errors.ts`'s module header for the full account.
+ */
+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, UnknownProxmoxError, } from "./errors.js";
+import * as Retry from "./retry.js";
+import { getNodeTime } from "./services/nodes.js";
+const testCredentials = credentials({
+    tokenId: "root@pam!test",
+    secret: "test-secret",
+    baseUrl: "https://pve.test:8006",
+});
+const fakePve = (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(getNodeTime({ node: "pve1" }).pipe(Retry.none, Effect.provide(Layer.mergeAll(fakePve(status, body), testCredentials)), Effect.flip));
+describe("protocol.ts error decoding", () => {
+    test("a bare 400 (no `errors` object) is BadRequest, never UnknownProxmoxError", async () => {
+        const error = await call(400, { data: null, message: "invalid parameter" });
+        expect(error).toBeInstanceOf(BadRequest);
+        expect(error).not.toBeInstanceOf(UnknownProxmoxError);
+        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" },
+        });
+    });
+    // 418 is neither in PROXMOX_STATUS_MAP nor >= 500 (the unmapped-5xx
+    // fallback in core's makeRestProtocol answers a bare `InternalServerError`
+    // for those before `unknownError` is ever reached — see that decode step).
+    test("a genuinely unmapped, non-5xx status still falls back to UnknownProxmoxError", async () => {
+        const error = await call(418, { data: null, message: "weird" });
+        expect(error).toBeInstanceOf(UnknownProxmoxError);
+    });
+    test('the {"data": ...} envelope is unwrapped before decode', async () => {
+        const result = await Effect.runPromise(getNodeTime({ node: "pve1" }).pipe(Effect.provide(Layer.mergeAll(fakePve(200, {
+            data: {
+                time: 1700000000,
+                timezone: "UTC",
+                localtime: 1700000000,
+            },
+        }), testCredentials))));
+        expect(result).toMatchObject({ time: 1700000000, timezone: "UTC" });
+    });
+});
+//# 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,50 @@
+/**
+ * Proxmox retry surface — a veneer over `@distilled.cloud/core/retry`.
+ *
+ * The `Retry` service tag is threaded into every generated operation via
+ * `API.make({ retry: Retry })`, so a caller-installed policy applies to all
+ * Proxmox calls below it and core's `makeDefault` is the fallback when none
+ * is provided.
+ *
+ * @example
+ * ```ts
+ * import * as Proxmox from "@distilled.cloud/proxmox";
+ *
+ * myEffect.pipe(Proxmox.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, "ProxmoxRetry", Retries.Policy>;
+/** Context tag for configuring retry behavior of Proxmox API calls. */
+export declare class Retry extends Retry_base {
+}
+/** Provides a custom retry policy to every Proxmox 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;;;;;;;;;;;;;;GAcG;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,uEAAuE;AACvE,qBAAa,KAAM,SAAQ,UAAgD;CAAG;AAE9E,yEAAyE;AACzE,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,43 @@
+/**
+ * Proxmox retry surface — a veneer over `@distilled.cloud/core/retry`.
+ *
+ * The `Retry` service tag is threaded into every generated operation via
+ * `API.make({ retry: Retry })`, so a caller-installed policy applies to all
+ * Proxmox calls below it and core's `makeDefault` is the fallback when none
+ * is provided.
+ *
+ * @example
+ * ```ts
+ * import * as Proxmox from "@distilled.cloud/proxmox";
+ *
+ * myEffect.pipe(Proxmox.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 API calls. */
+export class Retry extends Context.Service()("ProxmoxRetry") {
+}
+/** Provides a custom retry policy to every Proxmox 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;;;;;;;;;;;;;;GAcG;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,uEAAuE;AACvE,MAAM,OAAO,KAAM,SAAQ,OAAO,CAAC,OAAO,EAAiB,CAAC,cAAc,CAAC;CAAG;AAE9E,yEAAyE;AACzE,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"}