@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.
Files changed (44) hide show
  1. package/CHANGELOG.md +10 -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 +28408 -28157
  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/src/qm-monitor.ts DELETED
@@ -1,303 +0,0 @@
1
- // Proxmox-API Interactive proxmox API for developpers how do not like reading docs
2
- // Copyright (C) 2020-2022 Chemouni Uriel <uchemouni@gmail.com>
3
- //
4
- // This program is free software: you can redistribute it and/or modify
5
- // it under the terms of the GNU General Public License as published by
6
- // the Free Software Foundation, either version 3 of the License, or
7
- // (at your option) any later version.
8
- //
9
- // This program is distributed in the hope that it will be useful,
10
- // but WITHOUT ANY WARRANTY; without even the implied warranty of
11
- // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
- // GNU General Public License for more details.
13
- //
14
- // You should have received a copy of the GNU General Public License
15
- // along with this program. If not, see <http://www.gnu.org/licenses/>.
16
-
17
- import type { Proxmox } from "./model.js";
18
-
19
- // 'mem', // ERROR: VM XXX qmp command 'human-monitor-command' failed - got timeout
20
- // 'tlb', // ERROR: VM XXX qmp command 'human-monitor-command' failed - got timeout
21
-
22
- export const VALID_QEMU_INFO_SIMPLE = [
23
- "backup",
24
- "balloon",
25
- "block-jobs",
26
- "blockstats",
27
- "capture",
28
- "chardev",
29
- "cpus",
30
- "cpustats",
31
- "dump",
32
- "history",
33
- "hotpluggable-cpus",
34
- "ioapic",
35
- "iothreads",
36
- "irq",
37
- "jit",
38
- "kvm",
39
- "memdev",
40
- "memory-devices",
41
- "memory_size_summary",
42
- "mice",
43
- "migrate",
44
- "migrate_cache_size",
45
- "migrate_capabilities",
46
- "migrate_parameters",
47
- "name",
48
- "network",
49
- "numa",
50
- "opcount",
51
- "pci",
52
- "pic",
53
- "profile",
54
- "qdm",
55
- "qtree",
56
- "ramblock",
57
- "rdma",
58
- "roms",
59
- "savevm",
60
- "sev",
61
- "snapshots",
62
- "spice",
63
- "status",
64
- "tpm",
65
- "usb",
66
- "usbhost",
67
- "usernet",
68
- "uuid",
69
- "version",
70
- "vm-generation-id",
71
- "vnc",
72
- ] as const;
73
-
74
- export const VALID_QEMU_INFO_OPTION = [
75
- "block",
76
- "lapic",
77
- "mtree",
78
- "qom-tree",
79
- "registers",
80
- "sync-profile",
81
- "trace-events",
82
- ] as const;
83
-
84
- export const VALID_QEMU_INFO_PARAM = [
85
- "rocker-of-dpa-flows",
86
- "rocker-of-dpa-groups",
87
- "rocker-ports",
88
- ] as const;
89
-
90
- export type QemuInfoSimple = (typeof VALID_QEMU_INFO_SIMPLE)[number];
91
- export type QemuInfoOption = (typeof VALID_QEMU_INFO_OPTION)[number];
92
- export type QemuInfoParam = (typeof VALID_QEMU_INFO_PARAM)[number];
93
-
94
- /** One USB device attached to the guest, from `info usb`. */
95
- export interface USBInfo {
96
- device: string;
97
- port: string;
98
- speed: string;
99
- /**
100
- * Absent for a device QEMU reports without a product string - the trailing
101
- * `, Product ..., ID: ...` is optional in the monitor's own output.
102
- */
103
- product?: string;
104
- /** Absent for the same reason as {@link USBInfo.product}. */
105
- id?: string;
106
- }
107
-
108
- /** One USB device present on the host, from `info usbhost`. */
109
- export interface USBHostInfo {
110
- bus: number;
111
- addr: number;
112
- port: string;
113
- speed: string;
114
- class: string;
115
- vendorId: string;
116
- productId: string;
117
- name: string;
118
- }
119
-
120
- /** Narrows which host devices {@link QmMonitor.infoUsbhost} returns. */
121
- export interface USBHostFilter {
122
- vendorId?: RegExp;
123
- productId?: RegExp;
124
- name?: RegExp;
125
- }
126
-
127
- // Device 1.1, Port 1, Speed 1.5 Mb/s, Product USB OPTICAL MOUSE , ID: mouse
128
- // Device 1.0, Port 2, Speed 12 Mb/s, Product Gaming KB , ID: keyboard
129
- const GUEST_USB =
130
- /Device ([\d.]+), Port ([\d.]+), Speed ([\d KMGTbfs/.]+)(?:, Product (.+), ID: (.+))?/g;
131
-
132
- // Bus 1, Addr 4, Port 2, Speed 480 Mb/s
133
- // Class 00: USB device 1234:5678, Some Device
134
- const HOST_USB =
135
- /Bus (\d+), Addr (\d+), Port ([\d.]+), Speed ([\d KMGTbfs/.]+)[\r\n]\s+Class (\d+): USB device ([0-9a-f]{4}):([0-9a-f]{4}), (.*)/gm;
136
-
137
- /** Strip an optional `0x` prefix from a USB vendor or product id. */
138
- function bareHexId(value: string): string {
139
- return value.replace(/^0x/i, "");
140
- }
141
-
142
- /**
143
- * QEMU monitor access for one guest, over
144
- * `POST /nodes/{node}/qemu/{vmid}/monitor`.
145
- *
146
- * The monitor is a debugging interface: commands are passed through
147
- * unvalidated and replies are unstructured text whose format is not stable
148
- * across QEMU versions. Prefer a real endpoint wherever one exists.
149
- */
150
- export class QmMonitor {
151
- readonly node: string;
152
- readonly vmid: number;
153
- /** Send a raw monitor command and return its unparsed reply. */
154
- readonly monitor: (command: string) => Promise<string>;
155
-
156
- constructor(proxmox: Proxmox.Api, node: string, vmid: number) {
157
- this.node = node;
158
- this.vmid = vmid;
159
- const post = proxmox.nodes.$(node).qemu.$(vmid).monitor.$post;
160
- this.monitor = (command) => post({ command });
161
- }
162
-
163
- info(type: QemuInfoSimple): Promise<string>;
164
- info(type: QemuInfoOption, ...args: string[]): Promise<string>;
165
- info(type: QemuInfoParam, arg1: string, ...args: string[]): Promise<string>;
166
- /** Run `info <type>` and return the raw reply. */
167
- async info(
168
- type: QemuInfoSimple | QemuInfoOption | QemuInfoParam,
169
- ...args: string[]
170
- ): Promise<string> {
171
- const suffix = args.length > 0 ? ` ${args.join(" ")}` : "";
172
- return this.monitor(`info ${type}${suffix}`);
173
- }
174
-
175
- /**
176
- * USB devices currently attached to the guest.
177
- *
178
- * @throws if the reply has lines the device pattern did not match, which
179
- * means QEMU changed the format and the result would be silently short.
180
- */
181
- async infoUsb(): Promise<USBInfo[]> {
182
- const text = await this.info("usb");
183
- const expected = (text.match(/[\r\n]+/g) ?? []).length;
184
- const devices: USBInfo[] = [];
185
-
186
- for (const match of text.matchAll(GUEST_USB)) {
187
- const [, device = "", port = "", speed = "", product, id] = match;
188
- devices.push({ device, port, speed, product, id });
189
- }
190
-
191
- if (devices.length !== expected) {
192
- throw new Error(
193
- `Parsed ${devices.length} USB devices but the reply has ${expected} lines. ` +
194
- `The monitor output format may have changed:\n${text}`,
195
- );
196
- }
197
- return devices;
198
- }
199
-
200
- /**
201
- * USB devices present on the host, optionally narrowed by
202
- * vendor id, product id or name.
203
- */
204
- async infoUsbhost(filter?: USBHostFilter): Promise<USBHostInfo[]> {
205
- const text = await this.info("usbhost");
206
- const devices: USBHostInfo[] = [];
207
-
208
- for (const match of text.matchAll(HOST_USB)) {
209
- const [
210
- ,
211
- bus = "",
212
- addr = "",
213
- port = "",
214
- speed = "",
215
- deviceClass = "",
216
- vendorId = "",
217
- productId = "",
218
- name = "",
219
- ] = match;
220
- devices.push({
221
- bus: Number(bus),
222
- addr: Number(addr),
223
- port,
224
- speed,
225
- class: deviceClass,
226
- vendorId,
227
- productId,
228
- name,
229
- });
230
- }
231
-
232
- if (!filter) return devices;
233
- return devices.filter(
234
- (usb) =>
235
- (!filter.name || filter.name.test(usb.name)) &&
236
- // Each of these tested `usb.name` before, so filtering by vendor or
237
- // product id matched on the wrong field entirely.
238
- (!filter.vendorId || filter.vendorId.test(usb.vendorId)) &&
239
- (!filter.productId || filter.productId.test(usb.productId)),
240
- );
241
- }
242
-
243
- /**
244
- * Attach a host USB device by vendor and product id.
245
- *
246
- * @param id Identifier for the new device, used to detach it later.
247
- */
248
- async deviceAddById(
249
- id: string,
250
- params: { vendorId: string; productId: string },
251
- ): Promise<string> {
252
- const vendorId = bareHexId(params.vendorId);
253
- const productId = bareHexId(params.productId);
254
- return this.monitor(
255
- `device_add usb-host,vendorid=0x${vendorId},productid=0x${productId},id=${id}`,
256
- );
257
- }
258
-
259
- /**
260
- * Attach a host USB device by physical port, which survives swapping a
261
- * device for another of the same model.
262
- */
263
- async deviceAddByPort(
264
- id: string,
265
- params: { bus: number; port: string },
266
- ): Promise<string> {
267
- return this.monitor(
268
- `device_add usb-host,hostbus=${params.bus},hostport=${params.port},id=${id}`,
269
- );
270
- }
271
-
272
- /** Detach a device previously added under `id`. */
273
- async deviceDel(id: string): Promise<string> {
274
- return this.monitor(`device_del ${id}`);
275
- }
276
-
277
- /**
278
- * Attach every host device matching `filter` that is not already present.
279
- *
280
- * The first is added as `id`, subsequent ones as `id-1`, `id-2` and so on.
281
- *
282
- * @returns the ids that were attached.
283
- * @throws if `id` is already attached to the guest.
284
- */
285
- async deviceAddMissing(id: string, filter: USBHostFilter): Promise<string[]> {
286
- const attached = await this.infoUsb();
287
- if (attached.some((device) => device.id === id)) {
288
- throw new Error(`USB device ${id} already present`);
289
- }
290
-
291
- const candidates = await this.infoUsbhost(filter);
292
- const added: string[] = [];
293
- // Sequential, not concurrent: these were previously fired without being
294
- // awaited at all, so failures vanished and the guest saw an unbounded
295
- // burst of monitor commands.
296
- for (const [index, device] of candidates.entries()) {
297
- const deviceId = index ? `${id}-${index}` : id;
298
- await this.deviceAddByPort(deviceId, device);
299
- added.push(deviceId);
300
- }
301
- return added;
302
- }
303
- }