@homeflare/distilled-proxmox-backup 0.2.0

package/src/services/version.ts

@@ -0,0 +1,49 @@
+// AUTO-GENERATED by scripts/generate.ts from .generated-specs (apidoc.js, via scripts/apidoc.ts — see its header). Do not edit.
+import * as S from "@distilled.cloud/core/schema";
+import * as API from "@distilled.cloud/core/api";
+import * as T from "../traits.ts";
+import {
+  ProxmoxBackupProtocol,
+  type ProxmoxBackupOpError,
+  type ProxmoxBackupOpContext,
+} from "../protocol.ts";
+import * as Retry from "../retry.ts";
+
+export type { ProxmoxBackupOpError, ProxmoxBackupOpContext };
+
+export interface GetVersionRequest {}
+export const GetVersionRequest = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({}).pipe(T.Http({ method: "GET", uri: "/version", code: 200 })),
+).annotate({
+  identifier: "GetVersionRequest",
+}) as any as S.Schema<GetVersionRequest>;
+
+export interface GetVersionResponse {
+  release: string;
+  repoid: string;
+  version: string;
+}
+export const GetVersionResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    release: S.String,
+    repoid: S.String,
+    version: S.String,
+  }),
+).annotate({
+  identifier: "GetVersionResponse",
+}) as any as S.Schema<GetVersionResponse>;
+
+export type GetVersionError = ProxmoxBackupOpError;
+/** Proxmox Backup Server API version. */
+export const getVersion: API.OperationMethod<
+  GetVersionRequest,
+  GetVersionResponse,
+  GetVersionError,
+  ProxmoxBackupOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: GetVersionRequest,
+  output: GetVersionResponse,
+  errors: [],
+  protocol: ProxmoxBackupProtocol,
+  retry: Retry.Retry,
+}));

package/src/task.ts

@@ -0,0 +1,84 @@
+/**
+ * Awaiting a PBS task — trap (a) from `src/protocol.ts`'s header.
+ *
+ * Ported from `packages/proxmox/src/task.ts` unchanged in its polling
+ * logic and exact-equality check — PBS answers a long-running action
+ * (backup, sync job, garbage collection, tape write, …) with HTTP 200 and
+ * a bare UPID string the moment the task is QUEUED, the same as PVE. The
+ * only way to know whether it actually succeeded is to poll `GET /nodes/
+ * {node}/tasks/{upid}/status` — this package's generated
+ * `Services.nodes.getNodeTaskStatus` — until the response carries an
+ * `exitstatus`, and then check that value.
+ *
+ * ⛔ `exitstatus` IS COMPARED FOR EXACT EQUALITY TO `"OK"`, NEVER A PREFIX
+ *   OR SUBSTRING CHECK — carried from PVE's identical warning; not
+ *   independently re-measured that PBS also answers `"OK (warnings)"`
+ *   (no live PBS calls in this build), but the exact-equality form is
+ *   strictly safer than a looser one either way, so there is no reason to
+ *   weaken it pending that confirmation.
+ *
+ * `awaitTask` does not itself apply a deadline — wrap the call with
+ * `Effect.timeout` (or `Retry.transient`/a caller-supplied policy).
+ *
+ * NOT carried from PVE: `ClusterNodeUnreachable` in the failure union —
+ * see `src/errors.ts`'s header for why PBS has no cluster-forwarding trap.
+ */
+import * as Effect from "effect/Effect";
+import type * as Duration from "effect/Duration";
+import type { ProxmoxBackupOpContext } from "./protocol.ts";
+import { ProxmoxBackupTaskFailed } from "./errors.ts";
+import * as nodes from "./services/nodes.ts";
+import type {
+  GetNodeTaskStatusError,
+  GetNodeTaskStatusResponse,
+} from "./services/nodes.ts";
+
+/** Identifies one PBS task. `node` is always the single PBS host — kept as a field for parity with `@distilled.cloud/proxmox`'s identical shape, and because the vendor schema's own path template names it `{node}` regardless. */
+export interface TaskRef {
+  readonly node: string;
+  readonly upid: string;
+}
+
+export interface AwaitTaskOptions {
+  /** Delay between polls. Default 1 second. */
+  readonly pollInterval?: Duration.Input;
+}
+
+/**
+ * Poll a task to completion. Resolves with the FINAL status response (so a
+ * caller can read `pid`/`starttime`/etc. without a second call) once
+ * `exitstatus` is exactly `"OK"`; fails with {@link ProxmoxBackupTaskFailed}
+ * for any other `exitstatus`, or with whatever `getNodeTaskStatus` itself
+ * failed with.
+ */
+export const awaitTask = (
+  ref: TaskRef,
+  options: AwaitTaskOptions = {},
+): Effect.Effect<
+  GetNodeTaskStatusResponse,
+  ProxmoxBackupTaskFailed | GetNodeTaskStatusError,
+  ProxmoxBackupOpContext
+> =>
+  Effect.gen(function* () {
+    const pollInterval = options.pollInterval ?? "1 second";
+    while (true) {
+      const status = yield* nodes.getNodeTaskStatus({
+        node: ref.node,
+        upid: ref.upid,
+      });
+      if (status.exitstatus === undefined) {
+        yield* Effect.sleep(pollInterval);
+        continue;
+      }
+      if (status.exitstatus !== "OK") {
+        return yield* Effect.fail(
+          new ProxmoxBackupTaskFailed({
+            node: ref.node,
+            upid: ref.upid,
+            exitstatus: status.exitstatus,
+          }),
+        );
+      }
+      return status;
+    }
+  });

package/src/traits.ts

@@ -0,0 +1,46 @@
+/**
+ * Proxmox Backup Server SDK trait surface — hand-written.
+ *
+ * Copied unchanged from `packages/proxmox/src/traits.ts`. Re-exports the
+ * generic protocol traits from core so generated operations import
+ * everything from one place. PBS speaks form-urlencoded/query REST with a
+ * `{"data": …}` envelope and no bare-array response bodies of its own
+ * shape beyond what `RawResponse`/`RawResponseRoot` already cover (see
+ * `scripts/convert.ts`'s header), so there are no PBS-specific traits.
+ */
+export {
+  Body,
+  Header,
+  Query,
+  Label,
+  Http,
+  ResponseCode,
+  HttpBody,
+  FormDataFile,
+  KeyDictionary,
+  UnionCases,
+  applyErrorMatchers,
+  getErrorMatchers,
+  type HttpTrait,
+  type ErrorMatcher,
+  bodySymbol,
+  headerSymbol,
+  querySymbol,
+  labelSymbol,
+  httpSymbol,
+  responseCodeSymbol,
+  httpBodySymbol,
+  formDataFileSymbol,
+  keyDictionarySymbol,
+  unionCasesSymbol,
+  errorMatchersSymbol,
+} from "@distilled.cloud/core/trait";
+
+// Bearer-REST protocol traits (bare-payload responses; PBS has no
+// sensitive-member marking today — every generated member is plain).
+export {
+  RawResponse,
+  RawResponseRoot,
+  rawResponseSymbol,
+  rawResponseRootSymbol,
+} from "@distilled.cloud/core/protocol-rest";