@virtbase/proxmox-api 3.0.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/CHANGELOG.md +10 -53
  2. package/LICENSE +22 -0
  3. package/README.md +81 -82
  4. package/dist/client.d.ts +13 -7
  5. package/dist/client.js +23 -23
  6. package/dist/errors.d.ts +364 -0
  7. package/dist/errors.js +372 -0
  8. package/dist/index.d.ts +5 -3
  9. package/dist/index.js +3 -18
  10. package/dist/model.d.ts +28408 -28157
  11. package/dist/model.js +4 -16
  12. package/dist/proxmox-engine.d.ts +273 -54
  13. package/dist/proxmox-engine.js +772 -248
  14. package/dist/proxy.d.ts +61 -19
  15. package/dist/proxy.js +118 -33
  16. package/dist/qm-monitor.d.ts +225 -25
  17. package/dist/qm-monitor.js +152 -52
  18. package/dist/schema-info.d.ts +12 -0
  19. package/dist/schema-info.js +13 -0
  20. package/dist/tasks.d.ts +129 -0
  21. package/dist/tasks.js +132 -0
  22. package/package.json +33 -34
  23. package/dist/client.d.ts.map +0 -1
  24. package/dist/client.js.map +0 -1
  25. package/dist/index.d.ts.map +0 -1
  26. package/dist/index.js.map +0 -1
  27. package/dist/model.d.ts.map +0 -1
  28. package/dist/model.js.map +0 -1
  29. package/dist/proxmox-engine.d.ts.map +0 -1
  30. package/dist/proxmox-engine.js.map +0 -1
  31. package/dist/proxy.d.ts.map +0 -1
  32. package/dist/proxy.js.map +0 -1
  33. package/dist/qm-monitor.d.ts.map +0 -1
  34. package/dist/qm-monitor.js.map +0 -1
  35. package/src/__tests__/helpers.ts +0 -39
  36. package/src/__tests__/proxmox-engine.test.ts +0 -393
  37. package/src/__tests__/proxy.test.ts +0 -190
  38. package/src/__tests__/qm-monitor.test.ts +0 -215
  39. package/src/client.ts +0 -58
  40. package/src/index.ts +0 -34
  41. package/src/model.ts +0 -32101
  42. package/src/proxmox-engine.ts +0 -452
  43. package/src/proxy.ts +0 -195
  44. package/src/qm-monitor.ts +0 -303
@@ -0,0 +1,364 @@
1
+ /**
2
+ * Stable discriminant carried by every error this library throws, for telling
3
+ * failures apart without `instanceof`.
4
+ *
5
+ * @remarks
6
+ * Each code belongs to one error class, with two exceptions:
7
+ * {@link waitForTask} reports its own timeout, and an abort between two
8
+ * status checks, as a plain {@link ProxmoxError} with the code `timeout` or
9
+ * `aborted`.
10
+ */
11
+ export type ProxmoxErrorCode = "config" | "connection" | "timeout" | "aborted" | "response" | "api" | "authentication" | "permission" | "parameter" | "task";
12
+ /**
13
+ * Identifies the request an error or event belongs to.
14
+ *
15
+ * Carries neither credentials nor parameters, so it is safe to log.
16
+ */
17
+ export interface ProxmoxRequestInfo {
18
+ /**
19
+ * HTTP method in upper case, e.g. `GET`.
20
+ */
21
+ method: string;
22
+ /**
23
+ * Concrete path, e.g. `/api2/json/nodes/pve1/qemu/100/config`.
24
+ */
25
+ path: string;
26
+ /**
27
+ * The same path with `*` for each placeholder, for grouping.
28
+ */
29
+ pathTemplate: string;
30
+ /**
31
+ * Origin the request was sent to, e.g. `https://192.0.2.10:8006`.
32
+ */
33
+ origin: string;
34
+ /**
35
+ * 1 for the first try, incremented on each retry. The replay that follows
36
+ * a ticket renewal keeps the number of the attempt it replaces.
37
+ */
38
+ attempt: number;
39
+ }
40
+ /**
41
+ * Base class of the errors this library throws for unusable input, failed
42
+ * requests and failed tasks; catch it to handle all of them in one place.
43
+ *
44
+ * @remarks
45
+ * Prefer {@link ProxmoxError.isInstance} or the `code` field over `instanceof`
46
+ * when the package might be installed twice: the check is a cross-copy brand
47
+ * rather than class identity.
48
+ *
49
+ * Two kinds of failure are not a `ProxmoxError`: {@link QmMonitor} reports
50
+ * monitor output it cannot use with a plain `Error`, and an error thrown by
51
+ * an `otp` callback reaches the caller unchanged.
52
+ */
53
+ export declare class ProxmoxError extends Error {
54
+ /**
55
+ * The kind of failure. Unlike the class, it can be compared across copies
56
+ * of the package.
57
+ */
58
+ readonly code: ProxmoxErrorCode;
59
+ /**
60
+ * The request that failed. Absent on errors that do not stem from one
61
+ * request: {@link ProxmoxConfigError}, {@link ProxmoxTaskError} and the
62
+ * errors {@link waitForTask} throws when it stops waiting.
63
+ */
64
+ readonly request?: ProxmoxRequestInfo;
65
+ /**
66
+ * Creates an error named after the concrete class being constructed.
67
+ *
68
+ * @param code - Discriminant for the kind of failure.
69
+ * @param message - Human-readable description, fit for a log line.
70
+ * @param options - Context of the failure.
71
+ * @param options.cause - Underlying error, exposed as `cause`. The property
72
+ * is not set at all when this is `undefined`.
73
+ * @param options.request - The request the failure belongs to.
74
+ */
75
+ constructor(code: ProxmoxErrorCode, message: string, options?: {
76
+ cause?: unknown;
77
+ request?: ProxmoxRequestInfo;
78
+ });
79
+ /**
80
+ * Reports whether a value is an error thrown by any copy of this library.
81
+ *
82
+ * @param value - Anything, typically the value caught by a `catch` clause.
83
+ * @returns `true` when `value` is an object carrying the library's brand,
84
+ * including one created by another installed copy of the package, for
85
+ * which `instanceof` is `false`.
86
+ */
87
+ static isInstance(value: unknown): value is ProxmoxError;
88
+ /**
89
+ * Returns the form `JSON.stringify` serialises, which is safe to log.
90
+ *
91
+ * @returns The `name`, `code`, `message` and `request` of the error. The
92
+ * `cause` and the stack trace are left out.
93
+ */
94
+ toJSON(): Record<string, unknown>;
95
+ }
96
+ /**
97
+ * Signals input the client cannot work with, detected before any request is
98
+ * sent.
99
+ *
100
+ * @remarks
101
+ * Thrown synchronously by the {@link ProxmoxEngine} constructor for unusable
102
+ * options, by the path proxy for a path value that is empty, `.` or `..`,
103
+ * and by {@link parseUpid} for a string that is not a task identifier.
104
+ * {@link ProxmoxEngine.getTicket} and {@link waitForTask} reject with it, for
105
+ * a client that uses an API token and for a malformed identifier
106
+ * respectively. It never has a `request`.
107
+ */
108
+ export declare class ProxmoxConfigError extends ProxmoxError {
109
+ constructor(message: string);
110
+ }
111
+ /**
112
+ * Signals that the connection failed before a complete response arrived: a
113
+ * DNS failure, a refused connection, a TLS rejection or a reset.
114
+ *
115
+ * @remarks
116
+ * The underlying error is on `cause`. A connection that breaks while the
117
+ * response body is being read is reported the same way. Whether Proxmox
118
+ * carried the request out is unknown, which is why only `GET` requests are
119
+ * retried after it.
120
+ */
121
+ export declare class ProxmoxConnectionError extends ProxmoxError {
122
+ /**
123
+ * Creates a connection error.
124
+ *
125
+ * @param message - Human-readable description, fit for a log line.
126
+ * @param options - Context of the failure.
127
+ * @param options.cause - The error `fetch` or the body stream failed with.
128
+ * @param options.request - The request that got no response.
129
+ * @param code - Discriminant to report. Subclasses pass their own; it is
130
+ * `connection` when omitted.
131
+ */
132
+ constructor(message: string, options: {
133
+ cause?: unknown;
134
+ request?: ProxmoxRequestInfo;
135
+ }, code?: "connection" | "timeout");
136
+ }
137
+ /**
138
+ * Signals that a request exceeded its timeout before its response arrived.
139
+ *
140
+ * @remarks
141
+ * The limit is `authTimeout` for a login request, and `queryTimeout` or the
142
+ * per-call `timeout` for any other. It covers a single attempt up to the end
143
+ * of the response body, or up to the response headers when the body is
144
+ * handed back as a stream. As with any {@link ProxmoxConnectionError}, the
145
+ * request may still have been carried out.
146
+ */
147
+ export declare class ProxmoxTimeoutError extends ProxmoxConnectionError {
148
+ /**
149
+ * The limit that was exceeded, in milliseconds.
150
+ */
151
+ readonly timeout: number;
152
+ /**
153
+ * Creates a timeout error whose message names the request and the limit.
154
+ *
155
+ * @param timeout - The limit that was exceeded, in milliseconds.
156
+ * @param request - The request that timed out.
157
+ */
158
+ constructor(timeout: number, request: ProxmoxRequestInfo);
159
+ }
160
+ /**
161
+ * Signals that the caller's own `AbortSignal` cancelled a request, whether it
162
+ * was waiting for a login, in flight, or waiting to be retried.
163
+ */
164
+ export declare class ProxmoxAbortError extends ProxmoxError {
165
+ /**
166
+ * Creates an abort error whose message names the request.
167
+ *
168
+ * @param request - The request that was cancelled.
169
+ * @param cause - What the abort surfaced as: the signal's `reason`, or the
170
+ * error `fetch` rejected with when the request was already in flight.
171
+ */
172
+ constructor(request: ProxmoxRequestInfo, cause?: unknown);
173
+ }
174
+ /**
175
+ * Signals a response that arrived but could not be understood: a success
176
+ * whose JSON body does not parse, or a login reply that carries no ticket.
177
+ */
178
+ export declare class ProxmoxResponseError extends ProxmoxError {
179
+ /**
180
+ * HTTP status of the response, which is a success status.
181
+ */
182
+ readonly status: number;
183
+ /**
184
+ * Creates a response error.
185
+ *
186
+ * @param message - Human-readable description, fit for a log line.
187
+ * @param status - HTTP status of the response.
188
+ * @param options - Context of the failure.
189
+ * @param options.cause - The error that decoding the body failed with.
190
+ * @param options.request - The request the response answers.
191
+ */
192
+ constructor(message: string, status: number, options: {
193
+ cause?: unknown;
194
+ request?: ProxmoxRequestInfo;
195
+ });
196
+ }
197
+ /**
198
+ * Describes an error response, as needed to construct a
199
+ * {@link ProxmoxApiError}.
200
+ */
201
+ export interface ProxmoxApiErrorDetails {
202
+ /**
203
+ * HTTP status of the response.
204
+ */
205
+ status: number;
206
+ /**
207
+ * Text of the status line. Empty when HTTP/2 or a reverse proxy dropped it.
208
+ */
209
+ statusText: string;
210
+ /**
211
+ * Proxmox's own explanation, from the body or the status line.
212
+ */
213
+ reason: string;
214
+ /**
215
+ * Per-parameter messages, when Proxmox rejected specific parameters.
216
+ */
217
+ errors?: Record<string, string>;
218
+ /**
219
+ * The decoded response body, when there was one.
220
+ */
221
+ body?: unknown;
222
+ /**
223
+ * The request that was answered with the error.
224
+ */
225
+ request: ProxmoxRequestInfo;
226
+ }
227
+ /**
228
+ * Signals that Proxmox answered with an error status.
229
+ *
230
+ * @remarks
231
+ * `status` and `reason` say what went wrong; `errors` names the offending
232
+ * parameters when there are any. Statuses `400`, `401` and `403` are thrown
233
+ * as the subclasses {@link ProxmoxParameterError},
234
+ * {@link ProxmoxAuthenticationError} and {@link ProxmoxPermissionError};
235
+ * every other status is thrown as this class with the code `api`.
236
+ */
237
+ export declare class ProxmoxApiError extends ProxmoxError {
238
+ /**
239
+ * HTTP status of the response.
240
+ */
241
+ readonly status: number;
242
+ /**
243
+ * Text of the status line. Empty when HTTP/2 or a reverse proxy dropped it.
244
+ */
245
+ readonly statusText: string;
246
+ /**
247
+ * Proxmox's own explanation, from the body or the status line.
248
+ */
249
+ readonly reason: string;
250
+ /**
251
+ * Per-parameter messages, keyed by parameter name. Empty when Proxmox
252
+ * blamed no specific parameter.
253
+ */
254
+ readonly errors: Record<string, string>;
255
+ /**
256
+ * The decoded response body, or `undefined` when there was none.
257
+ */
258
+ readonly body: unknown;
259
+ /**
260
+ * The request that was answered with the error. Always present.
261
+ */
262
+ readonly request: ProxmoxRequestInfo;
263
+ /**
264
+ * Creates an API error whose message names the request, the status, the
265
+ * reason and any rejected parameters.
266
+ *
267
+ * @param details - The error response.
268
+ * @param code - Discriminant to report. Subclasses pass their own; it is
269
+ * `api` when omitted.
270
+ */
271
+ constructor(details: ProxmoxApiErrorDetails, code?: ProxmoxErrorCode);
272
+ /**
273
+ * Returns the form `JSON.stringify` serialises, which is safe to log.
274
+ *
275
+ * @returns The fields of {@link ProxmoxError.toJSON} plus `status`,
276
+ * `reason` and `errors`. The `statusText` and the `body` are left out.
277
+ */
278
+ toJSON(): Record<string, unknown>;
279
+ }
280
+ /**
281
+ * Signals a `401`: the credentials were rejected.
282
+ *
283
+ * @remarks
284
+ * The cause is a wrong password, an unknown or revoked token, an expired
285
+ * ticket that could not be renewed, or a login that needs a second factor
286
+ * (`tfaRequired`).
287
+ */
288
+ export declare class ProxmoxAuthenticationError extends ProxmoxApiError {
289
+ /**
290
+ * `true` when a password login was answered with a second-factor challenge
291
+ * and no `otp` was available to answer it. The client raises this case
292
+ * itself, with the status `401`, as Proxmox does not answer the challenge
293
+ * with an error status.
294
+ */
295
+ readonly tfaRequired: boolean;
296
+ /**
297
+ * Creates an authentication error.
298
+ *
299
+ * @param details - The error response.
300
+ * @param tfaRequired - Whether the login failed for want of a second
301
+ * factor. `false` when omitted.
302
+ */
303
+ constructor(details: ProxmoxApiErrorDetails, tfaRequired?: boolean);
304
+ }
305
+ /**
306
+ * Signals a `403`: the caller is authenticated but not allowed, because of a
307
+ * missing privilege or an API token used on an endpoint that only accepts a
308
+ * ticket.
309
+ */
310
+ export declare class ProxmoxPermissionError extends ProxmoxApiError {
311
+ constructor(details: ProxmoxApiErrorDetails);
312
+ }
313
+ /**
314
+ * Signals a `400`: Proxmox rejected one or more parameters, which `errors`
315
+ * names.
316
+ */
317
+ export declare class ProxmoxParameterError extends ProxmoxApiError {
318
+ constructor(details: ProxmoxApiErrorDetails);
319
+ }
320
+ /**
321
+ * Picks the error class that matches a response status.
322
+ *
323
+ * @param details - The error response.
324
+ * @returns A {@link ProxmoxParameterError} for `400`, a
325
+ * {@link ProxmoxAuthenticationError} for `401`, a
326
+ * {@link ProxmoxPermissionError} for `403` and a plain
327
+ * {@link ProxmoxApiError} for every other status.
328
+ */
329
+ export declare function apiErrorFor(details: ProxmoxApiErrorDetails): ProxmoxApiError;
330
+ /**
331
+ * Signals that a background task ran to completion and reported failure;
332
+ * thrown by {@link waitForTask}.
333
+ *
334
+ * @remarks
335
+ * The request that started the task succeeded - Proxmox answers with a UPID
336
+ * and does the work in the background - so this is the only place the
337
+ * failure surfaces. The error has no `request`.
338
+ */
339
+ export declare class ProxmoxTaskError extends ProxmoxError {
340
+ /**
341
+ * Identifier of the task that failed.
342
+ */
343
+ readonly upid: string;
344
+ /**
345
+ * Proxmox's exit status: the error text, `WARNINGS: <n>` when warnings
346
+ * were to count as failure, or `unknown` when the task stopped without
347
+ * reporting one.
348
+ */
349
+ readonly exitstatus: string;
350
+ /**
351
+ * Creates a task error whose message names the task and its exit status.
352
+ *
353
+ * @param upid - Identifier of the task that failed.
354
+ * @param exitstatus - The exit status the task reported.
355
+ */
356
+ constructor(upid: string, exitstatus: string);
357
+ /**
358
+ * Returns the form `JSON.stringify` serialises, which is safe to log.
359
+ *
360
+ * @returns The fields of {@link ProxmoxError.toJSON} plus `upid` and
361
+ * `exitstatus`.
362
+ */
363
+ toJSON(): Record<string, unknown>;
364
+ }