@xiangyixie/dsh-superagent 0.9.3 → 0.10.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/lib/control.js CHANGED
@@ -1,494 +1,495 @@
1
- /**
2
- * Local HTTP control plane for dsh-superagent.
3
- *
4
- * The five tools only exist inside a host session. Another UI — an editor
5
- * panel, a dashboard, a script — cannot call them without importing this
6
- * package's internals and holding a live agent. This module exposes the same
7
- * five operations over loopback HTTP so an embedder needs nothing but `fetch`.
8
- *
9
- * Safety properties, in order of importance:
10
- *
11
- * - Off unless `controlPort` is configured. A plugin should not open a socket
12
- * just because it was installed.
13
- * - Bound to 127.0.0.1, never a routable interface.
14
- * - Every request needs `Authorization: Bearer <token>`. The token is random
15
- * per process and written to `<stateDir>/control.json` with mode 0600, so it
16
- * is readable by the user who runs the host and nobody else.
17
- * - The `Host` header must name the loopback address and port we listen on,
18
- * which blocks DNS-rebinding attacks from a browser page.
19
- * - No CORS headers are sent, so a page on another origin cannot read replies.
20
- * - Bodies are capped, requests time out, and long polls are capped, so a
21
- * wedged client cannot pin the host.
22
- *
23
- * The HTTP layer is transport only: every action is a callback supplied by the
24
- * plugin, so a start over HTTP goes through exactly the same checks as
25
- * `superagent_start` (live session, child guard, quota, budgets).
26
- *
27
- * @module dsh-superagent/control
28
- */
29
- import { randomBytes, timingSafeEqual } from 'node:crypto'
30
- import fsp from 'node:fs/promises'
31
- import { createServer } from 'node:http'
32
- import os from 'node:os'
33
- import path from 'node:path'
34
- import { classifyError } from './errors.js'
35
-
36
- /** Bodies are JSON commands, never uploaded files. */
37
- const BODY_LIMIT = 64 * 1024
38
- /** Longest block one request may ask for. `superagent_status` caps at 3600 s. */
39
- const MAX_WAIT_SECONDS = 300
40
- /**
41
- * Bounds how long a client may take to *send* a request (headers plus body).
42
- * Node measures this on the receiving side, so it does not cut a long poll:
43
- * the 300 s wait happens while the response is being produced.
44
- */
45
- const REQUEST_TIMEOUT_MS = 60_000
46
- const DISCOVERY_FILE = 'control.json'
47
- const ROUTE_HINT = 'GET / lists the endpoints; docs/embedding.md has request and response examples.'
48
-
49
- /** Error shape used by the routing layer to choose a status code. */
50
- class HttpError extends Error {
51
- constructor(status, message, { id = 'bad-request', hint } = {}) {
52
- super(message)
53
- this.status = status
54
- this.id = id
55
- this.hint = hint
56
- }
57
- }
58
-
59
- function clampWait(value) {
60
- const seconds = Number(value)
61
- if (!Number.isFinite(seconds) || seconds <= 0) return 0
62
- return Math.min(MAX_WAIT_SECONDS, Math.trunc(seconds))
63
- }
64
-
65
- function sameToken(given, expected) {
66
- const a = Buffer.from(given)
67
- const b = Buffer.from(expected)
68
- return a.length === b.length && timingSafeEqual(a, b)
69
- }
70
-
71
- function send(res, status, payload) {
72
- if (res.headersSent) return
73
- const body = `${JSON.stringify(payload)}\n`
74
- res.writeHead(status, {
75
- 'content-type': 'application/json; charset=utf-8',
76
- 'content-length': Buffer.byteLength(body),
77
- 'cache-control': 'no-store',
78
- 'x-content-type-options': 'nosniff',
79
- })
80
- res.end(body)
81
- }
82
-
83
- /** Map a thrown error to an HTTP status using the same classifier users see. */
84
- function statusFor(error) {
85
- if (error instanceof HttpError) return error.status
86
- switch (classifyError(error).id) {
87
- case 'unknown-run':
88
- return 404
89
- case 'no-goal':
90
- return 400
91
- case 'run-owned':
92
- case 'quota':
93
- case 'budget':
94
- case 'no-agent':
95
- case 'no-session':
96
- case 'recursion':
97
- // A worker session cannot own a run; the caller can fix that by naming a
98
- // different session, so this is not a server failure.
99
- return 409
100
- case 'no-subagents':
101
- // The host lacks a service the plugin needs; no request can fix that.
102
- return 503
103
- default:
104
- // Includes corrupt state: a broken file is ours to fix, not the caller's.
105
- return 500
106
- }
107
- }
108
-
109
- function errorPayload(error) {
110
- if (error instanceof HttpError) {
111
- // Transport-level refusals are not host failures; do not dress them in the
112
- // "call superagent_list and retry" hint meant for a broken run.
113
- return {
114
- ok: false,
115
- error: { id: error.id, summary: error.message, hint: error.hint ?? null, detail: error.message },
116
- }
117
- }
118
- const { id, summary, hint, detail } = classifyError(error)
119
- return { ok: false, error: { id, summary, hint, detail } }
120
- }
121
-
122
- /**
123
- * Read a request body as text, refusing anything over the cap.
124
- * @param {import('node:http').IncomingMessage} req - request.
125
- * @returns {Promise<string>} body text.
126
- */
127
- function readBody(req) {
128
- return new Promise((resolve, reject) => {
129
- const chunks = []
130
- let size = 0
131
- let settled = false
132
- const fail = error => {
133
- if (settled) return
134
- settled = true
135
- reject(error)
136
- }
137
- req.on('data', chunk => {
138
- if (settled) return
139
- size += chunk.length
140
- if (size > BODY_LIMIT) {
141
- // Keep draining instead of destroying the socket: the client then gets
142
- // a readable 413 rather than a connection reset it cannot interpret.
143
- fail(new HttpError(413, `request body is larger than ${BODY_LIMIT} bytes`, {
144
- id: 'body-too-large',
145
- hint: 'send only the documented JSON fields; reports and files are not accepted here.',
146
- }))
147
- req.resume()
148
- return
149
- }
150
- chunks.push(chunk)
151
- })
152
- req.on('end', () => {
153
- if (settled) return
154
- settled = true
155
- resolve(Buffer.concat(chunks).toString('utf8'))
156
- })
157
- req.on('error', fail)
158
- req.on('aborted', () => fail(new HttpError(400, 'the client aborted the request', { id: 'aborted' })))
159
- })
160
- }
161
-
162
- async function readJson(req) {
163
- const text = (await readBody(req)).trim()
164
- if (!text) return {}
165
- try {
166
- const parsed = JSON.parse(text)
167
- if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
168
- throw new Error('body must be a JSON object')
169
- }
170
- return parsed
171
- } catch (error) {
172
- throw new HttpError(400, `request body is not a JSON object: ${error?.message ?? error}`, {
173
- id: 'bad-json',
174
- hint: 'send a JSON object such as {"goal": "...", "session_id": "..."}.',
175
- })
176
- }
177
- }
178
-
179
- /**
180
- * Create the control plane. Nothing is bound until `start()` is called.
181
- *
182
- * @param {object} options - dependencies.
183
- * @param {number} options.port - 1–65535, or 0 for an ephemeral port.
184
- * @param {string} options.stateRoot - directory that receives `control.json`.
185
- * @param {string} options.version - plugin version reported by `/health`.
186
- * @param {{
187
- * list: (query: object) => Promise<object>,
188
- * status: (runId: string, waitSeconds: number) => Promise<object>,
189
- * start: (body: object) => Promise<object>,
190
- * cancel: (runId: string) => Promise<object>,
191
- * resume: (runId: string, body: object) => Promise<object>,
192
- * }} options.actions - plugin operations; each returns a serializable payload.
193
- * @param {(message: string) => void} [options.log] - diagnostics sink.
194
- */
195
- export function createControlPlane({ port, stateRoot, version, actions, log = () => {} }) {
196
- const token = randomBytes(32).toString('base64url')
197
- // Identifies this plane, not just this process: a host that reloads the
198
- // plugin can run two planes in one pid, and only the newest may delete the
199
- // discovery file. A pid check alone would let the old one delete the new one.
200
- const instanceId = randomBytes(6).toString('hex')
201
- const discoveryPath = path.join(stateRoot, DISCOVERY_FILE)
202
- const startedAt = new Date().toISOString()
203
- let boundPort = null
204
- let server = null
205
- let closing = null
206
- let starting = null
207
- let stopRequested = false
208
-
209
- const url = () => `http://127.0.0.1:${boundPort}`
210
- const allowedHosts = () => new Set([
211
- `127.0.0.1:${boundPort}`,
212
- `localhost:${boundPort}`,
213
- `[::1]:${boundPort}`,
214
- ])
215
-
216
- function authorize(req) {
217
- if (!boundPort) {
218
- throw new HttpError(503, 'the control plane is not listening yet', {
219
- id: 'not-ready',
220
- hint: 'the host is still binding the port; retry in a moment. If it persists, check the host log for a controlPort error.',
221
- })
222
- }
223
- const host = String(req.headers.host ?? '').toLowerCase()
224
- // A browser page pointed at 127.0.0.1 by DNS rebinding sends its own
225
- // hostname here. Requiring the loopback name closes that path.
226
- if (!allowedHosts().has(host)) {
227
- throw new HttpError(
228
- 403,
229
- `unexpected Host header "${host}"; the control plane answers only on 127.0.0.1 and localhost`,
230
- { id: 'forbidden-host', hint: `connect to ${boundPort ? url() : 'the URL in the discovery file'} directly.` },
231
- )
232
- }
233
- const header = String(req.headers.authorization ?? '')
234
- const match = /^Bearer\s+(\S+)$/i.exec(header)
235
- if (!match || !sameToken(match[1], token)) {
236
- throw new HttpError(401, 'missing or wrong bearer token', {
237
- id: 'unauthorized',
238
- hint: `read the "token" field in ${discoveryPath} and send "Authorization: Bearer <token>". `
239
- + 'The token is regenerated each time the host starts.',
240
- })
241
- }
242
- }
243
-
244
- /**
245
- * Route one request. Kept separate from the socket so tests can drive it
246
- * through a real server without any special-case code.
247
- */
248
- async function handle(req, res) {
249
- try {
250
- authorize(req)
251
- const url = new URL(req.url ?? '/', 'http://127.0.0.1')
252
- const parts = url.pathname.split('/').filter(Boolean)
253
- const method = req.method ?? 'GET'
254
-
255
- if (parts.length === 0) {
256
- if (method !== 'GET') throw new HttpError(405, 'only GET is allowed here', { id: 'method-not-allowed', hint: ROUTE_HINT })
257
- send(res, 200, {
258
- ok: true,
259
- data: {
260
- service: 'dsh-superagent',
261
- version,
262
- pid: process.pid,
263
- endpoints: ['GET /health', 'GET /runs', 'GET /runs/:id', 'POST /runs', 'POST /runs/:id/cancel', 'POST /runs/:id/resume'],
264
- },
265
- })
266
- return
267
- }
268
-
269
- if (parts[0] === 'health' && parts.length === 1) {
270
- if (method !== 'GET') throw new HttpError(405, 'only GET is allowed here', { id: 'method-not-allowed', hint: ROUTE_HINT })
271
- const health = await actions.health?.()
272
- send(res, 200, {
273
- ok: true,
274
- data: {
275
- service: 'dsh-superagent',
276
- version,
277
- pid: process.pid,
278
- hostname: os.hostname(),
279
- stateDir: stateRoot,
280
- startedAt,
281
- uptimeSeconds: Math.round(process.uptime()),
282
- ...(health ?? {}),
283
- },
284
- })
285
- return
286
- }
287
-
288
- if (parts[0] !== 'runs' || parts.length > 3) {
289
- throw new HttpError(404, `no route for ${method} ${url.pathname}`, { id: 'not-found', hint: ROUTE_HINT })
290
- }
291
-
292
- if (parts.length === 1) {
293
- if (method === 'GET') {
294
- const payload = await actions.list({ limit: url.searchParams.get('limit') })
295
- send(res, 200, { ok: true, data: payload.data, text: payload.text })
296
- return
297
- }
298
- if (method === 'POST') {
299
- const body = await readJson(req)
300
- const payload = await actions.start(body)
301
- send(res, 202, { ok: true, data: payload.data, text: payload.text })
302
- return
303
- }
304
- throw new HttpError(405, `${method} is not allowed on /runs; use GET or POST`, { id: 'method-not-allowed', hint: ROUTE_HINT })
305
- }
306
-
307
- let runId = ''
308
- try {
309
- runId = decodeURIComponent(parts[1])
310
- } catch {
311
- // A malformed escape is the caller's mistake, not a host failure.
312
- throw new HttpError(400, `run id "${parts[1]}" is not valid percent-encoding`, { id: 'bad-run-id', hint: ROUTE_HINT })
313
- }
314
- if (!runId) throw new HttpError(400, 'run id is empty', { id: 'bad-run-id', hint: ROUTE_HINT })
315
-
316
- if (parts.length === 2) {
317
- if (method !== 'GET') throw new HttpError(405, `${method} is not allowed on /runs/:id; use GET`, { id: 'method-not-allowed', hint: ROUTE_HINT })
318
- const wait = clampWait(url.searchParams.get('wait'))
319
- const payload = await actions.status(runId, wait)
320
- send(res, 200, { ok: true, data: payload.data, text: payload.text })
321
- return
322
- }
323
-
324
- const action = parts[2]
325
- if (action !== 'cancel' && action !== 'resume') {
326
- throw new HttpError(404, `no route for ${method} ${url.pathname}`, { id: 'not-found', hint: ROUTE_HINT })
327
- }
328
- if (method !== 'POST') {
329
- throw new HttpError(405, `${method} is not allowed on /runs/:id/${action}; use POST`, { id: 'method-not-allowed', hint: ROUTE_HINT })
330
- }
331
- if (action === 'cancel') {
332
- const payload = await actions.cancel(runId)
333
- send(res, 200, { ok: true, data: payload.data, text: payload.text })
334
- return
335
- }
336
- const body = await readJson(req)
337
- const payload = await actions.resume(runId, body)
338
- send(res, 202, { ok: true, data: payload.data, text: payload.text })
339
- } catch (error) {
340
- const status = statusFor(error)
341
- // A 5xx is a plugin bug or a broken state directory; say so in the host
342
- // log as well, because the client may never read the response.
343
- if (status >= 500) log(`control request failed: ${error?.message ?? error}`)
344
- send(res, status, errorPayload(error))
345
- }
346
- }
347
-
348
- async function writeDiscovery() {
349
- const doc = {
350
- service: 'dsh-superagent',
351
- version,
352
- url: url(),
353
- token,
354
- pid: process.pid,
355
- instanceId,
356
- hostname: os.hostname(),
357
- stateDir: stateRoot,
358
- startedAt,
359
- }
360
- const tmp = `${discoveryPath}.${process.pid}.${instanceId}.tmp`
361
- // `wx` refuses a pre-existing path, so a planted symlink cannot redirect a
362
- // file that contains the token. 0600 before any content is written.
363
- const handle = await fsp.open(tmp, 'wx', 0o600)
364
- try {
365
- await handle.writeFile(`${JSON.stringify(doc, null, 2)}\n`, 'utf8')
366
- } finally {
367
- await handle.close()
368
- }
369
- await fsp.rename(tmp, discoveryPath)
370
- try {
371
- await fsp.chmod(discoveryPath, 0o600)
372
- } catch {
373
- // Windows ignores most mode bits; the file's ACL still applies.
374
- }
375
- }
376
-
377
- async function removeDiscovery() {
378
- try {
379
- const current = JSON.parse(await fsp.readFile(discoveryPath, 'utf8'))
380
- // Another plane may have replaced the file after this one stopped
381
- // listening; deleting its discovery file would break that plane.
382
- if (current?.instanceId !== instanceId) return
383
- await fsp.unlink(discoveryPath)
384
- } catch {
385
- // Already gone, or replaced by something unreadable. Nothing to remove.
386
- }
387
- // A crash between the write and the rename leaves a token file behind.
388
- await fsp.unlink(`${discoveryPath}.${process.pid}.${instanceId}.tmp`).catch(() => {})
389
- }
390
-
391
- /** Close the listening socket, if any, and forget its port. */
392
- async function closeServer() {
393
- if (!server) return
394
- const instance = server
395
- server = null
396
- boundPort = null
397
- await new Promise(resolve => {
398
- instance.close(() => resolve())
399
- // Long polls hold sockets open; do not wait for them to finish.
400
- instance.closeAllConnections?.()
401
- })
402
- }
403
-
404
- return {
405
- discoveryPath,
406
- get port() {
407
- return boundPort
408
- },
409
- get url() {
410
- return boundPort ? url() : null
411
- },
412
-
413
- /**
414
- * Bind the loopback port and publish the discovery file.
415
- *
416
- * The whole operation is tracked in `starting` so a dispose that lands in
417
- * the middle of it cannot leave a listener behind: `stop()` waits for the
418
- * start to settle, and a start that sees `stopRequested` closes itself
419
- * before it ever publishes a discovery file.
420
- *
421
- * @returns {Promise<{ port: number, url: string }>} where it listens.
422
- */
423
- async start() {
424
- if (server) return { port: boundPort, url: url() }
425
- // Two starts in one mount would bind twice and lose track of the first
426
- // listener; share the in-flight attempt instead.
427
- if (starting) return starting
428
- if (stopRequested) throw new Error('the control plane has been stopped; a new instance is required')
429
- const run = (async () => {
430
- const instance = createServer((req, res) => {
431
- handle(req, res).catch(error => {
432
- log(`control handler crashed: ${error?.message ?? error}`)
433
- send(res, 500, errorPayload(error))
434
- })
435
- })
436
- instance.requestTimeout = REQUEST_TIMEOUT_MS
437
- instance.headersTimeout = 10_000
438
- instance.keepAliveTimeout = 5_000
439
- instance.maxConnections = 64
440
- await new Promise((resolve, reject) => {
441
- const onError = error => reject(error)
442
- instance.once('error', onError)
443
- instance.listen(port, '127.0.0.1', () => {
444
- instance.off('error', onError)
445
- resolve()
446
- })
447
- })
448
- server = instance
449
- boundPort = instance.address().port
450
- if (stopRequested) {
451
- await closeServer()
452
- throw new Error('the control plane was stopped before it finished starting')
453
- }
454
- try {
455
- await writeDiscovery()
456
- } catch (error) {
457
- // Listening without a discovery file is a silent, unreachable server:
458
- // close it and report the real cause instead of claiming success.
459
- await closeServer()
460
- throw new Error(`cannot write the discovery file ${discoveryPath}: ${error?.message ?? error}`)
461
- }
462
- log(`control plane listening on ${url()} (token in ${discoveryPath})`)
463
- return { port: boundPort, url: url() }
464
- })()
465
- starting = run
466
- try {
467
- return await run
468
- } finally {
469
- // Only clear our own attempt; a later start may already own `starting`.
470
- if (starting === run) starting = null
471
- }
472
- },
473
-
474
- /** Close the socket and remove this process's discovery file. */
475
- async stop() {
476
- stopRequested = true
477
- // Let a start that is already binding finish first; otherwise it could
478
- // publish a discovery file after this stop has cleaned up.
479
- if (starting) {
480
- try {
481
- await starting
482
- } catch {
483
- // A start that failed has nothing left to close.
484
- }
485
- }
486
- if (closing) return closing
487
- closing = (async () => {
488
- await closeServer()
489
- await removeDiscovery()
490
- })()
491
- return closing
492
- },
493
- }
494
- }
1
+ /**
2
+ * Local HTTP control plane for dsh-superagent.
3
+ *
4
+ * The five tools only exist inside a host session. Another UI — an editor
5
+ * panel, a dashboard, a script — cannot call them without importing this
6
+ * package's internals and holding a live agent. This module exposes the same
7
+ * five operations over loopback HTTP so an embedder needs nothing but `fetch`.
8
+ *
9
+ * Safety properties, in order of importance:
10
+ *
11
+ * - Off unless `controlPort` is configured. A plugin should not open a socket
12
+ * just because it was installed.
13
+ * - Bound to 127.0.0.1, never a routable interface.
14
+ * - Every request needs `Authorization: Bearer <token>`. The token is random
15
+ * per process and written to `<stateDir>/control.json` with mode 0600, so it
16
+ * is readable by the user who runs the host and nobody else.
17
+ * - The `Host` header must name the loopback address and port we listen on,
18
+ * which blocks DNS-rebinding attacks from a browser page.
19
+ * - No CORS headers are sent, so a page on another origin cannot read replies.
20
+ * - Bodies are capped, requests time out, and long polls are capped, so a
21
+ * wedged client cannot pin the host.
22
+ *
23
+ * The HTTP layer is transport only: every action is a callback supplied by the
24
+ * plugin, so a start over HTTP goes through exactly the same checks as
25
+ * `superagent_start` (live session, child guard, quota, budgets).
26
+ *
27
+ * @module dsh-superagent/control
28
+ */
29
+ import { randomBytes, timingSafeEqual } from 'node:crypto'
30
+ import fsp from 'node:fs/promises'
31
+ import { createServer } from 'node:http'
32
+ import os from 'node:os'
33
+ import path from 'node:path'
34
+ import { classifyError } from './errors.js'
35
+
36
+ /** Bodies are JSON commands, never uploaded files. */
37
+ const BODY_LIMIT = 64 * 1024
38
+ /** Longest block one request may ask for. `superagent_status` caps at 3600 s. */
39
+ const MAX_WAIT_SECONDS = 300
40
+ /**
41
+ * Bounds how long a client may take to *send* a request (headers plus body).
42
+ * Node measures this on the receiving side, so it does not cut a long poll:
43
+ * the 300 s wait happens while the response is being produced.
44
+ */
45
+ const REQUEST_TIMEOUT_MS = 60_000
46
+ const DISCOVERY_FILE = 'control.json'
47
+ const ROUTE_HINT = 'GET / lists the endpoints; docs/embedding.md has request and response examples.'
48
+
49
+ /** Error shape used by the routing layer to choose a status code. */
50
+ class HttpError extends Error {
51
+ constructor(status, message, { id = 'bad-request', hint } = {}) {
52
+ super(message)
53
+ this.status = status
54
+ this.id = id
55
+ this.hint = hint
56
+ }
57
+ }
58
+
59
+ function clampWait(value) {
60
+ const seconds = Number(value)
61
+ if (!Number.isFinite(seconds) || seconds <= 0) return 0
62
+ return Math.min(MAX_WAIT_SECONDS, Math.trunc(seconds))
63
+ }
64
+
65
+ function sameToken(given, expected) {
66
+ const a = Buffer.from(given)
67
+ const b = Buffer.from(expected)
68
+ return a.length === b.length && timingSafeEqual(a, b)
69
+ }
70
+
71
+ function send(res, status, payload) {
72
+ if (res.headersSent) return
73
+ const body = `${JSON.stringify(payload)}\n`
74
+ res.writeHead(status, {
75
+ 'content-type': 'application/json; charset=utf-8',
76
+ 'content-length': Buffer.byteLength(body),
77
+ 'cache-control': 'no-store',
78
+ 'x-content-type-options': 'nosniff',
79
+ })
80
+ res.end(body)
81
+ }
82
+
83
+ /** Map a thrown error to an HTTP status using the same classifier users see. */
84
+ function statusFor(error) {
85
+ if (error instanceof HttpError) return error.status
86
+ switch (classifyError(error).id) {
87
+ case 'unknown-run':
88
+ return 404
89
+ case 'no-goal':
90
+ return 400
91
+ case 'run-owned':
92
+ case 'wrong-session':
93
+ case 'quota':
94
+ case 'budget':
95
+ case 'no-agent':
96
+ case 'no-session':
97
+ case 'recursion':
98
+ // A worker session cannot own a run; the caller can fix that by naming a
99
+ // different session, so this is not a server failure.
100
+ return 409
101
+ case 'no-subagents':
102
+ // The host lacks a service the plugin needs; no request can fix that.
103
+ return 503
104
+ default:
105
+ // Includes corrupt state: a broken file is ours to fix, not the caller's.
106
+ return 500
107
+ }
108
+ }
109
+
110
+ function errorPayload(error) {
111
+ if (error instanceof HttpError) {
112
+ // Transport-level refusals are not host failures; do not dress them in the
113
+ // "call superagent_list and retry" hint meant for a broken run.
114
+ return {
115
+ ok: false,
116
+ error: { id: error.id, summary: error.message, hint: error.hint ?? null, detail: error.message },
117
+ }
118
+ }
119
+ const { id, summary, hint, detail } = classifyError(error)
120
+ return { ok: false, error: { id, summary, hint, detail } }
121
+ }
122
+
123
+ /**
124
+ * Read a request body as text, refusing anything over the cap.
125
+ * @param {import('node:http').IncomingMessage} req - request.
126
+ * @returns {Promise<string>} body text.
127
+ */
128
+ function readBody(req) {
129
+ return new Promise((resolve, reject) => {
130
+ const chunks = []
131
+ let size = 0
132
+ let settled = false
133
+ const fail = error => {
134
+ if (settled) return
135
+ settled = true
136
+ reject(error)
137
+ }
138
+ req.on('data', chunk => {
139
+ if (settled) return
140
+ size += chunk.length
141
+ if (size > BODY_LIMIT) {
142
+ // Keep draining instead of destroying the socket: the client then gets
143
+ // a readable 413 rather than a connection reset it cannot interpret.
144
+ fail(new HttpError(413, `request body is larger than ${BODY_LIMIT} bytes`, {
145
+ id: 'body-too-large',
146
+ hint: 'send only the documented JSON fields; reports and files are not accepted here.',
147
+ }))
148
+ req.resume()
149
+ return
150
+ }
151
+ chunks.push(chunk)
152
+ })
153
+ req.on('end', () => {
154
+ if (settled) return
155
+ settled = true
156
+ resolve(Buffer.concat(chunks).toString('utf8'))
157
+ })
158
+ req.on('error', fail)
159
+ req.on('aborted', () => fail(new HttpError(400, 'the client aborted the request', { id: 'aborted' })))
160
+ })
161
+ }
162
+
163
+ async function readJson(req) {
164
+ const text = (await readBody(req)).trim()
165
+ if (!text) return {}
166
+ try {
167
+ const parsed = JSON.parse(text)
168
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
169
+ throw new Error('body must be a JSON object')
170
+ }
171
+ return parsed
172
+ } catch (error) {
173
+ throw new HttpError(400, `request body is not a JSON object: ${error?.message ?? error}`, {
174
+ id: 'bad-json',
175
+ hint: 'send a JSON object such as {"goal": "...", "session_id": "..."}.',
176
+ })
177
+ }
178
+ }
179
+
180
+ /**
181
+ * Create the control plane. Nothing is bound until `start()` is called.
182
+ *
183
+ * @param {object} options - dependencies.
184
+ * @param {number} options.port - 1–65535, or 0 for an ephemeral port.
185
+ * @param {string} options.stateRoot - directory that receives `control.json`.
186
+ * @param {string} options.version - plugin version reported by `/health`.
187
+ * @param {{
188
+ * list: (query: object) => Promise<object>,
189
+ * status: (runId: string, waitSeconds: number) => Promise<object>,
190
+ * start: (body: object) => Promise<object>,
191
+ * cancel: (runId: string) => Promise<object>,
192
+ * resume: (runId: string, body: object) => Promise<object>,
193
+ * }} options.actions - plugin operations; each returns a serializable payload.
194
+ * @param {(message: string) => void} [options.log] - diagnostics sink.
195
+ */
196
+ export function createControlPlane({ port, stateRoot, version, actions, log = () => {} }) {
197
+ const token = randomBytes(32).toString('base64url')
198
+ // Identifies this plane, not just this process: a host that reloads the
199
+ // plugin can run two planes in one pid, and only the newest may delete the
200
+ // discovery file. A pid check alone would let the old one delete the new one.
201
+ const instanceId = randomBytes(6).toString('hex')
202
+ const discoveryPath = path.join(stateRoot, DISCOVERY_FILE)
203
+ const startedAt = new Date().toISOString()
204
+ let boundPort = null
205
+ let server = null
206
+ let closing = null
207
+ let starting = null
208
+ let stopRequested = false
209
+
210
+ const url = () => `http://127.0.0.1:${boundPort}`
211
+ const allowedHosts = () => new Set([
212
+ `127.0.0.1:${boundPort}`,
213
+ `localhost:${boundPort}`,
214
+ `[::1]:${boundPort}`,
215
+ ])
216
+
217
+ function authorize(req) {
218
+ if (!boundPort) {
219
+ throw new HttpError(503, 'the control plane is not listening yet', {
220
+ id: 'not-ready',
221
+ hint: 'the host is still binding the port; retry in a moment. If it persists, check the host log for a controlPort error.',
222
+ })
223
+ }
224
+ const host = String(req.headers.host ?? '').toLowerCase()
225
+ // A browser page pointed at 127.0.0.1 by DNS rebinding sends its own
226
+ // hostname here. Requiring the loopback name closes that path.
227
+ if (!allowedHosts().has(host)) {
228
+ throw new HttpError(
229
+ 403,
230
+ `unexpected Host header "${host}"; the control plane answers only on 127.0.0.1 and localhost`,
231
+ { id: 'forbidden-host', hint: `connect to ${boundPort ? url() : 'the URL in the discovery file'} directly.` },
232
+ )
233
+ }
234
+ const header = String(req.headers.authorization ?? '')
235
+ const match = /^Bearer\s+(\S+)$/i.exec(header)
236
+ if (!match || !sameToken(match[1], token)) {
237
+ throw new HttpError(401, 'missing or wrong bearer token', {
238
+ id: 'unauthorized',
239
+ hint: `read the "token" field in ${discoveryPath} and send "Authorization: Bearer <token>". `
240
+ + 'The token is regenerated each time the host starts.',
241
+ })
242
+ }
243
+ }
244
+
245
+ /**
246
+ * Route one request. Kept separate from the socket so tests can drive it
247
+ * through a real server without any special-case code.
248
+ */
249
+ async function handle(req, res) {
250
+ try {
251
+ authorize(req)
252
+ const url = new URL(req.url ?? '/', 'http://127.0.0.1')
253
+ const parts = url.pathname.split('/').filter(Boolean)
254
+ const method = req.method ?? 'GET'
255
+
256
+ if (parts.length === 0) {
257
+ if (method !== 'GET') throw new HttpError(405, 'only GET is allowed here', { id: 'method-not-allowed', hint: ROUTE_HINT })
258
+ send(res, 200, {
259
+ ok: true,
260
+ data: {
261
+ service: 'dsh-superagent',
262
+ version,
263
+ pid: process.pid,
264
+ endpoints: ['GET /health', 'GET /runs', 'GET /runs/:id', 'POST /runs', 'POST /runs/:id/cancel', 'POST /runs/:id/resume'],
265
+ },
266
+ })
267
+ return
268
+ }
269
+
270
+ if (parts[0] === 'health' && parts.length === 1) {
271
+ if (method !== 'GET') throw new HttpError(405, 'only GET is allowed here', { id: 'method-not-allowed', hint: ROUTE_HINT })
272
+ const health = await actions.health?.()
273
+ send(res, 200, {
274
+ ok: true,
275
+ data: {
276
+ service: 'dsh-superagent',
277
+ version,
278
+ pid: process.pid,
279
+ hostname: os.hostname(),
280
+ stateDir: stateRoot,
281
+ startedAt,
282
+ uptimeSeconds: Math.round(process.uptime()),
283
+ ...(health ?? {}),
284
+ },
285
+ })
286
+ return
287
+ }
288
+
289
+ if (parts[0] !== 'runs' || parts.length > 3) {
290
+ throw new HttpError(404, `no route for ${method} ${url.pathname}`, { id: 'not-found', hint: ROUTE_HINT })
291
+ }
292
+
293
+ if (parts.length === 1) {
294
+ if (method === 'GET') {
295
+ const payload = await actions.list({ limit: url.searchParams.get('limit') })
296
+ send(res, 200, { ok: true, data: payload.data, text: payload.text })
297
+ return
298
+ }
299
+ if (method === 'POST') {
300
+ const body = await readJson(req)
301
+ const payload = await actions.start(body)
302
+ send(res, 202, { ok: true, data: payload.data, text: payload.text })
303
+ return
304
+ }
305
+ throw new HttpError(405, `${method} is not allowed on /runs; use GET or POST`, { id: 'method-not-allowed', hint: ROUTE_HINT })
306
+ }
307
+
308
+ let runId = ''
309
+ try {
310
+ runId = decodeURIComponent(parts[1])
311
+ } catch {
312
+ // A malformed escape is the caller's mistake, not a host failure.
313
+ throw new HttpError(400, `run id "${parts[1]}" is not valid percent-encoding`, { id: 'bad-run-id', hint: ROUTE_HINT })
314
+ }
315
+ if (!runId) throw new HttpError(400, 'run id is empty', { id: 'bad-run-id', hint: ROUTE_HINT })
316
+
317
+ if (parts.length === 2) {
318
+ if (method !== 'GET') throw new HttpError(405, `${method} is not allowed on /runs/:id; use GET`, { id: 'method-not-allowed', hint: ROUTE_HINT })
319
+ const wait = clampWait(url.searchParams.get('wait'))
320
+ const payload = await actions.status(runId, wait)
321
+ send(res, 200, { ok: true, data: payload.data, text: payload.text })
322
+ return
323
+ }
324
+
325
+ const action = parts[2]
326
+ if (action !== 'cancel' && action !== 'resume') {
327
+ throw new HttpError(404, `no route for ${method} ${url.pathname}`, { id: 'not-found', hint: ROUTE_HINT })
328
+ }
329
+ if (method !== 'POST') {
330
+ throw new HttpError(405, `${method} is not allowed on /runs/:id/${action}; use POST`, { id: 'method-not-allowed', hint: ROUTE_HINT })
331
+ }
332
+ if (action === 'cancel') {
333
+ const payload = await actions.cancel(runId)
334
+ send(res, 200, { ok: true, data: payload.data, text: payload.text })
335
+ return
336
+ }
337
+ const body = await readJson(req)
338
+ const payload = await actions.resume(runId, body)
339
+ send(res, 202, { ok: true, data: payload.data, text: payload.text })
340
+ } catch (error) {
341
+ const status = statusFor(error)
342
+ // A 5xx is a plugin bug or a broken state directory; say so in the host
343
+ // log as well, because the client may never read the response.
344
+ if (status >= 500) log(`control request failed: ${error?.message ?? error}`)
345
+ send(res, status, errorPayload(error))
346
+ }
347
+ }
348
+
349
+ async function writeDiscovery() {
350
+ const doc = {
351
+ service: 'dsh-superagent',
352
+ version,
353
+ url: url(),
354
+ token,
355
+ pid: process.pid,
356
+ instanceId,
357
+ hostname: os.hostname(),
358
+ stateDir: stateRoot,
359
+ startedAt,
360
+ }
361
+ const tmp = `${discoveryPath}.${process.pid}.${instanceId}.tmp`
362
+ // `wx` refuses a pre-existing path, so a planted symlink cannot redirect a
363
+ // file that contains the token. 0600 before any content is written.
364
+ const handle = await fsp.open(tmp, 'wx', 0o600)
365
+ try {
366
+ await handle.writeFile(`${JSON.stringify(doc, null, 2)}\n`, 'utf8')
367
+ } finally {
368
+ await handle.close()
369
+ }
370
+ await fsp.rename(tmp, discoveryPath)
371
+ try {
372
+ await fsp.chmod(discoveryPath, 0o600)
373
+ } catch {
374
+ // Windows ignores most mode bits; the file's ACL still applies.
375
+ }
376
+ }
377
+
378
+ async function removeDiscovery() {
379
+ try {
380
+ const current = JSON.parse(await fsp.readFile(discoveryPath, 'utf8'))
381
+ // Another plane may have replaced the file after this one stopped
382
+ // listening; deleting its discovery file would break that plane.
383
+ if (current?.instanceId !== instanceId) return
384
+ await fsp.unlink(discoveryPath)
385
+ } catch {
386
+ // Already gone, or replaced by something unreadable. Nothing to remove.
387
+ }
388
+ // A crash between the write and the rename leaves a token file behind.
389
+ await fsp.unlink(`${discoveryPath}.${process.pid}.${instanceId}.tmp`).catch(() => {})
390
+ }
391
+
392
+ /** Close the listening socket, if any, and forget its port. */
393
+ async function closeServer() {
394
+ if (!server) return
395
+ const instance = server
396
+ server = null
397
+ boundPort = null
398
+ await new Promise(resolve => {
399
+ instance.close(() => resolve())
400
+ // Long polls hold sockets open; do not wait for them to finish.
401
+ instance.closeAllConnections?.()
402
+ })
403
+ }
404
+
405
+ return {
406
+ discoveryPath,
407
+ get port() {
408
+ return boundPort
409
+ },
410
+ get url() {
411
+ return boundPort ? url() : null
412
+ },
413
+
414
+ /**
415
+ * Bind the loopback port and publish the discovery file.
416
+ *
417
+ * The whole operation is tracked in `starting` so a dispose that lands in
418
+ * the middle of it cannot leave a listener behind: `stop()` waits for the
419
+ * start to settle, and a start that sees `stopRequested` closes itself
420
+ * before it ever publishes a discovery file.
421
+ *
422
+ * @returns {Promise<{ port: number, url: string }>} where it listens.
423
+ */
424
+ async start() {
425
+ if (server) return { port: boundPort, url: url() }
426
+ // Two starts in one mount would bind twice and lose track of the first
427
+ // listener; share the in-flight attempt instead.
428
+ if (starting) return starting
429
+ if (stopRequested) throw new Error('the control plane has been stopped; a new instance is required')
430
+ const run = (async () => {
431
+ const instance = createServer((req, res) => {
432
+ handle(req, res).catch(error => {
433
+ log(`control handler crashed: ${error?.message ?? error}`)
434
+ send(res, 500, errorPayload(error))
435
+ })
436
+ })
437
+ instance.requestTimeout = REQUEST_TIMEOUT_MS
438
+ instance.headersTimeout = 10_000
439
+ instance.keepAliveTimeout = 5_000
440
+ instance.maxConnections = 64
441
+ await new Promise((resolve, reject) => {
442
+ const onError = error => reject(error)
443
+ instance.once('error', onError)
444
+ instance.listen(port, '127.0.0.1', () => {
445
+ instance.off('error', onError)
446
+ resolve()
447
+ })
448
+ })
449
+ server = instance
450
+ boundPort = instance.address().port
451
+ if (stopRequested) {
452
+ await closeServer()
453
+ throw new Error('the control plane was stopped before it finished starting')
454
+ }
455
+ try {
456
+ await writeDiscovery()
457
+ } catch (error) {
458
+ // Listening without a discovery file is a silent, unreachable server:
459
+ // close it and report the real cause instead of claiming success.
460
+ await closeServer()
461
+ throw new Error(`cannot write the discovery file ${discoveryPath}: ${error?.message ?? error}`)
462
+ }
463
+ log(`control plane listening on ${url()} (token in ${discoveryPath})`)
464
+ return { port: boundPort, url: url() }
465
+ })()
466
+ starting = run
467
+ try {
468
+ return await run
469
+ } finally {
470
+ // Only clear our own attempt; a later start may already own `starting`.
471
+ if (starting === run) starting = null
472
+ }
473
+ },
474
+
475
+ /** Close the socket and remove this process's discovery file. */
476
+ async stop() {
477
+ stopRequested = true
478
+ // Let a start that is already binding finish first; otherwise it could
479
+ // publish a discovery file after this stop has cleaned up.
480
+ if (starting) {
481
+ try {
482
+ await starting
483
+ } catch {
484
+ // A start that failed has nothing left to close.
485
+ }
486
+ }
487
+ if (closing) return closing
488
+ closing = (async () => {
489
+ await closeServer()
490
+ await removeDiscovery()
491
+ })()
492
+ return closing
493
+ },
494
+ }
495
+ }