@virtbase/proxmox-api 3.0.0 → 5.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 +21 -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 +28875 -28491
  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
package/dist/errors.js ADDED
@@ -0,0 +1,372 @@
1
+ /**
2
+ * Brand carried by every {@link ProxmoxError}.
3
+ *
4
+ * Registered with `Symbol.for`, so every copy of the package resolves to the
5
+ * same symbol and can recognise errors created by another copy.
6
+ */
7
+ const BRAND = Symbol.for("@virtbase/proxmox-api.error");
8
+ /**
9
+ * Base class of the errors this library throws for unusable input, failed
10
+ * requests and failed tasks; catch it to handle all of them in one place.
11
+ *
12
+ * @remarks
13
+ * Prefer {@link ProxmoxError.isInstance} or the `code` field over `instanceof`
14
+ * when the package might be installed twice: the check is a cross-copy brand
15
+ * rather than class identity.
16
+ *
17
+ * Two kinds of failure are not a `ProxmoxError`: {@link QmMonitor} reports
18
+ * monitor output it cannot use with a plain `Error`, and an error thrown by
19
+ * an `otp` callback reaches the caller unchanged.
20
+ */
21
+ export class ProxmoxError extends Error {
22
+ /**
23
+ * The kind of failure. Unlike the class, it can be compared across copies
24
+ * of the package.
25
+ */
26
+ code;
27
+ /**
28
+ * The request that failed. Absent on errors that do not stem from one
29
+ * request: {@link ProxmoxConfigError}, {@link ProxmoxTaskError} and the
30
+ * errors {@link waitForTask} throws when it stops waiting.
31
+ */
32
+ request;
33
+ /**
34
+ * Creates an error named after the concrete class being constructed.
35
+ *
36
+ * @param code - Discriminant for the kind of failure.
37
+ * @param message - Human-readable description, fit for a log line.
38
+ * @param options - Context of the failure.
39
+ * @param options.cause - Underlying error, exposed as `cause`. The property
40
+ * is not set at all when this is `undefined`.
41
+ * @param options.request - The request the failure belongs to.
42
+ */
43
+ constructor(code, message, options) {
44
+ super(message, options?.cause === undefined ? undefined : { cause: options.cause });
45
+ this.name = new.target.name;
46
+ this.code = code;
47
+ this.request = options?.request;
48
+ Object.defineProperty(this, BRAND, { value: true });
49
+ }
50
+ /**
51
+ * Reports whether a value is an error thrown by any copy of this library.
52
+ *
53
+ * @param value - Anything, typically the value caught by a `catch` clause.
54
+ * @returns `true` when `value` is an object carrying the library's brand,
55
+ * including one created by another installed copy of the package, for
56
+ * which `instanceof` is `false`.
57
+ */
58
+ static isInstance(value) {
59
+ return typeof value === "object" && value !== null && BRAND in value;
60
+ }
61
+ /**
62
+ * Returns the form `JSON.stringify` serialises, which is safe to log.
63
+ *
64
+ * @returns The `name`, `code`, `message` and `request` of the error. The
65
+ * `cause` and the stack trace are left out.
66
+ */
67
+ toJSON() {
68
+ return {
69
+ name: this.name,
70
+ code: this.code,
71
+ message: this.message,
72
+ request: this.request,
73
+ };
74
+ }
75
+ }
76
+ /**
77
+ * Signals input the client cannot work with, detected before any request is
78
+ * sent.
79
+ *
80
+ * @remarks
81
+ * Thrown synchronously by the {@link ProxmoxEngine} constructor for unusable
82
+ * options, by the path proxy for a path value that is empty, `.` or `..`,
83
+ * and by {@link parseUpid} for a string that is not a task identifier.
84
+ * {@link ProxmoxEngine.getTicket} and {@link waitForTask} reject with it, for
85
+ * a client that uses an API token and for a malformed identifier
86
+ * respectively. It never has a `request`.
87
+ */
88
+ export class ProxmoxConfigError extends ProxmoxError {
89
+ constructor(message) {
90
+ super("config", message);
91
+ }
92
+ }
93
+ /**
94
+ * Signals that the connection failed before a complete response arrived: a
95
+ * DNS failure, a refused connection, a TLS rejection or a reset.
96
+ *
97
+ * @remarks
98
+ * The underlying error is on `cause`. A connection that breaks while the
99
+ * response body is being read is reported the same way. Whether Proxmox
100
+ * carried the request out is unknown, which is why only `GET` requests are
101
+ * retried after it.
102
+ */
103
+ export class ProxmoxConnectionError extends ProxmoxError {
104
+ /**
105
+ * Creates a connection error.
106
+ *
107
+ * @param message - Human-readable description, fit for a log line.
108
+ * @param options - Context of the failure.
109
+ * @param options.cause - The error `fetch` or the body stream failed with.
110
+ * @param options.request - The request that got no response.
111
+ * @param code - Discriminant to report. Subclasses pass their own; it is
112
+ * `connection` when omitted.
113
+ */
114
+ constructor(message, options, code = "connection") {
115
+ super(code, message, options);
116
+ }
117
+ }
118
+ /**
119
+ * Signals that a request exceeded its timeout before its response arrived.
120
+ *
121
+ * @remarks
122
+ * The limit is `authTimeout` for a login request, and `queryTimeout` or the
123
+ * per-call `timeout` for any other. It covers a single attempt up to the end
124
+ * of the response body, or up to the response headers when the body is
125
+ * handed back as a stream. As with any {@link ProxmoxConnectionError}, the
126
+ * request may still have been carried out.
127
+ */
128
+ export class ProxmoxTimeoutError extends ProxmoxConnectionError {
129
+ /**
130
+ * The limit that was exceeded, in milliseconds.
131
+ */
132
+ timeout;
133
+ /**
134
+ * Creates a timeout error whose message names the request and the limit.
135
+ *
136
+ * @param timeout - The limit that was exceeded, in milliseconds.
137
+ * @param request - The request that timed out.
138
+ */
139
+ constructor(timeout, request) {
140
+ super(`${request.method} ${request.path} timed out after ${timeout} ms`, { request }, "timeout");
141
+ this.timeout = timeout;
142
+ }
143
+ }
144
+ /**
145
+ * Signals that the caller's own `AbortSignal` cancelled a request, whether it
146
+ * was waiting for a login, in flight, or waiting to be retried.
147
+ */
148
+ export class ProxmoxAbortError extends ProxmoxError {
149
+ /**
150
+ * Creates an abort error whose message names the request.
151
+ *
152
+ * @param request - The request that was cancelled.
153
+ * @param cause - What the abort surfaced as: the signal's `reason`, or the
154
+ * error `fetch` rejected with when the request was already in flight.
155
+ */
156
+ constructor(request, cause) {
157
+ super("aborted", `${request.method} ${request.path} was aborted`, {
158
+ cause,
159
+ request,
160
+ });
161
+ }
162
+ }
163
+ /**
164
+ * Signals a response that arrived but could not be understood: a success
165
+ * whose JSON body does not parse, or a login reply that carries no ticket.
166
+ */
167
+ export class ProxmoxResponseError extends ProxmoxError {
168
+ /**
169
+ * HTTP status of the response, which is a success status.
170
+ */
171
+ status;
172
+ /**
173
+ * Creates a response error.
174
+ *
175
+ * @param message - Human-readable description, fit for a log line.
176
+ * @param status - HTTP status of the response.
177
+ * @param options - Context of the failure.
178
+ * @param options.cause - The error that decoding the body failed with.
179
+ * @param options.request - The request the response answers.
180
+ */
181
+ constructor(message, status, options) {
182
+ super("response", message, options);
183
+ this.status = status;
184
+ }
185
+ }
186
+ /**
187
+ * Builds the message of an API error.
188
+ *
189
+ * @param details - The error response to describe.
190
+ * @returns `<method> <path> failed: <status> <reason>`, followed by the
191
+ * per-parameter messages in parentheses when there are any.
192
+ */
193
+ function describe(details) {
194
+ const { request, status, reason, errors } = details;
195
+ const fields = Object.entries(errors ?? {})
196
+ .map(([name, problem]) => `${name}: ${problem}`)
197
+ .join("; ");
198
+ return (`${request.method} ${request.path} failed: ${status} ${reason}` +
199
+ (fields ? ` (${fields})` : ""));
200
+ }
201
+ /**
202
+ * Signals that Proxmox answered with an error status.
203
+ *
204
+ * @remarks
205
+ * `status` and `reason` say what went wrong; `errors` names the offending
206
+ * parameters when there are any. Statuses `400`, `401` and `403` are thrown
207
+ * as the subclasses {@link ProxmoxParameterError},
208
+ * {@link ProxmoxAuthenticationError} and {@link ProxmoxPermissionError};
209
+ * every other status is thrown as this class with the code `api`.
210
+ */
211
+ export class ProxmoxApiError extends ProxmoxError {
212
+ /**
213
+ * HTTP status of the response.
214
+ */
215
+ status;
216
+ /**
217
+ * Text of the status line. Empty when HTTP/2 or a reverse proxy dropped it.
218
+ */
219
+ statusText;
220
+ /**
221
+ * Proxmox's own explanation, from the body or the status line.
222
+ */
223
+ reason;
224
+ /**
225
+ * Per-parameter messages, keyed by parameter name. Empty when Proxmox
226
+ * blamed no specific parameter.
227
+ */
228
+ errors;
229
+ /**
230
+ * The decoded response body, or `undefined` when there was none.
231
+ */
232
+ body;
233
+ /**
234
+ * Creates an API error whose message names the request, the status, the
235
+ * reason and any rejected parameters.
236
+ *
237
+ * @param details - The error response.
238
+ * @param code - Discriminant to report. Subclasses pass their own; it is
239
+ * `api` when omitted.
240
+ */
241
+ constructor(details, code = "api") {
242
+ super(code, describe(details), { request: details.request });
243
+ this.status = details.status;
244
+ this.statusText = details.statusText;
245
+ this.reason = details.reason;
246
+ this.errors = details.errors ?? {};
247
+ this.body = details.body;
248
+ }
249
+ /**
250
+ * Returns the form `JSON.stringify` serialises, which is safe to log.
251
+ *
252
+ * @returns The fields of {@link ProxmoxError.toJSON} plus `status`,
253
+ * `reason` and `errors`. The `statusText` and the `body` are left out.
254
+ */
255
+ toJSON() {
256
+ return {
257
+ ...super.toJSON(),
258
+ status: this.status,
259
+ reason: this.reason,
260
+ errors: this.errors,
261
+ };
262
+ }
263
+ }
264
+ /**
265
+ * Signals a `401`: the credentials were rejected.
266
+ *
267
+ * @remarks
268
+ * The cause is a wrong password, an unknown or revoked token, an expired
269
+ * ticket that could not be renewed, or a login that needs a second factor
270
+ * (`tfaRequired`).
271
+ */
272
+ export class ProxmoxAuthenticationError extends ProxmoxApiError {
273
+ /**
274
+ * `true` when a password login was answered with a second-factor challenge
275
+ * and no `otp` was available to answer it. The client raises this case
276
+ * itself, with the status `401`, as Proxmox does not answer the challenge
277
+ * with an error status.
278
+ */
279
+ tfaRequired;
280
+ /**
281
+ * Creates an authentication error.
282
+ *
283
+ * @param details - The error response.
284
+ * @param tfaRequired - Whether the login failed for want of a second
285
+ * factor. `false` when omitted.
286
+ */
287
+ constructor(details, tfaRequired = false) {
288
+ super(details, "authentication");
289
+ this.tfaRequired = tfaRequired;
290
+ }
291
+ }
292
+ /**
293
+ * Signals a `403`: the caller is authenticated but not allowed, because of a
294
+ * missing privilege or an API token used on an endpoint that only accepts a
295
+ * ticket.
296
+ */
297
+ export class ProxmoxPermissionError extends ProxmoxApiError {
298
+ constructor(details) {
299
+ super(details, "permission");
300
+ }
301
+ }
302
+ /**
303
+ * Signals a `400`: Proxmox rejected one or more parameters, which `errors`
304
+ * names.
305
+ */
306
+ export class ProxmoxParameterError extends ProxmoxApiError {
307
+ constructor(details) {
308
+ super(details, "parameter");
309
+ }
310
+ }
311
+ /**
312
+ * Picks the error class that matches a response status.
313
+ *
314
+ * @param details - The error response.
315
+ * @returns A {@link ProxmoxParameterError} for `400`, a
316
+ * {@link ProxmoxAuthenticationError} for `401`, a
317
+ * {@link ProxmoxPermissionError} for `403` and a plain
318
+ * {@link ProxmoxApiError} for every other status.
319
+ */
320
+ export function apiErrorFor(details) {
321
+ switch (details.status) {
322
+ case 400:
323
+ return new ProxmoxParameterError(details);
324
+ case 401:
325
+ return new ProxmoxAuthenticationError(details);
326
+ case 403:
327
+ return new ProxmoxPermissionError(details);
328
+ default:
329
+ return new ProxmoxApiError(details);
330
+ }
331
+ }
332
+ /**
333
+ * Signals that a background task ran to completion and reported failure;
334
+ * thrown by {@link waitForTask}.
335
+ *
336
+ * @remarks
337
+ * The request that started the task succeeded - Proxmox answers with a UPID
338
+ * and does the work in the background - so this is the only place the
339
+ * failure surfaces. The error has no `request`.
340
+ */
341
+ export class ProxmoxTaskError extends ProxmoxError {
342
+ /**
343
+ * Identifier of the task that failed.
344
+ */
345
+ upid;
346
+ /**
347
+ * Proxmox's exit status: the error text, `WARNINGS: <n>` when warnings
348
+ * were to count as failure, or `unknown` when the task stopped without
349
+ * reporting one.
350
+ */
351
+ exitstatus;
352
+ /**
353
+ * Creates a task error whose message names the task and its exit status.
354
+ *
355
+ * @param upid - Identifier of the task that failed.
356
+ * @param exitstatus - The exit status the task reported.
357
+ */
358
+ constructor(upid, exitstatus) {
359
+ super("task", `Task ${upid} failed: ${exitstatus}`);
360
+ this.upid = upid;
361
+ this.exitstatus = exitstatus;
362
+ }
363
+ /**
364
+ * Returns the form `JSON.stringify` serialises, which is safe to log.
365
+ *
366
+ * @returns The fields of {@link ProxmoxError.toJSON} plus `upid` and
367
+ * `exitstatus`.
368
+ */
369
+ toJSON() {
370
+ return { ...super.toJSON(), upid: this.upid, exitstatus: this.exitstatus };
371
+ }
372
+ }
package/dist/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  export { proxmoxApi as default, proxmoxApi } from "./client.js";
2
+ export { ProxmoxAbortError, ProxmoxApiError, ProxmoxAuthenticationError, ProxmoxConfigError, ProxmoxConnectionError, ProxmoxError, type ProxmoxErrorCode, ProxmoxParameterError, ProxmoxPermissionError, type ProxmoxRequestInfo, ProxmoxResponseError, ProxmoxTaskError, ProxmoxTimeoutError, } from "./errors.js";
2
3
  export type { Proxmox } from "./model.js";
3
- export { ProxmoxEngine, type ProxmoxEngineOptions, type ProxmoxEngineOptionsCommon, type ProxmoxEngineOptionsPass, type ProxmoxEngineOptionsToken, } from "./proxmox-engine.js";
4
- export type { ApiParamType, ApiRequestable } from "./proxy.js";
4
+ export { type FetchInterface, ProxmoxEngine, type ProxmoxEngineOptions, type ProxmoxEngineOptionsCommon, type ProxmoxEngineOptionsPass, type ProxmoxEngineOptionsToken, type ProxmoxRequestEvent, } from "./proxmox-engine.js";
5
+ export type { ApiParamType, ApiRequestable, RequestOptions } from "./proxy.js";
5
6
  export { QmMonitor, type USBHostFilter, type USBHostInfo, type USBInfo, } from "./qm-monitor.js";
6
- //# sourceMappingURL=index.d.ts.map
7
+ export { PVE_OPERATION_COUNT, PVE_SCHEMA_VERSION, PVE_VERSION, } from "./schema-info.js";
8
+ export { type ParsedUpid, parseUpid, type TaskStatus, type WaitForTaskOptions, waitForTask, } from "./tasks.js";
package/dist/index.js CHANGED
@@ -1,21 +1,6 @@
1
- // Proxmox-API Interactive proxmox API for developpers how do not like reading docs
2
- // Copyright (C) 2020-2022 Chemouni Uriel <uchemouni@gmail.com>
3
- //
4
- // This program is free software: you can redistribute it and/or modify
5
- // it under the terms of the GNU General Public License as published by
6
- // the Free Software Foundation, either version 3 of the License, or
7
- // (at your option) any later version.
8
- //
9
- // This program is distributed in the hope that it will be useful,
10
- // but WITHOUT ANY WARRANTY; without even the implied warranty of
11
- // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
- // GNU General Public License for more details.
13
- //
14
- // You should have received a copy of the GNU General Public License
15
- // along with this program. If not, see <http://www.gnu.org/licenses/>.
16
1
  export { proxmoxApi as default, proxmoxApi } from "./client.js";
2
+ export { ProxmoxAbortError, ProxmoxApiError, ProxmoxAuthenticationError, ProxmoxConfigError, ProxmoxConnectionError, ProxmoxError, ProxmoxParameterError, ProxmoxPermissionError, ProxmoxResponseError, ProxmoxTaskError, ProxmoxTimeoutError, } from "./errors.js";
17
3
  export { ProxmoxEngine, } from "./proxmox-engine.js";
18
4
  export { QmMonitor, } from "./qm-monitor.js";
19
- // for stress test
20
- // export { buildApiProxy } from './proxy';
21
- //# sourceMappingURL=index.js.map
5
+ export { PVE_OPERATION_COUNT, PVE_SCHEMA_VERSION, PVE_VERSION, } from "./schema-info.js";
6
+ export { parseUpid, waitForTask, } from "./tasks.js";