@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.
- package/CHANGELOG.md +10 -53
- package/LICENSE +22 -0
- package/README.md +81 -82
- package/dist/client.d.ts +13 -7
- package/dist/client.js +23 -23
- package/dist/errors.d.ts +364 -0
- package/dist/errors.js +372 -0
- package/dist/index.d.ts +5 -3
- package/dist/index.js +3 -18
- package/dist/model.d.ts +28408 -28157
- package/dist/model.js +4 -16
- package/dist/proxmox-engine.d.ts +273 -54
- package/dist/proxmox-engine.js +772 -248
- package/dist/proxy.d.ts +61 -19
- package/dist/proxy.js +118 -33
- package/dist/qm-monitor.d.ts +225 -25
- package/dist/qm-monitor.js +152 -52
- package/dist/schema-info.d.ts +12 -0
- package/dist/schema-info.js +13 -0
- package/dist/tasks.d.ts +129 -0
- package/dist/tasks.js +132 -0
- package/package.json +33 -34
- package/dist/client.d.ts.map +0 -1
- package/dist/client.js.map +0 -1
- package/dist/index.d.ts.map +0 -1
- package/dist/index.js.map +0 -1
- package/dist/model.d.ts.map +0 -1
- package/dist/model.js.map +0 -1
- package/dist/proxmox-engine.d.ts.map +0 -1
- package/dist/proxmox-engine.js.map +0 -1
- package/dist/proxy.d.ts.map +0 -1
- package/dist/proxy.js.map +0 -1
- package/dist/qm-monitor.d.ts.map +0 -1
- package/dist/qm-monitor.js.map +0 -1
- package/src/__tests__/helpers.ts +0 -39
- package/src/__tests__/proxmox-engine.test.ts +0 -393
- package/src/__tests__/proxy.test.ts +0 -190
- package/src/__tests__/qm-monitor.test.ts +0 -215
- package/src/client.ts +0 -58
- package/src/index.ts +0 -34
- package/src/model.ts +0 -32101
- package/src/proxmox-engine.ts +0 -452
- package/src/proxy.ts +0 -195
- package/src/qm-monitor.ts +0 -303
package/dist/errors.d.ts
ADDED
|
@@ -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
|
+
}
|