@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.
@@ -0,0 +1,433 @@
1
+ /**
2
+ * Bounded historical recovery + retention for DSH log directories.
3
+ *
4
+ * A running DSH process owns ONLY `<dsh-root>/<its own dsh_instance_id>`. It may
5
+ * inspect sibling (historical) directories — a previous DSH launch under the
6
+ * same HQ Edge process leaves one behind every time DSH restarts — but every
7
+ * modification MUST be preceded by successfully acquiring THAT directory's OS
8
+ * ownership lock.
9
+ *
10
+ * That ordering is the whole safety argument (§5):
11
+ * - the parent HQ Edge process never rotates DSH logs while DSH runs;
12
+ * - one DSH process never rotates another LIVE DSH process's log;
13
+ * - a directory whose owner is gone can be repaired by any later DSH process.
14
+ *
15
+ * Recovery is idempotent, bounded in time and file count, never rewrites
16
+ * `instance.json`, never overwrites a published archive, and preserves
17
+ * anything it cannot verify.
18
+ */
19
+ import { existsSync, promises as fsPromises, renameSync, unlinkSync } from 'node:fs'
20
+ import { randomUUID } from 'node:crypto'
21
+ import { join } from 'node:path'
22
+
23
+ import { appendDiagnostic, atomicPublish, errorMessage, isUuid, withFsRetries } from './fs-utils.js'
24
+ import { readDshInstanceMetadata, RECOVERY_LOG_FILENAME } from './identity.js'
25
+ import { acquireHistoricalDshOwnership, recordRecoveryDiagnostic } from './ownership.js'
26
+ import {
27
+ ARCHIVE_SUFFIX,
28
+ QUARANTINE_MARKER,
29
+ SEALED_MARKER,
30
+ TEMP_MARKER,
31
+ archivePathFromTempName,
32
+ compressFileToArchive,
33
+ isArchiveName,
34
+ tempArchivePathFor,
35
+ verifyGzipArchive,
36
+ } from './rotation.js'
37
+
38
+ export interface DshMaintenanceOptions {
39
+ /** The DSH log root (`<edge>/dsh`). Each child directory is one DSH instance. */
40
+ instancesRoot: string
41
+ /** This process's own directory — never touched by maintenance. */
42
+ ownInstanceDir: string
43
+ maxDirectories?: number
44
+ maxFilesPerDirectory?: number
45
+ timeBudgetMs?: number
46
+ /** A directory younger than this is assumed to be a live, just-started process. */
47
+ minAgeMs?: number
48
+ now?: () => number
49
+ /** Structured sink into the CURRENT process's log (never a historical one). */
50
+ report?: (record: Record<string, unknown>) => void
51
+ }
52
+
53
+ export interface DshMaintenanceReport {
54
+ scanned: number
55
+ skippedLive: number
56
+ skippedInvalid: number
57
+ skippedRecent: number
58
+ recovered: number
59
+ preserved: number
60
+ quarantined: number
61
+ deletedFiles: number
62
+ deletedDirectories: number
63
+ truncated: boolean
64
+ details: Array<{ dir: string; action: string; detail?: string }>
65
+ }
66
+
67
+ function emptyReport(): DshMaintenanceReport {
68
+ return {
69
+ scanned: 0,
70
+ skippedLive: 0,
71
+ skippedInvalid: 0,
72
+ skippedRecent: 0,
73
+ recovered: 0,
74
+ preserved: 0,
75
+ quarantined: 0,
76
+ deletedFiles: 0,
77
+ deletedDirectories: 0,
78
+ truncated: false,
79
+ details: [],
80
+ }
81
+ }
82
+
83
+ function report(options: DshMaintenanceOptions, record: Record<string, unknown>): void {
84
+ appendDiagnostic(join(options.ownInstanceDir, RECOVERY_LOG_FILENAME), record)
85
+ try {
86
+ options.report?.(record)
87
+ } catch {
88
+ /* reporting must never break maintenance */
89
+ }
90
+ }
91
+
92
+ function archivePathForArtifact(dir: string, name: string): string {
93
+ // dsh.<date>.1.log.gz.tmp-<uuid> -> dsh.<date>.1.log.gz
94
+ // dsh.<date>.1.log.sealed-<uuid> -> dsh.<date>.1.log.gz
95
+ if (name.includes(TEMP_MARKER)) return archivePathFromTempName(dir, name)
96
+ const stem = name.slice(0, name.indexOf(SEALED_MARKER))
97
+ return join(dir, `${stem}${ARCHIVE_SUFFIX}`)
98
+ }
99
+
100
+ function uniqueArchivePath(preferred: string): string {
101
+ if (!existsSync(preferred)) return preferred
102
+ const stem = preferred.slice(0, -ARCHIVE_SUFFIX.length)
103
+ for (let seq = 1; seq < 1_000; seq += 1) {
104
+ const candidate = `${stem}.${seq}${ARCHIVE_SUFFIX}`
105
+ if (!existsSync(candidate)) return candidate
106
+ }
107
+ return `${stem}.${randomUUID()}${ARCHIVE_SUFFIX}`
108
+ }
109
+
110
+ /**
111
+ * Repairs incomplete rotation artifacts left by a previous DSH process.
112
+ * Safe to run repeatedly and safe to run while other DSH processes are active
113
+ * (their directories are skipped because their ownership lock is held).
114
+ */
115
+ export async function recoverDshInstances(options: DshMaintenanceOptions): Promise<DshMaintenanceReport> {
116
+ const now = options.now ?? Date.now
117
+ const maxDirectories = options.maxDirectories ?? 64
118
+ const maxFiles = options.maxFilesPerDirectory ?? 256
119
+ const deadline = now() + (options.timeBudgetMs ?? 3_000)
120
+ const minAgeMs = options.minAgeMs ?? 5_000
121
+ const result = emptyReport()
122
+ // An explicit 0 (or negative) disables the guard entirely. The comparison below
123
+ // must not run at all in that case: on NTFS the directory mtime can round a few
124
+ // milliseconds into the FUTURE relative to `Date.now()`, which would otherwise
125
+ // make `now() - mtimeMs` negative and skip a directory that is known quiescent.
126
+ const recentGuard = minAgeMs > 0
127
+ const note = (dir: string, action: string, detail?: string) => {
128
+ result.details.push({ dir, action, detail })
129
+ report(options, { event: 'dsh-historical-recovery', dir, action, detail })
130
+ }
131
+
132
+ let names: string[]
133
+ try {
134
+ names = await fsPromises.readdir(options.instancesRoot)
135
+ } catch {
136
+ return result
137
+ }
138
+
139
+ for (const name of names.slice(0, maxDirectories)) {
140
+ if (now() > deadline) {
141
+ result.truncated = true
142
+ break
143
+ }
144
+ const dir = join(options.instancesRoot, name)
145
+ if (dir === options.ownInstanceDir) continue
146
+ if (!isUuid(name)) {
147
+ result.skippedInvalid += 1
148
+ note(dir, 'preserved-invalid-name')
149
+ continue
150
+ }
151
+
152
+ let stat
153
+ try {
154
+ stat = await fsPromises.stat(dir)
155
+ if (!stat.isDirectory()) continue
156
+ } catch {
157
+ continue
158
+ }
159
+ result.scanned += 1
160
+
161
+ const metadata = readDshInstanceMetadata(dir)
162
+ if (!metadata) {
163
+ result.skippedInvalid += 1
164
+ note(dir, 'preserved-corrupt-metadata')
165
+ continue
166
+ }
167
+ if (recentGuard && Math.max(0, now() - stat.mtimeMs) < minAgeMs) {
168
+ result.skippedRecent += 1
169
+ note(dir, 'skipped-recent')
170
+ continue
171
+ }
172
+
173
+ const ownership = await acquireHistoricalDshOwnership(dir, metadata.dshInstanceId)
174
+ if (!ownership) {
175
+ result.skippedLive += 1
176
+ note(dir, 'skipped-live-owner')
177
+ continue
178
+ }
179
+
180
+ try {
181
+ let files: string[]
182
+ try {
183
+ files = (await fsPromises.readdir(dir)).slice(0, maxFiles)
184
+ } catch {
185
+ continue
186
+ }
187
+ for (const file of files) {
188
+ if (now() > deadline) {
189
+ result.truncated = true
190
+ break
191
+ }
192
+ if (file.includes(QUARANTINE_MARKER)) continue // already handled (idempotent)
193
+ if (!file.includes(TEMP_MARKER) && !file.includes(SEALED_MARKER)) continue
194
+
195
+ const path = join(dir, file)
196
+ const canonicalArchive = archivePathForArtifact(dir, file)
197
+ // The existence check MUST use the canonical name. `uniqueArchivePath`
198
+ // would return a fresh numbered candidate whenever the canonical
199
+ // archive already exists, hiding the "already published" case.
200
+ const canonicalExists = existsSync(canonicalArchive)
201
+
202
+ if (file.includes(TEMP_MARKER)) {
203
+ try {
204
+ await verifyGzipArchive(path)
205
+ } catch {
206
+ try {
207
+ renameSync(path, `${path}${QUARANTINE_MARKER}${randomUUID()}`)
208
+ result.quarantined += 1
209
+ note(dir, 'quarantined-invalid-temp', file)
210
+ } catch {
211
+ result.preserved += 1
212
+ note(dir, 'preserved-invalid-temp', file)
213
+ }
214
+ continue
215
+ }
216
+ if (canonicalExists) {
217
+ // A published archive already exists — never overwrite it. The
218
+ // verified temp is redundant, so it can be removed safely.
219
+ try {
220
+ unlinkSync(path)
221
+ result.deletedFiles += 1
222
+ note(dir, 'removed-redundant-temp', file)
223
+ } catch {
224
+ result.preserved += 1
225
+ }
226
+ continue
227
+ }
228
+ try {
229
+ if (atomicPublish(path, canonicalArchive)) {
230
+ result.recovered += 1
231
+ note(dir, 'published-temp-archive', file)
232
+ } else {
233
+ result.preserved += 1
234
+ note(dir, 'preserved-publish-conflict', file)
235
+ }
236
+ } catch {
237
+ result.preserved += 1
238
+ note(dir, 'preserved-publish-failure', file)
239
+ }
240
+ continue
241
+ }
242
+
243
+ // SEALED_MARKER: a sealed source whose compression never completed.
244
+ if (canonicalExists) {
245
+ // The archive exists, so the source is redundant. Deletion is
246
+ // conservative: keep it for the next maintenance pass.
247
+ result.preserved += 1
248
+ note(dir, 'preserved-redundant-sealed', file)
249
+ continue
250
+ }
251
+ const archivePath = uniqueArchivePath(canonicalArchive)
252
+ const tmp = tempArchivePathFor(archivePath)
253
+ try {
254
+ await compressFileToArchive(path, tmp)
255
+ await verifyGzipArchive(tmp)
256
+ if (atomicPublish(tmp, archivePath)) {
257
+ await withFsRetries(() => unlinkSync(path), { attempts: 3, baseDelayMs: 25, totalTimeoutMs: 800 })
258
+ result.recovered += 1
259
+ note(dir, 'recovered-sealed-source', file)
260
+ } else {
261
+ result.preserved += 1
262
+ note(dir, 'preserved-archive-conflict', file)
263
+ }
264
+ } catch (err) {
265
+ result.preserved += 1
266
+ note(dir, 'preserved-compression-failure', `${file}: ${errorMessage(err).slice(0, 160)}`)
267
+ try {
268
+ if (existsSync(tmp)) unlinkSync(tmp)
269
+ } catch {
270
+ /* preserved as an incomplete artifact */
271
+ }
272
+ }
273
+ }
274
+ } finally {
275
+ ownership.release()
276
+ recordRecoveryDiagnostic(dir, { event: 'recovery-lock-released', pid: process.pid })
277
+ }
278
+ }
279
+ return result
280
+ }
281
+
282
+ /** Files that may remain in an expired instance directory. */
283
+ const METADATA_FILES = new Set(['instance.json', 'owner.lock', 'recovery.log', 'fatal.log', 'logging-health.log'])
284
+
285
+ /**
286
+ * Per-instance retention. Never deletes an active directory: ownership
287
+ * acquisition fails while the owner is alive. Never deletes a directory that
288
+ * still has incomplete recovery artifacts.
289
+ */
290
+ export async function cleanupExpiredDshInstances(
291
+ options: DshMaintenanceOptions & { retentionDays?: number },
292
+ ): Promise<DshMaintenanceReport> {
293
+ const now = options.now ?? Date.now
294
+ const retentionMs = (options.retentionDays ?? 30) * 24 * 60 * 60 * 1000
295
+ const deadline = now() + (options.timeBudgetMs ?? 3_000)
296
+ const result = emptyReport()
297
+ const note = (dir: string, action: string, detail?: string) => {
298
+ result.details.push({ dir, action, detail })
299
+ report(options, { event: 'dsh-historical-cleanup', dir, action, detail })
300
+ }
301
+
302
+ let names: string[]
303
+ try {
304
+ names = await fsPromises.readdir(options.instancesRoot)
305
+ } catch {
306
+ return result
307
+ }
308
+
309
+ for (const name of names.slice(0, options.maxDirectories ?? 64)) {
310
+ if (now() > deadline) {
311
+ result.truncated = true
312
+ break
313
+ }
314
+ const dir = join(options.instancesRoot, name)
315
+ if (dir === options.ownInstanceDir || !isUuid(name)) continue
316
+ const metadata = readDshInstanceMetadata(dir)
317
+ if (!metadata) {
318
+ result.skippedInvalid += 1
319
+ note(dir, 'preserved-corrupt-metadata')
320
+ continue
321
+ }
322
+ let stat
323
+ try {
324
+ stat = await fsPromises.stat(dir)
325
+ } catch {
326
+ continue
327
+ }
328
+ if (Math.max(0, now() - stat.mtimeMs) < retentionMs) continue
329
+ result.scanned += 1
330
+
331
+ const ownership = await acquireHistoricalDshOwnership(dir, metadata.dshInstanceId)
332
+ if (!ownership) {
333
+ result.skippedLive += 1
334
+ note(dir, 'skipped-live-owner')
335
+ continue
336
+ }
337
+ try {
338
+ let files: string[]
339
+ try {
340
+ files = await fsPromises.readdir(dir)
341
+ } catch {
342
+ continue
343
+ }
344
+ if (files.some((file) => file.includes(TEMP_MARKER) || file.includes(SEALED_MARKER) || file.includes(QUARANTINE_MARKER))) {
345
+ result.preserved += 1
346
+ note(dir, 'preserved-unrecovered-artifacts')
347
+ continue
348
+ }
349
+ for (const file of files) {
350
+ if (METADATA_FILES.has(file)) continue
351
+ // Ownership was ACQUIRED above, which proves no live process owns this
352
+ // directory. Its `.log` file is therefore historical, not an active
353
+ // destination, and is eligible for retention cleanup. Active files are
354
+ // protected by the ownership check, not by their extension.
355
+ if (!isArchiveName(file) && !file.endsWith('.log')) {
356
+ result.preserved += 1
357
+ note(dir, 'preserved-unknown-file', file)
358
+ continue
359
+ }
360
+ try {
361
+ await withFsRetries(() => unlinkSync(join(dir, file)), {
362
+ attempts: 3,
363
+ baseDelayMs: 25,
364
+ totalTimeoutMs: 800,
365
+ })
366
+ result.deletedFiles += 1
367
+ } catch {
368
+ result.preserved += 1
369
+ note(dir, 'preserved-delete-failure', file)
370
+ }
371
+ }
372
+ const remaining = await fsPromises.readdir(dir)
373
+ if (remaining.every((file) => METADATA_FILES.has(file))) {
374
+ try {
375
+ await fsPromises.rm(dir, { recursive: true, force: true })
376
+ result.deletedDirectories += 1
377
+ note(dir, 'deleted-expired-dsh-instance')
378
+ } catch {
379
+ note(dir, 'preserved-delete-directory-failure')
380
+ }
381
+ }
382
+ } finally {
383
+ ownership.release()
384
+ }
385
+ }
386
+ return result
387
+ }
388
+
389
+ export interface LegacyPluginLogReport {
390
+ files: Array<{ path: string; size: number; action: 'preserved' }>
391
+ totalBytes: number
392
+ note: string
393
+ }
394
+
395
+ /**
396
+ * Conservative handling of the pre-isolation shared plugin log (§3).
397
+ *
398
+ * Old builds wrote `<HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log[.N]` from
399
+ * every plugin in every DSH process. Those files have no ownership metadata
400
+ * and may still be written by an older build during a rolling upgrade, so this
401
+ * function only REPORTS them. Nothing is moved, compressed or deleted: a
402
+ * one-time, operator-reviewed migration is the only safe way to retire them.
403
+ */
404
+ export async function reportLegacyPluginLogs(logBaseDir: string): Promise<LegacyPluginLogReport> {
405
+ const files: LegacyPluginLogReport['files'] = []
406
+ let totalBytes = 0
407
+ const legacyDir = join(logBaseDir, 'dsh-plugins')
408
+ let names: string[]
409
+ try {
410
+ names = await fsPromises.readdir(legacyDir)
411
+ } catch {
412
+ return { files, totalBytes: 0, note: 'no legacy dsh-plugins directory' }
413
+ }
414
+ for (const name of names) {
415
+ if (!name.endsWith('.log') && !isArchiveName(name)) continue
416
+ const path = join(legacyDir, name)
417
+ try {
418
+ const stat = await fsPromises.stat(path)
419
+ if (!stat.isFile()) continue
420
+ files.push({ path, size: stat.size, action: 'preserved' })
421
+ totalBytes += stat.size
422
+ } catch {
423
+ /* preserve */
424
+ }
425
+ }
426
+ return {
427
+ files,
428
+ totalBytes,
429
+ note:
430
+ `Preserved ${files.length} legacy shared plugin log file(s) (${totalBytes} bytes). ` +
431
+ 'No file was moved or deleted: ownership cannot be established from the old naming scheme.',
432
+ }
433
+ }
package/src/redact.ts CHANGED
@@ -29,6 +29,14 @@ const BEARER_IN_STRING = /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/i
29
29
  /** Strings at least this long that look like a single opaque credential blob. */
30
30
  const OPAQUE_SECRET = /^[A-Za-z0-9_-]{32,}$/
31
31
 
32
+ /**
33
+ * UUIDs are identifiers, not secrets. Every record carries at least
34
+ * `installationId` / `edgeInstanceId` / `dshInstanceId`, all UUID-shaped, so
35
+ * without this exemption the shape-based rule would blank out exactly the
36
+ * fields that make a multi-process log attributable.
37
+ */
38
+ const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
39
+
32
40
  export const REDACTED = '[redacted]'
33
41
 
34
42
  /** Maximum object depth walked before the value is collapsed. Cycle-safe. */
@@ -88,6 +96,7 @@ function redactInner(value: unknown, depth: number, seen: WeakSet<object>): unkn
88
96
  /** Redact credentials embedded in an otherwise ordinary string. */
89
97
  function redactString(value: string): string {
90
98
  if (BEARER_IN_STRING.test(value)) return value.replace(BEARER_IN_STRING, '$1 ' + REDACTED)
99
+ if (UUID_SHAPE.test(value)) return value
91
100
  // A bare 32+ char opaque blob is almost always a credential. Project paths,
92
101
  // URLs and sentences all contain separators, so they survive this filter.
93
102
  if (OPAQUE_SECRET.test(value)) return REDACTED