@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/proxy.d.ts CHANGED
@@ -1,39 +1,81 @@
1
1
  /**
2
- * Parameters for one API call.
3
- *
4
- * Values are whatever the endpoint declares in `model.ts`; the engine encodes
5
- * them on the way out.
2
+ * Parameters for one API call, as declared for the endpoint in `model.ts`.
6
3
  */
7
4
  export type ApiParamType = Record<string, unknown>;
5
+ /**
6
+ * Per-call overrides, passed as the second argument of any `$method()`.
7
+ *
8
+ * @remarks
9
+ * The proxy hands them to the transport untouched. The behaviour described
10
+ * here is that of {@link ProxmoxEngine}; another {@link ApiRequestable} has
11
+ * to honour them itself.
12
+ */
13
+ export interface RequestOptions {
14
+ /**
15
+ * Cancels the request, including a retry or a login it is waiting on. The
16
+ * call then rejects with a {@link ProxmoxAbortError}.
17
+ */
18
+ signal?: AbortSignal;
19
+ /**
20
+ * Milliseconds before an attempt of this request gives up. Overrides
21
+ * `queryTimeout`.
22
+ */
23
+ timeout?: number;
24
+ /**
25
+ * Retries for this request. Overrides the client's `maxRetries`. Ignored
26
+ * for every method but `GET`, the only one that is ever retried.
27
+ */
28
+ maxRetries?: number;
29
+ /**
30
+ * Extra headers for this request. They win over the client's `headers`
31
+ * but cannot replace the authentication headers.
32
+ */
33
+ headers?: Record<string, string>;
34
+ }
8
35
  /**
9
36
  * The transport the proxy calls into.
10
37
  *
11
38
  * Implement it to send requests somewhere other than a live cluster - a
12
39
  * recorded fixture, a queue, a per-tenant router - and hand the result to
13
- * {@link buildApiProxy} or `proxmoxApi()`.
40
+ * `proxmoxApi()`.
14
41
  */
15
42
  export interface ApiRequestable {
16
43
  /**
17
- * Execute one request.
44
+ * Performs one API call on behalf of the proxy.
18
45
  *
19
- * @param httpMethod GET, POST, PUT or DELETE.
20
- * @param path The concrete path, placeholders already substituted.
21
- * @param pathTemplate The same path with `*` in place of each substituted
22
- * value, which makes calls to one endpoint groupable for logging or
23
- * metrics regardless of the ids involved.
24
- * @param params Query or body parameters.
46
+ * @param httpMethod - The method as written after the `$` of the call:
47
+ * `get`, `post`, `put` or `delete` for the generated methods. The proxy
48
+ * does not change its case.
49
+ * @param path - The concrete path, placeholders already substituted.
50
+ * @param pathTemplate - The same path with `*` in place of each substituted
51
+ * value, so calls to one endpoint can be grouped regardless of the ids.
52
+ * @param params - Query or body parameters, as the caller passed them.
53
+ * @param options - Per-call overrides, as the caller passed them.
54
+ * @returns The value the `$method()` call resolves with: for Proxmox, the
55
+ * content of the response's `data` field.
25
56
  */
26
- doRequest(httpMethod: string, path: string, pathTemplate: string, params?: ApiParamType): Promise<unknown>;
57
+ doRequest(httpMethod: string, path: string, pathTemplate: string, params?: ApiParamType | null, options?: RequestOptions): Promise<unknown>;
27
58
  }
28
59
  /**
29
- * Build the proxy that turns property access into API paths.
60
+ * Builds the proxy that turns property access into API paths.
30
61
  *
62
+ * @remarks
31
63
  * Nothing is requested while the path is walked - each step returns a new
32
- * proxy. The call happens when a `$`-prefixed method is invoked.
64
+ * proxy. The call happens when a `$`-prefixed method is invoked, which
65
+ * passes the method name, the path, its template, the parameters and the
66
+ * options to `engine.doRequest()` and returns its result.
67
+ *
68
+ * A plain property appends a segment and `$(value)` appends the value of a
69
+ * path variable. Both throw a {@link ProxmoxConfigError} for a segment that
70
+ * is empty, `.` or `..`. A leading underscore is removed from a property
71
+ * name, which reaches segments that collide with a reserved name: on the
72
+ * root, `on` is `undefined` while `_on` addresses `/on`.
33
73
  *
34
- * @param engine Transport to send requests through.
35
- * @param path Prefix every path is built on, normally `/api2/json`.
36
- * @typeParam T The generated API shape to present, e.g. `Proxmox.Api`.
74
+ * @typeParam T - The generated API shape to present, e.g. `Proxmox.Api`. It
75
+ * is asserted, not checked: the proxy itself accepts any path.
76
+ * @param engine - Transport to send requests through.
77
+ * @param path - Prefix every path is built on, normally `/api2/json`. It is
78
+ * used as given, without escaping.
79
+ * @returns The root proxy.
37
80
  */
38
81
  export declare function buildApiProxy<T>(engine: ApiRequestable, path: string): T;
39
- //# sourceMappingURL=proxy.d.ts.map
package/dist/proxy.js CHANGED
@@ -1,18 +1,4 @@
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/>.
1
+ import { ProxmoxConfigError } from "./errors.js";
16
2
  /**
17
3
  * Keys that resolve on the node instead of extending the path.
18
4
  *
@@ -20,12 +6,13 @@
20
6
  * silently build `/toString` and hand back another proxy.
21
7
  */
22
8
  const OBJECT_KEYS = new Set([
9
+ "toJSON",
23
10
  "toString",
24
11
  "valueOf",
25
12
  "toLocaleString",
26
13
  ]);
27
14
  /**
28
- * Reserved at the root only.
15
+ * Keys reserved at the root only.
29
16
  *
30
17
  * A root proxy is the value most likely to be handed to code that sniffs for
31
18
  * an EventEmitter - a logger, a test harness - and every one of those probes
@@ -49,18 +36,35 @@ const EVENT_EMITTER_KEYS = new Set([
49
36
  "removeListener",
50
37
  "setMaxListeners",
51
38
  ]);
39
+ /**
40
+ * Every key that resolves on the root node instead of extending the path.
41
+ */
52
42
  const ROOT_KEYS = new Set([
53
43
  ...OBJECT_KEYS,
54
44
  ...EVENT_EMITTER_KEYS,
55
45
  ]);
56
46
  /**
57
- * Characters that would change the shape of the URL rather than sit inside a
58
- * path segment. A `/` would invent a path level; `?` and `#` would start a
59
- * query or fragment and drop the rest of the path.
47
+ * Encodes one value for use as a single path segment.
48
+ *
49
+ * @remarks
50
+ * Everything that could change which endpoint is addressed is neutralised:
51
+ * `/`, `?`, `#`, `\` and `%` are percent-encoded, and the dot segments `.`
52
+ * and `..` - which a URL parser resolves even when percent-encoded - are
53
+ * refused outright, as is an empty value. `:` and `@` are legal inside a
54
+ * segment and stay readable, since UPIDs and user ids are full of them.
55
+ *
56
+ * @param value - A segment name or the value of a path variable. A number is
57
+ * used in its decimal form.
58
+ * @returns The value encoded as by `encodeURIComponent`, except that `:` and
59
+ * `@` are left as they are.
60
+ * @throws A {@link ProxmoxConfigError} if the value is empty, `.` or `..`.
60
61
  */
61
- const UNSAFE_IN_SEGMENT = /[/?#]/g;
62
62
  function escapeSegment(value) {
63
- return String(value).replace(UNSAFE_IN_SEGMENT, (char) => encodeURIComponent(char));
63
+ const text = String(value);
64
+ if (text === "" || text === "." || text === "..") {
65
+ throw new ProxmoxConfigError(`Invalid path value ${JSON.stringify(text)}: it cannot be used as a path segment.`);
66
+ }
67
+ return encodeURIComponent(text).replace(/%3A/g, ":").replace(/%40/g, "@");
64
68
  }
65
69
  /**
66
70
  * One node of the path being built.
@@ -69,20 +73,64 @@ function escapeSegment(value) {
69
73
  * path can be held onto and reused.
70
74
  */
71
75
  class ApiNode {
76
+ /**
77
+ * Transport that requests made from this node are sent through.
78
+ */
72
79
  engine;
80
+ /**
81
+ * The concrete path walked so far.
82
+ */
73
83
  path;
84
+ /**
85
+ * The same path with `*` for each substituted value, handed to the
86
+ * transport as the path template.
87
+ */
74
88
  model;
75
89
  constructor(engine, path, model) {
76
90
  this.engine = engine;
77
91
  this.path = path;
78
92
  this.model = model;
79
93
  }
94
+ /**
95
+ * Describes the node for logs and debuggers.
96
+ *
97
+ * @returns The path in the form `ProxyApi{path:/api2/json/nodes}`.
98
+ */
80
99
  toString() {
81
100
  return `ProxyApi{path:${this.path}}`;
82
101
  }
102
+ /**
103
+ * Returns the form `JSON.stringify` serialises.
104
+ *
105
+ * @returns The path alone; the transport is left out.
106
+ */
107
+ toJSON() {
108
+ return { path: this.path };
109
+ }
83
110
  }
84
111
  /**
85
- * Resolve one property access into either a request function or the next node.
112
+ * Resolves one property access into either a request function or the next
113
+ * node.
114
+ *
115
+ * @remarks
116
+ * The key decides the result:
117
+ *
118
+ * - `$` gives a function that takes the value of a path variable and
119
+ * returns the child node for it. The value is escaped in the path and
120
+ * appears as `*` in the template.
121
+ * - Any other key starting with `$` gives a function that sends a request
122
+ * for the node, with the rest of the key as the method.
123
+ * - Every other key gives the child node for that segment.
124
+ *
125
+ * Children are always created with the non-root handler, so the names
126
+ * reserved at the root are ordinary segments from the first level down.
127
+ *
128
+ * @param node - The node the property was read from.
129
+ * @param key - The property name.
130
+ * @returns A function for a `$` key, the proxy of a child node otherwise.
131
+ * @throws A {@link ProxmoxConfigError} if the key names a segment that is
132
+ * empty, `.` or `..` once a leading underscore is removed. The function
133
+ * returned for `$` throws it for such a value.
86
134
  */
87
135
  function navigate(node, key) {
88
136
  if (key === "$") {
@@ -90,21 +138,41 @@ function navigate(node, key) {
90
138
  }
91
139
  if (key.startsWith("$")) {
92
140
  const httpMethod = key.slice(1);
93
- return (params) => node.engine.doRequest(httpMethod, node.path, node.model, params);
141
+ return (params, options) => node.engine.doRequest(httpMethod, node.path, node.model, params, options);
94
142
  }
95
143
  // A leading underscore is the escape hatch for segments that collide with a
96
144
  // reserved name: `_on` requests `/on`.
97
- const segment = key.startsWith("_") ? key.slice(1) : key;
145
+ const segment = escapeSegment(key.startsWith("_") ? key.slice(1) : key);
98
146
  return descend(node, segment, segment, childHandler);
99
147
  }
148
+ /**
149
+ * Creates the proxy for a child of a node.
150
+ *
151
+ * @param node - The parent, which is left unchanged.
152
+ * @param pathSegment - Segment to append to the concrete path. It must
153
+ * already be escaped.
154
+ * @param modelSegment - Segment to append to the path template: the same
155
+ * segment, or `*` for the value of a path variable.
156
+ * @param handler - Traps for the new proxy.
157
+ * @returns A proxy around the new node.
158
+ */
100
159
  function descend(node, pathSegment, modelSegment, handler) {
101
160
  return new Proxy(new ApiNode(node.engine, `${node.path}/${pathSegment}`, `${node.model}/${modelSegment}`), handler);
102
161
  }
162
+ /**
163
+ * Creates the traps that make a node navigable.
164
+ *
165
+ * @param reserved - Property names that are read from the node itself. A
166
+ * name the node does not have reads as `undefined`.
167
+ * @returns A handler that reads symbols and reserved names from the node
168
+ * and resolves every other property with {@link navigate}.
169
+ */
103
170
  function createHandler(reserved) {
104
171
  return {
105
- // `new proxmox.nodes()` yields the node rather than throwing, which keeps
106
- // the proxy inert in code that probes values by constructing them.
107
- construct: (target) => target,
172
+ /**
173
+ * Reads symbols and reserved names from the node itself, and resolves
174
+ * every other property into a request function or a child node.
175
+ */
108
176
  get(target, property) {
109
177
  if (typeof property === "symbol" || reserved.has(property)) {
110
178
  const value = Reflect.get(target, property);
@@ -117,19 +185,36 @@ function createHandler(reserved) {
117
185
  },
118
186
  };
119
187
  }
188
+ /**
189
+ * Traps for every node below the root.
190
+ */
120
191
  const childHandler = createHandler(OBJECT_KEYS);
192
+ /**
193
+ * Traps for the root node, which reserves the EventEmitter names as well.
194
+ */
121
195
  const rootHandler = createHandler(ROOT_KEYS);
122
196
  /**
123
- * Build the proxy that turns property access into API paths.
197
+ * Builds the proxy that turns property access into API paths.
124
198
  *
199
+ * @remarks
125
200
  * Nothing is requested while the path is walked - each step returns a new
126
- * proxy. The call happens when a `$`-prefixed method is invoked.
201
+ * proxy. The call happens when a `$`-prefixed method is invoked, which
202
+ * passes the method name, the path, its template, the parameters and the
203
+ * options to `engine.doRequest()` and returns its result.
204
+ *
205
+ * A plain property appends a segment and `$(value)` appends the value of a
206
+ * path variable. Both throw a {@link ProxmoxConfigError} for a segment that
207
+ * is empty, `.` or `..`. A leading underscore is removed from a property
208
+ * name, which reaches segments that collide with a reserved name: on the
209
+ * root, `on` is `undefined` while `_on` addresses `/on`.
127
210
  *
128
- * @param engine Transport to send requests through.
129
- * @param path Prefix every path is built on, normally `/api2/json`.
130
- * @typeParam T The generated API shape to present, e.g. `Proxmox.Api`.
211
+ * @typeParam T - The generated API shape to present, e.g. `Proxmox.Api`. It
212
+ * is asserted, not checked: the proxy itself accepts any path.
213
+ * @param engine - Transport to send requests through.
214
+ * @param path - Prefix every path is built on, normally `/api2/json`. It is
215
+ * used as given, without escaping.
216
+ * @returns The root proxy.
131
217
  */
132
218
  export function buildApiProxy(engine, path) {
133
219
  return new Proxy(new ApiNode(engine, path, path), rootHandler);
134
220
  }
135
- //# sourceMappingURL=proxy.js.map
@@ -1,96 +1,296 @@
1
1
  import type { Proxmox } from "./model.js";
2
- export declare const VALID_QEMU_INFO_SIMPLE: readonly ["backup", "balloon", "block-jobs", "blockstats", "capture", "chardev", "cpus", "cpustats", "dump", "history", "hotpluggable-cpus", "ioapic", "iothreads", "irq", "jit", "kvm", "memdev", "memory-devices", "memory_size_summary", "mice", "migrate", "migrate_cache_size", "migrate_capabilities", "migrate_parameters", "name", "network", "numa", "opcount", "pci", "pic", "profile", "qdm", "qtree", "ramblock", "rdma", "roms", "savevm", "sev", "snapshots", "spice", "status", "tpm", "usb", "usbhost", "usernet", "uuid", "version", "vm-generation-id", "vnc"];
3
- export declare const VALID_QEMU_INFO_OPTION: readonly ["block", "lapic", "mtree", "qom-tree", "registers", "sync-profile", "trace-events"];
4
- export declare const VALID_QEMU_INFO_PARAM: readonly ["rocker-of-dpa-flows", "rocker-of-dpa-groups", "rocker-ports"];
2
+ /**
3
+ * `info` subcommands that take no argument.
4
+ *
5
+ * `mem` and `tlb` are left out on purpose: both time out through the PVE
6
+ * monitor endpoint.
7
+ */
8
+ declare const VALID_QEMU_INFO_SIMPLE: readonly ["backup", "balloon", "block-jobs", "blockstats", "capture", "chardev", "cpus", "cpustats", "dump", "history", "hotpluggable-cpus", "ioapic", "iothreads", "irq", "jit", "kvm", "memdev", "memory-devices", "memory_size_summary", "mice", "migrate", "migrate_cache_size", "migrate_capabilities", "migrate_parameters", "name", "network", "numa", "opcount", "pci", "pic", "profile", "qdm", "qtree", "ramblock", "rdma", "roms", "savevm", "sev", "snapshots", "spice", "status", "tpm", "usb", "usbhost", "usernet", "uuid", "version", "vm-generation-id", "vnc"];
9
+ /**
10
+ * `info` subcommands that accept optional arguments.
11
+ */
12
+ declare const VALID_QEMU_INFO_OPTION: readonly ["block", "lapic", "mtree", "qom-tree", "registers", "sync-profile", "trace-events"];
13
+ /**
14
+ * `info` subcommands that need at least one argument.
15
+ */
16
+ declare const VALID_QEMU_INFO_PARAM: readonly ["rocker-of-dpa-flows", "rocker-of-dpa-groups", "rocker-ports"];
17
+ /**
18
+ * Name of an `info` subcommand that {@link QmMonitor.info} sends without
19
+ * arguments.
20
+ */
5
21
  export type QemuInfoSimple = (typeof VALID_QEMU_INFO_SIMPLE)[number];
22
+ /**
23
+ * Name of an `info` subcommand that {@link QmMonitor.info} sends with or
24
+ * without arguments.
25
+ */
6
26
  export type QemuInfoOption = (typeof VALID_QEMU_INFO_OPTION)[number];
27
+ /**
28
+ * Name of an `info` subcommand that {@link QmMonitor.info} only sends with
29
+ * at least one argument.
30
+ */
7
31
  export type QemuInfoParam = (typeof VALID_QEMU_INFO_PARAM)[number];
8
- /** One USB device attached to the guest, from `info usb`. */
32
+ /**
33
+ * One USB device attached to the guest, as parsed from `info usb` by
34
+ * {@link QmMonitor.infoUsb}.
35
+ */
9
36
  export interface USBInfo {
37
+ /**
38
+ * The device's address as QEMU prints it, e.g. `1.1`.
39
+ */
10
40
  device: string;
41
+ /**
42
+ * Port of the guest's USB bus the device sits on, e.g. `1`.
43
+ */
11
44
  port: string;
45
+ /**
46
+ * Speed with its unit, e.g. `1.5 Mb/s`.
47
+ */
12
48
  speed: string;
13
49
  /**
50
+ * Product name exactly as QEMU prints it, which can end in a space.
51
+ *
14
52
  * Absent for a device QEMU reports without a product string - the trailing
15
- * `, Product ..., ID: ...` is optional in the monitor's own output.
53
+ * `, Product ..., ID: ...` is optional in the monitor's own output, and is
54
+ * only recognised as a whole.
16
55
  */
17
56
  product?: string;
18
- /** Absent for the same reason as {@link USBInfo.product}. */
57
+ /**
58
+ * Identifier the device was added under, which
59
+ * {@link QmMonitor.deviceDel} takes. Absent for the same reason as
60
+ * {@link USBInfo.product}.
61
+ */
19
62
  id?: string;
20
63
  }
21
- /** One USB device present on the host, from `info usbhost`. */
64
+ /**
65
+ * One USB device present on the host, as parsed from `info usbhost` by
66
+ * {@link QmMonitor.infoUsbhost}.
67
+ */
22
68
  export interface USBHostInfo {
69
+ /**
70
+ * Number of the host bus the device is on.
71
+ */
23
72
  bus: number;
73
+ /**
74
+ * Address of the device on that bus.
75
+ */
24
76
  addr: number;
77
+ /**
78
+ * Physical port on that bus, e.g. `2`. Together with `bus` it is what
79
+ * {@link QmMonitor.deviceAddByPort} takes.
80
+ */
25
81
  port: string;
82
+ /**
83
+ * Speed with its unit, e.g. `480 Mb/s`.
84
+ */
26
85
  speed: string;
86
+ /**
87
+ * Device class code as printed, e.g. `00`.
88
+ */
27
89
  class: string;
90
+ /**
91
+ * Four lower-case hexadecimal digits without a `0x` prefix, e.g. `046d`.
92
+ */
28
93
  vendorId: string;
94
+ /**
95
+ * Four lower-case hexadecimal digits without a `0x` prefix, e.g. `c52b`.
96
+ */
29
97
  productId: string;
98
+ /**
99
+ * Product name as the host reports it. May be empty.
100
+ */
30
101
  name: string;
31
102
  }
32
- /** Narrows which host devices {@link QmMonitor.infoUsbhost} returns. */
103
+ /**
104
+ * Narrows which host devices {@link QmMonitor.infoUsbhost} returns.
105
+ *
106
+ * A device is kept when it matches every pattern given; an empty filter
107
+ * keeps all of them. Each pattern is applied with `RegExp.prototype.test`
108
+ * to one device after another, so it must not carry the `g` or `y` flag,
109
+ * which make `test` remember its position between calls.
110
+ */
33
111
  export interface USBHostFilter {
112
+ /**
113
+ * Tested against {@link USBHostInfo.vendorId}.
114
+ */
34
115
  vendorId?: RegExp;
116
+ /**
117
+ * Tested against {@link USBHostInfo.productId}.
118
+ */
35
119
  productId?: RegExp;
120
+ /**
121
+ * Tested against {@link USBHostInfo.name}.
122
+ */
36
123
  name?: RegExp;
37
124
  }
38
125
  /**
39
- * QEMU monitor access for one guest, over
40
- * `POST /nodes/{node}/qemu/{vmid}/monitor`.
126
+ * Gives access to the QEMU monitor of one guest, over
127
+ * `POST /nodes/{node}/qemu/{vmid}/monitor`; use it for monitor commands that
128
+ * have no endpoint of their own.
41
129
  *
130
+ * @remarks
42
131
  * The monitor is a debugging interface: commands are passed through
43
132
  * unvalidated and replies are unstructured text whose format is not stable
44
133
  * across QEMU versions. Prefer a real endpoint wherever one exists.
134
+ *
135
+ * Every method sends at least one request and fails with the error of that
136
+ * request - a {@link ProxmoxError} when the client is backed by a
137
+ * {@link ProxmoxEngine}. Nothing here is retried, as the requests are
138
+ * `POST`s.
45
139
  */
46
140
  export declare class QmMonitor {
141
+ /**
142
+ * Name of the node the guest runs on.
143
+ */
47
144
  readonly node: string;
145
+ /**
146
+ * Id of the guest.
147
+ */
48
148
  readonly vmid: number;
49
- /** Send a raw monitor command and return its unparsed reply. */
149
+ /**
150
+ * Sends a raw monitor command and returns its unparsed reply.
151
+ *
152
+ * @param command - The command line, handed to the monitor as it is.
153
+ * @returns The monitor's reply as text.
154
+ * @throws A {@link ProxmoxError} if the request fails.
155
+ */
50
156
  readonly monitor: (command: string) => Promise<string>;
157
+ /**
158
+ * Binds a monitor to one guest, without sending anything.
159
+ *
160
+ * @param proxmox - Client to send the monitor commands through.
161
+ * @param node - Name of the node the guest runs on.
162
+ * @param vmid - Id of the guest.
163
+ * @throws A {@link ProxmoxConfigError} if `node` is empty, `.` or `..`.
164
+ */
51
165
  constructor(proxmox: Proxmox.Api, node: string, vmid: number);
166
+ /**
167
+ * Runs `info <type>` for a subcommand that takes no argument.
168
+ *
169
+ * @param type - The `info` subcommand.
170
+ * @returns The monitor's unparsed reply.
171
+ * @throws A {@link ProxmoxError} if the request fails.
172
+ */
52
173
  info(type: QemuInfoSimple): Promise<string>;
174
+ /**
175
+ * Runs `info <type>` for a subcommand that accepts arguments.
176
+ *
177
+ * @param type - The `info` subcommand.
178
+ * @param args - Arguments for the subcommand, appended to the command
179
+ * separated by single spaces and otherwise as given.
180
+ * @returns The monitor's unparsed reply.
181
+ * @throws A {@link ProxmoxError} if the request fails.
182
+ */
53
183
  info(type: QemuInfoOption, ...args: string[]): Promise<string>;
184
+ /**
185
+ * Runs `info <type>` for a subcommand that needs at least one argument.
186
+ *
187
+ * @param type - The `info` subcommand.
188
+ * @param arg1 - The argument the subcommand requires.
189
+ * @param args - Further arguments. All of them are appended to the command
190
+ * separated by single spaces and otherwise as given.
191
+ * @returns The monitor's unparsed reply.
192
+ * @throws A {@link ProxmoxError} if the request fails.
193
+ */
54
194
  info(type: QemuInfoParam, arg1: string, ...args: string[]): Promise<string>;
55
195
  /**
56
- * USB devices currently attached to the guest.
196
+ * Lists the USB devices currently attached to the guest, from `info usb`.
57
197
  *
58
- * @throws if the reply has lines the device pattern did not match, which
59
- * means QEMU changed the format and the result would be silently short.
198
+ * @returns One entry per device, in the order of the reply. Empty for an
199
+ * empty reply.
200
+ * @throws A {@link ProxmoxError} with code `response` if the number of
201
+ * devices recognised differs from the number of lines in the reply, which
202
+ * means the output format changed and the result would be silently short.
203
+ * @throws A {@link ProxmoxError} if the request fails.
60
204
  */
61
205
  infoUsb(): Promise<USBInfo[]>;
62
206
  /**
63
- * USB devices present on the host, optionally narrowed by
64
- * vendor id, product id or name.
207
+ * Lists the USB devices present on the host, from `info usbhost`,
208
+ * optionally narrowed by vendor id, product id or name.
209
+ *
210
+ * @remarks
211
+ * Unlike {@link QmMonitor.infoUsb}, this does not verify that the whole
212
+ * reply was understood: an entry the pattern does not recognise is left
213
+ * out without an error.
214
+ *
215
+ * @param filter - Keeps only the devices that match every pattern given.
216
+ * All devices are returned when it is omitted.
217
+ * @returns The devices, in the order of the reply.
218
+ * @throws A {@link ProxmoxError} if the request fails.
65
219
  */
66
220
  infoUsbhost(filter?: USBHostFilter): Promise<USBHostInfo[]>;
67
221
  /**
68
- * Attach a host USB device by vendor and product id.
222
+ * Attaches a host USB device to the guest by vendor and product id.
69
223
  *
70
- * @param id Identifier for the new device, used to detach it later.
224
+ * @remarks
225
+ * Sends `device_add usb-host,vendorid=0x...,productid=0x...,id=...`. The
226
+ * values are inserted into the command as given, without validation or
227
+ * escaping.
228
+ *
229
+ * @param id - Identifier for the new device, used to detach it later.
230
+ * @param params - The device to attach.
231
+ * @param params.vendorId - Vendor id in hexadecimal, with or without a
232
+ * `0x` prefix.
233
+ * @param params.productId - Product id in hexadecimal, with or without a
234
+ * `0x` prefix.
235
+ * @returns The monitor's unparsed reply.
236
+ * @throws A {@link ProxmoxError} if the request fails.
71
237
  */
72
238
  deviceAddById(id: string, params: {
73
239
  vendorId: string;
74
240
  productId: string;
75
241
  }): Promise<string>;
76
242
  /**
77
- * Attach a host USB device by physical port, which survives swapping a
78
- * device for another of the same model.
243
+ * Attaches a host USB device to the guest by physical port, which survives
244
+ * swapping a device for another of the same model.
245
+ *
246
+ * @remarks
247
+ * Sends `device_add usb-host,hostbus=...,hostport=...,id=...`. The values
248
+ * are inserted into the command as given, without validation or escaping.
249
+ *
250
+ * @param id - Identifier for the new device, used to detach it later.
251
+ * @param params - The port to attach; a {@link USBHostInfo} fits.
252
+ * @param params.bus - Number of the host bus.
253
+ * @param params.port - Port on that bus.
254
+ * @returns The monitor's unparsed reply.
255
+ * @throws A {@link ProxmoxError} if the request fails.
79
256
  */
80
257
  deviceAddByPort(id: string, params: {
81
258
  bus: number;
82
259
  port: string;
83
260
  }): Promise<string>;
84
- /** Detach a device previously added under `id`. */
261
+ /**
262
+ * Detaches a device previously added under `id`, by sending
263
+ * `device_del <id>`.
264
+ *
265
+ * @param id - Identifier the device was added under. It is inserted into
266
+ * the command as given.
267
+ * @returns The monitor's unparsed reply.
268
+ * @throws A {@link ProxmoxError} if the request fails.
269
+ */
85
270
  deviceDel(id: string): Promise<string>;
86
271
  /**
87
- * Attach every host device matching `filter` that is not already present.
272
+ * Attaches every host USB device matching `filter`, by physical port,
273
+ * provided nothing is attached to the guest under `id` yet.
88
274
  *
275
+ * @remarks
89
276
  * The first is added as `id`, subsequent ones as `id-1`, `id-2` and so on.
277
+ * The check against the guest covers `id` alone: whether a matching host
278
+ * device is already attached under another identifier is not looked at.
279
+ *
280
+ * The devices are attached one at a time, after one `info usb` and one
281
+ * `info usbhost` request. When a request fails, the devices attached
282
+ * before it stay attached.
90
283
  *
91
- * @returns the ids that were attached.
92
- * @throws if `id` is already attached to the guest.
284
+ * @param id - Identifier for the first device and stem for the others.
285
+ * @param filter - Selects the host devices. An empty filter selects every
286
+ * USB device on the host.
287
+ * @returns The ids that were attached, in order. Empty when no host device
288
+ * matches.
289
+ * @throws A {@link ProxmoxError} with code `config` if a device is already
290
+ * attached to the guest under `id`, with code `response` if the reply to
291
+ * `info usb` cannot be parsed in full, and with the request's own code if
292
+ * a request fails.
93
293
  */
94
294
  deviceAddMissing(id: string, filter: USBHostFilter): Promise<string[]>;
95
295
  }
96
- //# sourceMappingURL=qm-monitor.d.ts.map
296
+ export {};