@homeflare/distilled-proxmox 0.2.0

package/src/services/version.ts

@@ -0,0 +1,54 @@
+// AUTO-GENERATED by scripts/generate.ts from .generated-specs (apidata.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 {
+  ProxmoxProtocol,
+  type ProxmoxOpError,
+  type ProxmoxOpContext,
+} from "../protocol.ts";
+import * as Retry from "../retry.ts";
+
+export type { ProxmoxOpError, ProxmoxOpContext };
+
+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 type GetVersionResponseConsole = "applet" | "vv" | "html5" | "xtermjs";
+export const GetVersionResponseConsole = S.String;
+
+export interface GetVersionResponse {
+  console?: GetVersionResponseConsole;
+  release: string;
+  repoid: string;
+  version: string;
+}
+export const GetVersionResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    console: S.optional(GetVersionResponseConsole),
+    release: S.String,
+    repoid: S.String,
+    version: S.String,
+  }),
+).annotate({
+  identifier: "GetVersionResponse",
+}) as any as S.Schema<GetVersionResponse>;
+
+export type GetVersionError = ProxmoxOpError;
+/** API version details, including some parts of the global datacenter config. */
+export const getVersion: API.OperationMethod<
+  GetVersionRequest,
+  GetVersionResponse,
+  GetVersionError,
+  ProxmoxOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: GetVersionRequest,
+  output: GetVersionResponse,
+  errors: [],
+  protocol: ProxmoxProtocol,
+  retry: Retry.Retry,
+}));

package/src/task.ts

@@ -0,0 +1,87 @@
+/**
+ * Awaiting a PVE task — trap (a) from `src/protocol.ts`'s header.
+ *
+ * PVE answers a long-running action (VM start, backup, migration, …) with
+ * HTTP 200 and a bare UPID string the moment the task is QUEUED, not once
+ * it finishes. 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. PVE also answers `"OK (warnings)"` (the task
+ *   finished with recoverable warnings) — `startsWith("OK")` would treat
+ *   that as an ordinary success and swallow the warning entirely, and
+ *   `includes("OK")` is even looser. Anything other than the literal
+ *   string `"OK"` — `"OK (warnings)"` included — fails with
+ *   {@link ProxmoxTaskFailed}, carrying the vendor's own text verbatim so a
+ *   caller that wants to treat warnings as success can still do so by
+ *   matching on the message.
+ *
+ * `awaitTask` does not itself apply a deadline — wrap the call with
+ * `Effect.timeout` (or `Retry.transient`/a caller-supplied policy) the way
+ * any other Effect program composes one; a fixed timeout baked in here
+ * would be wrong for a backup that legitimately runs for hours and right
+ * for a config reload that should fail fast, and this module cannot know
+ * which operation queued the UPID it was handed.
+ */
+import * as Effect from "effect/Effect";
+import type * as Duration from "effect/Duration";
+import type { ProxmoxOpContext } from "./protocol.ts";
+import { ProxmoxTaskFailed } from "./errors.ts";
+import * as nodes from "./services/nodes.ts";
+import type {
+  GetNodeTaskStatusError,
+  GetNodeTaskStatusResponse,
+} from "./services/nodes.ts";
+
+/** Identifies one PVE task. `node` is the cluster member that OWNS the task — see the module header. */
+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 ProxmoxTaskFailed}
+ * for any other `exitstatus`, or with whatever `getNodeTaskStatus` itself
+ * failed with (a typed HTTP error, `ClusterNodeUnreachable` if the node
+ * this task lives on drops out of the cluster mid-poll, …).
+ */
+export const awaitTask = (
+  ref: TaskRef,
+  options: AwaitTaskOptions = {},
+): Effect.Effect<
+  GetNodeTaskStatusResponse,
+  ProxmoxTaskFailed | GetNodeTaskStatusError,
+  ProxmoxOpContext
+> =>
+  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 ProxmoxTaskFailed({
+            node: ref.node,
+            upid: ref.upid,
+            exitstatus: status.exitstatus,
+          }),
+        );
+      }
+      return status;
+    }
+  });

package/src/traits.ts

@@ -0,0 +1,45 @@
+/**
+ * Proxmox VE SDK trait surface — hand-written.
+ *
+ * Re-exports the generic protocol traits from core so generated operations
+ * import everything from one place. PVE 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 PVE-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; PVE has no
+// sensitive-member marking today — every generated member is plain).
+export {
+  RawResponse,
+  RawResponseRoot,
+  rawResponseSymbol,
+  rawResponseRootSymbol,
+} from "@distilled.cloud/core/protocol-rest";