@huaqiu/dsh-plugin-log 0.6.22 → 0.6.24
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/README.md +118 -0
- package/lib/client.d.ts +9 -3
- package/lib/client.js +73 -17
- package/lib/index.d.mts +303 -19
- package/lib/index.mjs +2376 -350
- package/package.json +1 -1
- package/src/client.ts +39 -16
- package/src/fields.ts +31 -0
- package/src/fs-utils.ts +245 -0
- package/src/identity.ts +263 -0
- package/src/index.ts +408 -314
- package/src/ownership.ts +268 -0
- package/src/paths.ts +88 -41
- package/src/recovery.ts +433 -0
- package/src/redact.ts +9 -0
- package/src/rotation.ts +724 -0
- package/src/runtime.ts +633 -0
package/src/runtime.ts
ADDED
|
@@ -0,0 +1,633 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Process-wide logging runtime for ONE DSH process.
|
|
3
|
+
*
|
|
4
|
+
* This module is the only place that decides WHERE records go. Plugins never
|
|
5
|
+
* see it: they call `getLogger()` and get a namespaced logger.
|
|
6
|
+
*
|
|
7
|
+
* Startup order (docs/tasks/dsh-plugin-log-isolation.md §4):
|
|
8
|
+
* 1. read the parent logging context from the environment
|
|
9
|
+
* 2. generate `dsh_instance_id` (per LAUNCH, never per plugin)
|
|
10
|
+
* 3. create `<dsh-root>/<dsh_instance_id>/` exclusively
|
|
11
|
+
* 4. write `instance.json` atomically (never overwrite)
|
|
12
|
+
* 5. acquire the OS ownership lock for that directory
|
|
13
|
+
* 6. open `dsh.<date>.log` and replay records buffered during 1–5
|
|
14
|
+
*
|
|
15
|
+
* Steps 1–4 are synchronous so that `logDir()` / `logFilePath()` are correct
|
|
16
|
+
* the instant DSH starts. Step 5 is asynchronous (a socket bind resolves on the
|
|
17
|
+
* event loop), so records emitted in the meantime are buffered — bounded — and
|
|
18
|
+
* replayed after ownership is confirmed. If ownership cannot be established the
|
|
19
|
+
* destination is marked unavailable and the buffer is dropped: there is
|
|
20
|
+
* deliberately no fallback to a shared writable file.
|
|
21
|
+
*
|
|
22
|
+
* ## Why `globalThis`
|
|
23
|
+
*
|
|
24
|
+
* A plugin bundle may inline its own copy of this package, so a module-level
|
|
25
|
+
* singleton would give each copy its own sink, rotation counter and buffer.
|
|
26
|
+
* The state lives on `globalThis` under a `Symbol.for` key, which is a genuine
|
|
27
|
+
* process-wide registry: every copy — bundled, external or duplicated —
|
|
28
|
+
* cooperates on one destination.
|
|
29
|
+
*/
|
|
30
|
+
import { existsSync, mkdirSync } from 'node:fs'
|
|
31
|
+
import { join } from 'node:path'
|
|
32
|
+
|
|
33
|
+
import {
|
|
34
|
+
DSH_METADATA_SCHEMA_VERSION,
|
|
35
|
+
FATAL_LOG_FILENAME,
|
|
36
|
+
INSTANCE_METADATA_FILENAME,
|
|
37
|
+
createDshIdentity,
|
|
38
|
+
instanceDirFor,
|
|
39
|
+
readDshInstanceMetadata,
|
|
40
|
+
readDshLogContext,
|
|
41
|
+
type DshInstanceMetadata,
|
|
42
|
+
type DshLogContext,
|
|
43
|
+
} from './identity.js'
|
|
44
|
+
import { acquireDshOwnership, type DshOwnershipHandle } from './ownership.js'
|
|
45
|
+
import {
|
|
46
|
+
DSH_ROTATION,
|
|
47
|
+
DshLogWriter,
|
|
48
|
+
type DshRotationConfig,
|
|
49
|
+
type DshRotationFaults,
|
|
50
|
+
type LoggingHealth,
|
|
51
|
+
} from './rotation.js'
|
|
52
|
+
import { cleanupExpiredDshInstances, recoverDshInstances, reportLegacyPluginLogs } from './recovery.js'
|
|
53
|
+
import { appendDiagnostic, atomicCreateNewFile } from './fs-utils.js'
|
|
54
|
+
import { getLogBaseDir } from './paths.js'
|
|
55
|
+
|
|
56
|
+
const STATE_KEY = Symbol.for('@huaqiu/dsh-plugin-log/runtime')
|
|
57
|
+
const HOST_SINK_KEY = Symbol.for('@huaqiu/dsh-plugin-log/host-sink')
|
|
58
|
+
const STDIO_GUARD_KEY = Symbol.for('@huaqiu/dsh-plugin-log/stdio')
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* A sink supplied by the DSH host. When present the package delegates the
|
|
62
|
+
* actual transport (and its lifecycle) to DSH instead of opening its own file
|
|
63
|
+
* — the preferred integration when DSH exposes a native logging service.
|
|
64
|
+
*/
|
|
65
|
+
export interface HostLogSink {
|
|
66
|
+
write(line: string): void
|
|
67
|
+
flush?(): Promise<void>
|
|
68
|
+
close?(): void
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
export interface DshLogRuntimeConfig {
|
|
72
|
+
/** Explicit DSH log ROOT. The instance directory is always appended. */
|
|
73
|
+
dshLogRoot?: string
|
|
74
|
+
/** HQ Edge log base override, used when no DSH root is given. */
|
|
75
|
+
baseDir?: string
|
|
76
|
+
/** Test / host injection of the instance id. Production generates one. */
|
|
77
|
+
dshInstanceId?: string
|
|
78
|
+
rotation?: DshRotationConfig
|
|
79
|
+
/** Test-only: skip the OS lock (never in production). */
|
|
80
|
+
skipOwnership?: boolean
|
|
81
|
+
ownershipTimeoutMs?: number
|
|
82
|
+
now?: () => Date
|
|
83
|
+
faults?: DshRotationFaults
|
|
84
|
+
/** Extra structured sink for internal diagnostics (tests). */
|
|
85
|
+
onDiagnostic?: (record: Record<string, unknown>) => void
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
type OwnershipState = 'pending' | 'held' | 'skipped' | 'unavailable'
|
|
89
|
+
|
|
90
|
+
interface DshRuntimeState {
|
|
91
|
+
readonly schema: 2
|
|
92
|
+
config: DshLogRuntimeConfig | null
|
|
93
|
+
context: DshLogContext | null
|
|
94
|
+
identity: DshInstanceMetadata | null
|
|
95
|
+
instanceDir: string | null
|
|
96
|
+
ownership: DshOwnershipHandle | null
|
|
97
|
+
ownershipState: OwnershipState
|
|
98
|
+
ownershipPromise: Promise<void> | null
|
|
99
|
+
writer: DshLogWriter | null
|
|
100
|
+
ready: boolean
|
|
101
|
+
degradedReason: string | null
|
|
102
|
+
pending: string[]
|
|
103
|
+
pendingBytes: number
|
|
104
|
+
droppedBeforeReady: number
|
|
105
|
+
shutdown: boolean
|
|
106
|
+
shutdownPromise: Promise<void> | null
|
|
107
|
+
maintenanceScheduled: boolean
|
|
108
|
+
generation: number
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const MAX_PENDING_RECORDS = 2_000
|
|
112
|
+
const MAX_PENDING_BYTES = 1024 * 1024
|
|
113
|
+
const DEFAULT_OWNERSHIP_TIMEOUT_MS = 5_000
|
|
114
|
+
const FLUSH_TIMEOUT_MS = 5_000
|
|
115
|
+
const MAINTENANCE_DELAY_MS = 1_500
|
|
116
|
+
const MAINTENANCE_BUDGET_MS = 3_000
|
|
117
|
+
const RETENTION_DAYS = 30
|
|
118
|
+
|
|
119
|
+
function freshState(): DshRuntimeState {
|
|
120
|
+
return {
|
|
121
|
+
schema: 2,
|
|
122
|
+
config: null,
|
|
123
|
+
context: null,
|
|
124
|
+
identity: null,
|
|
125
|
+
instanceDir: null,
|
|
126
|
+
ownership: null,
|
|
127
|
+
ownershipState: 'pending',
|
|
128
|
+
ownershipPromise: null,
|
|
129
|
+
writer: null,
|
|
130
|
+
ready: false,
|
|
131
|
+
degradedReason: null,
|
|
132
|
+
pending: [],
|
|
133
|
+
pendingBytes: 0,
|
|
134
|
+
droppedBeforeReady: 0,
|
|
135
|
+
shutdown: false,
|
|
136
|
+
shutdownPromise: null,
|
|
137
|
+
maintenanceScheduled: false,
|
|
138
|
+
generation: 0,
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function state(): DshRuntimeState {
|
|
143
|
+
const registry = globalThis as Record<symbol, unknown>
|
|
144
|
+
const existing = registry[STATE_KEY] as DshRuntimeState | undefined
|
|
145
|
+
if (existing && existing.schema === 2) return existing
|
|
146
|
+
const created = freshState()
|
|
147
|
+
registry[STATE_KEY] = created
|
|
148
|
+
return created
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function hostSink(): HostLogSink | null {
|
|
152
|
+
const registry = globalThis as Record<symbol, unknown>
|
|
153
|
+
return (registry[HOST_SINK_KEY] as HostLogSink | undefined) ?? null
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* Installs a DSH-host-provided sink. MUST be called before the first log
|
|
158
|
+
* record: once the package has established its own destination (and taken the
|
|
159
|
+
* ownership lock), silently switching transports would abandon a directory it
|
|
160
|
+
* owns. A late call is ignored and diagnosed rather than throwing.
|
|
161
|
+
*/
|
|
162
|
+
export function installHostLogSink(sink: HostLogSink | null): void {
|
|
163
|
+
const registry = globalThis as Record<symbol, unknown>
|
|
164
|
+
if (sink === null) {
|
|
165
|
+
delete registry[HOST_SINK_KEY]
|
|
166
|
+
return
|
|
167
|
+
}
|
|
168
|
+
const s = state()
|
|
169
|
+
if (s.identity !== null) {
|
|
170
|
+
appendDiagnostic(join(s.instanceDir ?? '.', FATAL_LOG_FILENAME), {
|
|
171
|
+
event: 'host-sink-installed-too-late',
|
|
172
|
+
detail: 'installHostLogSink() must be called before the first log record',
|
|
173
|
+
})
|
|
174
|
+
return
|
|
175
|
+
}
|
|
176
|
+
registry[HOST_SINK_KEY] = sink
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
function degraded(reason: string, detail?: string): void {
|
|
180
|
+
const s = state()
|
|
181
|
+
s.degradedReason = reason
|
|
182
|
+
s.ownershipState = 'unavailable'
|
|
183
|
+
if (s.instanceDir && detail) {
|
|
184
|
+
appendDiagnostic(join(s.instanceDir, FATAL_LOG_FILENAME), {
|
|
185
|
+
event: 'logging-degraded',
|
|
186
|
+
reason,
|
|
187
|
+
detail,
|
|
188
|
+
dshInstanceId: s.identity?.dshInstanceId ?? null,
|
|
189
|
+
pid: process.pid,
|
|
190
|
+
})
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
// ── stdio guard ─────────────────────────────────────────────────────────────
|
|
195
|
+
|
|
196
|
+
interface StdioGuard {
|
|
197
|
+
stdout: boolean
|
|
198
|
+
stderr: boolean
|
|
199
|
+
reported: boolean
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* DSH's stdout/stderr are pipes owned by HQ Edge. If the parent dies or closes
|
|
204
|
+
* the pipe, writing to it raises EPIPE asynchronously on the stream, which
|
|
205
|
+
* without a listener is an uncaught exception: a logging call would take the
|
|
206
|
+
* DSH process down. Install one `error` listener per stream, mark the stream
|
|
207
|
+
* unusable and stop mirroring to it.
|
|
208
|
+
*/
|
|
209
|
+
function installStdioGuard(): StdioGuard {
|
|
210
|
+
const registry = globalThis as Record<symbol, unknown>
|
|
211
|
+
const existing = registry[STDIO_GUARD_KEY] as StdioGuard | undefined
|
|
212
|
+
if (existing) return existing
|
|
213
|
+
|
|
214
|
+
const guard: StdioGuard = { stdout: true, stderr: true, reported: false }
|
|
215
|
+
const attach = (name: 'stdout' | 'stderr', stream: NodeJS.WriteStream | undefined): void => {
|
|
216
|
+
if (!stream || typeof stream.on !== 'function') return
|
|
217
|
+
stream.on('error', (err: unknown) => {
|
|
218
|
+
guard[name] = false
|
|
219
|
+
if (guard.reported) return
|
|
220
|
+
guard.reported = true
|
|
221
|
+
const s = state()
|
|
222
|
+
if (!s.instanceDir) return
|
|
223
|
+
appendDiagnostic(join(s.instanceDir, FATAL_LOG_FILENAME), {
|
|
224
|
+
event: 'stdio-error',
|
|
225
|
+
stream: name,
|
|
226
|
+
code: (err as NodeJS.ErrnoException | undefined)?.code ?? 'UNKNOWN',
|
|
227
|
+
message: err instanceof Error ? err.message : String(err),
|
|
228
|
+
note: 'console mirroring disabled; file logging unaffected',
|
|
229
|
+
})
|
|
230
|
+
})
|
|
231
|
+
}
|
|
232
|
+
attach('stdout', process.stdout)
|
|
233
|
+
attach('stderr', process.stderr)
|
|
234
|
+
registry[STDIO_GUARD_KEY] = guard
|
|
235
|
+
return guard
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** True when `name` is still safe to write to. */
|
|
239
|
+
export function isStdioHealthy(name: 'stdout' | 'stderr'): boolean {
|
|
240
|
+
return installStdioGuard()[name]
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
// ── initialization ──────────────────────────────────────────────────────────
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* Creates the instance directory and metadata, then starts ownership
|
|
247
|
+
* acquisition in the background. Idempotent: later calls return immediately.
|
|
248
|
+
*/
|
|
249
|
+
export function initializeDshRuntime(config: DshLogRuntimeConfig = {}): void {
|
|
250
|
+
const s = state()
|
|
251
|
+
if (s.shutdown) return
|
|
252
|
+
if (s.identity !== null) return
|
|
253
|
+
|
|
254
|
+
s.config = config
|
|
255
|
+
s.generation += 1
|
|
256
|
+
const generation = s.generation
|
|
257
|
+
|
|
258
|
+
const context = readDshLogContext(process.env, {
|
|
259
|
+
dshLogRoot: config.dshLogRoot,
|
|
260
|
+
baseDir: config.baseDir,
|
|
261
|
+
})
|
|
262
|
+
s.context = context
|
|
263
|
+
|
|
264
|
+
// Ensure the root exists before the exclusive per-instance creation, which
|
|
265
|
+
// must fail rather than reuse an existing directory.
|
|
266
|
+
try {
|
|
267
|
+
mkdirSync(context.dshLogRoot, { recursive: true })
|
|
268
|
+
} catch (err) {
|
|
269
|
+
degraded('dsh-log-root-unavailable', String(err))
|
|
270
|
+
return
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
let identity: DshInstanceMetadata | null = null
|
|
274
|
+
let instanceDir: string | null = null
|
|
275
|
+
for (let attempt = 0; attempt < 3 && identity === null; attempt += 1) {
|
|
276
|
+
const candidate = createDshIdentity(context, {
|
|
277
|
+
dshInstanceId: config.dshInstanceId,
|
|
278
|
+
now: config.now?.(),
|
|
279
|
+
})
|
|
280
|
+
const candidateDir = instanceDirFor(candidate)
|
|
281
|
+
|
|
282
|
+
let created = false
|
|
283
|
+
try {
|
|
284
|
+
// Non-recursive on purpose: a UUID collision must be visible, never
|
|
285
|
+
// silently merged.
|
|
286
|
+
mkdirSync(candidateDir)
|
|
287
|
+
created = true
|
|
288
|
+
} catch {
|
|
289
|
+
created = false
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
if (!created) {
|
|
293
|
+
if (!existsSync(candidateDir)) {
|
|
294
|
+
degraded('instance-directory-unavailable', candidateDir)
|
|
295
|
+
return
|
|
296
|
+
}
|
|
297
|
+
// The directory already exists. Adopt it ONLY when its metadata names
|
|
298
|
+
// this exact instance id (a restart of the same logical instance, e.g.
|
|
299
|
+
// a test with a fixed id, or a crashed process whose directory was
|
|
300
|
+
// never cleaned). Ownership is still acquired later: if a live process
|
|
301
|
+
// owns it, the destination degrades instead of sharing the file.
|
|
302
|
+
const existing = readDshInstanceMetadata(candidateDir)
|
|
303
|
+
if (existing !== null && existing.dshInstanceId === candidate.dshInstanceId) {
|
|
304
|
+
identity = candidate
|
|
305
|
+
instanceDir = candidateDir
|
|
306
|
+
break
|
|
307
|
+
}
|
|
308
|
+
if (config.dshInstanceId !== undefined) {
|
|
309
|
+
degraded('instance-directory-collision', candidateDir)
|
|
310
|
+
return
|
|
311
|
+
}
|
|
312
|
+
continue
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
const metadataPath = join(candidateDir, INSTANCE_METADATA_FILENAME)
|
|
316
|
+
const metadata = { ...candidate, schemaVersion: DSH_METADATA_SCHEMA_VERSION }
|
|
317
|
+
if (!atomicCreateNewFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`)) {
|
|
318
|
+
degraded('instance-metadata-collision', metadataPath)
|
|
319
|
+
return
|
|
320
|
+
}
|
|
321
|
+
identity = candidate
|
|
322
|
+
instanceDir = candidateDir
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
if (identity === null || instanceDir === null) {
|
|
326
|
+
degraded('instance-identity-unavailable')
|
|
327
|
+
return
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
s.identity = identity
|
|
331
|
+
s.instanceDir = instanceDir
|
|
332
|
+
|
|
333
|
+
// A host-provided sink replaces the file transport entirely (the host owns
|
|
334
|
+
// rotation, ownership and shutdown in that mode).
|
|
335
|
+
if (hostSink() !== null) {
|
|
336
|
+
s.ready = true
|
|
337
|
+
s.ownershipState = 'skipped'
|
|
338
|
+
s.writer = null
|
|
339
|
+
flushPendingIntoHost()
|
|
340
|
+
return
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
const rotation = config.rotation ?? DSH_ROTATION
|
|
344
|
+
const skipOwnership = config.skipOwnership === true
|
|
345
|
+
|
|
346
|
+
s.ownershipPromise = (async () => {
|
|
347
|
+
let handle: DshOwnershipHandle | null = null
|
|
348
|
+
try {
|
|
349
|
+
handle = await acquireDshOwnership(instanceDir as string, identity!.dshInstanceId, {
|
|
350
|
+
diagnostics: true,
|
|
351
|
+
})
|
|
352
|
+
} catch {
|
|
353
|
+
handle = null
|
|
354
|
+
}
|
|
355
|
+
if (s.generation !== generation) {
|
|
356
|
+
handle?.release()
|
|
357
|
+
return
|
|
358
|
+
}
|
|
359
|
+
if (!handle && !skipOwnership) {
|
|
360
|
+
degraded('ownership-unavailable', instanceDir ?? undefined)
|
|
361
|
+
dropPending()
|
|
362
|
+
return
|
|
363
|
+
}
|
|
364
|
+
s.ownership = handle
|
|
365
|
+
s.ownershipState = skipOwnership ? 'skipped' : 'held'
|
|
366
|
+
|
|
367
|
+
const writer = new DshLogWriter({
|
|
368
|
+
dir: instanceDir as string,
|
|
369
|
+
baseName: 'dsh',
|
|
370
|
+
cfg: rotation,
|
|
371
|
+
faults: config.faults,
|
|
372
|
+
now: config.now,
|
|
373
|
+
onDiagnostic: config.onDiagnostic,
|
|
374
|
+
})
|
|
375
|
+
writer.open()
|
|
376
|
+
if (s.shutdown) {
|
|
377
|
+
await writer.close()
|
|
378
|
+
handle?.release()
|
|
379
|
+
return
|
|
380
|
+
}
|
|
381
|
+
s.writer = writer
|
|
382
|
+
s.ready = true
|
|
383
|
+
flushPendingIntoWriter(writer)
|
|
384
|
+
scheduleMaintenance()
|
|
385
|
+
})()
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
function dropPending(): void {
|
|
389
|
+
const s = state()
|
|
390
|
+
s.droppedBeforeReady += s.pending.length
|
|
391
|
+
s.pending = []
|
|
392
|
+
s.pendingBytes = 0
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
function flushPendingIntoWriter(writer: DshLogWriter): void {
|
|
396
|
+
const s = state()
|
|
397
|
+
const pending = s.pending
|
|
398
|
+
s.pending = []
|
|
399
|
+
s.pendingBytes = 0
|
|
400
|
+
for (const line of pending) writer.write(line)
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
function flushPendingIntoHost(): void {
|
|
404
|
+
const sink = hostSink()
|
|
405
|
+
if (!sink) return
|
|
406
|
+
const s = state()
|
|
407
|
+
const pending = s.pending
|
|
408
|
+
s.pending = []
|
|
409
|
+
s.pendingBytes = 0
|
|
410
|
+
for (const line of pending) {
|
|
411
|
+
try {
|
|
412
|
+
sink.write(line)
|
|
413
|
+
} catch {
|
|
414
|
+
s.droppedBeforeReady += 1
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
// ── record intake ───────────────────────────────────────────────────────────
|
|
420
|
+
|
|
421
|
+
/**
|
|
422
|
+
* Accepts one already-serialized JSONL record. Never throws, never blocks.
|
|
423
|
+
* Before the destination is ready the record is buffered (bounded); if the
|
|
424
|
+
* destination is unavailable it is dropped — logging must never fail plugin
|
|
425
|
+
* business logic.
|
|
426
|
+
*/
|
|
427
|
+
export function enqueueRecord(line: string): void {
|
|
428
|
+
const s = state()
|
|
429
|
+
if (s.shutdown) return
|
|
430
|
+
|
|
431
|
+
const sink = hostSink()
|
|
432
|
+
if (sink !== null) {
|
|
433
|
+
try {
|
|
434
|
+
sink.write(line)
|
|
435
|
+
} catch {
|
|
436
|
+
s.droppedBeforeReady += 1
|
|
437
|
+
}
|
|
438
|
+
return
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
if (s.writer !== null && s.ready) {
|
|
442
|
+
s.writer.write(line)
|
|
443
|
+
return
|
|
444
|
+
}
|
|
445
|
+
if (s.degradedReason !== null && s.ownershipState === 'unavailable') {
|
|
446
|
+
s.droppedBeforeReady += 1
|
|
447
|
+
return
|
|
448
|
+
}
|
|
449
|
+
const bytes = Buffer.byteLength(line, 'utf8')
|
|
450
|
+
if (s.pending.length >= MAX_PENDING_RECORDS || s.pendingBytes + bytes > MAX_PENDING_BYTES) {
|
|
451
|
+
s.droppedBeforeReady += 1
|
|
452
|
+
return
|
|
453
|
+
}
|
|
454
|
+
s.pending.push(line)
|
|
455
|
+
s.pendingBytes += bytes
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
// ── readiness / health ──────────────────────────────────────────────────────
|
|
459
|
+
|
|
460
|
+
function withTimeout<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> {
|
|
461
|
+
return Promise.race([promise, new Promise<T>((resolve) => {
|
|
462
|
+
const timer = setTimeout(() => resolve(fallback), ms)
|
|
463
|
+
timer.unref()
|
|
464
|
+
})])
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
/** Resolves when the destination is decided (held, skipped or unavailable). */
|
|
468
|
+
export async function awaitRuntimeReady(timeoutMs = DEFAULT_OWNERSHIP_TIMEOUT_MS): Promise<boolean> {
|
|
469
|
+
const s = state()
|
|
470
|
+
if (s.ready) return true
|
|
471
|
+
if (s.degradedReason !== null) return false
|
|
472
|
+
if (!s.ownershipPromise) return false
|
|
473
|
+
const settled = await withTimeout(
|
|
474
|
+
s.ownershipPromise.then(() => s.ready || s.degradedReason === null),
|
|
475
|
+
timeoutMs,
|
|
476
|
+
false,
|
|
477
|
+
)
|
|
478
|
+
return settled && (s.ready || s.ownershipState === 'skipped')
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
export interface DshRuntimeSnapshot {
|
|
482
|
+
readonly dshInstanceId: string | null
|
|
483
|
+
readonly instanceDir: string | null
|
|
484
|
+
readonly logFile: string | null
|
|
485
|
+
readonly logRoot: string | null
|
|
486
|
+
readonly ready: boolean
|
|
487
|
+
readonly ownership: OwnershipState
|
|
488
|
+
readonly degradedReason: string | null
|
|
489
|
+
readonly droppedBeforeReady: number
|
|
490
|
+
readonly health: LoggingHealth | null
|
|
491
|
+
}
|
|
492
|
+
|
|
493
|
+
export function getRuntimeSnapshot(): DshRuntimeSnapshot {
|
|
494
|
+
const s = state()
|
|
495
|
+
return {
|
|
496
|
+
dshInstanceId: s.identity?.dshInstanceId ?? null,
|
|
497
|
+
instanceDir: s.instanceDir,
|
|
498
|
+
logFile: s.writer?.path ?? null,
|
|
499
|
+
logRoot: s.context?.dshLogRoot ?? null,
|
|
500
|
+
ready: s.ready,
|
|
501
|
+
ownership: s.ownershipState,
|
|
502
|
+
degradedReason: s.degradedReason,
|
|
503
|
+
droppedBeforeReady: s.droppedBeforeReady,
|
|
504
|
+
health: s.writer?.getHealth() ?? null,
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/** Identity of this DSH process, or null before initialization. */
|
|
509
|
+
export function getDshIdentity(): DshInstanceMetadata | null {
|
|
510
|
+
return state().identity
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
/** Context the log root and parent identities resolved from. */
|
|
514
|
+
export function getDshLogContext(): DshLogContext | null {
|
|
515
|
+
return state().context
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
// ── maintenance ─────────────────────────────────────────────────────────────
|
|
519
|
+
|
|
520
|
+
/**
|
|
521
|
+
* Repairs and prunes HISTORICAL sibling directories. Runs on the serialized
|
|
522
|
+
* writer chain's behalf but touches only directories whose ownership lock is
|
|
523
|
+
* free — i.e. whose DSH process is gone.
|
|
524
|
+
*/
|
|
525
|
+
export async function runRuntimeMaintenance(
|
|
526
|
+
options: { timeBudgetMs?: number; retentionDays?: number; minAgeMs?: number } = {},
|
|
527
|
+
): Promise<void> {
|
|
528
|
+
const s = state()
|
|
529
|
+
if (!s.instanceDir || !s.context) return
|
|
530
|
+
if (s.shutdown) return
|
|
531
|
+
const ownInstanceDir = s.instanceDir
|
|
532
|
+
const instancesRoot = s.context.dshLogRoot
|
|
533
|
+
const report = (record: Record<string, unknown>) => {
|
|
534
|
+
// Diagnostics go to the CURRENT process's own directory, never a
|
|
535
|
+
// historical one that may be deleted by this very pass.
|
|
536
|
+
appendDiagnostic(join(ownInstanceDir, 'maintenance.log'), record)
|
|
537
|
+
}
|
|
538
|
+
try {
|
|
539
|
+
await recoverDshInstances({
|
|
540
|
+
instancesRoot,
|
|
541
|
+
ownInstanceDir,
|
|
542
|
+
timeBudgetMs: options.timeBudgetMs ?? MAINTENANCE_BUDGET_MS,
|
|
543
|
+
minAgeMs: options.minAgeMs,
|
|
544
|
+
report,
|
|
545
|
+
})
|
|
546
|
+
await cleanupExpiredDshInstances({
|
|
547
|
+
instancesRoot,
|
|
548
|
+
ownInstanceDir,
|
|
549
|
+
retentionDays: options.retentionDays ?? RETENTION_DAYS,
|
|
550
|
+
timeBudgetMs: options.timeBudgetMs ?? MAINTENANCE_BUDGET_MS,
|
|
551
|
+
report,
|
|
552
|
+
})
|
|
553
|
+
const legacy = await reportLegacyPluginLogs(getLogBaseDir(s.config?.baseDir))
|
|
554
|
+
if (legacy.files.length > 0) report({ event: 'legacy-plugin-logs', ...legacy })
|
|
555
|
+
} catch {
|
|
556
|
+
/* maintenance must never affect plugin logging */
|
|
557
|
+
}
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
function scheduleMaintenance(): void {
|
|
561
|
+
const s = state()
|
|
562
|
+
if (s.maintenanceScheduled) return
|
|
563
|
+
s.maintenanceScheduled = true
|
|
564
|
+
const timer = setTimeout(() => {
|
|
565
|
+
void runRuntimeMaintenance()
|
|
566
|
+
}, MAINTENANCE_DELAY_MS)
|
|
567
|
+
timer.unref()
|
|
568
|
+
}
|
|
569
|
+
|
|
570
|
+
// ── flush / shutdown ────────────────────────────────────────────────────────
|
|
571
|
+
|
|
572
|
+
/** Waits for everything enqueued so far, bounded. */
|
|
573
|
+
export async function flushRuntime(): Promise<void> {
|
|
574
|
+
const s = state()
|
|
575
|
+
const sink = hostSink()
|
|
576
|
+
if (sink !== null) {
|
|
577
|
+
try {
|
|
578
|
+
await sink.flush?.()
|
|
579
|
+
} catch {
|
|
580
|
+
/* a failed flush must not surface */
|
|
581
|
+
}
|
|
582
|
+
return
|
|
583
|
+
}
|
|
584
|
+
if (s.ownershipPromise) await withTimeout(s.ownershipPromise, FLUSH_TIMEOUT_MS, undefined)
|
|
585
|
+
if (s.writer) await withTimeout(s.writer.flush(), FLUSH_TIMEOUT_MS, undefined)
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
/**
|
|
589
|
+
* Final flush + close + ownership release. Owned by the DSH host only: a
|
|
590
|
+
* plugin unload must never call this, because it would close the destination
|
|
591
|
+
* for every other plugin in the process.
|
|
592
|
+
*/
|
|
593
|
+
export async function shutdownRuntime(): Promise<void> {
|
|
594
|
+
const s = state()
|
|
595
|
+
if (s.shutdownPromise) return s.shutdownPromise
|
|
596
|
+
s.shutdown = true
|
|
597
|
+
s.shutdownPromise = (async () => {
|
|
598
|
+
const sink = hostSink()
|
|
599
|
+
if (sink !== null) {
|
|
600
|
+
try {
|
|
601
|
+
await sink.flush?.()
|
|
602
|
+
sink.close?.()
|
|
603
|
+
} catch {
|
|
604
|
+
/* ignore */
|
|
605
|
+
}
|
|
606
|
+
return
|
|
607
|
+
}
|
|
608
|
+
if (s.ownershipPromise) await withTimeout(s.ownershipPromise, FLUSH_TIMEOUT_MS, undefined)
|
|
609
|
+
const writer = s.writer
|
|
610
|
+
s.writer = null
|
|
611
|
+
if (writer) {
|
|
612
|
+
await withTimeout(writer.flush(), FLUSH_TIMEOUT_MS, undefined)
|
|
613
|
+
await withTimeout(writer.close(), FLUSH_TIMEOUT_MS, undefined)
|
|
614
|
+
}
|
|
615
|
+
const ownership = s.ownership
|
|
616
|
+
s.ownership = null
|
|
617
|
+
ownership?.release()
|
|
618
|
+
})()
|
|
619
|
+
return s.shutdownPromise
|
|
620
|
+
}
|
|
621
|
+
|
|
622
|
+
/**
|
|
623
|
+
* Test/teardown helper: shuts the runtime down and forgets all state so a test
|
|
624
|
+
* can re-initialize with different configuration. Never called in production.
|
|
625
|
+
*/
|
|
626
|
+
export async function resetRuntime(): Promise<void> {
|
|
627
|
+
const s = state()
|
|
628
|
+
await shutdownRuntime()
|
|
629
|
+
const registry = globalThis as Record<symbol, unknown>
|
|
630
|
+
const fresh = freshState()
|
|
631
|
+
fresh.generation = s.generation + 1
|
|
632
|
+
registry[STATE_KEY] = fresh
|
|
633
|
+
}
|