dsh-aiterm 0.5.1 → 0.5.12
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/CONTRACTS.md +104 -22
- package/README.md +202 -26
- package/client/HistoryPanel.jsx +342 -29
- package/client/api.js +44 -3
- package/client/locale.js +40 -2
- package/cordis.patch.yml +1 -0
- package/lib/client.js +30 -30
- package/lib/host/autolog.js +107 -4
- package/lib/host/config.js +14 -0
- package/lib/host/disclosure.js +357 -0
- package/lib/host/exporter.js +447 -159
- package/lib/host/history-store.js +1735 -295
- package/lib/host/permission.js +13 -0
- package/lib/host/prompt.js +24 -4
- package/lib/host/registry.js +858 -76
- package/lib/host/routes.js +45 -2
- package/lib/host/tools.js +280 -22
- package/lib/index.js +2 -2
- package/package.json +2 -2
- package/scripts/smoke-client.mjs +193 -6
|
@@ -1,11 +1,38 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* On-disk terminal history (CONTRACTS.md §10).
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
* `
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
4
|
+
* Every call to {@link HistoryStore#openSession} reserves a **new** journal
|
|
5
|
+
* file with an exclusive create (`wx`) instead of appending to a file named
|
|
6
|
+
* after the logical session id:
|
|
7
|
+
*
|
|
8
|
+
* <dir>/<safe session id>~<random uuid>.ndjson
|
|
9
|
+
*
|
|
10
|
+
* Session ids are stable only inside one registry lifetime (`st-1` starts over
|
|
11
|
+
* after a plugin reload), so a name keyed by the id alone let a new session
|
|
12
|
+
* append its output to an older session's journal. The incarnation suffix is
|
|
13
|
+
* reserved atomically by the filesystem: two overlapping plugin instances, a
|
|
14
|
+
* reloaded instance and a still-pending flusher from the old instance all get
|
|
15
|
+
* different files, and no old journal is ever reopened for append.
|
|
16
|
+
*
|
|
17
|
+
* The journal itself carries its provenance as private NDJSON metadata lines:
|
|
18
|
+
*
|
|
19
|
+
* {"_aiterm":"journal","version":1,"id":"st-1","owner":"<dsh session id>",...}
|
|
20
|
+
* {"_aiterm":"close","version":1,"closedAt":...,"aiAccess":"wo",...}
|
|
21
|
+
*
|
|
22
|
+
* Owner and the AI permission at close time therefore survive a restart, a
|
|
23
|
+
* lost/corrupt `index.json`, and a last-writer-wins catalog race between two
|
|
24
|
+
* stores. A journal without a valid header, or a closed journal without valid
|
|
25
|
+
* close permission, is *unattributed* and fails closed for AI reads/exports.
|
|
26
|
+
*
|
|
27
|
+
* `index.json` is kept for one purpose only: describing **legacy** journals
|
|
28
|
+
* written by older versions, which have no provenance. Those files are never
|
|
29
|
+
* rewritten, never deleted by retention, and are never assigned an owner. The
|
|
30
|
+
* human legacy (no-owner) bucket can still read catalogued legacy history;
|
|
31
|
+
* AI reads and any named-owner read fail closed.
|
|
32
|
+
*
|
|
33
|
+
* Appends are buffered in memory and flushed on a timer or when the buffer
|
|
34
|
+
* grows past 64 KiB, so a chatty remote cannot turn terminal output into one
|
|
35
|
+
* filesystem call per packet.
|
|
9
36
|
*
|
|
10
37
|
* The store is a convenience layer, never a dependency: every disk error is
|
|
11
38
|
* logged and swallowed. A full disk or a read-only home directory must not break
|
|
@@ -15,15 +42,14 @@
|
|
|
15
42
|
* caller creates it through `init()`.
|
|
16
43
|
*/
|
|
17
44
|
|
|
18
|
-
import {
|
|
45
|
+
import { createHash, randomUUID } from 'node:crypto'
|
|
46
|
+
import { appendFile, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
|
|
19
47
|
import { join } from 'node:path'
|
|
20
48
|
|
|
21
|
-
import { boundInteger, ensureDir, readJsonIfPresent
|
|
49
|
+
import { boundInteger, ensureDir, readJsonIfPresent } from './util.js'
|
|
22
50
|
|
|
23
|
-
/**
|
|
51
|
+
/** Legacy catalog file name inside the history directory (read-only here). */
|
|
24
52
|
const INDEX_FILE = 'index.json'
|
|
25
|
-
/** Catalog format version written by this store. */
|
|
26
|
-
const CATALOG_VERSION = 1
|
|
27
53
|
/** Default retention window: 24 hours. */
|
|
28
54
|
const DEFAULT_RETENTION_MS = 24 * 60 * 60 * 1000
|
|
29
55
|
/** Default journal cap per session: 8 MiB. */
|
|
@@ -40,6 +66,28 @@ const DEFAULT_QUERY_MAX_BYTES = 8 * 1024 * 1024
|
|
|
40
66
|
const DEFAULT_MAX_MATCHES = 100
|
|
41
67
|
/** Sessions' worth of pre-open output buffered to cover the open/append race. */
|
|
42
68
|
const MAX_ORPHAN_SESSIONS = 32
|
|
69
|
+
/** Journal metadata marker discriminator. */
|
|
70
|
+
const META_MARKER = '_aiterm'
|
|
71
|
+
/** Journal metadata format version. */
|
|
72
|
+
const META_VERSION = 1
|
|
73
|
+
/** `open(..., 'wx')` collisions retried before giving up. */
|
|
74
|
+
const MAX_RESERVE_ATTEMPTS = 8
|
|
75
|
+
/** Largest journal header line accepted. */
|
|
76
|
+
const MAX_HEADER_BYTES = 16 * 1024
|
|
77
|
+
/** Bytes read from a journal tail when hydrating bookmarkkeeping fields. */
|
|
78
|
+
const TAIL_READ_BYTES = 64 * 1024
|
|
79
|
+
/** Separate an incarnation suffix from the safe session id. */
|
|
80
|
+
const INCARNATION_SEPARATOR = '~'
|
|
81
|
+
/** Directory holding one empty reservation file per allocated `st-N` id. */
|
|
82
|
+
const IDS_DIR = '.ids'
|
|
83
|
+
/** Minimum interval between opportunistic history-directory rescans. */
|
|
84
|
+
const SCAN_COOLDOWN_MS = 1000
|
|
85
|
+
/** Hard cap on one id-allocation walk (collisions should never reach this). */
|
|
86
|
+
const MAX_ID_ATTEMPTS = 100_000
|
|
87
|
+
/** Default bound for one session's unsaved buffered output. */
|
|
88
|
+
const DEFAULT_MAX_PENDING_BYTES = 1024 * 1024
|
|
89
|
+
/** Minimum delay between repeated write-failure/drop warnings. */
|
|
90
|
+
const FAILURE_LOG_INTERVAL_MS = 60_000
|
|
43
91
|
|
|
44
92
|
/**
|
|
45
93
|
* @typedef {object} CatalogEntry
|
|
@@ -56,6 +104,31 @@ const MAX_ORPHAN_SESSIONS = 32
|
|
|
56
104
|
* @property {number} lastTs timestamp of the newest output record.
|
|
57
105
|
*/
|
|
58
106
|
|
|
107
|
+
/**
|
|
108
|
+
* Private provenance record for one journal incarnation. The owner, close
|
|
109
|
+
* permission and journal path are deliberately absent from the public
|
|
110
|
+
* `CatalogEntry` shape and from every tool result.
|
|
111
|
+
*
|
|
112
|
+
* @typedef {object} Recording
|
|
113
|
+
* @property {string} id logical session id.
|
|
114
|
+
* @property {string} historyId stable opaque address for this incarnation.
|
|
115
|
+
* @property {string | null} owner owning DSH session id; `null` = ownerless.
|
|
116
|
+
* @property {string} journal absolute journal path.
|
|
117
|
+
* @property {string} title
|
|
118
|
+
* @property {'ssh' | 'telnet'} transport
|
|
119
|
+
* @property {string} host
|
|
120
|
+
* @property {number} port
|
|
121
|
+
* @property {string} username
|
|
122
|
+
* @property {number} createdAt
|
|
123
|
+
* @property {number} [closedAt]
|
|
124
|
+
* @property {'ro' | 'wo' | 'rw'} [aiAccess] AI permission recorded at close.
|
|
125
|
+
* @property {number} [truncatedAt]
|
|
126
|
+
* @property {number} bytes retained output bytes.
|
|
127
|
+
* @property {number} lastTs timestamp of the newest output record.
|
|
128
|
+
* @property {number} [mtime] filesystem modification time (epoch ms).
|
|
129
|
+
* @property {number} fileBytes current journal file size.
|
|
130
|
+
*/
|
|
131
|
+
|
|
59
132
|
/**
|
|
60
133
|
* @typedef {object} HistoryMatch
|
|
61
134
|
* @property {number} at epoch ms.
|
|
@@ -83,7 +156,7 @@ const MAX_ORPHAN_SESSIONS = 32
|
|
|
83
156
|
* @typedef {object} ActiveSession
|
|
84
157
|
* @property {string} id
|
|
85
158
|
* @property {string} file absolute journal path.
|
|
86
|
-
* @property {
|
|
159
|
+
* @property {Recording} entry provenance record (same object as in the map).
|
|
87
160
|
* @property {PendingRecord[]} pending buffered records not yet written.
|
|
88
161
|
* @property {number} pendingBytes buffered decoded bytes.
|
|
89
162
|
* @property {ReturnType<typeof setTimeout> | undefined} timer flush timer.
|
|
@@ -92,7 +165,8 @@ const MAX_ORPHAN_SESSIONS = 32
|
|
|
92
165
|
*/
|
|
93
166
|
|
|
94
167
|
/**
|
|
95
|
-
* Per-session journal store with
|
|
168
|
+
* Per-session journal store with an incarnation journal, provenance metadata
|
|
169
|
+
* and retention policy.
|
|
96
170
|
*/
|
|
97
171
|
export class HistoryStore {
|
|
98
172
|
/**
|
|
@@ -111,29 +185,60 @@ export class HistoryStore {
|
|
|
111
185
|
this.maxBytesPerSession = boundInteger(opts.maxBytesPerSession, DEFAULT_MAX_BYTES_PER_SESSION, 256, 512 * 1024 * 1024)
|
|
112
186
|
this.maxSessions = boundInteger(opts.maxSessions, DEFAULT_MAX_SESSIONS, 1, 10_000)
|
|
113
187
|
this.flushIntervalMs = boundInteger(opts.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS, 10, 60_000)
|
|
188
|
+
this.maxPendingBytes = boundInteger(opts.maxPendingBytes, DEFAULT_MAX_PENDING_BYTES, 1024, 64 * 1024 * 1024)
|
|
114
189
|
this.log = typeof opts.log === 'function' ? opts.log : () => {}
|
|
115
190
|
/** @type {Promise<void> | undefined} */
|
|
116
191
|
this.ready = undefined
|
|
117
|
-
/**
|
|
118
|
-
|
|
192
|
+
/**
|
|
193
|
+
* Attributed journals by absolute path. Provenance lives here (hydrated from
|
|
194
|
+
* each journal header), never in the shared index.
|
|
195
|
+
* @type {Map<string, Recording>}
|
|
196
|
+
*/
|
|
197
|
+
this.recordings = new Map()
|
|
198
|
+
/** @type {Map<string, Recording[]>} */
|
|
199
|
+
this.byId = new Map()
|
|
200
|
+
/** @type {Map<string, Recording>} stable incarnation address -> recording. */
|
|
201
|
+
this.byHistory = new Map()
|
|
202
|
+
/** Every id that must never be handed out again (journals or reservations). */
|
|
203
|
+
this.usedIds = new Set()
|
|
204
|
+
/** @type {number | undefined} next candidate for `st-N` allocation. */
|
|
205
|
+
this.idHint = undefined
|
|
206
|
+
/** Last full directory scan, used to throttle unknown-id lookups. */
|
|
207
|
+
this.lastScanAt = 0
|
|
208
|
+
/** Number of directory scans (diagnostics/tests). */
|
|
209
|
+
this.scanCount = 0
|
|
210
|
+
/**
|
|
211
|
+
* Legacy catalog entries from `index.json`, keyed by id. These files have no
|
|
212
|
+
* provenance; they are exposed only through the explicit human legacy bucket.
|
|
213
|
+
* @type {Map<string, CatalogEntry>}
|
|
214
|
+
*/
|
|
215
|
+
this.legacy = new Map()
|
|
119
216
|
/** @type {Map<string, ActiveSession>} */
|
|
120
217
|
this.active = new Map()
|
|
121
218
|
/**
|
|
122
219
|
* Output that arrived before `openSession()` finished. The registry opens
|
|
123
220
|
* the journal without awaiting it (a disk hiccup must not delay a connect),
|
|
124
221
|
* so the first banner bytes can race ahead of the registration; they are
|
|
125
|
-
* adopted when the session opens instead of being lost.
|
|
222
|
+
* adopted when the session opens instead of being lost. The key includes the
|
|
223
|
+
* owner so a failed open can never hand one owner's bytes to another.
|
|
126
224
|
* @type {Map<string, { records: PendingRecord[], bytes: number }>}
|
|
127
225
|
*/
|
|
128
226
|
this.orphans = new Map()
|
|
129
227
|
this.disposed = false
|
|
130
|
-
|
|
131
|
-
|
|
228
|
+
this.scanned = false
|
|
229
|
+
/** Async close operations that must finish before `dispose()` resolves. */
|
|
230
|
+
this.operations = new Set()
|
|
231
|
+
/** In-flight reservation/open operations, so a fast close can wait for one. */
|
|
232
|
+
this.openOps = new Set()
|
|
233
|
+
/** Close intents whose metadata append failed, keyed by historyId. */
|
|
234
|
+
this.pendingCloseRecords = new Map()
|
|
235
|
+
this.closeRetryTimer = undefined
|
|
236
|
+
this.closeRetryDelayMs = 0
|
|
132
237
|
}
|
|
133
238
|
|
|
134
239
|
/**
|
|
135
|
-
* Create the directory, load
|
|
136
|
-
* never throws.
|
|
240
|
+
* Create the directory, load legacy metadata and hydrate attributed journals.
|
|
241
|
+
* Idempotent and never throws.
|
|
137
242
|
* @returns {Promise<void>} completion.
|
|
138
243
|
*/
|
|
139
244
|
async init() {
|
|
@@ -145,82 +250,259 @@ export class HistoryStore {
|
|
|
145
250
|
}
|
|
146
251
|
try {
|
|
147
252
|
await ensureDir(this.dir)
|
|
253
|
+
await ensureDir(this.idsDirectory).catch(() => {})
|
|
148
254
|
} catch (error) {
|
|
149
255
|
this.warn('cannot create history directory', error)
|
|
150
256
|
}
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
const entry = normalizeEntry(raw)
|
|
155
|
-
if (entry !== undefined) this.catalog.set(entry.id, entry)
|
|
156
|
-
}
|
|
157
|
-
await this.prune(Date.now())
|
|
257
|
+
await this.loadLegacyCatalog()
|
|
258
|
+
await this.scan()
|
|
259
|
+
await this.pruneRecordings(Date.now())
|
|
158
260
|
})()
|
|
159
261
|
return this.ready
|
|
160
262
|
}
|
|
161
263
|
|
|
162
264
|
/**
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
*
|
|
265
|
+
* Allocate a globally unique `st-N` id that stays unique across restarts and
|
|
266
|
+
* concurrent Host instances.
|
|
267
|
+
*
|
|
268
|
+
* The directory is scanned only to pick a starting candidate; the reservation
|
|
269
|
+
* file is created with `open(..., 'wx')`, so two processes that race for the
|
|
270
|
+
* same candidate cannot both win. A candidate is also skipped when any
|
|
271
|
+
* journal (legacy or incarnation) already exists for it, because an id whose
|
|
272
|
+
* history predates reservations must keep its address.
|
|
273
|
+
* @returns {Promise<string | undefined>} the allocated id, or undefined when
|
|
274
|
+
* durable allocation is unavailable (the caller must then not open history
|
|
275
|
+
* for the session, so it can never collide with an old journal).
|
|
276
|
+
*/
|
|
277
|
+
async allocateSessionId(options = {}) {
|
|
278
|
+
await this.ensureReady()
|
|
279
|
+
if (this.dir.length === 0) return undefined
|
|
280
|
+
const isIdAvailable = typeof options.isIdAvailable === 'function' ? options.isIdAvailable : undefined
|
|
281
|
+
let used
|
|
282
|
+
try {
|
|
283
|
+
used = await this.collectUsedIdsForAllocation()
|
|
284
|
+
} catch (error) {
|
|
285
|
+
this.warn('cannot scan ids for allocation', error)
|
|
286
|
+
return undefined
|
|
287
|
+
}
|
|
288
|
+
this.usedIds = used
|
|
289
|
+
let max = 0
|
|
290
|
+
for (const id of used) {
|
|
291
|
+
const match = /^st-(\d+)$/.exec(id)
|
|
292
|
+
if (match === null) continue
|
|
293
|
+
const value = Number(match[1])
|
|
294
|
+
if (Number.isFinite(value) && value > max) max = value
|
|
295
|
+
}
|
|
296
|
+
// A stale in-memory hint is advanced by the fresh high-water mark; the
|
|
297
|
+
// candidate loop itself does no directory I/O except the atomic wx create.
|
|
298
|
+
this.idHint = Math.max(this.idHint ?? 0, max + 1)
|
|
299
|
+
for (let attempt = 0; attempt < MAX_ID_ATTEMPTS; attempt += 1) {
|
|
300
|
+
const id = `st-${this.idHint}`
|
|
301
|
+
this.idHint += 1
|
|
302
|
+
if (used.has(id)) continue
|
|
303
|
+
if (isIdAvailable !== undefined) {
|
|
304
|
+
let available
|
|
305
|
+
try {
|
|
306
|
+
available = await isIdAvailable(id)
|
|
307
|
+
} catch (error) {
|
|
308
|
+
this.warn(`cannot check id availability for ${id}`, error)
|
|
309
|
+
return undefined
|
|
310
|
+
}
|
|
311
|
+
if (!available) {
|
|
312
|
+
used.add(id)
|
|
313
|
+
continue
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
let handle
|
|
317
|
+
try {
|
|
318
|
+
handle = await open(join(this.idsDirectory, id), 'wx', 0o600)
|
|
319
|
+
} catch (error) {
|
|
320
|
+
if (error?.code === 'EEXIST') {
|
|
321
|
+
used.add(id)
|
|
322
|
+
continue
|
|
323
|
+
}
|
|
324
|
+
this.warn(`cannot reserve session id ${id}`, error)
|
|
325
|
+
return undefined
|
|
326
|
+
}
|
|
327
|
+
try {
|
|
328
|
+
await handle.writeFile(`${JSON.stringify({ id, reservedAt: Date.now() })}\n`, 'utf8')
|
|
329
|
+
await handle.sync()
|
|
330
|
+
} catch (error) {
|
|
331
|
+
this.warn(`cannot persist session id reservation ${id}`, error)
|
|
332
|
+
return undefined
|
|
333
|
+
} finally {
|
|
334
|
+
try {
|
|
335
|
+
await handle.close()
|
|
336
|
+
} catch {
|
|
337
|
+
// the reservation exists; a close failure is harmless
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
// One final check for an uncoordinated old writer that created a journal
|
|
341
|
+
// after the scan. Non-ENOENT directory errors fail allocation immediately
|
|
342
|
+
// instead of walking 100k candidates.
|
|
343
|
+
let exists
|
|
344
|
+
try {
|
|
345
|
+
exists = await this.journalFileExists(id)
|
|
346
|
+
} catch (error) {
|
|
347
|
+
this.warn('cannot verify the allocated journal id', error)
|
|
348
|
+
return undefined
|
|
349
|
+
}
|
|
350
|
+
if (exists) {
|
|
351
|
+
used.add(id)
|
|
352
|
+
continue
|
|
353
|
+
}
|
|
354
|
+
used.add(id)
|
|
355
|
+
return id
|
|
356
|
+
}
|
|
357
|
+
this.warn('cannot allocate a unique session id')
|
|
358
|
+
return undefined
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/**
|
|
362
|
+
* One scan to build the occupied-id set used by allocation. Values are taken
|
|
363
|
+
* from journal basenames (incarnation prefix / legacy stem) and `.ids`
|
|
364
|
+
* reservations; headers are not needed for `st-N` allocation.
|
|
365
|
+
* @returns {Promise<Set<string>>} used ids.
|
|
366
|
+
* @private
|
|
367
|
+
*/
|
|
368
|
+
async collectUsedIdsForAllocation() {
|
|
369
|
+
const used = new Set(this.usedIds)
|
|
370
|
+
let names
|
|
371
|
+
try {
|
|
372
|
+
names = await readdir(this.dir)
|
|
373
|
+
} catch (error) {
|
|
374
|
+
if (error?.code !== 'ENOENT') throw error
|
|
375
|
+
names = []
|
|
376
|
+
}
|
|
377
|
+
for (const name of names) {
|
|
378
|
+
if (!name.endsWith('.ndjson')) continue
|
|
379
|
+
if (isIncarnationName(name)) {
|
|
380
|
+
const marker = name.indexOf(INCARNATION_SEPARATOR)
|
|
381
|
+
if (marker > 0) used.add(name.slice(0, marker))
|
|
382
|
+
} else {
|
|
383
|
+
used.add(name.slice(0, -'.ndjson'.length))
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
let reservations
|
|
387
|
+
try {
|
|
388
|
+
reservations = await readdir(this.idsDirectory)
|
|
389
|
+
} catch (error) {
|
|
390
|
+
if (error?.code !== 'ENOENT') throw error
|
|
391
|
+
reservations = []
|
|
392
|
+
}
|
|
393
|
+
for (const name of reservations) used.add(name)
|
|
394
|
+
return used
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
/**
|
|
398
|
+
* Strict journal existence check for allocation (one readdir on success).
|
|
399
|
+
* @param {string} id session id.
|
|
400
|
+
* @returns {Promise<boolean>} true when a journal occupies the id.
|
|
401
|
+
* @private
|
|
402
|
+
*/
|
|
403
|
+
async journalFileExists(id) {
|
|
404
|
+
const safe = safeSessionFileName(id)
|
|
405
|
+
const names = await readdir(this.dir)
|
|
406
|
+
return names.some((name) => name === `${safe}.ndjson` || (name.startsWith(`${safe}${INCARNATION_SEPARATOR}`) && name.endsWith('.ndjson')))
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
/**
|
|
410
|
+
* @returns {string} reservation directory path.
|
|
411
|
+
*/
|
|
412
|
+
get idsDirectory() {
|
|
413
|
+
return this.dir.length > 0 ? join(this.dir, IDS_DIR) : ''
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
/**
|
|
417
|
+
* Register a new session incarnation and start buffering output.
|
|
418
|
+
*
|
|
419
|
+
* The journal is claimed with `open(file, 'wx')` before any byte is written:
|
|
420
|
+
* two stores, two processes or a reloaded plugin racing on the same logical id
|
|
421
|
+
* each get their own file. An existing journal is never reopened or appended.
|
|
422
|
+
* @param {{ id: string, owner?: string | null, title?: string, transport?: 'ssh' | 'telnet', host?: string, port?: number, username?: string, createdAt?: number }} meta session metadata.
|
|
423
|
+
* @returns {Promise<{ historyId: string, journal: string, fileBytes: number } | false>} the
|
|
424
|
+
* reserved incarnation handle, or `false` when no journal could be created.
|
|
166
425
|
*/
|
|
167
426
|
async openSession(meta) {
|
|
168
|
-
if (this.disposed) return
|
|
427
|
+
if (this.disposed) return false
|
|
428
|
+
const run = this.openInternal(meta)
|
|
429
|
+
this.openOps.add(run)
|
|
430
|
+
const forget = () => {
|
|
431
|
+
this.openOps.delete(run)
|
|
432
|
+
}
|
|
433
|
+
run.then(forget, forget)
|
|
434
|
+
return run
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
/**
|
|
438
|
+
* @param {{ id: string, owner?: string | null, title?: string, transport?: 'ssh' | 'telnet', host?: string, port?: number, username?: string, createdAt?: number }} meta session metadata.
|
|
439
|
+
* @returns {Promise<boolean>} whether a journal was reserved.
|
|
440
|
+
* @private
|
|
441
|
+
*/
|
|
442
|
+
async openInternal(meta) {
|
|
169
443
|
await this.ensureReady()
|
|
170
|
-
if (this.dir.length === 0) return
|
|
444
|
+
if (this.dir.length === 0) return false
|
|
171
445
|
const source = meta !== null && typeof meta === 'object' ? meta : {}
|
|
172
446
|
const id = typeof source.id === 'string' && source.id.length > 0 ? source.id : ''
|
|
173
447
|
if (id.length === 0) {
|
|
174
448
|
this.log('debug', '[aiterm] history: openSession without an id ignored')
|
|
175
|
-
return
|
|
449
|
+
return false
|
|
176
450
|
}
|
|
451
|
+
const owner = normalizeOwnerValue(source.owner)
|
|
177
452
|
const now = Date.now()
|
|
178
|
-
const previous = this.catalog.get(id)
|
|
179
453
|
const createdAt =
|
|
180
|
-
typeof source.createdAt === 'number' && Number.isFinite(source.createdAt)
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
const
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
454
|
+
typeof source.createdAt === 'number' && Number.isFinite(source.createdAt) ? Math.floor(source.createdAt) : now
|
|
455
|
+
// Retire a previous incarnation held by this store (same id) BEFORE
|
|
456
|
+
// reserving a new journal. A failed retire must not leave an orphan empty
|
|
457
|
+
// journal behind, and an unsaved older incarnation must stay writable.
|
|
458
|
+
const previous = this.active.get(id)
|
|
459
|
+
if (previous !== undefined) {
|
|
460
|
+
await this.writePending(previous)
|
|
461
|
+
if (previous.pending.length > 0 || previous.corrupt || previous.pendingClose !== undefined) {
|
|
462
|
+
this.warn(`cannot retire ${id} for a new incarnation: its bytes or close intent are still unsaved`)
|
|
463
|
+
return false
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
const reserved = await this.reserveJournal(id, owner, {
|
|
467
|
+
title: typeof source.title === 'string' && source.title.length > 0 ? source.title.slice(0, 120) : id,
|
|
190
468
|
transport: source.transport === 'telnet' ? 'telnet' : 'ssh',
|
|
191
|
-
host: typeof source.host === 'string' ? source.host.slice(0, 253) :
|
|
192
|
-
port: boundInteger(source.port,
|
|
193
|
-
username: typeof source.username === 'string' ? source.username.slice(0, 128) :
|
|
469
|
+
host: typeof source.host === 'string' ? source.host.slice(0, 253) : '',
|
|
470
|
+
port: boundInteger(source.port, 22, 1, 65_535),
|
|
471
|
+
username: typeof source.username === 'string' ? source.username.slice(0, 128) : '',
|
|
194
472
|
createdAt,
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
const file = this.fileFor(id)
|
|
201
|
-
let fileBytes = 0
|
|
202
|
-
try {
|
|
203
|
-
const info = await stat(file)
|
|
204
|
-
fileBytes = info.size
|
|
205
|
-
} catch (error) {
|
|
206
|
-
if (error?.code !== 'ENOENT') this.warn(`cannot stat ${file}`, error)
|
|
473
|
+
})
|
|
474
|
+
if (reserved === undefined) return false
|
|
475
|
+
if (previous !== undefined) {
|
|
476
|
+
if (previous.timer !== undefined) clearTimeout(previous.timer)
|
|
477
|
+
this.active.delete(id)
|
|
207
478
|
}
|
|
479
|
+
this.register(reserved)
|
|
480
|
+
|
|
208
481
|
/** @type {ActiveSession} */
|
|
209
482
|
const state = {
|
|
210
483
|
id,
|
|
211
|
-
file,
|
|
212
|
-
entry,
|
|
484
|
+
file: reserved.journal,
|
|
485
|
+
entry: reserved,
|
|
213
486
|
pending: [],
|
|
214
487
|
pendingBytes: 0,
|
|
215
488
|
timer: undefined,
|
|
216
489
|
chain: Promise.resolve(),
|
|
217
|
-
fileBytes,
|
|
490
|
+
fileBytes: reserved.fileBytes,
|
|
491
|
+
droppedBytes: 0,
|
|
492
|
+
writeFailures: 0,
|
|
493
|
+
retryDelayMs: 0,
|
|
494
|
+
degraded: false,
|
|
495
|
+
lastFailureLogAt: 0,
|
|
496
|
+
lastDropLogAt: 0,
|
|
497
|
+
pendingClose: undefined,
|
|
498
|
+
corrupt: false,
|
|
218
499
|
}
|
|
219
500
|
this.active.set(id, state)
|
|
220
501
|
// Adopt output that raced ahead of this open (first banner, fast telnet).
|
|
221
|
-
const
|
|
502
|
+
const orphanKey = orphanKeyFor(id, owner)
|
|
503
|
+
const orphan = this.orphans.get(orphanKey)
|
|
222
504
|
if (orphan !== undefined) {
|
|
223
|
-
this.orphans.delete(
|
|
505
|
+
this.orphans.delete(orphanKey)
|
|
224
506
|
if (orphan.records.length > 0) {
|
|
225
507
|
state.pending.push(...orphan.records)
|
|
226
508
|
state.pendingBytes += orphan.bytes
|
|
@@ -230,9 +512,8 @@ export class HistoryStore {
|
|
|
230
512
|
this.scheduleFlush(state, this.flushIntervalMs)
|
|
231
513
|
}
|
|
232
514
|
}
|
|
233
|
-
if (fileBytes >
|
|
234
|
-
|
|
235
|
-
if (fileBytes > this.maxBytesPerSession) await this.truncateSession(state)
|
|
515
|
+
if (reserved.fileBytes > this.maxBytesPerSession) await this.truncateSession(state)
|
|
516
|
+
return { historyId: reserved.historyId, journal: reserved.journal, fileBytes: reserved.fileBytes }
|
|
236
517
|
}
|
|
237
518
|
|
|
238
519
|
/**
|
|
@@ -242,9 +523,10 @@ export class HistoryStore {
|
|
|
242
523
|
* @param {string} sessionId session id.
|
|
243
524
|
* @param {string} text decoded output.
|
|
244
525
|
* @param {number} [at] epoch ms (default: now).
|
|
526
|
+
* @param {unknown} [owner] owning DSH session id (the registry always passes it).
|
|
245
527
|
* @returns {void}
|
|
246
528
|
*/
|
|
247
|
-
appendChunk(sessionId, text, at) {
|
|
529
|
+
appendChunk(sessionId, text, at, owner) {
|
|
248
530
|
if (this.disposed) return
|
|
249
531
|
if (typeof text !== 'string' || text.length === 0) return
|
|
250
532
|
let bytes
|
|
@@ -257,18 +539,86 @@ export class HistoryStore {
|
|
|
257
539
|
const timestamp = typeof at === 'number' && Number.isFinite(at) ? Math.floor(at) : Date.now()
|
|
258
540
|
/** @type {PendingRecord} */
|
|
259
541
|
const record = { t: timestamp, d: bytes.toString('base64'), size: bytes.length }
|
|
260
|
-
const
|
|
261
|
-
|
|
262
|
-
|
|
542
|
+
const id = typeof sessionId === 'string' ? sessionId : ''
|
|
543
|
+
const wanted = normalizeOwnerValue(owner)
|
|
544
|
+
const state = this.active.get(id)
|
|
545
|
+
if (state === undefined || state.entry.owner !== wanted) {
|
|
546
|
+
this.bufferOrphan(id, wanted, record)
|
|
547
|
+
return
|
|
548
|
+
}
|
|
549
|
+
if (state.corrupt) {
|
|
550
|
+
this.dropPending(state, record.size, 'journal is marked corrupt; writes are disabled')
|
|
551
|
+
return
|
|
552
|
+
}
|
|
553
|
+
if (record.size > this.maxPendingBytes) {
|
|
554
|
+
this.dropPending(state, record.size, 'single chunk exceeds the pending bound')
|
|
263
555
|
return
|
|
264
556
|
}
|
|
265
557
|
state.pending.push(record)
|
|
266
558
|
state.pendingBytes += bytes.length
|
|
267
559
|
if (timestamp > state.entry.lastTs) state.entry.lastTs = timestamp
|
|
268
|
-
|
|
560
|
+
this.trimPending(state)
|
|
561
|
+
if (state.degraded) this.scheduleFlush(state, Math.max(this.flushIntervalMs, state.retryDelayMs))
|
|
562
|
+
else if (state.pendingBytes >= FLUSH_THRESHOLD_BYTES) this.scheduleFlush(state, 0)
|
|
269
563
|
else this.scheduleFlush(state, this.flushIntervalMs)
|
|
270
564
|
}
|
|
271
565
|
|
|
566
|
+
/**
|
|
567
|
+
* Bound one session's unsaved buffer. Oldest unsaved records are dropped
|
|
568
|
+
* first so the newest terminal output survives; a single oversized chunk is
|
|
569
|
+
* dropped as a whole. This is explicit loss, never a zero-loss promise.
|
|
570
|
+
* @param {ActiveSession} state session state.
|
|
571
|
+
* @returns {void}
|
|
572
|
+
* @private
|
|
573
|
+
*/
|
|
574
|
+
trimPending(state) {
|
|
575
|
+
while (state.pendingBytes > this.maxPendingBytes && state.pending.length > 0) {
|
|
576
|
+
const removed = state.pending.shift()
|
|
577
|
+
if (removed === undefined) break
|
|
578
|
+
state.pendingBytes -= removed.size
|
|
579
|
+
this.dropPending(state, removed.size, 'pending bound reached')
|
|
580
|
+
}
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/**
|
|
584
|
+
* Account for dropped bytes and emit a throttled warning.
|
|
585
|
+
* @param {ActiveSession} state session state.
|
|
586
|
+
* @param {number} bytes dropped bytes.
|
|
587
|
+
* @param {string} reason fixed reason.
|
|
588
|
+
* @returns {void}
|
|
589
|
+
* @private
|
|
590
|
+
*/
|
|
591
|
+
dropPending(state, bytes, reason) {
|
|
592
|
+
state.droppedBytes += Math.max(0, bytes)
|
|
593
|
+
state.degraded = true
|
|
594
|
+
const now = Date.now()
|
|
595
|
+
if (now - state.lastDropLogAt >= FAILURE_LOG_INTERVAL_MS) {
|
|
596
|
+
state.lastDropLogAt = now
|
|
597
|
+
this.warn(`dropped ${state.droppedBytes} buffered byte(s) for ${state.id}: ${reason}`)
|
|
598
|
+
}
|
|
599
|
+
}
|
|
600
|
+
|
|
601
|
+
/**
|
|
602
|
+
* Diagnostics for tests/operators. Counts are cumulative; `degraded` means
|
|
603
|
+
* the session has lost buffered bytes or is currently failing appends.
|
|
604
|
+
* @param {string} sessionId session id.
|
|
605
|
+
* @returns {Promise<{ pendingBytes: number, droppedBytes: number, writeFailures: number, retryDelayMs: number, degraded: boolean } | undefined>} stats.
|
|
606
|
+
*/
|
|
607
|
+
async stats(sessionId) {
|
|
608
|
+
await this.ensureReady()
|
|
609
|
+
const state = this.active.get(typeof sessionId === 'string' ? sessionId : '')
|
|
610
|
+
if (state === undefined) return undefined
|
|
611
|
+
return {
|
|
612
|
+
pendingBytes: state.pendingBytes,
|
|
613
|
+
droppedBytes: state.droppedBytes,
|
|
614
|
+
writeFailures: state.writeFailures,
|
|
615
|
+
retryDelayMs: state.retryDelayMs,
|
|
616
|
+
degraded: state.degraded,
|
|
617
|
+
pendingClose: state.pendingClose !== undefined,
|
|
618
|
+
corrupt: state.corrupt === true,
|
|
619
|
+
}
|
|
620
|
+
}
|
|
621
|
+
|
|
272
622
|
/**
|
|
273
623
|
* Flush buffered records for one session (or every session).
|
|
274
624
|
* @param {string} [sessionId] session to flush; omit for all.
|
|
@@ -281,93 +631,928 @@ export class HistoryStore {
|
|
|
281
631
|
if (state !== undefined) await this.writePending(state)
|
|
282
632
|
return
|
|
283
633
|
}
|
|
284
|
-
await Promise.allSettled([...this.active.values()].map((state) => this.writePending(state)))
|
|
634
|
+
await Promise.allSettled([...this.active.values()].map((state) => this.writePending(state)))
|
|
635
|
+
}
|
|
636
|
+
|
|
637
|
+
/**
|
|
638
|
+
* Wait for buffered writes and pending close-metadata appends.
|
|
639
|
+
* @returns {Promise<void>} completion.
|
|
640
|
+
*/
|
|
641
|
+
async whenIdle() {
|
|
642
|
+
await this.ensureReady()
|
|
643
|
+
while (this.openOps.size > 0) await Promise.allSettled([...this.openOps])
|
|
644
|
+
await Promise.allSettled([...this.active.values()].map((state) => this.writePending(state)))
|
|
645
|
+
while (this.operations.size > 0) await Promise.allSettled([...this.operations])
|
|
646
|
+
await this.retryPendingCloses().catch(() => {})
|
|
647
|
+
await Promise.allSettled([...this.active.values()].map((state) => state.chain))
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
/**
|
|
651
|
+
* Flush and mark a session closed. The journal and metadata stay for
|
|
652
|
+
* `listRecordings` / `queryRecording`; only the owning incarnation is touched.
|
|
653
|
+
* @param {string} sessionId session id.
|
|
654
|
+
* @param {{ closedAt?: number, permission?: { aiAccess?: unknown }, owner?: unknown, historyId?: string }} [info] close details.
|
|
655
|
+
* @returns {Promise<void>} completion.
|
|
656
|
+
*/
|
|
657
|
+
async closeSession(sessionId, info) {
|
|
658
|
+
if (this.disposed) return
|
|
659
|
+
const run = this.closeInternal(sessionId, info)
|
|
660
|
+
this.operations.add(run)
|
|
661
|
+
const forget = () => {
|
|
662
|
+
this.operations.delete(run)
|
|
663
|
+
}
|
|
664
|
+
run.then(forget, forget)
|
|
665
|
+
return run
|
|
666
|
+
}
|
|
667
|
+
|
|
668
|
+
/**
|
|
669
|
+
* @param {string} sessionId session id.
|
|
670
|
+
* @param {{ closedAt?: number, permission?: { aiAccess?: unknown }, owner?: unknown }} [info] close details.
|
|
671
|
+
* @returns {Promise<void>} completion.
|
|
672
|
+
* @private
|
|
673
|
+
*/
|
|
674
|
+
async closeInternal(sessionId, info) {
|
|
675
|
+
await this.ensureReady()
|
|
676
|
+
// A close may race the fire-and-forget open from `create()` (the registry
|
|
677
|
+
// never blocks a connect on disk). Wait for in-flight reservations so the
|
|
678
|
+
// close metadata is appended to the same incarnation, never lost.
|
|
679
|
+
if (this.openOps.size > 0) await Promise.allSettled([...this.openOps])
|
|
680
|
+
const id = typeof sessionId === 'string' ? sessionId : ''
|
|
681
|
+
const details = info !== null && typeof info === 'object' ? info : {}
|
|
682
|
+
const ownerGiven = details.owner !== undefined
|
|
683
|
+
const wanted = ownerGiven ? normalizeOwnerValue(details.owner) : undefined
|
|
684
|
+
const address = typeof details.historyId === 'string' && details.historyId.length > 0 ? details.historyId : undefined
|
|
685
|
+
const closedAt =
|
|
686
|
+
typeof details.closedAt === 'number' && Number.isFinite(details.closedAt) ? Math.floor(details.closedAt) : Date.now()
|
|
687
|
+
const aiAccess = typeof details.permission?.aiAccess === 'string' && isAiAccess(details.permission.aiAccess)
|
|
688
|
+
? details.permission.aiAccess
|
|
689
|
+
: undefined
|
|
690
|
+
/** @type {{ id: string, owner: string | null, closedAt: number, aiAccess?: 'ro' | 'wo' | 'rw', historyId?: string }} */
|
|
691
|
+
const intent = {
|
|
692
|
+
id,
|
|
693
|
+
owner: ownerGiven ? wanted : null,
|
|
694
|
+
closedAt,
|
|
695
|
+
historyId: address,
|
|
696
|
+
ownerGiven,
|
|
697
|
+
}
|
|
698
|
+
if (aiAccess !== undefined) intent.aiAccess = aiAccess
|
|
699
|
+
this.dropOrphans(id, wanted)
|
|
700
|
+
|
|
701
|
+
const state = this.active.get(id)
|
|
702
|
+
// A close must target exactly the incarnation this store opened. When a
|
|
703
|
+
// reservation failed there is no active state: never guess another
|
|
704
|
+
// incarnation by id/owner, because stamping a permission onto a crashed
|
|
705
|
+
// journal would turn an unknown-permission file into an AI-readable one.
|
|
706
|
+
if (
|
|
707
|
+
state !== undefined &&
|
|
708
|
+
(!ownerGiven || state.entry.owner === wanted) &&
|
|
709
|
+
(address === undefined || state.entry.historyId === address)
|
|
710
|
+
) {
|
|
711
|
+
if (state.corrupt) {
|
|
712
|
+
this.warn(`refusing to close ${id}: its journal is marked corrupt`)
|
|
713
|
+
return
|
|
714
|
+
}
|
|
715
|
+
state.pendingClose = intent
|
|
716
|
+
await this.writePending(state)
|
|
717
|
+
// If the data flush is still incomplete the close stays pending; the same
|
|
718
|
+
// writer retries and appends the close metadata only after data succeeds.
|
|
719
|
+
if (state.pendingClose !== undefined) {
|
|
720
|
+
if (!this.disposed) this.scheduleFlush(state, Math.max(1000, state.retryDelayMs || 1000))
|
|
721
|
+
}
|
|
722
|
+
return
|
|
723
|
+
}
|
|
724
|
+
this.dropOrphans(id, wanted)
|
|
725
|
+
if (address !== undefined) {
|
|
726
|
+
const exact = this.byHistory.get(address)
|
|
727
|
+
if (exact !== undefined && exact.id === id && (!ownerGiven || exact.owner === wanted)) {
|
|
728
|
+
intent.historyId = exact.historyId
|
|
729
|
+
if (!(await this.appendCloseFor(exact, intent))) {
|
|
730
|
+
this.pendingCloseRecords.set(exact.historyId, intent)
|
|
731
|
+
this.scheduleCloseRetry()
|
|
732
|
+
}
|
|
733
|
+
}
|
|
734
|
+
}
|
|
735
|
+
}
|
|
736
|
+
|
|
737
|
+
/**
|
|
738
|
+
* Append close metadata for an exact recording; update in-memory permission
|
|
739
|
+
* only after the append succeeded. Never touches another incarnation.
|
|
740
|
+
* @param {Recording} recording recording.
|
|
741
|
+
* @param {{ closedAt: number, aiAccess?: 'ro' | 'wo' | 'rw', historyId?: string }} intent close intent.
|
|
742
|
+
* @returns {Promise<boolean>} whether the metadata was written.
|
|
743
|
+
* @private
|
|
744
|
+
*/
|
|
745
|
+
async appendCloseFor(recording, intent) {
|
|
746
|
+
if (recording === null || typeof recording !== 'object') return false
|
|
747
|
+
if (typeof intent.historyId === 'string' && recording.historyId !== intent.historyId) return false
|
|
748
|
+
/** @type {Record<string, unknown>} */
|
|
749
|
+
const meta = {
|
|
750
|
+
[META_MARKER]: 'close',
|
|
751
|
+
version: META_VERSION,
|
|
752
|
+
closedAt: intent.closedAt,
|
|
753
|
+
bytes: Math.max(0, Math.floor(recording.bytes)),
|
|
754
|
+
lastTs: Math.max(0, Math.floor(recording.lastTs)),
|
|
755
|
+
}
|
|
756
|
+
if (intent.aiAccess !== undefined) meta.aiAccess = intent.aiAccess
|
|
757
|
+
const line = `${JSON.stringify(meta)}\n`
|
|
758
|
+
try {
|
|
759
|
+
await this.appendCloseLine(recording.journal, line)
|
|
760
|
+
recording.fileBytes += Buffer.byteLength(line, 'utf8')
|
|
761
|
+
recording.closedAt = intent.closedAt
|
|
762
|
+
recording.mtime = Date.now()
|
|
763
|
+
if (intent.aiAccess !== undefined) recording.aiAccess = intent.aiAccess
|
|
764
|
+
return true
|
|
765
|
+
} catch (error) {
|
|
766
|
+
this.warn(`cannot append close metadata for ${recording.id}`, error)
|
|
767
|
+
return false
|
|
768
|
+
}
|
|
769
|
+
}
|
|
770
|
+
|
|
771
|
+
/**
|
|
772
|
+
* Low-level close metadata append (overridable in tests).
|
|
773
|
+
* @param {string} file journal path.
|
|
774
|
+
* @param {string} line encoded metadata line.
|
|
775
|
+
* @returns {Promise<void>} completion.
|
|
776
|
+
*/
|
|
777
|
+
async appendCloseLine(file, line) {
|
|
778
|
+
await appendFile(file, line, { mode: 0o600 })
|
|
779
|
+
}
|
|
780
|
+
|
|
781
|
+
/**
|
|
782
|
+
* Retry pending close metadata without touching any other incarnation.
|
|
783
|
+
* @returns {Promise<void>} completion.
|
|
784
|
+
* @private
|
|
785
|
+
*/
|
|
786
|
+
async retryPendingCloses() {
|
|
787
|
+
if (this.pendingCloseRecords.size === 0) return
|
|
788
|
+
for (const [historyId, intent] of [...this.pendingCloseRecords]) {
|
|
789
|
+
const recording = this.byHistory.get(historyId)
|
|
790
|
+
if (recording === undefined || recording.id !== intent.id) {
|
|
791
|
+
this.pendingCloseRecords.delete(historyId)
|
|
792
|
+
continue
|
|
793
|
+
}
|
|
794
|
+
if (intent.ownerGiven === true && recording.owner !== normalizeOwnerValue(intent.owner)) {
|
|
795
|
+
// recording identity is the key; owner is fixed at open and re-checked
|
|
796
|
+
// here so a stale intent cannot stamp a reused id.
|
|
797
|
+
this.pendingCloseRecords.delete(historyId)
|
|
798
|
+
continue
|
|
799
|
+
}
|
|
800
|
+
if (await this.appendCloseFor(recording, intent)) this.pendingCloseRecords.delete(historyId)
|
|
801
|
+
}
|
|
802
|
+
this.scheduleCloseRetry()
|
|
803
|
+
}
|
|
804
|
+
|
|
805
|
+
/**
|
|
806
|
+
* One bounded retry timer for close metadata.
|
|
807
|
+
* @returns {void}
|
|
808
|
+
* @private
|
|
809
|
+
*/
|
|
810
|
+
scheduleCloseRetry() {
|
|
811
|
+
if (this.disposed || this.pendingCloseRecords.size === 0 || this.closeRetryTimer !== undefined) return
|
|
812
|
+
this.closeRetryDelayMs = Math.min(60_000, Math.max(1000, (this.closeRetryDelayMs || 1000) * 2))
|
|
813
|
+
this.closeRetryTimer = setTimeout(() => {
|
|
814
|
+
this.closeRetryTimer = undefined
|
|
815
|
+
void this.retryPendingCloses()
|
|
816
|
+
}, this.closeRetryDelayMs)
|
|
817
|
+
if (typeof this.closeRetryTimer?.unref === 'function') this.closeRetryTimer.unref()
|
|
818
|
+
}
|
|
819
|
+
|
|
820
|
+
/**
|
|
821
|
+
* Attributed recordings (new journals with a valid provenance header).
|
|
822
|
+
* The returned objects carry private `owner`, `aiAccess` and `journal`
|
|
823
|
+
* fields: callers must map them to the public catalog shape before exposing
|
|
824
|
+
* them to tools or the browser.
|
|
825
|
+
* @param {{ limit?: number, since?: number, until?: number }} [query] filter.
|
|
826
|
+
* @returns {Promise<Recording[]>} recordings, newest activity first.
|
|
827
|
+
*/
|
|
828
|
+
async listRecordings(query = {}) {
|
|
829
|
+
const page = await this.listRecordingsPage(query)
|
|
830
|
+
return page.recordings
|
|
831
|
+
}
|
|
832
|
+
|
|
833
|
+
/**
|
|
834
|
+
* Paged attributed recordings with owner filtering applied **before** the
|
|
835
|
+
* limit, so another owner cannot crowd this owner's rows out and the total is
|
|
836
|
+
* truthful. `total` counts all matching rows; `truncated` means offset+shown
|
|
837
|
+
* is below it.
|
|
838
|
+
* @param {{ limit?: number, offset?: number, owner?: unknown, since?: number, until?: number }} [query] filter/paging.
|
|
839
|
+
* @returns {Promise<{ recordings: Recording[], total: number, truncated: boolean }>} page.
|
|
840
|
+
*/
|
|
841
|
+
async listRecordingsPage(query = {}) {
|
|
842
|
+
await this.ensureReady()
|
|
843
|
+
const options = query !== null && typeof query === 'object' ? query : {}
|
|
844
|
+
const limit = boundInteger(options.limit, 100, 1, 20_000)
|
|
845
|
+
const offset = boundInteger(options.offset, 0, 0, 100_000)
|
|
846
|
+
const since = typeof options.since === 'number' && Number.isFinite(options.since) ? options.since : -Infinity
|
|
847
|
+
const until = typeof options.until === 'number' && Number.isFinite(options.until) ? options.until : Infinity
|
|
848
|
+
const ownerFilter = options.owner !== undefined ? normalizeOwnerValue(options.owner) : undefined
|
|
849
|
+
const filtered = [...this.recordings.values()]
|
|
850
|
+
.filter((recording) => ownerFilter === undefined || recording.owner === ownerFilter)
|
|
851
|
+
.filter((recording) => activity(recording) >= since && recording.createdAt <= until)
|
|
852
|
+
.sort(newestFirst)
|
|
853
|
+
const page = filtered.slice(offset, offset + limit)
|
|
854
|
+
return {
|
|
855
|
+
recordings: page.map((recording) => ({ ...recording })),
|
|
856
|
+
total: filtered.length,
|
|
857
|
+
truncated: offset + page.length < filtered.length,
|
|
858
|
+
snapshot: pageSnapshot(filtered),
|
|
859
|
+
}
|
|
860
|
+
}
|
|
861
|
+
|
|
862
|
+
/**
|
|
863
|
+
* Paged legacy entries. The legacy catalog is normally small, but the same
|
|
864
|
+
* owner/limit discipline keeps recoverability explicit.
|
|
865
|
+
* @param {{ limit?: number, offset?: number, since?: number, until?: number }} [query] filter/paging.
|
|
866
|
+
* @returns {Promise<{ sessions: CatalogEntry[], total: number, truncated: boolean }>} page.
|
|
867
|
+
*/
|
|
868
|
+
async listLegacySessionsPage(query = {}) {
|
|
869
|
+
await this.ensureReady()
|
|
870
|
+
const options = query !== null && typeof query === 'object' ? query : {}
|
|
871
|
+
const limit = boundInteger(options.limit, 100, 1, 20_000)
|
|
872
|
+
const offset = boundInteger(options.offset, 0, 0, 100_000)
|
|
873
|
+
const since = typeof options.since === 'number' && Number.isFinite(options.since) ? options.since : -Infinity
|
|
874
|
+
const until = typeof options.until === 'number' && Number.isFinite(options.until) ? options.until : Infinity
|
|
875
|
+
const filtered = [...this.legacy.values()]
|
|
876
|
+
.filter((entry) => activity(entry) >= since && entry.createdAt <= until)
|
|
877
|
+
.sort(newestFirst)
|
|
878
|
+
const page = filtered.slice(offset, offset + limit)
|
|
879
|
+
return {
|
|
880
|
+
sessions: page.map((entry) => publicEntry(entry)),
|
|
881
|
+
total: filtered.length,
|
|
882
|
+
truncated: offset + page.length < filtered.length,
|
|
883
|
+
snapshot: pageSnapshot(filtered),
|
|
884
|
+
}
|
|
885
|
+
}
|
|
886
|
+
|
|
887
|
+
/**
|
|
888
|
+
* Legacy catalog entries (ownerless, from the old `index.json`).
|
|
889
|
+
* @param {{ limit?: number, since?: number, until?: number }} [query] filter.
|
|
890
|
+
* @returns {Promise<CatalogEntry[]>} legacy entries, newest activity first.
|
|
891
|
+
*/
|
|
892
|
+
async listLegacySessions(query = {}) {
|
|
893
|
+
const page = await this.listLegacySessionsPage(query)
|
|
894
|
+
return page.sessions
|
|
895
|
+
}
|
|
896
|
+
|
|
897
|
+
/**
|
|
898
|
+
* Catalogued legacy entry for one id, if any. The caller must enforce the
|
|
899
|
+
* human-only legacy policy; this method only answers what the old index says.
|
|
900
|
+
* @param {string} sessionId session id.
|
|
901
|
+
* @returns {Promise<CatalogEntry | undefined>} legacy entry.
|
|
902
|
+
*/
|
|
903
|
+
async legacyEntry(sessionId) {
|
|
904
|
+
await this.ensureReady()
|
|
905
|
+
return typeof sessionId === 'string' ? this.legacy.get(sessionId) : undefined
|
|
906
|
+
}
|
|
907
|
+
|
|
908
|
+
/**
|
|
909
|
+
* Exact legacy journal path for a catalogued legacy entry. Unlike
|
|
910
|
+
* `journalForSync`, this never resolves a new-format incarnation, so the
|
|
911
|
+
* explicit legacy view cannot accidentally export a different file.
|
|
912
|
+
* @param {string} sessionId session id.
|
|
913
|
+
* @returns {Promise<string | undefined>} legacy journal path.
|
|
914
|
+
*/
|
|
915
|
+
async legacyJournal(sessionId) {
|
|
916
|
+
await this.ensureReady()
|
|
917
|
+
return typeof sessionId === 'string' && this.legacy.has(sessionId) ? this.legacyFileFor(sessionId) : undefined
|
|
918
|
+
}
|
|
919
|
+
|
|
920
|
+
/**
|
|
921
|
+
* Resolve one exact incarnation by its opaque history address.
|
|
922
|
+
* @param {string} historyId incarnation address.
|
|
923
|
+
* @param {string | null} wanted normalized owner.
|
|
924
|
+
* @param {'human' | 'ai'} actor caller.
|
|
925
|
+
* @returns {Promise<{ kind: 'attributed', recording: Recording } | undefined>} resolution.
|
|
926
|
+
*/
|
|
927
|
+
async resolveByHistoryId(historyId, wanted, actor) {
|
|
928
|
+
if (typeof historyId !== 'string' || historyId.length === 0) return undefined
|
|
929
|
+
await this.ensureReady()
|
|
930
|
+
if (actor === 'ai' && wanted === null) return undefined
|
|
931
|
+
let recording = this.byHistory.get(historyId)
|
|
932
|
+
if (recording === undefined && this.scanned && Date.now() - this.lastScanAt >= SCAN_COOLDOWN_MS) {
|
|
933
|
+
await this.scan()
|
|
934
|
+
recording = this.byHistory.get(historyId)
|
|
935
|
+
}
|
|
936
|
+
if (recording === undefined || recording.owner !== wanted) return undefined
|
|
937
|
+
return { kind: 'attributed', recording }
|
|
938
|
+
}
|
|
939
|
+
|
|
940
|
+
/**
|
|
941
|
+
* Resolve one journal for a read by an owner-scoped caller.
|
|
942
|
+
*
|
|
943
|
+
* Attributed journals are matched by the owner recorded in the header; when
|
|
944
|
+
* several incarnations share a logical id, the newest one for that owner is
|
|
945
|
+
* used. Legacy journals are only resolvable by the explicit human legacy
|
|
946
|
+
* (owner `null`) bucket. Orphans are never resolvable.
|
|
947
|
+
* @param {string} sessionId session id.
|
|
948
|
+
* @param {unknown} owner requester owner (`null` = legacy bucket).
|
|
949
|
+
* @param {'human' | 'ai'} actor caller.
|
|
950
|
+
* @returns {Promise<{ kind: 'attributed', recording: Recording } | { kind: 'legacy', entry: CatalogEntry } | undefined>} resolution.
|
|
951
|
+
*/
|
|
952
|
+
async resolveForRead(sessionId, owner, actor, historyId) {
|
|
953
|
+
await this.ensureReady()
|
|
954
|
+
if (typeof sessionId !== 'string' || sessionId.length === 0) return undefined
|
|
955
|
+
const wanted = normalizeOwnerValue(owner)
|
|
956
|
+
if (typeof historyId === 'string' && historyId.length > 0) {
|
|
957
|
+
const resolved = await this.resolveByHistoryId(historyId, wanted, actor)
|
|
958
|
+
if (resolved === undefined) return undefined
|
|
959
|
+
if (resolved.recording.id !== sessionId) return undefined
|
|
960
|
+
return resolved
|
|
961
|
+
}
|
|
962
|
+
// An AI caller must never fall into the ownerless bucket, even if a caller
|
|
963
|
+
// forgets to check before reaching the store.
|
|
964
|
+
if (actor === 'ai' && wanted === null) return undefined
|
|
965
|
+
const list = await this.lookupRecordings(sessionId)
|
|
966
|
+
const owned = list.filter((recording) => recording.owner === wanted).sort(newestFirst)
|
|
967
|
+
if (owned.length > 0) return { kind: 'attributed', recording: owned[0] }
|
|
968
|
+
if (actor === 'human' && wanted === null) {
|
|
969
|
+
const entry = this.legacy.get(sessionId)
|
|
970
|
+
if (entry !== undefined) return { kind: 'legacy', entry }
|
|
971
|
+
}
|
|
972
|
+
return undefined
|
|
973
|
+
}
|
|
974
|
+
|
|
975
|
+
/**
|
|
976
|
+
* Current in-memory recording for an exact incarnation address.
|
|
977
|
+
*
|
|
978
|
+
* The returned object is live: a concurrent close may add `aiAccess`/
|
|
979
|
+
* `closedAt` after the caller looked. Callers that authorize before using it
|
|
980
|
+
* must re-check owner and permission at the point of use.
|
|
981
|
+
* @param {string} historyId opaque address.
|
|
982
|
+
* @returns {Recording | undefined} recording.
|
|
983
|
+
*/
|
|
984
|
+
recordingByHistoryIdSync(historyId) {
|
|
985
|
+
if (typeof historyId !== 'string' || historyId.length === 0) return undefined
|
|
986
|
+
return this.byHistory.get(historyId)
|
|
987
|
+
}
|
|
988
|
+
|
|
989
|
+
/**
|
|
990
|
+
* Whether the recorded closed permission lets the AI read this journal.
|
|
991
|
+
* An absent or unknown value fails closed.
|
|
992
|
+
* @param {Recording} recording recording.
|
|
993
|
+
* @returns {boolean} true only for `ro`/`rw`.
|
|
994
|
+
*/
|
|
995
|
+
canAiRead(recording) {
|
|
996
|
+
return recording !== null && typeof recording === 'object' && (recording.aiAccess === 'ro' || recording.aiAccess === 'rw')
|
|
997
|
+
}
|
|
998
|
+
|
|
999
|
+
/**
|
|
1000
|
+
* Synchronous journal lookup for the exporter. The caller has already
|
|
1001
|
+
* resolved/listed this id; this method re-checks owner and permission so a
|
|
1002
|
+
* facade cannot accidentally fall back to another owner's or a legacy file.
|
|
1003
|
+
* @param {string} sessionId session id.
|
|
1004
|
+
* @param {{ owner?: unknown, actor?: 'human' | 'ai' }} [options] requester.
|
|
1005
|
+
* @returns {string | undefined} absolute journal path.
|
|
1006
|
+
*/
|
|
1007
|
+
journalForSync(sessionId, options = {}) {
|
|
1008
|
+
const id = typeof sessionId === 'string' ? sessionId : ''
|
|
1009
|
+
if (id.length === 0) return undefined
|
|
1010
|
+
const wanted = normalizeOwnerValue(options.owner)
|
|
1011
|
+
const actor = options.actor === 'human' ? 'human' : 'ai'
|
|
1012
|
+
if (actor === 'ai' && wanted === null) return undefined
|
|
1013
|
+
const address = typeof options.historyId === 'string' && options.historyId.length > 0 ? options.historyId : undefined
|
|
1014
|
+
if (address !== undefined) {
|
|
1015
|
+
const exact = this.byHistory.get(address)
|
|
1016
|
+
if (exact === undefined || exact.id !== id || exact.owner !== wanted) return undefined
|
|
1017
|
+
if (actor === 'ai' && !this.canAiRead(exact)) return undefined
|
|
1018
|
+
return exact.journal
|
|
1019
|
+
}
|
|
1020
|
+
const state = this.active.get(id)
|
|
1021
|
+
if (state !== undefined && state.entry.owner === wanted) return state.file
|
|
1022
|
+
const owned = (this.byId.get(id) ?? []).filter((recording) => recording.owner === wanted).sort(newestFirst)
|
|
1023
|
+
if (owned.length > 0) {
|
|
1024
|
+
const recording = owned[0]
|
|
1025
|
+
if (actor === 'ai' && (wanted === null || !this.canAiRead(recording))) return undefined
|
|
1026
|
+
return recording.journal
|
|
1027
|
+
}
|
|
1028
|
+
if (actor === 'human' && wanted === null && this.legacy.has(id)) return this.legacyFileFor(id)
|
|
1029
|
+
return undefined
|
|
1030
|
+
}
|
|
1031
|
+
|
|
1032
|
+
/**
|
|
1033
|
+
* Journal path of the active incarnation for an id, if this store owns it.
|
|
1034
|
+
* @param {string} sessionId session id.
|
|
1035
|
+
* @returns {string | undefined} absolute journal path.
|
|
1036
|
+
*/
|
|
1037
|
+
activeJournal(sessionId, owner, historyId) {
|
|
1038
|
+
const state = this.active.get(typeof sessionId === 'string' ? sessionId : '')
|
|
1039
|
+
if (state === undefined) return undefined
|
|
1040
|
+
const wanted = normalizeOwnerValue(owner)
|
|
1041
|
+
if (state.entry.owner !== wanted) return undefined
|
|
1042
|
+
if (typeof historyId === 'string' && historyId.length > 0 && state.entry.historyId !== historyId) return undefined
|
|
1043
|
+
return state.file
|
|
1044
|
+
}
|
|
1045
|
+
|
|
1046
|
+
/**
|
|
1047
|
+
* Exact active-incarnation handle for a live session (owner-checked).
|
|
1048
|
+
* @param {string} sessionId session id.
|
|
1049
|
+
* @param {unknown} owner owner.
|
|
1050
|
+
* @param {string} [historyId] optional exact address.
|
|
1051
|
+
* @returns {{ historyId: string, journal: string } | undefined} handle.
|
|
1052
|
+
*/
|
|
1053
|
+
activeHandle(sessionId, owner, historyId) {
|
|
1054
|
+
const state = this.active.get(typeof sessionId === 'string' ? sessionId : '')
|
|
1055
|
+
if (state === undefined) return undefined
|
|
1056
|
+
const wanted = normalizeOwnerValue(owner)
|
|
1057
|
+
if (state.entry.owner !== wanted) return undefined
|
|
1058
|
+
if (typeof historyId === 'string' && historyId.length > 0 && state.entry.historyId !== historyId) return undefined
|
|
1059
|
+
return { historyId: state.entry.historyId, journal: state.file }
|
|
1060
|
+
}
|
|
1061
|
+
|
|
1062
|
+
/**
|
|
1063
|
+
* Search one attributed journal. Metadata lines carry no `t`/`d` pair and are
|
|
1064
|
+
* therefore ignored by the record parser.
|
|
1065
|
+
* @param {Recording} recording recording.
|
|
1066
|
+
* @param {{ since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} [query] query.
|
|
1067
|
+
* @returns {Promise<HistoryQueryResult>} matches and scan bookkeeping.
|
|
1068
|
+
*/
|
|
1069
|
+
async queryRecording(recording, query = {}) {
|
|
1070
|
+
await this.ensureReady()
|
|
1071
|
+
if (recording === null || typeof recording !== 'object' || typeof recording.journal !== 'string') {
|
|
1072
|
+
return { matches: [], scannedBytes: 0, truncated: false }
|
|
1073
|
+
}
|
|
1074
|
+
return this.searchJournal(recording.journal, publicEntry(recording), query)
|
|
1075
|
+
}
|
|
1076
|
+
|
|
1077
|
+
/**
|
|
1078
|
+
* Catalogued legacy entry for one id, if any. The caller must enforce the
|
|
1079
|
+
* human-only legacy policy; this method only answers what the old index says.
|
|
1080
|
+
* @param {string} sessionId session id.
|
|
1081
|
+
* @returns {Promise<CatalogEntry | undefined>} legacy entry.
|
|
1082
|
+
*/
|
|
1083
|
+
async legacyEntry(sessionId) {
|
|
1084
|
+
await this.ensureReady()
|
|
1085
|
+
return typeof sessionId === 'string' ? this.legacy.get(sessionId) : undefined
|
|
1086
|
+
}
|
|
1087
|
+
|
|
1088
|
+
/**
|
|
1089
|
+
* Exact legacy journal path for a catalogued legacy entry. Unlike
|
|
1090
|
+
* `journalForSync`, this never resolves a new-format incarnation, so the
|
|
1091
|
+
* explicit legacy view cannot accidentally export a different file.
|
|
1092
|
+
* @param {string} sessionId session id.
|
|
1093
|
+
* @returns {Promise<string | undefined>} legacy journal path.
|
|
1094
|
+
*/
|
|
1095
|
+
async legacyJournal(sessionId) {
|
|
1096
|
+
await this.ensureReady()
|
|
1097
|
+
return typeof sessionId === 'string' && this.legacy.has(sessionId) ? this.legacyFileFor(sessionId) : undefined
|
|
1098
|
+
}
|
|
1099
|
+
|
|
1100
|
+
/**
|
|
1101
|
+
* Search one catalogued legacy journal (human legacy bucket only).
|
|
1102
|
+
* @param {CatalogEntry} entry legacy entry.
|
|
1103
|
+
* @param {{ since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} [query] query.
|
|
1104
|
+
* @returns {Promise<HistoryQueryResult>} matches and scan bookkeeping.
|
|
1105
|
+
*/
|
|
1106
|
+
async queryLegacy(entry, query = {}) {
|
|
1107
|
+
await this.ensureReady()
|
|
1108
|
+
if (entry === null || typeof entry !== 'object' || typeof entry.id !== 'string') {
|
|
1109
|
+
return { matches: [], scannedBytes: 0, truncated: false }
|
|
1110
|
+
}
|
|
1111
|
+
return this.searchJournal(this.legacyFileFor(entry.id), publicEntry(entry), query)
|
|
1112
|
+
}
|
|
1113
|
+
|
|
1114
|
+
/**
|
|
1115
|
+
* Owner-scoped read convenience. Callers that need to distinguish
|
|
1116
|
+
* "not found" from "permission denied" use {@link resolveForRead} plus
|
|
1117
|
+
* {@link canAiRead} (the registry does that); this wrapper fails closed.
|
|
1118
|
+
* @param {{ sessionId?: string, owner?: unknown, actor?: 'human' | 'ai', since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} [query] query.
|
|
1119
|
+
* @returns {Promise<HistoryQueryResult>} matches and scan bookkeeping.
|
|
1120
|
+
*/
|
|
1121
|
+
async query(query = {}) {
|
|
1122
|
+
await this.ensureReady()
|
|
1123
|
+
const options = query !== null && typeof query === 'object' ? query : {}
|
|
1124
|
+
const actor = options.actor === 'human' ? 'human' : 'ai'
|
|
1125
|
+
const wanted = normalizeOwnerValue(options.owner)
|
|
1126
|
+
const resolved = await this.resolveForRead(
|
|
1127
|
+
typeof options.sessionId === 'string' ? options.sessionId : '',
|
|
1128
|
+
wanted,
|
|
1129
|
+
actor,
|
|
1130
|
+
)
|
|
1131
|
+
if (resolved === undefined) return { matches: [], scannedBytes: 0, truncated: false }
|
|
1132
|
+
if (resolved.kind === 'attributed') {
|
|
1133
|
+
if (actor === 'ai' && (wanted === null || !this.canAiRead(resolved.recording))) {
|
|
1134
|
+
return { matches: [], scannedBytes: 0, truncated: false }
|
|
1135
|
+
}
|
|
1136
|
+
return this.queryRecording(resolved.recording, options)
|
|
1137
|
+
}
|
|
1138
|
+
if (actor !== 'human' || wanted !== null) return { matches: [], scannedBytes: 0, truncated: false }
|
|
1139
|
+
return this.queryLegacy(resolved.entry, options)
|
|
1140
|
+
}
|
|
1141
|
+
|
|
1142
|
+
/**
|
|
1143
|
+
* Apply retention and the size cap to attributed journals. Legacy files are
|
|
1144
|
+
* never deleted or rewritten: they are exactly the data this migration must
|
|
1145
|
+
* preserve.
|
|
1146
|
+
* @param {number} [now] epoch ms (default: now).
|
|
1147
|
+
* @returns {Promise<void>} completion.
|
|
1148
|
+
*/
|
|
1149
|
+
async prune(now) {
|
|
1150
|
+
if (this.disposed) return
|
|
1151
|
+
await this.ensureReady()
|
|
1152
|
+
await this.pruneRecordings(now)
|
|
1153
|
+
}
|
|
1154
|
+
|
|
1155
|
+
/**
|
|
1156
|
+
* Flush everything, finish pending metadata appends and stop timers.
|
|
1157
|
+
* Idempotent; never throws.
|
|
1158
|
+
* @returns {Promise<void>} completion.
|
|
1159
|
+
*/
|
|
1160
|
+
async dispose() {
|
|
1161
|
+
if (this.disposed) return
|
|
1162
|
+
this.disposed = true
|
|
1163
|
+
// Let an open that started before shutdown finish first: it may still add a
|
|
1164
|
+
// writer that must be flushed, and it must never be left unflushed.
|
|
1165
|
+
while (this.openOps.size > 0) await Promise.allSettled([...this.openOps])
|
|
1166
|
+
const states = [...this.active.values()]
|
|
1167
|
+
for (const state of states) {
|
|
1168
|
+
if (state.timer !== undefined) {
|
|
1169
|
+
clearTimeout(state.timer)
|
|
1170
|
+
state.timer = undefined
|
|
1171
|
+
}
|
|
1172
|
+
}
|
|
1173
|
+
await Promise.allSettled(states.map((state) => this.writePending(state)))
|
|
1174
|
+
await this.retryPendingCloses().catch(() => {})
|
|
1175
|
+
if (this.closeRetryTimer !== undefined) {
|
|
1176
|
+
clearTimeout(this.closeRetryTimer)
|
|
1177
|
+
this.closeRetryTimer = undefined
|
|
1178
|
+
}
|
|
1179
|
+
this.active.clear()
|
|
1180
|
+
this.orphans.clear()
|
|
1181
|
+
while (this.operations.size > 0) await Promise.allSettled([...this.operations])
|
|
1182
|
+
}
|
|
1183
|
+
|
|
1184
|
+
/**
|
|
1185
|
+
* Legacy path for one id, used only for catalogued pre-upgrade journals.
|
|
1186
|
+
* @param {string} id session id.
|
|
1187
|
+
* @returns {string} journal path.
|
|
1188
|
+
*/
|
|
1189
|
+
legacyFileFor(id) {
|
|
1190
|
+
return join(this.dir, `${safeSessionFileName(id)}.ndjson`)
|
|
1191
|
+
}
|
|
1192
|
+
|
|
1193
|
+
/**
|
|
1194
|
+
* Compatibility alias: older callers used `fileFor` for the legacy path.
|
|
1195
|
+
* New code must use {@link journalForSync} or {@link activeJournal}.
|
|
1196
|
+
* @param {string} id session id.
|
|
1197
|
+
* @returns {string} legacy journal path.
|
|
1198
|
+
*/
|
|
1199
|
+
fileFor(id) {
|
|
1200
|
+
return this.legacyFileFor(id)
|
|
1201
|
+
}
|
|
1202
|
+
|
|
1203
|
+
/**
|
|
1204
|
+
* Await `init()`, running it on first use.
|
|
1205
|
+
* @returns {Promise<void>} completion.
|
|
1206
|
+
*/
|
|
1207
|
+
async ensureReady() {
|
|
1208
|
+
if (this.ready === undefined) await this.init()
|
|
1209
|
+
else await this.ready
|
|
1210
|
+
}
|
|
1211
|
+
|
|
1212
|
+
/**
|
|
1213
|
+
* Read the legacy catalog. Entries are treated as ownerless metadata only:
|
|
1214
|
+
* an `owner` field written by some other version is ignored, never trusted.
|
|
1215
|
+
* @returns {Promise<void>} completion.
|
|
1216
|
+
* @private
|
|
1217
|
+
*/
|
|
1218
|
+
async loadLegacyCatalog() {
|
|
1219
|
+
const index = await readJsonIfPresent(join(this.dir, INDEX_FILE))
|
|
1220
|
+
const entries = index !== null && typeof index === 'object' && Array.isArray(index.sessions) ? index.sessions : []
|
|
1221
|
+
for (const raw of entries) {
|
|
1222
|
+
const entry = normalizeEntry(raw)
|
|
1223
|
+
if (entry !== undefined) {
|
|
1224
|
+
this.legacy.set(entry.id, entry)
|
|
1225
|
+
this.usedIds.add(entry.id)
|
|
1226
|
+
}
|
|
1227
|
+
}
|
|
1228
|
+
}
|
|
1229
|
+
|
|
1230
|
+
/**
|
|
1231
|
+
* Discover attributed journals by reading their first line. The directory is
|
|
1232
|
+
* scanned for read/list purposes only; it is never used to decide an append
|
|
1233
|
+
* target (that is the exclusive-create reservation in `reserveJournal`).
|
|
1234
|
+
* @returns {Promise<void>} completion.
|
|
1235
|
+
* @private
|
|
1236
|
+
*/
|
|
1237
|
+
async scan() {
|
|
1238
|
+
if (this.dir.length === 0) return
|
|
1239
|
+
let names
|
|
1240
|
+
try {
|
|
1241
|
+
names = await readdir(this.dir)
|
|
1242
|
+
} catch (error) {
|
|
1243
|
+
if (error?.code !== 'ENOENT') this.warn('cannot scan history directory', error)
|
|
1244
|
+
this.scanned = true
|
|
1245
|
+
return
|
|
1246
|
+
}
|
|
1247
|
+
this.scanned = true
|
|
1248
|
+
this.scanCount += 1
|
|
1249
|
+
this.lastScanAt = Date.now()
|
|
1250
|
+
for (const name of names) {
|
|
1251
|
+
if (name.endsWith('.ndjson') && !isIncarnationName(name)) {
|
|
1252
|
+
// A legacy journal occupies its id even before/without an index entry.
|
|
1253
|
+
this.usedIds.add(name.slice(0, -'.ndjson'.length))
|
|
1254
|
+
continue
|
|
1255
|
+
}
|
|
1256
|
+
if (!isIncarnationName(name)) continue
|
|
1257
|
+
const file = join(this.dir, name)
|
|
1258
|
+
try {
|
|
1259
|
+
const recording = await this.readRecording(file)
|
|
1260
|
+
if (recording !== undefined) {
|
|
1261
|
+
this.usedIds.add(recording.id)
|
|
1262
|
+
this.register(recording)
|
|
1263
|
+
}
|
|
1264
|
+
} catch (error) {
|
|
1265
|
+
this.warn(`cannot hydrate history journal ${name}`, error)
|
|
1266
|
+
}
|
|
1267
|
+
}
|
|
1268
|
+
try {
|
|
1269
|
+
for (const name of await readdir(this.idsDirectory)) this.usedIds.add(name)
|
|
1270
|
+
} catch {
|
|
1271
|
+
// no reservation directory yet
|
|
1272
|
+
}
|
|
1273
|
+
}
|
|
1274
|
+
|
|
1275
|
+
/**
|
|
1276
|
+
* Read one incarnation's header, size and close metadata.
|
|
1277
|
+
* @param {string} file absolute path.
|
|
1278
|
+
* @returns {Promise<Recording | undefined>} recording or undefined when the
|
|
1279
|
+
* header is missing/malformed (the file is then left untouched and fails
|
|
1280
|
+
* closed for every owner-scoped caller).
|
|
1281
|
+
* @private
|
|
1282
|
+
*/
|
|
1283
|
+
async readRecording(file) {
|
|
1284
|
+
const headerLine = await readFirstLine(file)
|
|
1285
|
+
const meta = parseJournalHeader(headerLine)
|
|
1286
|
+
if (meta === undefined) return undefined
|
|
1287
|
+
let info
|
|
1288
|
+
try {
|
|
1289
|
+
info = await stat(file)
|
|
1290
|
+
} catch {
|
|
1291
|
+
return undefined
|
|
1292
|
+
}
|
|
1293
|
+
const tail = await readTailLines(file, info.size)
|
|
1294
|
+
let closedAt
|
|
1295
|
+
let aiAccess
|
|
1296
|
+
let closedBytes
|
|
1297
|
+
let lastTs = meta.createdAt
|
|
1298
|
+
for (const line of tail) {
|
|
1299
|
+
const parsed = parseJsonObject(line)
|
|
1300
|
+
if (parsed === undefined) continue
|
|
1301
|
+
if (parsed[META_MARKER] === 'close') {
|
|
1302
|
+
const candidate = finiteInteger(parsed.closedAt, undefined)
|
|
1303
|
+
if (candidate !== undefined) closedAt = candidate
|
|
1304
|
+
if (typeof parsed.aiAccess === 'string' && isAiAccess(parsed.aiAccess)) aiAccess = parsed.aiAccess
|
|
1305
|
+
const bytes = finiteInteger(parsed.bytes, undefined)
|
|
1306
|
+
if (bytes !== undefined && bytes >= 0) closedBytes = bytes
|
|
1307
|
+
const closedLast = finiteInteger(parsed.lastTs, undefined)
|
|
1308
|
+
if (closedLast !== undefined && closedLast > lastTs) lastTs = closedLast
|
|
1309
|
+
} else if (typeof parsed.t === 'number' && Number.isFinite(parsed.t) && parsed.t > lastTs) {
|
|
1310
|
+
lastTs = Math.floor(parsed.t)
|
|
1311
|
+
}
|
|
1312
|
+
}
|
|
1313
|
+
const headerBytes = Buffer.byteLength(headerLine, 'utf8') + 1
|
|
1314
|
+
/** @type {Recording} */
|
|
1315
|
+
const recording = {
|
|
1316
|
+
...meta,
|
|
1317
|
+
historyId: historyIdOf(file),
|
|
1318
|
+
journal: file,
|
|
1319
|
+
fileBytes: info.size,
|
|
1320
|
+
mtime: info.mtimeMs,
|
|
1321
|
+
bytes: closedBytes !== undefined ? closedBytes : Math.max(0, info.size - headerBytes),
|
|
1322
|
+
lastTs,
|
|
1323
|
+
}
|
|
1324
|
+
if (closedAt !== undefined) recording.closedAt = closedAt
|
|
1325
|
+
if (aiAccess !== undefined) recording.aiAccess = aiAccess
|
|
1326
|
+
return recording
|
|
1327
|
+
}
|
|
1328
|
+
|
|
1329
|
+
/**
|
|
1330
|
+
* Add/merge one hydrated recording without replacing an active in-memory
|
|
1331
|
+
* writer (which owns the freshest buffered state).
|
|
1332
|
+
* @param {Recording} recording recording.
|
|
1333
|
+
* @returns {void}
|
|
1334
|
+
* @private
|
|
1335
|
+
*/
|
|
1336
|
+
register(recording) {
|
|
1337
|
+
const existing = this.recordings.get(recording.journal)
|
|
1338
|
+
if (existing !== undefined) {
|
|
1339
|
+
const active = [...this.active.values()].some((state) => state.entry === existing)
|
|
1340
|
+
if (!active) Object.assign(existing, recording)
|
|
1341
|
+
return
|
|
1342
|
+
}
|
|
1343
|
+
this.recordings.set(recording.journal, recording)
|
|
1344
|
+
if (typeof recording.historyId === 'string' && recording.historyId.length > 0) {
|
|
1345
|
+
this.byHistory.set(recording.historyId, recording)
|
|
1346
|
+
}
|
|
1347
|
+
const list = this.byId.get(recording.id)
|
|
1348
|
+
if (list === undefined) this.byId.set(recording.id, [recording])
|
|
1349
|
+
else list.push(recording)
|
|
1350
|
+
}
|
|
1351
|
+
|
|
1352
|
+
/**
|
|
1353
|
+
* @param {string} sessionId session id.
|
|
1354
|
+
* @returns {Promise<Recording[]>} recordings for the id (rescans once on miss).
|
|
1355
|
+
* @private
|
|
1356
|
+
*/
|
|
1357
|
+
async lookupRecordings(sessionId) {
|
|
1358
|
+
let list = this.byId.get(sessionId)
|
|
1359
|
+
if (list === undefined && this.scanned && Date.now() - this.lastScanAt >= SCAN_COOLDOWN_MS) {
|
|
1360
|
+
await this.scan()
|
|
1361
|
+
list = this.byId.get(sessionId)
|
|
1362
|
+
}
|
|
1363
|
+
return list ?? []
|
|
1364
|
+
}
|
|
1365
|
+
|
|
1366
|
+
/**
|
|
1367
|
+
* Reserve a brand-new journal incarnation with an exclusive create.
|
|
1368
|
+
* @param {string} id session id.
|
|
1369
|
+
* @param {string | null} owner owner.
|
|
1370
|
+
* @param {{ title: string, transport: 'ssh' | 'telnet', host: string, port: number, username: string, createdAt: number }} meta metadata.
|
|
1371
|
+
* @returns {Promise<Recording | undefined>} the reserved recording.
|
|
1372
|
+
* @private
|
|
1373
|
+
*/
|
|
1374
|
+
async reserveJournal(id, owner, meta) {
|
|
1375
|
+
for (let attempt = 0; attempt < MAX_RESERVE_ATTEMPTS; attempt += 1) {
|
|
1376
|
+
const file = join(this.dir, `${safeSessionFileName(id)}${INCARNATION_SEPARATOR}${randomUUID()}.ndjson`)
|
|
1377
|
+
let handle
|
|
1378
|
+
try {
|
|
1379
|
+
handle = await open(file, 'wx', 0o600)
|
|
1380
|
+
} catch (error) {
|
|
1381
|
+
if (error?.code === 'EEXIST') continue
|
|
1382
|
+
this.warn(`cannot reserve history journal for ${id}`, error)
|
|
1383
|
+
return undefined
|
|
1384
|
+
}
|
|
1385
|
+
try {
|
|
1386
|
+
/** @type {Record<string, unknown>} */
|
|
1387
|
+
const header = {
|
|
1388
|
+
[META_MARKER]: 'journal',
|
|
1389
|
+
version: META_VERSION,
|
|
1390
|
+
id: id.slice(0, 128),
|
|
1391
|
+
owner,
|
|
1392
|
+
title: meta.title,
|
|
1393
|
+
transport: meta.transport,
|
|
1394
|
+
host: meta.host,
|
|
1395
|
+
port: meta.port,
|
|
1396
|
+
username: meta.username,
|
|
1397
|
+
createdAt: meta.createdAt,
|
|
1398
|
+
}
|
|
1399
|
+
await handle.writeFile(`${JSON.stringify(header)}\n`, 'utf8')
|
|
1400
|
+
await handle.sync()
|
|
1401
|
+
const info = await handle.stat()
|
|
1402
|
+
/** @type {Recording} */
|
|
1403
|
+
const recording = {
|
|
1404
|
+
id: id.slice(0, 128),
|
|
1405
|
+
historyId: historyIdOf(file),
|
|
1406
|
+
owner,
|
|
1407
|
+
journal: file,
|
|
1408
|
+
title: meta.title,
|
|
1409
|
+
transport: meta.transport,
|
|
1410
|
+
host: meta.host,
|
|
1411
|
+
port: meta.port,
|
|
1412
|
+
username: meta.username,
|
|
1413
|
+
createdAt: meta.createdAt,
|
|
1414
|
+
bytes: 0,
|
|
1415
|
+
lastTs: meta.createdAt,
|
|
1416
|
+
mtime: info.mtimeMs,
|
|
1417
|
+
fileBytes: info.size,
|
|
1418
|
+
}
|
|
1419
|
+
return recording
|
|
1420
|
+
} catch (error) {
|
|
1421
|
+
this.warn(`cannot initialize history journal for ${id}`, error)
|
|
1422
|
+
// Never leave a headerless/partial reservation that later looks like an
|
|
1423
|
+
// unclosed orphan on restart.
|
|
1424
|
+
try {
|
|
1425
|
+
await rm(file, { force: true })
|
|
1426
|
+
} catch {
|
|
1427
|
+
// best effort; the file has no valid header and stays fail-closed
|
|
1428
|
+
}
|
|
1429
|
+
return undefined
|
|
1430
|
+
} finally {
|
|
1431
|
+
try {
|
|
1432
|
+
await handle.close()
|
|
1433
|
+
} catch {
|
|
1434
|
+
// the reservation already exists; a close failure is harmless
|
|
1435
|
+
}
|
|
1436
|
+
}
|
|
1437
|
+
}
|
|
1438
|
+
this.warn(`cannot reserve a unique history journal for ${id} after ${MAX_RESERVE_ATTEMPTS} attempts`)
|
|
1439
|
+
return undefined
|
|
1440
|
+
}
|
|
1441
|
+
|
|
1442
|
+
/**
|
|
1443
|
+
* Apply retention/cap internally (no `ensureReady`, so `init()` can call it).
|
|
1444
|
+
* @param {number} [now] epoch ms.
|
|
1445
|
+
* @returns {Promise<void>} completion.
|
|
1446
|
+
* @private
|
|
1447
|
+
*/
|
|
1448
|
+
async pruneRecordings(now) {
|
|
1449
|
+
const at = typeof now === 'number' && Number.isFinite(now) ? now : Date.now()
|
|
1450
|
+
const cutoff = at - this.retentionMs
|
|
1451
|
+
const activeJournals = new Set([...this.active.values()].map((state) => state.entry.journal))
|
|
1452
|
+
const all = [...this.recordings.values()].sort(newestFirst)
|
|
1453
|
+
let preservedOpen = 0
|
|
1454
|
+
for (const recording of all) {
|
|
1455
|
+
if (activeJournals.has(recording.journal)) continue
|
|
1456
|
+
// Without a cross-process lease we cannot prove that an unclosed journal
|
|
1457
|
+
// has no live writer elsewhere. Preserve it: deleting a live file is worse
|
|
1458
|
+
// than retaining a crashed incarnation until a human/retention decision.
|
|
1459
|
+
if (recording.closedAt === undefined) {
|
|
1460
|
+
preservedOpen += 1
|
|
1461
|
+
continue
|
|
1462
|
+
}
|
|
1463
|
+
let diskMtime = 0
|
|
1464
|
+
try {
|
|
1465
|
+
diskMtime = (await stat(recording.journal)).mtimeMs
|
|
1466
|
+
recording.mtime = diskMtime
|
|
1467
|
+
} catch {
|
|
1468
|
+
diskMtime = typeof recording.mtime === 'number' ? recording.mtime : 0
|
|
1469
|
+
}
|
|
1470
|
+
if (Math.max(retentionActivity(recording), diskMtime) < cutoff) await this.removeRecording(recording)
|
|
1471
|
+
}
|
|
1472
|
+
const remaining = [...this.recordings.values()]
|
|
1473
|
+
.filter((recording) => !activeJournals.has(recording.journal) && recording.closedAt !== undefined)
|
|
1474
|
+
// Refresh mtime before ordering: a recent external write must protect a
|
|
1475
|
+
// journal even when its last output timestamp is old.
|
|
1476
|
+
for (const recording of remaining) {
|
|
1477
|
+
try {
|
|
1478
|
+
recording.mtime = (await stat(recording.journal)).mtimeMs
|
|
1479
|
+
} catch {
|
|
1480
|
+
// keep the last known mtime
|
|
1481
|
+
}
|
|
1482
|
+
}
|
|
1483
|
+
remaining.sort((left, right) => retentionActivity(right) - retentionActivity(left))
|
|
1484
|
+
if (remaining.length > this.maxSessions) {
|
|
1485
|
+
for (const recording of remaining.slice(this.maxSessions)) await this.removeRecording(recording)
|
|
1486
|
+
}
|
|
1487
|
+
if (preservedOpen > 0) {
|
|
1488
|
+
this.warn(`preserved ${preservedOpen} unclosed journal(s) because no cross-process activity lease is available`)
|
|
1489
|
+
}
|
|
285
1490
|
}
|
|
286
1491
|
|
|
287
1492
|
/**
|
|
288
|
-
*
|
|
289
|
-
*
|
|
290
|
-
* @param {string} sessionId session id.
|
|
291
|
-
* @param {{ closedAt?: number }} [info] close details.
|
|
1493
|
+
* Delete one attributed journal (retention/cap only; legacy is untouched).
|
|
1494
|
+
* @param {Recording} recording recording.
|
|
292
1495
|
* @returns {Promise<void>} completion.
|
|
1496
|
+
* @private
|
|
293
1497
|
*/
|
|
294
|
-
async
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
const
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
}
|
|
305
|
-
|
|
1498
|
+
async removeRecording(recording) {
|
|
1499
|
+
this.recordings.delete(recording.journal)
|
|
1500
|
+
if (typeof recording.historyId === 'string') this.byHistory.delete(recording.historyId)
|
|
1501
|
+
const list = this.byId.get(recording.id)
|
|
1502
|
+
if (list !== undefined) {
|
|
1503
|
+
const next = list.filter((entry) => entry !== recording)
|
|
1504
|
+
if (next.length === 0) this.byId.delete(recording.id)
|
|
1505
|
+
else this.byId.set(recording.id, next)
|
|
1506
|
+
}
|
|
1507
|
+
try {
|
|
1508
|
+
await rm(recording.journal, { force: true })
|
|
1509
|
+
} catch (error) {
|
|
1510
|
+
this.warn(`cannot remove history for ${recording.id}`, error)
|
|
306
1511
|
}
|
|
307
|
-
this.orphans.delete(id)
|
|
308
|
-
const entry = this.catalog.get(id)
|
|
309
|
-
if (entry === undefined) return
|
|
310
|
-
const closedAt = info !== null && typeof info === 'object' && typeof info.closedAt === 'number' && Number.isFinite(info.closedAt)
|
|
311
|
-
? Math.floor(info.closedAt)
|
|
312
|
-
: Date.now()
|
|
313
|
-
entry.closedAt = closedAt
|
|
314
|
-
await this.saveIndex()
|
|
315
|
-
}
|
|
316
|
-
|
|
317
|
-
/**
|
|
318
|
-
* Catalog listing, newest activity first.
|
|
319
|
-
* @param {{ limit?: number, since?: number, until?: number }} [query] filter.
|
|
320
|
-
* @returns {Promise<CatalogEntry[]>} catalog entries (copies).
|
|
321
|
-
*/
|
|
322
|
-
async listSessions(query = {}) {
|
|
323
|
-
await this.ensureReady()
|
|
324
|
-
const options = query !== null && typeof query === 'object' ? query : {}
|
|
325
|
-
const limit = boundInteger(options.limit, 100, 1, 1000)
|
|
326
|
-
const since = typeof options.since === 'number' && Number.isFinite(options.since) ? options.since : -Infinity
|
|
327
|
-
const until = typeof options.until === 'number' && Number.isFinite(options.until) ? options.until : Infinity
|
|
328
|
-
const entries = [...this.catalog.values()].filter((entry) => {
|
|
329
|
-
const last = typeof entry.lastTs === 'number' ? entry.lastTs : entry.createdAt
|
|
330
|
-
return last >= since && entry.createdAt <= until
|
|
331
|
-
})
|
|
332
|
-
entries.sort((left, right) => activity(right) - activity(left))
|
|
333
|
-
return entries.slice(0, limit).map((entry) => publicEntry(entry))
|
|
334
1512
|
}
|
|
335
1513
|
|
|
336
1514
|
/**
|
|
337
|
-
*
|
|
338
|
-
*
|
|
339
|
-
*
|
|
340
|
-
*
|
|
341
|
-
* partially written NDJSON lines are skipped rather than failing the query.
|
|
342
|
-
* Without `search`, the most recent `maxMatches` lines are returned.
|
|
343
|
-
* @param {{ sessionId?: string, since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} query query.
|
|
1515
|
+
* Run the journal-tail search shared by attributed and legacy reads.
|
|
1516
|
+
* @param {string} file journal path.
|
|
1517
|
+
* @param {CatalogEntry} entry public entry.
|
|
1518
|
+
* @param {{ since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} [query] query.
|
|
344
1519
|
* @returns {Promise<HistoryQueryResult>} matches and scan bookkeeping.
|
|
1520
|
+
* @private
|
|
345
1521
|
*/
|
|
346
|
-
async
|
|
347
|
-
await this.ensureReady()
|
|
1522
|
+
async searchJournal(file, entry, query = {}) {
|
|
348
1523
|
const options = query !== null && typeof query === 'object' ? query : {}
|
|
349
|
-
const sessionId = typeof options.sessionId === 'string' ? options.sessionId : ''
|
|
350
1524
|
/** @type {HistoryQueryResult} */
|
|
351
1525
|
const result = { matches: [], scannedBytes: 0, truncated: false }
|
|
352
1526
|
if (this.dir.length === 0) return result
|
|
353
|
-
const
|
|
354
|
-
// A live session may still hold buffered bytes: flush so the query sees them.
|
|
355
|
-
if (this.active.has(sessionId)) await this.flush(sessionId)
|
|
356
|
-
const file = this.fileFor(sessionId)
|
|
1527
|
+
const maxBytes = boundInteger(options.maxBytes, DEFAULT_QUERY_MAX_BYTES, 256, 256 * 1024 * 1024)
|
|
357
1528
|
let buffer
|
|
358
1529
|
try {
|
|
359
|
-
|
|
1530
|
+
const info = await stat(file)
|
|
1531
|
+
const start = info.size > maxBytes ? info.size - maxBytes : 0
|
|
1532
|
+
const length = info.size - start
|
|
1533
|
+
if (info.size > maxBytes) result.truncated = true
|
|
1534
|
+
const handle = await open(file, 'r')
|
|
1535
|
+
try {
|
|
1536
|
+
const allocated = Buffer.allocUnsafe(length)
|
|
1537
|
+
let offset = 0
|
|
1538
|
+
while (offset < length) {
|
|
1539
|
+
const { bytesRead } = await handle.read(allocated, offset, length - offset, start + offset)
|
|
1540
|
+
if (bytesRead === 0) break
|
|
1541
|
+
offset += bytesRead
|
|
1542
|
+
}
|
|
1543
|
+
buffer = allocated.subarray(0, offset)
|
|
1544
|
+
} finally {
|
|
1545
|
+
await handle.close()
|
|
1546
|
+
}
|
|
360
1547
|
} catch (error) {
|
|
361
|
-
if (error?.code !== 'ENOENT') this.warn(`cannot read history for ${
|
|
1548
|
+
if (error?.code !== 'ENOENT') this.warn(`cannot read history for ${entry?.id ?? 'unknown session'}`, error)
|
|
362
1549
|
return withEntry(result, entry)
|
|
363
1550
|
}
|
|
364
1551
|
|
|
365
|
-
const maxBytes = boundInteger(options.maxBytes, DEFAULT_QUERY_MAX_BYTES, 256, 256 * 1024 * 1024)
|
|
366
1552
|
let scanStart = 0
|
|
367
|
-
if (
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
const newline = buffer.indexOf(0x0a, scanStart)
|
|
1553
|
+
if (result.truncated === true) {
|
|
1554
|
+
// `buffer` starts at the tail cut; discard a partial first line.
|
|
1555
|
+
const newline = buffer.indexOf(0x0a)
|
|
371
1556
|
scanStart = newline === -1 ? buffer.length : newline + 1
|
|
372
1557
|
}
|
|
373
1558
|
const scanBuffer = buffer.subarray(scanStart)
|
|
@@ -419,7 +1604,6 @@ export class HistoryStore {
|
|
|
419
1604
|
} else {
|
|
420
1605
|
/** @type {HistoryMatch[]} */
|
|
421
1606
|
const pendingAfter = []
|
|
422
|
-
let stopped = false
|
|
423
1607
|
for (let index = 0; index < records.length; index += 1) {
|
|
424
1608
|
const record = records[index]
|
|
425
1609
|
for (const match of pendingAfter) {
|
|
@@ -432,12 +1616,11 @@ export class HistoryStore {
|
|
|
432
1616
|
if (!pattern.test(record.text)) continue
|
|
433
1617
|
if (matches.length >= maxMatches) {
|
|
434
1618
|
result.truncated = true
|
|
435
|
-
stopped = true
|
|
436
1619
|
break
|
|
437
1620
|
}
|
|
438
1621
|
/** @type {HistoryMatch} */
|
|
439
1622
|
const match = {
|
|
440
|
-
at: timestampAt(boundaries,
|
|
1623
|
+
at: timestampAt(boundaries, records[index].offset),
|
|
441
1624
|
line: record.text,
|
|
442
1625
|
before: [],
|
|
443
1626
|
after: [],
|
|
@@ -446,106 +1629,31 @@ export class HistoryStore {
|
|
|
446
1629
|
matches.push(match)
|
|
447
1630
|
if (context > 0) pendingAfter.push(match)
|
|
448
1631
|
}
|
|
449
|
-
if (stopped) {
|
|
450
|
-
// Nothing extra to report beyond the truncation flag already set.
|
|
451
|
-
}
|
|
452
1632
|
}
|
|
453
1633
|
|
|
454
1634
|
result.matches = matches
|
|
455
1635
|
return withEntry(result, entry)
|
|
456
1636
|
}
|
|
457
1637
|
|
|
458
|
-
/**
|
|
459
|
-
* Apply retention and the catalog size cap, deleting both catalog entries and
|
|
460
|
-
* journal files. Safe to call at any time.
|
|
461
|
-
* @param {number} [now] epoch ms (default: now).
|
|
462
|
-
* @returns {Promise<void>} completion.
|
|
463
|
-
*/
|
|
464
|
-
async prune(now) {
|
|
465
|
-
if (this.disposed) return
|
|
466
|
-
const at = typeof now === 'number' && Number.isFinite(now) ? now : Date.now()
|
|
467
|
-
const cutoff = at - this.retentionMs
|
|
468
|
-
let changed = false
|
|
469
|
-
for (const [id, entry] of [...this.catalog]) {
|
|
470
|
-
// A live session is not retention-pruned: its writer still owns the file.
|
|
471
|
-
if (this.active.has(id)) continue
|
|
472
|
-
const last = typeof entry.lastTs === 'number' ? entry.lastTs : entry.createdAt
|
|
473
|
-
if (last < cutoff) {
|
|
474
|
-
this.catalog.delete(id)
|
|
475
|
-
this.orphans.delete(id)
|
|
476
|
-
changed = true
|
|
477
|
-
await this.removeFile(id)
|
|
478
|
-
}
|
|
479
|
-
}
|
|
480
|
-
if (this.catalog.size > this.maxSessions) {
|
|
481
|
-
const sorted = [...this.catalog.values()].sort((left, right) => activity(right) - activity(left))
|
|
482
|
-
for (const entry of sorted.slice(this.maxSessions)) {
|
|
483
|
-
this.catalog.delete(entry.id)
|
|
484
|
-
this.discardState(entry.id)
|
|
485
|
-
this.orphans.delete(entry.id)
|
|
486
|
-
changed = true
|
|
487
|
-
await this.removeFile(entry.id)
|
|
488
|
-
}
|
|
489
|
-
}
|
|
490
|
-
if (changed) await this.saveIndex()
|
|
491
|
-
}
|
|
492
|
-
|
|
493
|
-
/**
|
|
494
|
-
* Flush everything and stop timers. Idempotent; never throws.
|
|
495
|
-
* @returns {Promise<void>} completion.
|
|
496
|
-
*/
|
|
497
|
-
async dispose() {
|
|
498
|
-
if (this.disposed) return
|
|
499
|
-
this.disposed = true
|
|
500
|
-
const states = [...this.active.values()]
|
|
501
|
-
for (const state of states) {
|
|
502
|
-
if (state.timer !== undefined) {
|
|
503
|
-
clearTimeout(state.timer)
|
|
504
|
-
state.timer = undefined
|
|
505
|
-
}
|
|
506
|
-
}
|
|
507
|
-
await Promise.allSettled(states.map((state) => this.writePending(state)))
|
|
508
|
-
this.active.clear()
|
|
509
|
-
this.orphans.clear()
|
|
510
|
-
await this.saveIndex()
|
|
511
|
-
}
|
|
512
|
-
|
|
513
|
-
/**
|
|
514
|
-
* @param {string} id session id.
|
|
515
|
-
* @returns {string} journal path.
|
|
516
|
-
*/
|
|
517
|
-
fileFor(id) {
|
|
518
|
-
return join(this.dir, `${safeSessionFileName(id)}.ndjson`)
|
|
519
|
-
}
|
|
520
|
-
|
|
521
|
-
/**
|
|
522
|
-
* Await `init()`, running it on first use.
|
|
523
|
-
* @returns {Promise<void>} completion.
|
|
524
|
-
*/
|
|
525
|
-
async ensureReady() {
|
|
526
|
-
if (this.ready === undefined) await this.init()
|
|
527
|
-
else await this.ready
|
|
528
|
-
}
|
|
529
|
-
|
|
530
1638
|
/**
|
|
531
1639
|
* Hold output for a session whose `openSession()` has not finished yet.
|
|
532
|
-
* Bounded by session count and 64 KiB per session, so a session that never
|
|
533
|
-
* opens cannot grow the store.
|
|
534
1640
|
* @param {string} id session id.
|
|
1641
|
+
* @param {string | null} owner owner.
|
|
535
1642
|
* @param {PendingRecord} record decoded record.
|
|
536
1643
|
* @returns {void}
|
|
537
1644
|
* @private
|
|
538
1645
|
*/
|
|
539
|
-
bufferOrphan(id, record) {
|
|
1646
|
+
bufferOrphan(id, owner, record) {
|
|
540
1647
|
if (id.length === 0) return
|
|
541
|
-
|
|
1648
|
+
const key = orphanKeyFor(id, owner)
|
|
1649
|
+
let orphan = this.orphans.get(key)
|
|
542
1650
|
if (orphan === undefined) {
|
|
543
1651
|
if (this.orphans.size >= MAX_ORPHAN_SESSIONS) {
|
|
544
1652
|
const oldest = this.orphans.keys().next()
|
|
545
1653
|
if (oldest.done !== true) this.orphans.delete(oldest.value)
|
|
546
1654
|
}
|
|
547
1655
|
orphan = { records: [], bytes: 0 }
|
|
548
|
-
this.orphans.set(
|
|
1656
|
+
this.orphans.set(key, orphan)
|
|
549
1657
|
this.log('debug', `[aiterm] history: buffering output for not-yet-open session ${id}`)
|
|
550
1658
|
}
|
|
551
1659
|
if (orphan.bytes + record.size > FLUSH_THRESHOLD_BYTES) return
|
|
@@ -553,6 +1661,45 @@ export class HistoryStore {
|
|
|
553
1661
|
orphan.bytes += record.size
|
|
554
1662
|
}
|
|
555
1663
|
|
|
1664
|
+
/**
|
|
1665
|
+
* Drop every pre-open buffer for an id when the session closes.
|
|
1666
|
+
* @param {string} id session id.
|
|
1667
|
+
* @returns {void}
|
|
1668
|
+
* @private
|
|
1669
|
+
*/
|
|
1670
|
+
dropOrphans(id, owner) {
|
|
1671
|
+
if (owner !== undefined) {
|
|
1672
|
+
this.orphans.delete(orphanKeyFor(id, owner))
|
|
1673
|
+
return
|
|
1674
|
+
}
|
|
1675
|
+
const suffix = `\u0000${id}`
|
|
1676
|
+
for (const key of [...this.orphans.keys()]) {
|
|
1677
|
+
if (key.endsWith(suffix)) this.orphans.delete(key)
|
|
1678
|
+
}
|
|
1679
|
+
}
|
|
1680
|
+
|
|
1681
|
+
/**
|
|
1682
|
+
* Commit a close intent held by an active writer. The active writer is only
|
|
1683
|
+
* removed after the metadata append succeeds; on failure it stays so the retry
|
|
1684
|
+
* timer can try again, and AI remains fail-closed meanwhile.
|
|
1685
|
+
* @param {ActiveSession} state session state.
|
|
1686
|
+
* @returns {Promise<void>} completion.
|
|
1687
|
+
* @private
|
|
1688
|
+
*/
|
|
1689
|
+
async commitStateClose(state) {
|
|
1690
|
+
const intent = state.pendingClose
|
|
1691
|
+
if (intent === undefined) return
|
|
1692
|
+
if (state.pending.length > 0) return
|
|
1693
|
+
if (await this.appendCloseFor(state.entry, intent)) {
|
|
1694
|
+
state.pendingClose = undefined
|
|
1695
|
+
if (state.entry.historyId !== undefined) this.pendingCloseRecords.delete(state.entry.historyId)
|
|
1696
|
+
this.active.delete(state.id)
|
|
1697
|
+
return
|
|
1698
|
+
}
|
|
1699
|
+
state.retryDelayMs = Math.min(60_000, Math.max(1000, (state.retryDelayMs || 1000) * 2))
|
|
1700
|
+
if (!this.disposed) this.scheduleFlush(state, state.retryDelayMs)
|
|
1701
|
+
}
|
|
1702
|
+
|
|
556
1703
|
/**
|
|
557
1704
|
* Arm or re-arm a flush timer for a session.
|
|
558
1705
|
* @param {ActiveSession} state session state.
|
|
@@ -573,7 +1720,20 @@ export class HistoryStore {
|
|
|
573
1720
|
}
|
|
574
1721
|
|
|
575
1722
|
/**
|
|
576
|
-
*
|
|
1723
|
+
* Low-level append used by the buffered writer. Kept as a method so failure
|
|
1724
|
+
* behavior (retention of unsaved bytes, close fail-closed) can be exercised
|
|
1725
|
+
* deterministically by tests without touching real files.
|
|
1726
|
+
* @param {string} file journal path.
|
|
1727
|
+
* @param {Buffer} data encoded NDJSON batch.
|
|
1728
|
+
* @returns {Promise<void>} completion.
|
|
1729
|
+
*/
|
|
1730
|
+
async appendJournal(file, data) {
|
|
1731
|
+
await appendFile(file, data, { mode: 0o600 })
|
|
1732
|
+
}
|
|
1733
|
+
|
|
1734
|
+
/**
|
|
1735
|
+
* Append buffered records to this incarnation's journal, serialized per
|
|
1736
|
+
* session. Only the state's own file is ever touched.
|
|
577
1737
|
* @param {ActiveSession} state session state.
|
|
578
1738
|
* @returns {Promise<void>} completion.
|
|
579
1739
|
* @private
|
|
@@ -584,37 +1744,158 @@ export class HistoryStore {
|
|
|
584
1744
|
clearTimeout(state.timer)
|
|
585
1745
|
state.timer = undefined
|
|
586
1746
|
}
|
|
587
|
-
if (state.
|
|
1747
|
+
if (state.corrupt) return
|
|
1748
|
+
if (state.pending.length === 0) {
|
|
1749
|
+
if (state.pendingClose !== undefined) await this.commitStateClose(state)
|
|
1750
|
+
return
|
|
1751
|
+
}
|
|
588
1752
|
const batch = state.pending
|
|
589
1753
|
state.pending = []
|
|
590
1754
|
state.pendingBytes = 0
|
|
591
|
-
let payload = ''
|
|
592
|
-
let payloadBytes = 0
|
|
593
|
-
for (const record of batch) {
|
|
594
|
-
payload += `${JSON.stringify({ t: record.t, d: record.d })}\n`
|
|
595
|
-
payloadBytes += record.size
|
|
596
|
-
}
|
|
597
|
-
const data = Buffer.from(payload, 'utf8')
|
|
598
1755
|
try {
|
|
599
|
-
await
|
|
600
|
-
state.
|
|
601
|
-
state.
|
|
1756
|
+
await this.appendBatch(state, batch)
|
|
1757
|
+
const wasFailing = state.writeFailures > 0
|
|
1758
|
+
state.writeFailures = 0
|
|
1759
|
+
state.retryDelayMs = 0
|
|
1760
|
+
// Keep the alert sticky once bytes have actually been dropped.
|
|
1761
|
+
state.degraded = state.droppedBytes > 0
|
|
1762
|
+
if (wasFailing) {
|
|
1763
|
+
this.warn(`history writer recovered for ${state.id} (dropped=${state.droppedBytes})`)
|
|
1764
|
+
}
|
|
602
1765
|
} catch (error) {
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
1766
|
+
const payloadBytes = batch.reduce((sum, record) => sum + record.size, 0)
|
|
1767
|
+
// Keep the bytes for a retry (and for a later close that must not
|
|
1768
|
+
// stamp a permission while the data is still unsaved), but bound the
|
|
1769
|
+
// buffer so a permanent disk failure cannot grow memory without limit.
|
|
1770
|
+
state.pending = [...batch, ...state.pending]
|
|
1771
|
+
state.pendingBytes += payloadBytes
|
|
1772
|
+
this.trimPending(state)
|
|
1773
|
+
if (error?.rollbackOk === false) {
|
|
1774
|
+
// The partial line could not be truncated. Do not append more bytes
|
|
1775
|
+
// or pretend the journal is healthy; fail closed and leave it for a
|
|
1776
|
+
// human/retention decision.
|
|
1777
|
+
state.corrupt = true
|
|
1778
|
+
state.degraded = true
|
|
1779
|
+
this.warn(`history journal ${state.id} is corrupt after a failed rollback; writes disabled`, error)
|
|
1780
|
+
return
|
|
1781
|
+
}
|
|
1782
|
+
state.writeFailures += 1
|
|
1783
|
+
state.degraded = true
|
|
1784
|
+
const now = Date.now()
|
|
1785
|
+
if (state.writeFailures === 1 || now - state.lastFailureLogAt >= FAILURE_LOG_INTERVAL_MS) {
|
|
1786
|
+
state.lastFailureLogAt = now
|
|
1787
|
+
this.warn(
|
|
1788
|
+
`cannot append history for ${state.id} (failures=${state.writeFailures}, pending=${state.pendingBytes}, dropped=${state.droppedBytes})`,
|
|
1789
|
+
error,
|
|
1790
|
+
)
|
|
1791
|
+
}
|
|
1792
|
+
state.retryDelayMs = Math.min(60_000, Math.max(1000, (state.retryDelayMs || 1000) * 2))
|
|
1793
|
+
if (!this.disposed) this.scheduleFlush(state, state.retryDelayMs)
|
|
608
1794
|
return
|
|
609
1795
|
}
|
|
610
|
-
await this.
|
|
1796
|
+
if (state.fileBytes > this.maxBytesPerSession) await this.truncateSession(state)
|
|
1797
|
+
if (state.pendingClose !== undefined && state.pending.length === 0) await this.commitStateClose(state)
|
|
611
1798
|
}
|
|
612
1799
|
state.chain = state.chain.then(task, task)
|
|
613
1800
|
return state.chain
|
|
614
1801
|
}
|
|
615
1802
|
|
|
616
1803
|
/**
|
|
617
|
-
*
|
|
1804
|
+
* Append one batch inside a rollback boundary. The file is truncated back to
|
|
1805
|
+
* its size before this batch if any write/sync fails, so a partial NDJSON line
|
|
1806
|
+
* is never left for the next retry to duplicate. On rollback failure the error
|
|
1807
|
+
* carries `rollbackOk=false` and the writer is marked corrupt.
|
|
1808
|
+
* @param {ActiveSession} state session state.
|
|
1809
|
+
* @param {PendingRecord[]} batch records to append.
|
|
1810
|
+
* @returns {Promise<void>} completion.
|
|
1811
|
+
* @private
|
|
1812
|
+
*/
|
|
1813
|
+
async appendBatch(state, batch) {
|
|
1814
|
+
const startBytes = state.fileBytes
|
|
1815
|
+
let handle
|
|
1816
|
+
let payloadBytes = 0
|
|
1817
|
+
let lineBytes = 0
|
|
1818
|
+
try {
|
|
1819
|
+
handle = await this.openAppendHandle(state.file)
|
|
1820
|
+
for (const record of batch) {
|
|
1821
|
+
const line = Buffer.from(`${JSON.stringify({ t: record.t, d: record.d })}\n`, 'utf8')
|
|
1822
|
+
await this.writeHandle(handle, line)
|
|
1823
|
+
lineBytes += line.length
|
|
1824
|
+
payloadBytes += record.size
|
|
1825
|
+
}
|
|
1826
|
+
await handle.sync()
|
|
1827
|
+
} catch (error) {
|
|
1828
|
+
let rollbackOk = true
|
|
1829
|
+
if (handle !== undefined) {
|
|
1830
|
+
try {
|
|
1831
|
+
await this.truncateHandle(handle, startBytes)
|
|
1832
|
+
await handle.sync()
|
|
1833
|
+
} catch (rollbackError) {
|
|
1834
|
+
rollbackOk = false
|
|
1835
|
+
this.warn(`cannot roll back a partial history append for ${state.id}`, rollbackError)
|
|
1836
|
+
}
|
|
1837
|
+
}
|
|
1838
|
+
if (error !== null && typeof error === 'object') {
|
|
1839
|
+
error.rollbackOk = rollbackOk
|
|
1840
|
+
error.payloadBytes = payloadBytes
|
|
1841
|
+
}
|
|
1842
|
+
throw error
|
|
1843
|
+
} finally {
|
|
1844
|
+
if (handle !== undefined) {
|
|
1845
|
+
try {
|
|
1846
|
+
await handle.close()
|
|
1847
|
+
} catch {
|
|
1848
|
+
// close failure does not change the committed bytes
|
|
1849
|
+
}
|
|
1850
|
+
}
|
|
1851
|
+
}
|
|
1852
|
+
state.fileBytes = startBytes + lineBytes
|
|
1853
|
+
state.entry.bytes += payloadBytes
|
|
1854
|
+
state.entry.mtime = Date.now()
|
|
1855
|
+
}
|
|
1856
|
+
|
|
1857
|
+
/**
|
|
1858
|
+
* Open an append handle (overridable for deterministic partial-write tests).
|
|
1859
|
+
* @param {string} file journal path.
|
|
1860
|
+
* @returns {Promise<import('node:fs/promises').FileHandle>} handle.
|
|
1861
|
+
*/
|
|
1862
|
+
async openAppendHandle(file) {
|
|
1863
|
+
return open(file, 'a', 0o600)
|
|
1864
|
+
}
|
|
1865
|
+
|
|
1866
|
+
/**
|
|
1867
|
+
* Write all bytes, handling partial `FileHandle.write` results.
|
|
1868
|
+
* @param {import('node:fs/promises').FileHandle} handle handle.
|
|
1869
|
+
* @param {Buffer} buffer data.
|
|
1870
|
+
* @returns {Promise<void>} completion.
|
|
1871
|
+
*/
|
|
1872
|
+
async writeHandle(handle, buffer) {
|
|
1873
|
+
let offset = 0
|
|
1874
|
+
while (offset < buffer.length) {
|
|
1875
|
+
const { bytesWritten } = await handle.write(buffer, offset, buffer.length - offset)
|
|
1876
|
+
if (!Number.isInteger(bytesWritten) || bytesWritten <= 0) {
|
|
1877
|
+
const error = new Error('write made no progress')
|
|
1878
|
+
error.code = 'ENOSPC'
|
|
1879
|
+
throw error
|
|
1880
|
+
}
|
|
1881
|
+
offset += bytesWritten
|
|
1882
|
+
}
|
|
1883
|
+
}
|
|
1884
|
+
|
|
1885
|
+
/**
|
|
1886
|
+
* Roll a failed append back to its pre-batch size.
|
|
1887
|
+
* @param {import('node:fs/promises').FileHandle} handle handle.
|
|
1888
|
+
* @param {number} size byte offset.
|
|
1889
|
+
* @returns {Promise<void>} completion.
|
|
1890
|
+
*/
|
|
1891
|
+
async truncateHandle(handle, size) {
|
|
1892
|
+
await handle.truncate(size)
|
|
1893
|
+
}
|
|
1894
|
+
|
|
1895
|
+
/**
|
|
1896
|
+
* Rewrite a journal to its tail, always preserving the provenance header.
|
|
1897
|
+
* Without the header the data is unusable (fail closed), so a file whose
|
|
1898
|
+
* header cannot be found is left alone.
|
|
618
1899
|
* @param {ActiveSession} state session state.
|
|
619
1900
|
* @returns {Promise<void>} completion.
|
|
620
1901
|
* @private
|
|
@@ -629,12 +1910,17 @@ export class HistoryStore {
|
|
|
629
1910
|
return
|
|
630
1911
|
}
|
|
631
1912
|
const lines = buffer.toString('utf8').split('\n')
|
|
1913
|
+
const headerLine = lines.length > 0 && parseJournalHeader(lines[0]) !== undefined ? lines[0] : undefined
|
|
1914
|
+
if (headerLine === undefined) {
|
|
1915
|
+
this.warn(`refusing to truncate history for ${state.id}: provenance header is missing`)
|
|
1916
|
+
return
|
|
1917
|
+
}
|
|
632
1918
|
/** @type {string[]} */
|
|
633
1919
|
const kept = []
|
|
634
|
-
let fileBytes =
|
|
1920
|
+
let fileBytes = Buffer.byteLength(headerLine, 'utf8') + 1
|
|
635
1921
|
let payloadBytes = 0
|
|
636
1922
|
let lastTs = 0
|
|
637
|
-
for (let index = lines.length - 1; index >=
|
|
1923
|
+
for (let index = lines.length - 1; index >= 1; index -= 1) {
|
|
638
1924
|
const line = lines[index]
|
|
639
1925
|
if (line.length === 0) continue
|
|
640
1926
|
const lineBytes = Buffer.byteLength(line, 'utf8') + 1
|
|
@@ -648,7 +1934,7 @@ export class HistoryStore {
|
|
|
648
1934
|
if (parsed.t > lastTs) lastTs = parsed.t
|
|
649
1935
|
}
|
|
650
1936
|
kept.reverse()
|
|
651
|
-
const body = kept.length > 0 ? `${kept.join('\n')}\n` : ''
|
|
1937
|
+
const body = `${headerLine}\n${kept.length > 0 ? `${kept.join('\n')}\n` : ''}`
|
|
652
1938
|
const written = Buffer.byteLength(body, 'utf8')
|
|
653
1939
|
const temp = `${state.file}.${process.pid}.${Date.now()}.tmp`
|
|
654
1940
|
try {
|
|
@@ -665,54 +1951,9 @@ export class HistoryStore {
|
|
|
665
1951
|
}
|
|
666
1952
|
state.fileBytes = written
|
|
667
1953
|
state.entry.bytes = payloadBytes
|
|
1954
|
+
state.entry.mtime = Date.now()
|
|
668
1955
|
state.entry.truncatedAt = Date.now()
|
|
669
1956
|
if (lastTs > 0) state.entry.lastTs = lastTs
|
|
670
|
-
await this.saveIndex()
|
|
671
|
-
}
|
|
672
|
-
|
|
673
|
-
/**
|
|
674
|
-
* Persist the catalog atomically, serialized behind earlier writes.
|
|
675
|
-
* @returns {Promise<void>} completion (errors are logged, not thrown).
|
|
676
|
-
* @private
|
|
677
|
-
*/
|
|
678
|
-
saveIndex() {
|
|
679
|
-
const payload = { version: CATALOG_VERSION, sessions: [...this.catalog.values()].map((entry) => ({ ...entry })) }
|
|
680
|
-
const write = async () => {
|
|
681
|
-
try {
|
|
682
|
-
await writeJsonAtomic(join(this.dir, INDEX_FILE), payload)
|
|
683
|
-
} catch (error) {
|
|
684
|
-
this.warn('cannot write history index', error)
|
|
685
|
-
}
|
|
686
|
-
}
|
|
687
|
-
this.indexChain = this.indexChain.then(write, write)
|
|
688
|
-
return this.indexChain
|
|
689
|
-
}
|
|
690
|
-
|
|
691
|
-
/**
|
|
692
|
-
* Delete one session's journal file.
|
|
693
|
-
* @param {string} id session id.
|
|
694
|
-
* @returns {Promise<void>} completion.
|
|
695
|
-
* @private
|
|
696
|
-
*/
|
|
697
|
-
async removeFile(id) {
|
|
698
|
-
try {
|
|
699
|
-
await rm(this.fileFor(id), { force: true })
|
|
700
|
-
} catch (error) {
|
|
701
|
-
this.warn(`cannot remove history for ${id}`, error)
|
|
702
|
-
}
|
|
703
|
-
}
|
|
704
|
-
|
|
705
|
-
/**
|
|
706
|
-
* Drop buffered state for a session (after close or pruning).
|
|
707
|
-
* @param {string} id session id.
|
|
708
|
-
* @returns {void}
|
|
709
|
-
* @private
|
|
710
|
-
*/
|
|
711
|
-
discardState(id) {
|
|
712
|
-
const state = this.active.get(id)
|
|
713
|
-
if (state === undefined) return
|
|
714
|
-
if (state.timer !== undefined) clearTimeout(state.timer)
|
|
715
|
-
this.active.delete(id)
|
|
716
1957
|
}
|
|
717
1958
|
|
|
718
1959
|
/**
|
|
@@ -723,7 +1964,11 @@ export class HistoryStore {
|
|
|
723
1964
|
* @private
|
|
724
1965
|
*/
|
|
725
1966
|
warn(message, error) {
|
|
726
|
-
|
|
1967
|
+
// Prefer a stable error code over a free-form message: Node fs messages
|
|
1968
|
+
// contain absolute paths (including private incarnation journal paths).
|
|
1969
|
+
const detail = typeof error?.code === 'string'
|
|
1970
|
+
? error.code
|
|
1971
|
+
: error instanceof Error ? error.message : error === undefined ? '' : String(error)
|
|
727
1972
|
try {
|
|
728
1973
|
this.log('warn', `[aiterm] history: ${message}${detail.length > 0 ? `: ${detail}` : ''}`)
|
|
729
1974
|
} catch {
|
|
@@ -732,6 +1977,29 @@ export class HistoryStore {
|
|
|
732
1977
|
}
|
|
733
1978
|
}
|
|
734
1979
|
|
|
1980
|
+
/**
|
|
1981
|
+
* Normalize an owner for comparison in this store.
|
|
1982
|
+
* @param {unknown} value raw owner.
|
|
1983
|
+
* @returns {string | null} trimmed owner or `null`.
|
|
1984
|
+
*/
|
|
1985
|
+
export function normalizeOwnerValue(value) {
|
|
1986
|
+
if (typeof value !== 'string') return null
|
|
1987
|
+
const text = value.trim()
|
|
1988
|
+
if (text.length === 0) return null
|
|
1989
|
+
return text.slice(0, 128)
|
|
1990
|
+
}
|
|
1991
|
+
|
|
1992
|
+
/**
|
|
1993
|
+
* Stable key for pre-open output, scoped to one owner so a failed open cannot
|
|
1994
|
+
* leak bytes into a later incarnation owned by somebody else.
|
|
1995
|
+
* @param {string} id session id.
|
|
1996
|
+
* @param {string | null} owner owner.
|
|
1997
|
+
* @returns {string} key.
|
|
1998
|
+
*/
|
|
1999
|
+
function orphanKeyFor(id, owner) {
|
|
2000
|
+
return `${owner === null ? '\u0001null' : owner}\u0000${id}`
|
|
2001
|
+
}
|
|
2002
|
+
|
|
735
2003
|
/**
|
|
736
2004
|
* Turn a session id into a safe journal basename (ids come from the registry,
|
|
737
2005
|
* but this is the only place a string reaches a filesystem path).
|
|
@@ -746,13 +2014,185 @@ function safeSessionFileName(id) {
|
|
|
746
2014
|
}
|
|
747
2015
|
|
|
748
2016
|
/**
|
|
749
|
-
*
|
|
2017
|
+
* Whether a directory entry is a new-format incarnation journal.
|
|
2018
|
+
* Legacy files are `<id>.ndjson` (never enumerated as attributed data).
|
|
2019
|
+
* @param {string} name file name.
|
|
2020
|
+
* @returns {boolean} true for new-format journals.
|
|
2021
|
+
*/
|
|
2022
|
+
function isIncarnationName(name) {
|
|
2023
|
+
return name.endsWith('.ndjson') && name.includes(INCARNATION_SEPARATOR)
|
|
2024
|
+
}
|
|
2025
|
+
|
|
2026
|
+
/**
|
|
2027
|
+
* Read the first line of a file without slurping a large journal.
|
|
2028
|
+
* @param {string} file absolute path.
|
|
2029
|
+
* @returns {Promise<string>} first line (or the partial file when there is no newline).
|
|
2030
|
+
*/
|
|
2031
|
+
async function readFirstLine(file) {
|
|
2032
|
+
const handle = await open(file, 'r')
|
|
2033
|
+
try {
|
|
2034
|
+
const buffer = Buffer.allocUnsafe(MAX_HEADER_BYTES)
|
|
2035
|
+
const { bytesRead } = await handle.read(buffer, 0, MAX_HEADER_BYTES, 0)
|
|
2036
|
+
const chunk = buffer.subarray(0, bytesRead)
|
|
2037
|
+
const newline = chunk.indexOf(0x0a)
|
|
2038
|
+
return chunk.subarray(0, newline === -1 ? chunk.length : newline).toString('utf8')
|
|
2039
|
+
} finally {
|
|
2040
|
+
try {
|
|
2041
|
+
await handle.close()
|
|
2042
|
+
} catch {
|
|
2043
|
+
// read handle cleanup is best effort
|
|
2044
|
+
}
|
|
2045
|
+
}
|
|
2046
|
+
}
|
|
2047
|
+
|
|
2048
|
+
/**
|
|
2049
|
+
* Read the last lines of a journal for close metadata and newest timestamp.
|
|
2050
|
+
* @param {string} file absolute path.
|
|
2051
|
+
* @param {number} size file size.
|
|
2052
|
+
* @returns {Promise<string[]>} complete tail lines.
|
|
2053
|
+
*/
|
|
2054
|
+
async function readTailLines(file, size) {
|
|
2055
|
+
if (size <= 0) return []
|
|
2056
|
+
const start = Math.max(0, size - TAIL_READ_BYTES)
|
|
2057
|
+
const handle = await open(file, 'r')
|
|
2058
|
+
try {
|
|
2059
|
+
const buffer = Buffer.allocUnsafe(size - start)
|
|
2060
|
+
const { bytesRead } = await handle.read(buffer, 0, buffer.length, start)
|
|
2061
|
+
let text = buffer.subarray(0, bytesRead).toString('utf8')
|
|
2062
|
+
// A tail cut starts mid-line; drop that partial first line.
|
|
2063
|
+
if (start > 0) {
|
|
2064
|
+
const newline = text.indexOf('\n')
|
|
2065
|
+
text = newline === -1 ? '' : text.slice(newline + 1)
|
|
2066
|
+
}
|
|
2067
|
+
return text.split('\n').filter((line) => line.trim().length > 0)
|
|
2068
|
+
} finally {
|
|
2069
|
+
try {
|
|
2070
|
+
await handle.close()
|
|
2071
|
+
} catch {
|
|
2072
|
+
// read handle cleanup is best effort
|
|
2073
|
+
}
|
|
2074
|
+
}
|
|
2075
|
+
}
|
|
2076
|
+
|
|
2077
|
+
/**
|
|
2078
|
+
* Parse a journal header line.
|
|
2079
|
+
* @param {string} line first line.
|
|
2080
|
+
* @returns {{ id: string, owner: string | null, title: string, transport: 'ssh' | 'telnet', host: string, port: number, username: string, createdAt: number } | undefined} metadata.
|
|
2081
|
+
*/
|
|
2082
|
+
function parseJournalHeader(line) {
|
|
2083
|
+
const parsed = parseJsonObject(line)
|
|
2084
|
+
if (parsed === undefined) return undefined
|
|
2085
|
+
if (parsed[META_MARKER] !== 'journal') return undefined
|
|
2086
|
+
if (parsed.version !== META_VERSION) return undefined
|
|
2087
|
+
if (typeof parsed.id !== 'string' || parsed.id.length === 0) return undefined
|
|
2088
|
+
const ownerValid = parsed.owner === null || typeof parsed.owner === 'string'
|
|
2089
|
+
if (!ownerValid) return undefined
|
|
2090
|
+
let owner = null
|
|
2091
|
+
if (typeof parsed.owner === 'string') {
|
|
2092
|
+
const text = parsed.owner.trim()
|
|
2093
|
+
// An empty owner string in a header is corruption: an ownerless journal
|
|
2094
|
+
// must say `null`, so this file is left unattributed and fails closed.
|
|
2095
|
+
if (text.length === 0) return undefined
|
|
2096
|
+
owner = text.slice(0, 128)
|
|
2097
|
+
}
|
|
2098
|
+
return {
|
|
2099
|
+
id: parsed.id.slice(0, 128),
|
|
2100
|
+
owner,
|
|
2101
|
+
title: typeof parsed.title === 'string' ? parsed.title.slice(0, 120) : parsed.id.slice(0, 128),
|
|
2102
|
+
transport: parsed.transport === 'telnet' ? 'telnet' : 'ssh',
|
|
2103
|
+
host: typeof parsed.host === 'string' ? parsed.host.slice(0, 253) : '',
|
|
2104
|
+
port: boundInteger(parsed.port, 22, 1, 65_535),
|
|
2105
|
+
username: typeof parsed.username === 'string' ? parsed.username.slice(0, 128) : '',
|
|
2106
|
+
createdAt: finiteInteger(parsed.createdAt, 0),
|
|
2107
|
+
}
|
|
2108
|
+
}
|
|
2109
|
+
|
|
2110
|
+
/**
|
|
2111
|
+
* @param {unknown} value candidate.
|
|
2112
|
+
* @returns {boolean} whether it is a known AI access mode.
|
|
2113
|
+
*/
|
|
2114
|
+
function isAiAccess(value) {
|
|
2115
|
+
return value === 'ro' || value === 'wo' || value === 'rw'
|
|
2116
|
+
}
|
|
2117
|
+
|
|
2118
|
+
/**
|
|
2119
|
+
* Parse a JSON object defensively.
|
|
2120
|
+
* @param {string} line input line.
|
|
2121
|
+
* @returns {Record<string, unknown> | undefined} parsed object.
|
|
2122
|
+
*/
|
|
2123
|
+
function parseJsonObject(line) {
|
|
2124
|
+
if (typeof line !== 'string' || line.trim().length === 0) return undefined
|
|
2125
|
+
let parsed
|
|
2126
|
+
try {
|
|
2127
|
+
parsed = JSON.parse(line)
|
|
2128
|
+
} catch {
|
|
2129
|
+
return undefined
|
|
2130
|
+
}
|
|
2131
|
+
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined
|
|
2132
|
+
return /** @type {Record<string, unknown>} */ (parsed)
|
|
2133
|
+
}
|
|
2134
|
+
|
|
2135
|
+
/**
|
|
2136
|
+
* Stable address for one incarnation: its journal basename without extension.
|
|
2137
|
+
* @param {string} journal absolute journal path.
|
|
2138
|
+
* @returns {string} opaque history id.
|
|
2139
|
+
*/
|
|
2140
|
+
function historyIdOf(journal) {
|
|
2141
|
+
const base = String(journal).replace(/\\/g, '/').split('/').pop() ?? ''
|
|
2142
|
+
return base.endsWith('.ndjson') ? base.slice(0, -'.ndjson'.length) : base
|
|
2143
|
+
}
|
|
2144
|
+
|
|
2145
|
+
/**
|
|
2146
|
+
* Activity used consistently by retention and the maxSessions cap: the newest of
|
|
2147
|
+
* output timestamp, explicit close time and filesystem mtime. A recently closed
|
|
2148
|
+
* or recently written journal must not be treated as old just because its last
|
|
2149
|
+
* output record was old.
|
|
2150
|
+
* @param {{ createdAt: number, lastTs?: number, closedAt?: number, mtime?: number }} entry recording.
|
|
2151
|
+
* @returns {number} activity timestamp.
|
|
2152
|
+
*/
|
|
2153
|
+
function retentionActivity(entry) {
|
|
2154
|
+
return Math.max(
|
|
2155
|
+
activity(entry),
|
|
2156
|
+
typeof entry.closedAt === 'number' ? entry.closedAt : 0,
|
|
2157
|
+
typeof entry.mtime === 'number' ? entry.mtime : 0,
|
|
2158
|
+
)
|
|
2159
|
+
}
|
|
2160
|
+
|
|
2161
|
+
/**
|
|
2162
|
+
* Stable token for a complete filtered page set. A client that pages with an
|
|
2163
|
+
* offset can send it back; a change in any listed identity/activity means the
|
|
2164
|
+
* offsets may have shifted and the UI must reload instead of silently skipping.
|
|
2165
|
+
* @param {Array<Record<string, any>>} entries entries.
|
|
2166
|
+
* @returns {string} short snapshot token.
|
|
2167
|
+
*/
|
|
2168
|
+
function pageSnapshot(entries) {
|
|
2169
|
+
const payload = entries.map((entry) => [
|
|
2170
|
+
entry.id ?? '',
|
|
2171
|
+
entry.historyId ?? '',
|
|
2172
|
+
entry.createdAt ?? 0,
|
|
2173
|
+
entry.lastTs ?? 0,
|
|
2174
|
+
entry.closedAt ?? '',
|
|
2175
|
+
].join('\u0000')).join('\n')
|
|
2176
|
+
return createHash('sha256').update(payload).digest('hex').slice(0, 20)
|
|
2177
|
+
}
|
|
2178
|
+
|
|
2179
|
+
/**
|
|
2180
|
+
* @param {{ createdAt: number, lastTs?: number }} entry entry.
|
|
750
2181
|
* @returns {number} sortable activity timestamp.
|
|
751
2182
|
*/
|
|
752
2183
|
function activity(entry) {
|
|
753
2184
|
return typeof entry.lastTs === 'number' ? entry.lastTs : entry.createdAt
|
|
754
2185
|
}
|
|
755
2186
|
|
|
2187
|
+
/**
|
|
2188
|
+
* @param {{ createdAt: number, lastTs?: number }} left first.
|
|
2189
|
+
* @param {{ createdAt: number, lastTs?: number }} right second.
|
|
2190
|
+
* @returns {number} comparator, newest first.
|
|
2191
|
+
*/
|
|
2192
|
+
function newestFirst(left, right) {
|
|
2193
|
+
return activity(right) - activity(left) || right.createdAt - left.createdAt
|
|
2194
|
+
}
|
|
2195
|
+
|
|
756
2196
|
/**
|
|
757
2197
|
* @param {unknown} raw catalog value from disk.
|
|
758
2198
|
* @returns {CatalogEntry | undefined} normalized entry.
|
|
@@ -816,9 +2256,9 @@ function parseRecord(line) {
|
|
|
816
2256
|
*/
|
|
817
2257
|
function compileSearch(search) {
|
|
818
2258
|
try {
|
|
819
|
-
return new RegExp(search)
|
|
2259
|
+
return new RegExp(search, 'i')
|
|
820
2260
|
} catch {
|
|
821
|
-
return new RegExp(search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
|
|
2261
|
+
return new RegExp(search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
|
|
822
2262
|
}
|
|
823
2263
|
}
|
|
824
2264
|
|
|
@@ -873,10 +2313,9 @@ function timestampAt(boundaries, offset) {
|
|
|
873
2313
|
/**
|
|
874
2314
|
* Copy a catalog entry for public consumption.
|
|
875
2315
|
*
|
|
876
|
-
* `
|
|
877
|
-
*
|
|
878
|
-
*
|
|
879
|
-
* @param {CatalogEntry} entry catalog entry.
|
|
2316
|
+
* `owner`, `aiAccess` and `journal` are private provenance and are deliberately
|
|
2317
|
+
* dropped here: no tool result or browser payload may reveal them.
|
|
2318
|
+
* @param {CatalogEntry | Recording} entry catalog entry or recording.
|
|
880
2319
|
* @returns {CatalogEntry} a plain copy of the documented shape.
|
|
881
2320
|
*/
|
|
882
2321
|
function publicEntry(entry) {
|
|
@@ -892,6 +2331,7 @@ function publicEntry(entry) {
|
|
|
892
2331
|
bytes: entry.bytes,
|
|
893
2332
|
lastTs: entry.lastTs,
|
|
894
2333
|
}
|
|
2334
|
+
if (entry.historyId !== undefined) copy.historyId = entry.historyId
|
|
895
2335
|
if (entry.closedAt !== undefined) copy.closedAt = entry.closedAt
|
|
896
2336
|
return copy
|
|
897
2337
|
}
|