@xiangyixie/dsh-superagent 0.9.1 → 0.9.2
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 +259 -244
- package/LICENSE +21 -21
- package/README.md +589 -556
- package/bin/report.js +79 -79
- package/bin/watch.js +57 -57
- package/cordis.patch.yml +9 -9
- package/lib/control.js +494 -494
- package/lib/errors.js +199 -199
- package/lib/index.js +822 -822
- package/lib/orchestrator.js +1464 -1464
- package/lib/report.js +733 -733
- package/lib/store.js +385 -385
- package/lib/usage.js +152 -152
- package/lib/watch.js +458 -458
- package/package.json +67 -67
package/lib/control.js
CHANGED
|
@@ -1,494 +1,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 '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 '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
|
+
}
|