dsh-marker 0.0.0-stage → 0.1.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/src/bridge.js ADDED
@@ -0,0 +1,494 @@
1
+ /**
2
+ * The `/ext/anno` bridge: one websocket endpoint on the DSH host webserver,
3
+ * a token handshake, annotation fan-out, and the agent-initiated pick queue.
4
+ *
5
+ * The bridge owns no storage of its own — every mutation goes through
6
+ * `AnnotationStore` so the browser and the model see the same record.
7
+ */
8
+
9
+ import { createHash, timingSafeEqual } from 'node:crypto'
10
+
11
+ import { WebSocketServer } from 'ws'
12
+
13
+ import { describeEndpoint } from './endpoint.js'
14
+ import {
15
+ HELLO_TIMEOUT_MS,
16
+ HEALTH_PATH,
17
+ LIMITS,
18
+ PICK_TIMEOUT_MS,
19
+ PING_INTERVAL_MS,
20
+ PROTOCOL_VERSION,
21
+ WS_PATH,
22
+ encodeFrame,
23
+ newPickId,
24
+ normalizeRecord,
25
+ parseClientFrame,
26
+ sameDocument,
27
+ } from './protocol.js'
28
+
29
+ const CLOSE_UNAUTHORIZED = 4401
30
+ const CLOSE_FORBIDDEN = 4403
31
+ const CLOSE_PROTOCOL = 4400
32
+
33
+ /**
34
+ * Constant-time token comparison. Hashing first gives both sides the same
35
+ * length, which `timingSafeEqual` requires.
36
+ * @param {string} presented
37
+ * @param {string} expected
38
+ */
39
+ export function tokenMatches(presented, expected) {
40
+ if (typeof presented !== 'string' || typeof expected !== 'string') return false
41
+ const left = createHash('sha256').update(presented).digest()
42
+ const right = createHash('sha256').update(expected).digest()
43
+ return timingSafeEqual(left, right)
44
+ }
45
+
46
+ /** @param {unknown} error */
47
+ export function describeError(error) {
48
+ return error instanceof Error ? error.message : String(error)
49
+ }
50
+
51
+ /**
52
+ * @param {object} options
53
+ * @param {import('./store.js').AnnotationStore} options.store
54
+ * @param {string} options.token
55
+ * @param {(input: { data: Uint8Array, mediaType: string, name?: string }) => Promise<any>} [options.saveImage]
56
+ * @param {(record: any) => void | Promise<void>} [options.onCreated] Side effect of one accepted create (routed delivery).
57
+ * @param {{ info?: Function, warn?: Function, debug?: Function }} [options.logger]
58
+ * @param {string} [options.instanceId] This process's discovery id, published so a
59
+ * locator answer can be matched to the health answer of the same host.
60
+ */
61
+ export function createBridge({ store, token, saveImage, onCreated, logger = {}, instanceId }) {
62
+ const log = {
63
+ info: logger.info ?? (() => {}),
64
+ warn: logger.warn ?? (() => {}),
65
+ debug: logger.debug ?? (() => {}),
66
+ }
67
+ /** @type {Set<any>} */
68
+ const clients = new Set()
69
+ /** @type {Map<string, any>} */
70
+ const picks = new Map()
71
+ let heartbeat = null
72
+
73
+ /** @param {any} client @param {any} frame */
74
+ function send(client, frame) {
75
+ if (client.closed === true) return
76
+ // 1 is WebSocket.OPEN; a closing socket must not throw into the caller.
77
+ if (client.connection.readyState !== 1) return
78
+ client.connection.send(encodeFrame(frame))
79
+ }
80
+
81
+ /** @param {any} frame */
82
+ function broadcast(frame) {
83
+ for (const client of clients) if (client.authed) send(client, frame)
84
+ }
85
+
86
+ /** @param {string} type @param {any} record @param {number} seq */
87
+ function broadcastEvent(type, record, seq) {
88
+ broadcast({ t: 'anno.event', seq, type, record: toWire(record) })
89
+ }
90
+
91
+ /**
92
+ * @param {import('ws').WebSocket} connection
93
+ * @param {import('node:http').IncomingMessage} request
94
+ */
95
+ function onConnection(connection, request) {
96
+ const client = {
97
+ connection,
98
+ authed: false,
99
+ closed: false,
100
+ clientId: '',
101
+ remote: request?.socket?.remoteAddress ?? '',
102
+ helloDeadline: setTimeout(() => {
103
+ if (!client.authed) connection.close(CLOSE_PROTOCOL, 'hello timeout')
104
+ }, HELLO_TIMEOUT_MS),
105
+ }
106
+ client.helloDeadline.unref?.()
107
+ clients.add(client)
108
+
109
+ // `isAlive` is bridge state, not a ws property: the heartbeat clears it and
110
+ // a pong restores it, which is the standard liveness check for `ws`.
111
+ connection.isAlive = true
112
+ connection.on('pong', () => {
113
+ connection.isAlive = true
114
+ })
115
+ connection.on('message', (data) => {
116
+ void onMessage(client, data.toString())
117
+ })
118
+ connection.on('close', () => {
119
+ clearTimeout(client.helloDeadline)
120
+ client.closed = true
121
+ clients.delete(client)
122
+ })
123
+ connection.on('error', (error) => {
124
+ log.warn(`annotations: socket error: ${describeError(error)}`)
125
+ clearTimeout(client.helloDeadline)
126
+ client.closed = true
127
+ clients.delete(client)
128
+ })
129
+ }
130
+
131
+ /**
132
+ * @param {any} client
133
+ * @param {string} text
134
+ */
135
+ async function onMessage(client, text) {
136
+ const parsed = parseClientFrame(text)
137
+ if (!parsed.ok) {
138
+ reject(client, parsed.reason)
139
+ return
140
+ }
141
+ const frame = parsed.frame
142
+
143
+ if (frame.t === 'hello') {
144
+ if (!tokenMatches(frame.token, token)) {
145
+ client.connection.close(CLOSE_FORBIDDEN, 'bad token')
146
+ return
147
+ }
148
+ if (frame.version !== PROTOCOL_VERSION) {
149
+ send(client, {
150
+ t: 'error',
151
+ code: 'protocol-version',
152
+ message: `host speaks protocol ${PROTOCOL_VERSION}, client sent ${String(frame.version)}`,
153
+ })
154
+ client.connection.close(CLOSE_PROTOCOL, 'protocol version')
155
+ return
156
+ }
157
+ client.authed = true
158
+ client.clientId = typeof frame.clientId === 'string' ? frame.clientId : ''
159
+ clearTimeout(client.helloDeadline)
160
+ send(client, {
161
+ t: 'hello.ok',
162
+ version: PROTOCOL_VERSION,
163
+ wsPath: WS_PATH,
164
+ openCount: store.count((record) => record.state === 'open'),
165
+ activeSessions: [],
166
+ caps: { pick: true, query: true, mutate: true },
167
+ })
168
+ log.debug(`annotations: client ${client.clientId || '(anon)'} connected`)
169
+ return
170
+ }
171
+
172
+ if (!client.authed) {
173
+ reject(client, 'hello required before any other frame')
174
+ client.connection.close(CLOSE_UNAUTHORIZED, 'hello required')
175
+ return
176
+ }
177
+
178
+ switch (frame.t) {
179
+ case 'ping':
180
+ send(client, { t: 'pong' })
181
+ return
182
+ case 'anno.create':
183
+ await onCreate(client, frame)
184
+ return
185
+ case 'anno.query':
186
+ await onQuery(client, frame)
187
+ return
188
+ case 'anno.mutate':
189
+ await onMutate(client, frame)
190
+ return
191
+ case 'pick.result':
192
+ onPickResult(frame)
193
+ return
194
+ default:
195
+ reject(client, `unhandled frame ${frame.t}`)
196
+ }
197
+ }
198
+
199
+ /** @param {any} client @param {string} reason */
200
+ function reject(client, reason) {
201
+ send(client, { t: 'error', code: 'protocol', message: reason })
202
+ }
203
+
204
+ /**
205
+ * @param {any} client
206
+ * @param {any} frame
207
+ */
208
+ async function onCreate(client, frame) {
209
+ const record = normalizeRecord(frame.record)
210
+ const existing = store.get(record.id)
211
+ if (existing !== undefined) {
212
+ // Offline replay is expected: the same id may arrive twice.
213
+ send(client, { t: 'anno.ack', reqId: frame.reqId, id: record.id, seq: store.seq, state: existing.state })
214
+ return
215
+ }
216
+
217
+ if (typeof frame.targetImageB64 === 'string' && saveImage !== undefined) {
218
+ try {
219
+ const ref = await saveImage({
220
+ data: Buffer.from(frame.targetImageB64, 'base64'),
221
+ mediaType: imageMediaType(frame.targetImageMime),
222
+ name: `${record.id}.png`,
223
+ })
224
+ await store.setImage(record.id, ref)
225
+ record.host = { image: ref }
226
+ } catch (error) {
227
+ // A rejected crop must not cost the user their comment.
228
+ log.warn(`annotations: crop rejected for ${record.id}: ${describeError(error)}`)
229
+ }
230
+ }
231
+
232
+ const seq = await store.put(record)
233
+ send(client, { t: 'anno.ack', reqId: frame.reqId, id: record.id, seq, state: record.state })
234
+ broadcastEvent('created', record, seq)
235
+ // A routed annotation is also handed to the Web Client's queue; a delivery
236
+ // failure must not fail the annotation itself.
237
+ if (onCreated !== undefined) {
238
+ try {
239
+ await onCreated(record)
240
+ } catch (error) {
241
+ log.warn(`annotations: routed delivery failed for ${record.id}: ${describeError(error)}`)
242
+ }
243
+ }
244
+ void store.maybeCompact().catch(() => {})
245
+ }
246
+
247
+ /**
248
+ * @param {any} client
249
+ * @param {any} frame
250
+ */
251
+ async function onQuery(client, frame) {
252
+ const url = typeof frame.url === 'string' ? frame.url : ''
253
+ const all = store.list({ status: 'all', limit: LIMITS.listLimit })
254
+ const records = url === '' ? all : all.filter((record) => sameDocument(record, url))
255
+ send(client, {
256
+ t: 'anno.query.ok',
257
+ reqId: frame.reqId,
258
+ records: records.map(toWire),
259
+ openCount: records.filter((record) => record.state === 'open').length,
260
+ })
261
+ }
262
+
263
+ /**
264
+ * @param {any} client
265
+ * @param {any} frame
266
+ */
267
+ async function onMutate(client, frame) {
268
+ const current = store.get(frame.id)
269
+ if (current === undefined) {
270
+ send(client, { t: 'error', code: 'not-found', message: `no annotation ${frame.id}` })
271
+ return
272
+ }
273
+ if (frame.action === 'delete') {
274
+ await store.delete(frame.id)
275
+ broadcastEvent('deleted', { ...current, id: frame.id }, store.seq)
276
+ send(client, { t: 'anno.ack', reqId: frame.reqId, id: frame.id, seq: store.seq, state: 'deleted' })
277
+ return
278
+ }
279
+ /** @type {Record<string, any>} */
280
+ const patch = { updatedAt: new Date().toISOString() }
281
+ switch (frame.action) {
282
+ case 'resolve':
283
+ patch.state = 'resolved'
284
+ patch.resolution = {
285
+ by: 'user',
286
+ note: typeof frame.note === 'string' ? frame.note : '',
287
+ resolvedAt: Date.now(),
288
+ }
289
+ break
290
+ case 'wont_fix':
291
+ patch.state = 'wont_fix'
292
+ patch.resolution = {
293
+ by: 'user',
294
+ note: typeof frame.note === 'string' ? frame.note : '',
295
+ resolvedAt: Date.now(),
296
+ }
297
+ break
298
+ case 'reopen':
299
+ patch.state = 'open'
300
+ patch.resolution = null
301
+ break
302
+ case 'edit':
303
+ patch.comment = String(frame.comment)
304
+ break
305
+ default:
306
+ break
307
+ }
308
+ const updated = await store.patch(frame.id, patch)
309
+ send(client, { t: 'anno.ack', reqId: frame.reqId, id: frame.id, seq: store.seq, state: updated?.state })
310
+ broadcastEvent('updated', updated, store.seq)
311
+ }
312
+
313
+ /** @param {any} frame */
314
+ function onPickResult(frame) {
315
+ const pending = picks.get(frame.pickId)
316
+ if (pending === undefined) {
317
+ log.debug(`annotations: ignoring stale pick ${frame.pickId}`)
318
+ return
319
+ }
320
+ clearTimeout(pending.timer)
321
+ picks.delete(frame.pickId)
322
+ if (frame.ok === true) pending.resolve({ ok: true, record: frame.record })
323
+ else pending.resolve({ ok: false, reason: typeof frame.reason === 'string' ? frame.reason : 'cancelled' })
324
+ }
325
+
326
+ /**
327
+ * Ask the browser for one annotation and wait for the answer.
328
+ * @param {{ mode?: string, prompt: string, timeoutMs?: number, sessionId?: string, signal?: AbortSignal }} request
329
+ * @returns {Promise<{ ok: true, record: any } | { ok: false, reason: string }>}
330
+ */
331
+ function requestPick({ mode, prompt, timeoutMs, sessionId, signal }) {
332
+ const authed = [...clients].filter((client) => client.authed)
333
+ if (authed.length === 0) {
334
+ return Promise.reject(new Error('no browser connected: open Firefox/Zen with the dsh-marker extension'))
335
+ }
336
+ if (signal?.aborted === true) return Promise.reject(new Error('cancelled'))
337
+ const pickId = newPickId()
338
+ const budget = Math.max(1_000, Math.min(Number(timeoutMs) || PICK_TIMEOUT_MS, 15 * 60_000))
339
+
340
+ return new Promise((resolve, reject) => {
341
+ const settle = (result) => {
342
+ cleanup()
343
+ resolve(result)
344
+ }
345
+ const fail = (error) => {
346
+ cleanup()
347
+ reject(error)
348
+ }
349
+ const timer = setTimeout(() => {
350
+ broadcast({ t: 'pick.cancel', pickId })
351
+ settle({ ok: false, reason: 'timeout' })
352
+ }, budget)
353
+ timer.unref?.()
354
+ const onAbort = () => {
355
+ broadcast({ t: 'pick.cancel', pickId })
356
+ fail(new Error('cancelled'))
357
+ }
358
+ const cleanup = () => {
359
+ // An abort settles the pick without going through `onPickResult`, so
360
+ // the deadline must be disarmed here or it fires later and broadcasts
361
+ // a second `pick.cancel` for a banner that is already gone.
362
+ clearTimeout(timer)
363
+ picks.delete(pickId)
364
+ signal?.removeEventListener('abort', onAbort)
365
+ }
366
+ picks.set(pickId, { resolve: settle, reject: fail, timer })
367
+ signal?.addEventListener('abort', onAbort, { once: true })
368
+ broadcast({
369
+ t: 'pick.request',
370
+ pickId,
371
+ mode: mode ?? 'auto',
372
+ prompt,
373
+ timeoutMs: budget,
374
+ sessionId: sessionId ?? '',
375
+ })
376
+ })
377
+ }
378
+
379
+ /** Cancel every pending pick (profile unload). */
380
+ function cancelAllPicks() {
381
+ for (const [pickId, pending] of picks) {
382
+ clearTimeout(pending.timer)
383
+ broadcast({ t: 'pick.cancel', pickId })
384
+ pending.resolve({ ok: false, reason: 'host shutting down' })
385
+ }
386
+ picks.clear()
387
+ }
388
+
389
+ /**
390
+ * Register the HTTP health route and the websocket upgrade route.
391
+ * @param {any} webServer
392
+ * @returns {() => void} disposer
393
+ */
394
+ function attach(webServer) {
395
+ // `noServer` keeps the HTTP layer owned by DSH: the upgrade route decides
396
+ // which requests become websockets, and `ws` only frames the connection.
397
+ const wss = new WebSocketServer({ noServer: true, maxPayload: LIMITS.imageBase64Chars })
398
+ wss.on('connection', onConnection)
399
+
400
+ const health = webServer.register({
401
+ kind: 'exact',
402
+ path: HEALTH_PATH,
403
+ auth: 'anonymous',
404
+ handler: (request, response) => {
405
+ // Scheme negotiation: the host says which URL works, the browser does
406
+ // not guess. `describeEndpoint` reads the serving socket, the listener
407
+ // configuration, and the forwarding headers a TLS proxy sets.
408
+ const endpoint = describeEndpoint({ request, webServer })
409
+ const body = JSON.stringify({
410
+ ok: true,
411
+ version: PROTOCOL_VERSION,
412
+ // The locator's `instanceId` must equal this one: it is how the
413
+ // extension drops a stale answer, or an origin another process has
414
+ // since taken over, instead of connecting to the wrong host.
415
+ instanceId: typeof instanceId === 'string' ? instanceId : null,
416
+ secure: endpoint.secure,
417
+ wsUrl: endpoint.wsUrl,
418
+ wsPath: WS_PATH,
419
+ openCount: store.count((record) => record.state === 'open'),
420
+ clients: [...clients].filter((client) => client.authed).length,
421
+ })
422
+ response.writeHead(200, {
423
+ 'content-type': 'application/json; charset=utf-8',
424
+ 'cache-control': 'no-store',
425
+ 'access-control-allow-origin': '*',
426
+ 'access-control-allow-headers': 'content-type',
427
+ })
428
+ response.end(request.method === 'HEAD' ? undefined : body)
429
+ },
430
+ })
431
+
432
+ // The upgrade route is scheme-independent on purpose: `handleUpgrade` only
433
+ // needs the raw socket, and on a TLS listener that socket is already the
434
+ // decrypted stream. Nothing here may read `x-forwarded-*` or the request's
435
+ // origin to decide whether to accept the connection — a proxy that
436
+ // terminates TLS is invisible to the handshake, and the token is the only
437
+ // admission check.
438
+ const upgrade = webServer.registerUpgrade({
439
+ path: WS_PATH,
440
+ auth: 'anonymous',
441
+ handler: (request, socket, head) => {
442
+ wss.handleUpgrade(request, socket, head, (connection) => {
443
+ wss.emit('connection', connection, request)
444
+ })
445
+ },
446
+ })
447
+
448
+ heartbeat = setInterval(() => {
449
+ for (const client of clients) {
450
+ if (!client.authed) continue
451
+ if (client.connection.isAlive === false) {
452
+ client.connection.terminate()
453
+ continue
454
+ }
455
+ client.connection.isAlive = false
456
+ client.connection.ping()
457
+ }
458
+ }, PING_INTERVAL_MS)
459
+ heartbeat.unref?.()
460
+
461
+ return () => {
462
+ clearInterval(heartbeat)
463
+ heartbeat = null
464
+ cancelAllPicks()
465
+ for (const client of clients) client.connection.close(1001, 'host shutting down')
466
+ clients.clear()
467
+ wss.close()
468
+ health()
469
+ upgrade()
470
+ }
471
+ }
472
+
473
+ return {
474
+ attach,
475
+ broadcast,
476
+ requestPick,
477
+ cancelAllPicks,
478
+ stats() {
479
+ return { clients: [...clients].filter((client) => client.authed).length, picks: picks.size }
480
+ },
481
+ }
482
+ }
483
+
484
+ /** @param {any} record */
485
+ function toWire(record) {
486
+ if (!record) return record
487
+ const { host: _host, ...wire } = record
488
+ return wire
489
+ }
490
+
491
+ /** @param {unknown} mime */
492
+ function imageMediaType(mime) {
493
+ return mime === 'image/jpeg' || mime === 'image/webp' ? mime : 'image/png'
494
+ }