@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.
- package/CHANGELOG.md +21 -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 +28413 -28116
- 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 -32055
- package/src/proxmox-engine.ts +0 -452
- package/src/proxy.ts +0 -195
- 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
|
-
*
|
|
40
|
+
* `proxmoxApi()`.
|
|
14
41
|
*/
|
|
15
42
|
export interface ApiRequestable {
|
|
16
43
|
/**
|
|
17
|
-
*
|
|
44
|
+
* Performs one API call on behalf of the proxy.
|
|
18
45
|
*
|
|
19
|
-
* @param httpMethod
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
35
|
-
*
|
|
36
|
-
* @
|
|
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
|
-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
106
|
-
|
|
107
|
-
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
129
|
-
*
|
|
130
|
-
* @
|
|
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
|
package/dist/qm-monitor.d.ts
CHANGED
|
@@ -1,96 +1,296 @@
|
|
|
1
1
|
import type { Proxmox } from "./model.js";
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
* @
|
|
59
|
-
*
|
|
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,
|
|
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
|
-
*
|
|
222
|
+
* Attaches a host USB device to the guest by vendor and product id.
|
|
69
223
|
*
|
|
70
|
-
* @
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
92
|
-
* @
|
|
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
|
-
|
|
296
|
+
export {};
|