@virtbase/proxmox-api 2.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 +500 -0
- package/README.md +110 -0
- package/dist/client.d.ts +25 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +47 -0
- package/dist/client.js.map +1 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +21 -0
- package/dist/index.js.map +1 -0
- package/dist/model.d.ts +30331 -0
- package/dist/model.d.ts.map +1 -0
- package/dist/model.js +17 -0
- package/dist/model.js.map +1 -0
- package/dist/proxmox-engine.d.ts +112 -0
- package/dist/proxmox-engine.d.ts.map +1 -0
- package/dist/proxmox-engine.js +308 -0
- package/dist/proxmox-engine.js.map +1 -0
- package/dist/proxy.d.ts +39 -0
- package/dist/proxy.d.ts.map +1 -0
- package/dist/proxy.js +135 -0
- package/dist/proxy.js.map +1 -0
- package/dist/qm-monitor.d.ts +96 -0
- package/dist/qm-monitor.d.ts.map +1 -0
- package/dist/qm-monitor.js +212 -0
- package/dist/qm-monitor.js.map +1 -0
- package/package.json +65 -0
- package/src/__tests__/helpers.ts +39 -0
- package/src/__tests__/proxmox-engine.test.ts +393 -0
- package/src/__tests__/proxy.test.ts +190 -0
- package/src/__tests__/qm-monitor.test.ts +215 -0
- package/src/client.ts +58 -0
- package/src/index.ts +34 -0
- package/src/model.ts +32055 -0
- package/src/proxmox-engine.ts +452 -0
- package/src/proxy.ts +195 -0
- package/src/qm-monitor.ts +303 -0
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
|
|
2
|
+
import http from "node:http";
|
|
3
|
+
import type { AddressInfo } from "node:net";
|
|
4
|
+
import { ProxmoxEngine } from "../proxmox-engine.js";
|
|
5
|
+
|
|
6
|
+
interface Received {
|
|
7
|
+
method: string;
|
|
8
|
+
url: string;
|
|
9
|
+
body: string;
|
|
10
|
+
headers: http.IncomingHttpHeaders;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
const TOKEN = {
|
|
14
|
+
tokenID: "root@pam!test",
|
|
15
|
+
tokenSecret: "12345678-1234-1234-1234-1234567890ab",
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
let server: http.Server;
|
|
19
|
+
let port: number;
|
|
20
|
+
let received: Received[] = [];
|
|
21
|
+
/** Per-path reply queue, so a test can script a sequence of responses. */
|
|
22
|
+
let replies = new Map<string, Array<[number, string, string]>>();
|
|
23
|
+
/** Paths the server should never answer, to exercise transport failure. */
|
|
24
|
+
let hang = new Set<string>();
|
|
25
|
+
|
|
26
|
+
function reply(
|
|
27
|
+
path: string,
|
|
28
|
+
status: number,
|
|
29
|
+
body: string,
|
|
30
|
+
type = "application/json;charset=UTF-8",
|
|
31
|
+
) {
|
|
32
|
+
const queue = replies.get(path) ?? [];
|
|
33
|
+
queue.push([status, body, type]);
|
|
34
|
+
replies.set(path, queue);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
beforeAll(async () => {
|
|
38
|
+
server = http.createServer((req, res) => {
|
|
39
|
+
const chunks: Buffer[] = [];
|
|
40
|
+
req.on("data", (c: Buffer) => chunks.push(c));
|
|
41
|
+
req.on("end", () => {
|
|
42
|
+
const path = (req.url ?? "").split("?")[0] ?? "";
|
|
43
|
+
received.push({
|
|
44
|
+
method: req.method ?? "",
|
|
45
|
+
url: req.url ?? "",
|
|
46
|
+
body: Buffer.concat(chunks).toString("utf8"),
|
|
47
|
+
headers: req.headers,
|
|
48
|
+
});
|
|
49
|
+
if (hang.has(path)) {
|
|
50
|
+
res.destroy();
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
if (path === "/api2/json/access/ticket") {
|
|
54
|
+
res.writeHead(200, {
|
|
55
|
+
"content-type": "application/json;charset=UTF-8",
|
|
56
|
+
});
|
|
57
|
+
res.end(
|
|
58
|
+
JSON.stringify({
|
|
59
|
+
data: {
|
|
60
|
+
ticket: "TICKET",
|
|
61
|
+
CSRFPreventionToken: "CSRF",
|
|
62
|
+
username: "root@pam",
|
|
63
|
+
cap: {},
|
|
64
|
+
},
|
|
65
|
+
}),
|
|
66
|
+
);
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
const queued = replies.get(path)?.shift();
|
|
70
|
+
const [status, body, type] = queued ?? [
|
|
71
|
+
200,
|
|
72
|
+
JSON.stringify({ data: { ok: true } }),
|
|
73
|
+
"application/json;charset=UTF-8",
|
|
74
|
+
];
|
|
75
|
+
res.writeHead(status, { "content-type": type });
|
|
76
|
+
res.end(body);
|
|
77
|
+
});
|
|
78
|
+
});
|
|
79
|
+
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
|
|
80
|
+
port = (server.address() as AddressInfo).port;
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
afterAll(() => server.close());
|
|
84
|
+
|
|
85
|
+
function engine(overrides: Record<string, unknown> = {}) {
|
|
86
|
+
received = [];
|
|
87
|
+
replies = new Map();
|
|
88
|
+
hang = new Set();
|
|
89
|
+
return new ProxmoxEngine({
|
|
90
|
+
host: "127.0.0.1",
|
|
91
|
+
port,
|
|
92
|
+
schema: "http",
|
|
93
|
+
...TOKEN,
|
|
94
|
+
...overrides,
|
|
95
|
+
// The options type is a union and the spread can produce either arm.
|
|
96
|
+
// biome-ignore lint/suspicious/noExplicitAny: union spread, see above.
|
|
97
|
+
} as any);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
describe("parameter encoding", () => {
|
|
101
|
+
test("GET parameters go in the query string", async () => {
|
|
102
|
+
const e = engine();
|
|
103
|
+
await e.doRequest("GET", "/api2/json/nodes", "/api2/json/nodes", {
|
|
104
|
+
full: true,
|
|
105
|
+
});
|
|
106
|
+
expect(received[0]?.url).toBe("/api2/json/nodes?full=1");
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
test("booleans encode as 1 and 0", async () => {
|
|
110
|
+
const e = engine();
|
|
111
|
+
await e.doRequest("GET", "/api2/json/x", "/api2/json/x", {
|
|
112
|
+
yes: true,
|
|
113
|
+
no: false,
|
|
114
|
+
});
|
|
115
|
+
expect(received[0]?.url).toBe("/api2/json/x?yes=1&no=0");
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
test("arrays repeat the key", async () => {
|
|
119
|
+
const e = engine();
|
|
120
|
+
await e.doRequest("POST", "/api2/json/x", "/api2/json/x", {
|
|
121
|
+
command: ["touch", "/tmp/a"],
|
|
122
|
+
});
|
|
123
|
+
expect(received[0]?.body).toBe("command=touch&command=%2Ftmp%2Fa");
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
test("null and undefined are dropped rather than sent empty", async () => {
|
|
127
|
+
const e = engine();
|
|
128
|
+
await e.doRequest("GET", "/api2/json/x", "/api2/json/x", {
|
|
129
|
+
a: 1,
|
|
130
|
+
b: null,
|
|
131
|
+
c: undefined,
|
|
132
|
+
});
|
|
133
|
+
expect(received[0]?.url).toBe("/api2/json/x?a=1");
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
test("POST parameters go in a form-encoded body", async () => {
|
|
137
|
+
const e = engine();
|
|
138
|
+
await e.doRequest("POST", "/api2/json/x", "/api2/json/x", { name: "a b" });
|
|
139
|
+
expect(received[0]?.body).toBe("name=a+b");
|
|
140
|
+
expect(received[0]?.headers["content-type"]).toBe(
|
|
141
|
+
"application/x-www-form-urlencoded",
|
|
142
|
+
);
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
test("Content-Length matches the encoded body", async () => {
|
|
146
|
+
const e = engine();
|
|
147
|
+
await e.doRequest("POST", "/api2/json/x", "/api2/json/x", {
|
|
148
|
+
name: "naïve ✓",
|
|
149
|
+
});
|
|
150
|
+
const body = received[0]?.body ?? "";
|
|
151
|
+
expect(received[0]?.headers["content-length"]).toBe(
|
|
152
|
+
String(Buffer.byteLength(body)),
|
|
153
|
+
);
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
test("the caller's params object is not mutated", async () => {
|
|
157
|
+
const e = engine();
|
|
158
|
+
const params = { a: 1, b: null };
|
|
159
|
+
await e.doRequest("GET", "/api2/json/x", "/api2/json/x", params);
|
|
160
|
+
expect(params).toEqual({ a: 1, b: null });
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
test("a request with no parameters sends no body", async () => {
|
|
164
|
+
const e = engine();
|
|
165
|
+
await e.doRequest("GET", "/api2/json/x", "/api2/json/x");
|
|
166
|
+
expect(received[0]?.body).toBe("");
|
|
167
|
+
});
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
describe("authentication", () => {
|
|
171
|
+
test("a token authenticates without a login round trip", async () => {
|
|
172
|
+
const e = engine();
|
|
173
|
+
await e.doRequest("GET", "/api2/json/x", "/api2/json/x");
|
|
174
|
+
expect(received).toHaveLength(1);
|
|
175
|
+
expect(received[0]?.headers.authorization).toBe(
|
|
176
|
+
`PVEAPIToken=${TOKEN.tokenID}=${TOKEN.tokenSecret}`,
|
|
177
|
+
);
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
test("a password logs in first, then reuses the ticket", async () => {
|
|
181
|
+
const e = engine({
|
|
182
|
+
tokenID: undefined,
|
|
183
|
+
tokenSecret: undefined,
|
|
184
|
+
username: "root@pam",
|
|
185
|
+
password: "s3cret",
|
|
186
|
+
});
|
|
187
|
+
await e.doRequest("GET", "/api2/json/a", "/api2/json/a");
|
|
188
|
+
await e.doRequest("GET", "/api2/json/b", "/api2/json/b");
|
|
189
|
+
expect(received.map((r) => r.url)).toEqual([
|
|
190
|
+
"/api2/json/access/ticket",
|
|
191
|
+
"/api2/json/a",
|
|
192
|
+
"/api2/json/b",
|
|
193
|
+
]);
|
|
194
|
+
expect(received[1]?.headers.cookie).toBe("PVEAuthCookie=TICKET");
|
|
195
|
+
expect(received[1]?.headers.csrfpreventiontoken).toBe("CSRF");
|
|
196
|
+
});
|
|
197
|
+
|
|
198
|
+
test("a malformed tokenID is rejected at construction", () => {
|
|
199
|
+
expect(() => engine({ tokenID: "nope" })).toThrow(/invalid tokenID/);
|
|
200
|
+
});
|
|
201
|
+
|
|
202
|
+
test("a malformed tokenSecret is rejected at construction", () => {
|
|
203
|
+
expect(() => engine({ tokenSecret: "not-a-uuid" })).toThrow(
|
|
204
|
+
/invalid tokenSecret/,
|
|
205
|
+
);
|
|
206
|
+
});
|
|
207
|
+
|
|
208
|
+
test("a missing password is rejected at construction", () => {
|
|
209
|
+
expect(() =>
|
|
210
|
+
engine({ tokenID: undefined, tokenSecret: undefined, password: "" }),
|
|
211
|
+
).toThrow(/password is missing/);
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
test("getTicket returns the token without contacting the server", async () => {
|
|
215
|
+
const e = engine();
|
|
216
|
+
const { ticket, CSRFPreventionToken } = await e.getTicket();
|
|
217
|
+
expect(ticket).toBe(`PVEAPIToken=${TOKEN.tokenID}=${TOKEN.tokenSecret}`);
|
|
218
|
+
expect(CSRFPreventionToken).toBe("");
|
|
219
|
+
expect(received).toHaveLength(0);
|
|
220
|
+
});
|
|
221
|
+
});
|
|
222
|
+
|
|
223
|
+
describe("responses", () => {
|
|
224
|
+
test("the data envelope is unwrapped", async () => {
|
|
225
|
+
const e = engine();
|
|
226
|
+
reply("/api2/json/x", 200, JSON.stringify({ data: [{ node: "pve1" }] }));
|
|
227
|
+
expect(await e.doRequest("GET", "/api2/json/x", "/api2/json/x")).toEqual([
|
|
228
|
+
{ node: "pve1" },
|
|
229
|
+
]);
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
test("a respaced content-type is still parsed as JSON", async () => {
|
|
233
|
+
const e = engine();
|
|
234
|
+
reply(
|
|
235
|
+
"/api2/json/x",
|
|
236
|
+
200,
|
|
237
|
+
JSON.stringify({ data: 42 }),
|
|
238
|
+
"application/json; charset=utf-8",
|
|
239
|
+
);
|
|
240
|
+
expect(await e.doRequest("GET", "/api2/json/x", "/api2/json/x")).toBe(42);
|
|
241
|
+
});
|
|
242
|
+
|
|
243
|
+
test("octet-stream is handed back as a stream", async () => {
|
|
244
|
+
const e = engine();
|
|
245
|
+
reply("/api2/json/x", 200, "binary", "application/octet-stream");
|
|
246
|
+
const body = await e.doRequest("GET", "/api2/json/x", "/api2/json/x");
|
|
247
|
+
expect(body).toBeInstanceOf(ReadableStream);
|
|
248
|
+
});
|
|
249
|
+
});
|
|
250
|
+
|
|
251
|
+
describe("errors", () => {
|
|
252
|
+
test("400 throws with the decoded body", async () => {
|
|
253
|
+
const e = engine();
|
|
254
|
+
reply(
|
|
255
|
+
"/api2/json/x",
|
|
256
|
+
400,
|
|
257
|
+
JSON.stringify({ data: null, errors: { memory: "not an integer" } }),
|
|
258
|
+
);
|
|
259
|
+
expect(e.doRequest("PUT", "/api2/json/x", "/api2/json/x")).rejects.toThrow(
|
|
260
|
+
/not an integer/,
|
|
261
|
+
);
|
|
262
|
+
});
|
|
263
|
+
|
|
264
|
+
test("500 throws", async () => {
|
|
265
|
+
const e = engine();
|
|
266
|
+
reply("/api2/json/x", 500, JSON.stringify({ data: null }));
|
|
267
|
+
expect(e.doRequest("GET", "/api2/json/x", "/api2/json/x")).rejects.toThrow(
|
|
268
|
+
/return Error 500/,
|
|
269
|
+
);
|
|
270
|
+
});
|
|
271
|
+
|
|
272
|
+
test("an unexpected status throws", async () => {
|
|
273
|
+
const e = engine();
|
|
274
|
+
reply("/api2/json/x", 418, JSON.stringify({ data: null }));
|
|
275
|
+
expect(e.doRequest("GET", "/api2/json/x", "/api2/json/x")).rejects.toThrow(
|
|
276
|
+
/connection failed with 418/,
|
|
277
|
+
);
|
|
278
|
+
});
|
|
279
|
+
|
|
280
|
+
test("a transport failure is retried once, then throws with a cause", async () => {
|
|
281
|
+
// Injected rather than driven through the server: a dropped socket is
|
|
282
|
+
// retryable at the HTTP layer too, so counting requests server-side
|
|
283
|
+
// measures undici's retries as well as the engine's.
|
|
284
|
+
let attempts = 0;
|
|
285
|
+
const e = new ProxmoxEngine({
|
|
286
|
+
host: "127.0.0.1",
|
|
287
|
+
port,
|
|
288
|
+
schema: "http",
|
|
289
|
+
...TOKEN,
|
|
290
|
+
fetch: () => {
|
|
291
|
+
attempts++;
|
|
292
|
+
return Promise.reject(new Error("ECONNRESET"));
|
|
293
|
+
},
|
|
294
|
+
});
|
|
295
|
+
|
|
296
|
+
let error: unknown;
|
|
297
|
+
try {
|
|
298
|
+
await e.doRequest("GET", "/api2/json/x", "/api2/json/x");
|
|
299
|
+
} catch (caught) {
|
|
300
|
+
error = caught;
|
|
301
|
+
}
|
|
302
|
+
expect(error).toBeInstanceOf(Error);
|
|
303
|
+
expect((error as Error).message).toMatch(/FaILED to call GET/);
|
|
304
|
+
expect((error as Error).cause).toBeInstanceOf(Error);
|
|
305
|
+
expect(attempts).toBe(2);
|
|
306
|
+
});
|
|
307
|
+
|
|
308
|
+
test("a rejected ticket is discarded and the request replayed once", async () => {
|
|
309
|
+
let logins = 0;
|
|
310
|
+
let calls = 0;
|
|
311
|
+
const e = new ProxmoxEngine({
|
|
312
|
+
host: "127.0.0.1",
|
|
313
|
+
port,
|
|
314
|
+
schema: "http",
|
|
315
|
+
username: "root@pam",
|
|
316
|
+
password: "s3cret",
|
|
317
|
+
fetch: (url) => {
|
|
318
|
+
if (String(url).endsWith("/access/ticket")) {
|
|
319
|
+
logins++;
|
|
320
|
+
return Promise.resolve(
|
|
321
|
+
new Response(
|
|
322
|
+
JSON.stringify({
|
|
323
|
+
data: { ticket: `T${logins}`, CSRFPreventionToken: "C" },
|
|
324
|
+
}),
|
|
325
|
+
{ headers: { "content-type": "application/json;charset=UTF-8" } },
|
|
326
|
+
),
|
|
327
|
+
);
|
|
328
|
+
}
|
|
329
|
+
calls++;
|
|
330
|
+
// Reject the first attempt the way PVE rejects a stale ticket.
|
|
331
|
+
return Promise.resolve(
|
|
332
|
+
calls === 1
|
|
333
|
+
? new Response(JSON.stringify({ data: null }), {
|
|
334
|
+
status: 401,
|
|
335
|
+
statusText: "invalid PVE ticket",
|
|
336
|
+
headers: { "content-type": "application/json;charset=UTF-8" },
|
|
337
|
+
})
|
|
338
|
+
: new Response(JSON.stringify({ data: "ok" }), {
|
|
339
|
+
headers: { "content-type": "application/json;charset=UTF-8" },
|
|
340
|
+
}),
|
|
341
|
+
);
|
|
342
|
+
},
|
|
343
|
+
});
|
|
344
|
+
|
|
345
|
+
expect(await e.doRequest("GET", "/api2/json/x", "/api2/json/x")).toBe("ok");
|
|
346
|
+
expect(calls).toBe(2);
|
|
347
|
+
expect(logins).toBe(2);
|
|
348
|
+
});
|
|
349
|
+
|
|
350
|
+
test("a rejected token is not replayed, because it would fail again", async () => {
|
|
351
|
+
let calls = 0;
|
|
352
|
+
const e = new ProxmoxEngine({
|
|
353
|
+
host: "127.0.0.1",
|
|
354
|
+
port,
|
|
355
|
+
schema: "http",
|
|
356
|
+
...TOKEN,
|
|
357
|
+
fetch: () => {
|
|
358
|
+
calls++;
|
|
359
|
+
return Promise.resolve(
|
|
360
|
+
new Response(JSON.stringify({ data: null }), {
|
|
361
|
+
status: 401,
|
|
362
|
+
statusText: "invalid PVE ticket",
|
|
363
|
+
headers: { "content-type": "application/json;charset=UTF-8" },
|
|
364
|
+
}),
|
|
365
|
+
);
|
|
366
|
+
},
|
|
367
|
+
});
|
|
368
|
+
expect(e.doRequest("GET", "/api2/json/x", "/api2/json/x")).rejects.toThrow(
|
|
369
|
+
/401/,
|
|
370
|
+
);
|
|
371
|
+
await Bun.sleep(20);
|
|
372
|
+
expect(calls).toBe(1);
|
|
373
|
+
});
|
|
374
|
+
|
|
375
|
+
test("queryTimeout aborts a slow request", async () => {
|
|
376
|
+
const slow = http.createServer(() => {
|
|
377
|
+
/* never responds */
|
|
378
|
+
});
|
|
379
|
+
await new Promise<void>((resolve) => slow.listen(0, "127.0.0.1", resolve));
|
|
380
|
+
const e = new ProxmoxEngine({
|
|
381
|
+
host: "127.0.0.1",
|
|
382
|
+
port: (slow.address() as AddressInfo).port,
|
|
383
|
+
schema: "http",
|
|
384
|
+
...TOKEN,
|
|
385
|
+
queryTimeout: 150,
|
|
386
|
+
});
|
|
387
|
+
expect(e.doRequest("GET", "/api2/json/x", "/api2/json/x")).rejects.toThrow(
|
|
388
|
+
/FaILED to call/,
|
|
389
|
+
);
|
|
390
|
+
await Bun.sleep(600);
|
|
391
|
+
slow.close();
|
|
392
|
+
});
|
|
393
|
+
});
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Copyright (c) 2026 Janic Bellmann
|
|
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 <https://www.gnu.org/licenses/>.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import { describe, expect, test } from "bun:test";
|
|
19
|
+
import type { ApiParamType, ApiRequestable } from "../proxy.js";
|
|
20
|
+
import { buildApiProxy } from "../proxy.js";
|
|
21
|
+
|
|
22
|
+
interface Call {
|
|
23
|
+
method: string;
|
|
24
|
+
path: string;
|
|
25
|
+
template: string;
|
|
26
|
+
params?: ApiParamType;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function recorder() {
|
|
30
|
+
const calls: Call[] = [];
|
|
31
|
+
const engine: ApiRequestable = {
|
|
32
|
+
doRequest(method, path, template, params) {
|
|
33
|
+
calls.push({ method, path, template, params });
|
|
34
|
+
return Promise.resolve(null);
|
|
35
|
+
},
|
|
36
|
+
};
|
|
37
|
+
// These tests walk arbitrary paths rather than the generated surface, so
|
|
38
|
+
// the root is deliberately untyped.
|
|
39
|
+
// biome-ignore lint/suspicious/noExplicitAny: untyped root, see above.
|
|
40
|
+
return { calls, api: buildApiProxy<any>(engine, "/api2/json") };
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
describe("path building", () => {
|
|
44
|
+
test("property access becomes path segments", async () => {
|
|
45
|
+
const { calls, api } = recorder();
|
|
46
|
+
await api.cluster.resources.$get();
|
|
47
|
+
expect(calls[0]?.path).toBe("/api2/json/cluster/resources");
|
|
48
|
+
expect(calls[0]?.method).toBe("get");
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
test("$() substitutes a path variable", async () => {
|
|
52
|
+
const { calls, api } = recorder();
|
|
53
|
+
await api.nodes.$("pve1").qemu.$(100).config.$get();
|
|
54
|
+
expect(calls[0]?.path).toBe("/api2/json/nodes/pve1/qemu/100/config");
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
test("the template keeps substituted values out, for grouping", async () => {
|
|
58
|
+
const { calls, api } = recorder();
|
|
59
|
+
await api.nodes.$("pve1").qemu.$(100).config.$get();
|
|
60
|
+
expect(calls[0]?.template).toBe("/api2/json/nodes/*/qemu/*/config");
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
test("each verb maps to its method", async () => {
|
|
64
|
+
const { calls, api } = recorder();
|
|
65
|
+
await api.pools.$get();
|
|
66
|
+
await api.pools.$post();
|
|
67
|
+
await api.pools.$put();
|
|
68
|
+
await api.pools.$delete();
|
|
69
|
+
expect(calls.map((c) => c.method)).toEqual([
|
|
70
|
+
"get",
|
|
71
|
+
"post",
|
|
72
|
+
"put",
|
|
73
|
+
"delete",
|
|
74
|
+
]);
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
test("parameters are handed to the engine untouched", async () => {
|
|
78
|
+
const { calls, api } = recorder();
|
|
79
|
+
await api.nodes.$get({ full: true, tags: ["a", "b"] });
|
|
80
|
+
expect(calls[0]?.params).toEqual({ full: true, tags: ["a", "b"] });
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
test("walking the path sends nothing", () => {
|
|
84
|
+
const { calls, api } = recorder();
|
|
85
|
+
const partial = api.nodes.$("pve1").qemu.$(100);
|
|
86
|
+
expect(calls).toHaveLength(0);
|
|
87
|
+
expect(partial).toBeDefined();
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
test("a partially walked path can be reused", async () => {
|
|
91
|
+
const { calls, api } = recorder();
|
|
92
|
+
const vm = api.nodes.$("pve1").qemu.$(100);
|
|
93
|
+
await vm.config.$get();
|
|
94
|
+
await vm.status.current.$get();
|
|
95
|
+
expect(calls.map((c) => c.path)).toEqual([
|
|
96
|
+
"/api2/json/nodes/pve1/qemu/100/config",
|
|
97
|
+
"/api2/json/nodes/pve1/qemu/100/status/current",
|
|
98
|
+
]);
|
|
99
|
+
});
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
describe("segment escaping", () => {
|
|
103
|
+
test("a slash cannot invent a path level", async () => {
|
|
104
|
+
const { calls, api } = recorder();
|
|
105
|
+
await api.storage.$("local/iso").$get();
|
|
106
|
+
expect(calls[0]?.path).toBe("/api2/json/storage/local%2Fiso");
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
test("a question mark cannot start a query string", async () => {
|
|
110
|
+
const { calls, api } = recorder();
|
|
111
|
+
await api.storage.$("we?rd").$get();
|
|
112
|
+
expect(calls[0]?.path).toBe("/api2/json/storage/we%3Frd");
|
|
113
|
+
});
|
|
114
|
+
|
|
115
|
+
test("a hash cannot truncate the path", async () => {
|
|
116
|
+
const { calls, api } = recorder();
|
|
117
|
+
await api.storage.$("we#rd").$get();
|
|
118
|
+
expect(calls[0]?.path).toBe("/api2/json/storage/we%23rd");
|
|
119
|
+
});
|
|
120
|
+
|
|
121
|
+
test("colons survive, because UPIDs are full of them", async () => {
|
|
122
|
+
const { calls, api } = recorder();
|
|
123
|
+
await api.nodes.$("pve1").tasks.$("UPID:pve1:001:qmstart:").status.$get();
|
|
124
|
+
expect(calls[0]?.path).toBe(
|
|
125
|
+
"/api2/json/nodes/pve1/tasks/UPID:pve1:001:qmstart:/status",
|
|
126
|
+
);
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
test("numbers are accepted as ids", async () => {
|
|
130
|
+
const { calls, api } = recorder();
|
|
131
|
+
await api.nodes.$("pve1").qemu.$(100).$get();
|
|
132
|
+
expect(calls[0]?.path).toBe("/api2/json/nodes/pve1/qemu/100");
|
|
133
|
+
});
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
describe("reserved names", () => {
|
|
137
|
+
test("toString describes the node instead of extending the path", () => {
|
|
138
|
+
const { api } = recorder();
|
|
139
|
+
expect(String(api.nodes)).toBe("ProxyApi{path:/api2/json/nodes}");
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
test("EventEmitter probes on the root do not mint segments", () => {
|
|
143
|
+
const { api } = recorder();
|
|
144
|
+
expect(api.on).toBeUndefined();
|
|
145
|
+
expect(api.emit).toBeUndefined();
|
|
146
|
+
});
|
|
147
|
+
|
|
148
|
+
test("those names stay usable deeper down", async () => {
|
|
149
|
+
const { calls, api } = recorder();
|
|
150
|
+
await api.cluster.on.$get();
|
|
151
|
+
expect(calls[0]?.path).toBe("/api2/json/cluster/on");
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
test("a leading underscore escapes a reserved name at the root", async () => {
|
|
155
|
+
const { calls, api } = recorder();
|
|
156
|
+
await api._on.$get();
|
|
157
|
+
expect(calls[0]?.path).toBe("/api2/json/on");
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
test("symbols do not become segments", () => {
|
|
161
|
+
const { api } = recorder();
|
|
162
|
+
expect(api[Symbol.toStringTag]).toBeUndefined();
|
|
163
|
+
});
|
|
164
|
+
});
|
|
165
|
+
|
|
166
|
+
describe("awkward segment names", () => {
|
|
167
|
+
test("hyphenated segments work through bracket access", async () => {
|
|
168
|
+
const { calls, api } = recorder();
|
|
169
|
+
await api.nodes.$("pve1").qemu.$(100).agent["get-fsinfo"].$get();
|
|
170
|
+
expect(calls[0]?.path).toBe(
|
|
171
|
+
"/api2/json/nodes/pve1/qemu/100/agent/get-fsinfo",
|
|
172
|
+
);
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
test("the engine is reachable through a custom implementation", async () => {
|
|
176
|
+
const seen: string[] = [];
|
|
177
|
+
const api = buildApiProxy<Record<string, never>>(
|
|
178
|
+
{
|
|
179
|
+
doRequest(_method, path) {
|
|
180
|
+
seen.push(path);
|
|
181
|
+
return Promise.resolve("ok");
|
|
182
|
+
},
|
|
183
|
+
},
|
|
184
|
+
"/custom",
|
|
185
|
+
// biome-ignore lint/suspicious/noExplicitAny: as above.
|
|
186
|
+
) as any;
|
|
187
|
+
expect(await api.thing.$get()).toBe("ok");
|
|
188
|
+
expect(seen).toEqual(["/custom/thing"]);
|
|
189
|
+
});
|
|
190
|
+
});
|