@virtbase/proxmox-api 2.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 +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 +28413 -28116
  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 -32055
  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/model.js CHANGED
@@ -1,17 +1,5 @@
1
- // Proxmox-API Interactive proxmox API for developpers how do not like reading docs
2
- // Copyright (C) 2020-2024 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/>.
1
+ // Generated by @virtbase/proxmox-api-generator. Do not edit.
2
+ // Source: pve-docs 9.2.14 (Proxmox VE 9.2)
3
+ // SHA-256: 2458b5cc9a174224079982e81d7b6c5626b43523a5f026e29598456c8b46abe6
4
+ // Covers 684 operations.
16
5
  export {};
17
- //# sourceMappingURL=model.js.map
@@ -1,112 +1,331 @@
1
- import type { ApiParamType, ApiRequestable } from "./proxy.js";
1
+ import type { ProxmoxRequestInfo } from "./errors.js";
2
+ import { ProxmoxError } from "./errors.js";
3
+ import type { ApiParamType, ApiRequestable, RequestOptions } from "./proxy.js";
2
4
  /**
3
- * Common Proxmox authentification properties
5
+ * Shape of a `fetch` implementation accepted by {@link ProxmoxEngine}.
6
+ *
7
+ * @remarks
8
+ * Structurally satisfied by the platform `fetch`, so any WHATWG-compatible
9
+ * replacement - a mock, an instrumented wrapper, an agent-bound fetch - can be
10
+ * passed straight through.
11
+ *
12
+ * The engine calls it with a `URL` and with options holding the `method`,
13
+ * the `headers`, a `signal` that aborts on timeout or cancellation and, for
14
+ * a `POST` or `PUT` with parameters, a form-encoded string `body`. A
15
+ * rejection is reported as an abort, a timeout or a failed connection. An
16
+ * implementation that ignores the signal is neither timed out nor cancelled.
17
+ */
18
+ export type FetchInterface = (url: string | URL, options?: RequestInit) => Promise<Response>;
19
+ /**
20
+ * What the client reports through `onEvent`, for logging and metrics. Never
21
+ * contains credentials or parameters.
22
+ *
23
+ * @remarks
24
+ * Every event carries the {@link ProxmoxRequestInfo} of the attempt it
25
+ * belongs to, and its `type` says what happened:
26
+ *
27
+ * - `request`: the attempt is about to be sent. With password
28
+ * authentication the session is obtained first, so an attempt that fails
29
+ * while waiting for a login has no `request` event.
30
+ * - `response`: a success response with the given `status` was received and
31
+ * decoded.
32
+ * - `retry`: the attempt failed with `error` and is repeated after `delayMs`
33
+ * milliseconds.
34
+ * - `error`: the request failed for good with `error`, which is then thrown.
35
+ *
36
+ * `durationMs` is the time in milliseconds since the attempt began, which
37
+ * includes waiting for a login. Login requests are not reported themselves.
38
+ * Nor is a `401` that leads to a new login: its replay shows up as another
39
+ * `request` event with the same `attempt`.
40
+ */
41
+ export type ProxmoxRequestEvent = ProxmoxRequestInfo & ({
42
+ type: "request";
43
+ } | {
44
+ type: "response";
45
+ status: number;
46
+ durationMs: number;
47
+ } | {
48
+ type: "retry";
49
+ delayMs: number;
50
+ error: ProxmoxError;
51
+ } | {
52
+ type: "error";
53
+ durationMs: number;
54
+ error: ProxmoxError;
55
+ });
56
+ /**
57
+ * Connection settings shared by both ways of authenticating.
4
58
  */
5
59
  export interface ProxmoxEngineOptionsCommon {
6
60
  /**
7
- * Proxmox address
8
- * currently used as hostname, so it can not contains a port number.
61
+ * Hostname or IP address, without scheme or port. An IPv6 address may be
62
+ * given bare or in brackets.
9
63
  */
10
64
  host: string;
11
65
  /**
12
- * Proxmox connexion port, default is 8006
66
+ * Port of the API, an integer from 1 to 65535.
67
+ *
68
+ * @defaultValue `8006`
13
69
  */
14
70
  port?: number;
15
71
  /**
16
- * http protocol, can be http or https, default is https
72
+ * URL scheme.
73
+ *
74
+ * @defaultValue `"https"`
17
75
  */
18
76
  schema?: "https" | "http";
19
77
  /**
20
- * separated timeout for authentification call, default is 5 second
78
+ * Milliseconds allowed for each login request. A login that has to answer
79
+ * a second-factor challenge consists of two.
80
+ *
81
+ * @defaultValue `10000`
21
82
  */
22
83
  authTimeout?: number;
23
84
  /**
24
- * timeout for proxmox request, default is 60 seconds
85
+ * Milliseconds allowed for each attempt of every other request, from
86
+ * sending it to the end of the response body. A body handed back as a
87
+ * stream is covered only until the response headers arrive.
88
+ *
89
+ * @defaultValue `60000`
25
90
  */
26
91
  queryTimeout?: number;
27
92
  /**
28
- * print the request in curl or fetch format
93
+ * How often a failed `GET` is retried, with exponential backoff; `0` turns
94
+ * retries off. Other methods are never retried: they start tasks and
95
+ * change state, and Proxmox offers no way to make a repeat safe.
96
+ *
97
+ * A `GET` is retried when no response arrived - a connection error or a
98
+ * timeout - and when the status is 408, 429, 502, 503, 504, 595, 596, 597
99
+ * or 599.
100
+ *
101
+ * @defaultValue `2`
102
+ */
103
+ maxRetries?: number;
104
+ /**
105
+ * Extra headers sent with every request, login requests included. They can
106
+ * replace the default `Accept` and `User-Agent`, and give way to per-call
107
+ * headers and to the authentication headers.
108
+ */
109
+ headers?: Record<string, string>;
110
+ /**
111
+ * Replaces the platform `fetch`.
112
+ *
113
+ * @defaultValue `globalThis.fetch`
114
+ */
115
+ fetch?: FetchInterface;
116
+ /**
117
+ * Observes every request, response, retry and failure. Called
118
+ * synchronously as each one happens; whatever it throws is ignored, so it
119
+ * cannot fail a request.
29
120
  */
30
- debug?: "curl" | "fetch";
121
+ onEvent?: (event: ProxmoxRequestEvent) => void;
31
122
  }
32
123
  /**
33
- * Proxmox authentification as user / password
124
+ * Options for authenticating with a username and password, which yields a
125
+ * ticket that the engine caches and renews.
34
126
  */
35
127
  export interface ProxmoxEngineOptionsPass extends ProxmoxEngineOptionsCommon {
36
128
  /**
37
- * Your username, if not specified will use root@pam
129
+ * `user@realm`. The realm is required.
130
+ *
131
+ * @defaultValue `"root@pam"`
38
132
  */
39
133
  username?: string;
40
134
  /**
41
- * The password
135
+ * The user's password. Must not be empty.
42
136
  */
43
137
  password: string;
138
+ /**
139
+ * Second factor for accounts that require one: a current TOTP code, or a
140
+ * function returning one. Called on every login that Proxmox answers with
141
+ * a second-factor challenge, so prefer a function for anything that
142
+ * outlives a single ticket. An error it throws reaches the caller of the
143
+ * request unchanged.
144
+ */
145
+ otp?: string | (() => string | Promise<string>);
44
146
  }
45
147
  /**
46
- * Proxmox authentification as tokenID / tokenSecret
148
+ * Options for authenticating with an API token, which needs no login.
47
149
  */
48
150
  export interface ProxmoxEngineOptionsToken extends ProxmoxEngineOptionsCommon {
151
+ /**
152
+ * `USER@REALM!TOKENNAME`.
153
+ */
49
154
  tokenID: string;
155
+ /**
156
+ * The secret Proxmox issued for the token. Sent as it is; only its
157
+ * presence is checked.
158
+ */
50
159
  tokenSecret: string;
51
160
  }
52
161
  /**
53
- * Shape of a `fetch` implementation accepted by {@link ProxmoxEngine}.
162
+ * Options of {@link ProxmoxEngine} and `proxmoxApi()`: the connection
163
+ * settings plus the credentials for one way of authenticating.
54
164
  *
55
- * Structurally satisfied by the platform `fetch`, so any WHATWG-compatible
56
- * replacement - a mock, an instrumented wrapper, an agent-bound fetch - can be
57
- * passed straight through.
58
- */
59
- export type FetchInterface = (url: string | URL, options?: RequestInit) => Promise<Response>;
60
- /**
61
- * Type Union for proxmox Authentification options
165
+ * A `tokenID` selects token authentication, even next to a `password`.
62
166
  */
63
- export type ProxmoxEngineOptions = (ProxmoxEngineOptionsToken | ProxmoxEngineOptionsPass) & {
64
- fetch?: FetchInterface;
65
- };
167
+ export type ProxmoxEngineOptions = ProxmoxEngineOptionsToken | ProxmoxEngineOptionsPass;
66
168
  /**
67
- * Default Proxmox doRequest provider, this Class will be used if you provide Proxmox authentification options to the Proxy generator
169
+ * The HTTP transport behind `proxmoxApi()`: authentication, encoding, retries
170
+ * and error mapping. Construct it directly to keep hold of the session.
171
+ *
172
+ * @remarks
173
+ * Credentials and the session are held in private fields, so logging or
174
+ * serialising an engine never prints them.
175
+ *
176
+ * One engine serves any number of concurrent requests. With password
177
+ * authentication it logs in when the first request is made, caches the
178
+ * ticket, replaces it once it is an hour old and lets concurrent requests
179
+ * share a single login.
180
+ *
181
+ * @example
182
+ * ```ts
183
+ * const engine = new ProxmoxEngine({
184
+ * host: "192.0.2.10",
185
+ * username: "root@pam",
186
+ * password: process.env.PVE_PASSWORD!,
187
+ * });
188
+ * const proxmox = proxmoxApi(engine);
189
+ *
190
+ * const { ticket, CSRFPreventionToken } = await engine.getTicket();
191
+ * ```
68
192
  */
69
193
  export declare class ProxmoxEngine implements ApiRequestable {
70
- CSRFPreventionToken?: string;
71
- ticket?: string;
72
- private readonly username;
73
- private readonly password;
74
- private hostname;
75
- private port?;
76
- private readonly schema;
77
- private authTimeout;
78
- private queryTimeout;
79
- private debug?;
80
- private fetch;
194
+ #private;
195
+ /**
196
+ * The origin every request is sent to, e.g. `https://192.0.2.10:8006`.
197
+ */
198
+ readonly origin: string;
199
+ /**
200
+ * Validates the options and prepares the transport, without sending
201
+ * anything.
202
+ *
203
+ * @param options - Connection settings and credentials. A `tokenID`
204
+ * selects token authentication, even next to a `password`.
205
+ * @throws A {@link ProxmoxConfigError} if `schema` is neither `https` nor
206
+ * `http`, `port` is not an integer from 1 to 65535, `host` is not a bare
207
+ * hostname or IP address, `tokenID` does not read
208
+ * `USER@REALM!TOKENNAME`, `tokenSecret` is empty, neither a `tokenID`
209
+ * nor a `password` is given, or `username` has no realm.
210
+ */
81
211
  constructor(options: ProxmoxEngineOptions);
82
- get host(): string;
83
212
  /**
213
+ * The cached ticket of the last password login.
84
214
  *
85
- * @param method http method GET POST PUT of DELETE
86
- * @param path http path
87
- * @param pathTemplate http path without var replacements *
88
- * @param params query params
89
- * @param retries retries id
90
- * @returns data from remote response
215
+ * @remarks
216
+ * `undefined` before the first login, after {@link ProxmoxEngine.logout}
217
+ * and with token authentication. Reading it sends nothing and does not
218
+ * renew a ticket that is due; call {@link ProxmoxEngine.getTicket} to log
219
+ * in or renew as needed.
91
220
  */
92
- doRequest(method: string, path: string, pathTemplate: string, params?: ApiParamType, retries?: number): Promise<unknown>;
221
+ get ticket(): string | undefined;
93
222
  /**
94
- * Decode a response into the PVE `{ data, errors }` envelope.
223
+ * The CSRF token that belongs to {@link ProxmoxEngine.ticket}, which
224
+ * Proxmox demands alongside it for every request that is not a `GET`.
225
+ * `undefined` whenever the ticket is.
95
226
  */
96
- private readBody;
227
+ get CSRFPreventionToken(): string | undefined;
97
228
  /**
98
- * Echo the request that just failed, as a runnable `curl` line or as the
99
- * `fetch` call that produced it. Only fires when `debug` is set.
229
+ * Drops the cached ticket, so the next request logs in again.
230
+ *
231
+ * @remarks
232
+ * Nothing is sent, so the ticket itself stays valid until Proxmox expires
233
+ * it. A login already in flight is not cancelled, and its ticket is cached
234
+ * when it completes. With token authentication there is nothing to drop.
100
235
  */
101
- private logRequest;
236
+ logout(): void;
102
237
  /**
103
- * return the current ticket/token, or create new ones, is previous one had been discared, or missing.
104
- * @returns Proxmox API ticket and CSRFPreventionToken
238
+ * Returns the ticket and CSRF token, logging in first when there is none
239
+ * or the cached one is due for renewal.
240
+ *
241
+ * @remarks
242
+ * A cached ticket is returned as long as it is less than an hour old. A
243
+ * login already in flight is joined rather than doubled. A login is
244
+ * bounded by `authTimeout` per request and is not retried.
245
+ *
246
+ * @returns The ticket and the CSRF token that goes with it. Both are
247
+ * bearer credentials.
248
+ * @throws A {@link ProxmoxConfigError} if the engine authenticates with an
249
+ * API token, which has no ticket.
250
+ * @throws A {@link ProxmoxAuthenticationError} if Proxmox rejects the
251
+ * username or password, or asks for a second factor that the `otp`
252
+ * option does not supply. The latter has `tfaRequired` set.
253
+ * @throws A {@link ProxmoxTimeoutError} if a login request exceeds
254
+ * `authTimeout`.
255
+ * @throws A {@link ProxmoxConnectionError} if a login request gets no
256
+ * response.
257
+ * @throws A {@link ProxmoxResponseError} if the reply to a successful
258
+ * login carries no ticket or cannot be parsed.
259
+ * @throws A {@link ProxmoxApiError} if the login is answered with any
260
+ * other error status.
105
261
  */
106
262
  getTicket(): Promise<{
107
263
  ticket: string;
108
264
  CSRFPreventionToken: string;
109
265
  }>;
266
+ /**
267
+ * Sends one API request and returns its decoded reply.
268
+ *
269
+ * @remarks
270
+ * This is the primitive the proxy calls. Parameters travel as a
271
+ * form-encoded body for `POST` and `PUT`, and in the query string for
272
+ * every other method.
273
+ *
274
+ * With password authentication the request first waits for a session,
275
+ * which means a login when there is no ticket or the cached one is due
276
+ * for renewal. Concurrent requests share one login. A request answered
277
+ * with `401` is replayed with a fresh ticket - once, and for any method,
278
+ * since a rejected ticket means the request was never run. With an API
279
+ * token there is no login and a `401` is final.
280
+ *
281
+ * Only a `GET` is retried, up to `maxRetries` times: after a connection
282
+ * error, after a timeout - of the request or of the login it waited for -
283
+ * and after the statuses 408, 429, 502, 503, 504, 595, 596, 597 and 599.
284
+ * The delay is at most half a second before the first retry and doubles
285
+ * with each further one, up to eight seconds. An abort ends it at once.
286
+ *
287
+ * Every attempt has `timeout` milliseconds, counted from the moment it is
288
+ * sent, after any login, until the response body has been read. A body
289
+ * returned as a stream is covered only until the response headers arrive;
290
+ * from then on only `signal` can cancel it.
291
+ *
292
+ * Requests, responses, retries and the final failure are reported to
293
+ * `onEvent`. An error raised by a login names the login request, not this
294
+ * one, as its `request`. An error thrown by an `otp` callback is passed on
295
+ * unchanged and unreported.
296
+ *
297
+ * @param method - HTTP method, in upper or lower case.
298
+ * @param path - Path to request, appended to {@link ProxmoxEngine.origin}
299
+ * as it is. It has to start with `/` and to be escaped already.
300
+ * @param pathTemplate - The path with `*` in place of each id. Used only to
301
+ * label errors and events.
302
+ * @param params - Parameters to send. Booleans are sent as `1` and `0`, an
303
+ * array as its key repeated once per element; `null` and `undefined`
304
+ * values are left out. The object is not modified.
305
+ * @param options - Per-call overrides of the timeout, the retries and the
306
+ * headers, and a signal to cancel the request with.
307
+ * @returns The `data` field of a JSON reply, or `null` when it has none.
308
+ * A reply of type `application/octet-stream` yields the response body
309
+ * as a `ReadableStream`, and any other type the body as text, or `null`
310
+ * when it is empty.
311
+ * @throws A {@link ProxmoxAbortError} if `options.signal` is aborted
312
+ * before the request is sent, or aborts while it waits for a login, is
313
+ * in flight, or waits for a retry.
314
+ * @throws A {@link ProxmoxTimeoutError} if the request, or the login it
315
+ * waits for, exceeds its timeout and no retry is left.
316
+ * @throws A {@link ProxmoxConnectionError} if no complete response arrives
317
+ * and no retry is left.
318
+ * @throws A {@link ProxmoxParameterError} if Proxmox answers `400`.
319
+ * @throws A {@link ProxmoxAuthenticationError} if Proxmox answers `401`:
320
+ * to an API token, to a ticket for the second time in this call, or to
321
+ * the login. A login that needs a second factor which the `otp` option
322
+ * does not supply fails the same way, with `tfaRequired` set.
323
+ * @throws A {@link ProxmoxPermissionError} if Proxmox answers `403`.
324
+ * @throws A {@link ProxmoxApiError} if Proxmox answers with any other
325
+ * error status. For a status that is retried, this is the answer to the
326
+ * last attempt.
327
+ * @throws A {@link ProxmoxResponseError} if a success declares a JSON body
328
+ * that does not parse, or the reply to a login carries no ticket.
329
+ */
330
+ doRequest(method: string, path: string, pathTemplate: string, params?: ApiParamType | null, options?: RequestOptions): Promise<unknown>;
110
331
  }
111
- export default ProxmoxEngine;
112
- //# sourceMappingURL=proxmox-engine.d.ts.map