@huaqiu/dsh-plugin-log 0.6.23 → 0.6.25
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/index.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* `@huaqiu/dsh-plugin-log` — one
|
|
2
|
+
* `@huaqiu/dsh-plugin-log` — one shared, per-DSH-process log for every Huaqiu
|
|
3
|
+
* DSH plugin.
|
|
3
4
|
*
|
|
4
5
|
* ## Why this exists
|
|
5
6
|
*
|
|
@@ -7,75 +8,85 @@
|
|
|
7
8
|
* browser half logged to `console.*`, and the node half — the half that
|
|
8
9
|
* actually owns credentials, HTTP routes and agent tools — logged nothing at
|
|
9
10
|
* all outside the DSH process's stdout, which HQ Edge only captures as an
|
|
10
|
-
* opaque text blob.
|
|
11
|
-
* propagation, the only way to see what the node half resolved was to add
|
|
12
|
-
* temporary prints and re-run.
|
|
11
|
+
* opaque text blob.
|
|
13
12
|
*
|
|
14
|
-
*
|
|
15
|
-
* inside the current HQ Edge log tree:
|
|
13
|
+
* ## What changed (docs/tasks/dsh-plugin-log-isolation.md)
|
|
16
14
|
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
15
|
+
* The package is shared by every plugin, but the logging RESOURCE belongs to
|
|
16
|
+
* the DSH process that loads them. So:
|
|
19
17
|
*
|
|
20
|
-
*
|
|
18
|
+
* - one DSH process = one log directory = one active file;
|
|
19
|
+
* - the directory is `<dsh-root>/<dsh_instance_id>/`, where `dsh-root` is the
|
|
20
|
+
* parent HQ Edge instance's `dsh/` directory;
|
|
21
|
+
* - `dsh_instance_id` is generated per DSH LAUNCH — a restart produces a new
|
|
22
|
+
* directory, a plugin reload does not;
|
|
23
|
+
* - plugins never configure a destination or a rotation; they only name
|
|
24
|
+
* themselves (`pluginId`) and get a namespaced logger;
|
|
25
|
+
* - the DSH process owns rotation, compression, retention and shutdown.
|
|
21
26
|
*
|
|
22
|
-
*
|
|
23
|
-
* (`src/paths.ts`): the same root every HQ Edge runtime uses, so plugin logs
|
|
24
|
-
* land inside the current HQ Edge log tree:
|
|
27
|
+
* Layout:
|
|
25
28
|
*
|
|
26
|
-
* <HQ_EDGE_HOME>/logs/dsh
|
|
27
|
-
*
|
|
29
|
+
* <HQ_EDGE_HOME>/logs/instances/<edge-instance-id>/dsh/
|
|
30
|
+
* <dsh-instance-id>/
|
|
31
|
+
* instance.json ← identity of this DSH process
|
|
32
|
+
* owner.lock ← diagnostic only; existence ≠ ownership
|
|
33
|
+
* dsh.2026-11-11.log ← active log (owned by this process)
|
|
34
|
+
* dsh.2026-11-11.log.gz ← published archive
|
|
28
35
|
*
|
|
29
|
-
*
|
|
36
|
+
* ## Guarantees
|
|
30
37
|
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
* - Pure `node:fs` / `node:os` / `node:path` — no native modules, no shelling
|
|
40
|
-
* out, nothing that differs between macOS, Linux and Windows but the path
|
|
41
|
-
* separators (handled by `node:path`).
|
|
42
|
-
* - Rotation uses unlink-then-rename, because Windows cannot rename over an
|
|
43
|
-
* existing file.
|
|
44
|
-
* - File names never embed `:` or other Windows-illegal characters.
|
|
45
|
-
* - If the log directory cannot be created (read-only install, locked-down
|
|
46
|
-
* profile) we fall back to the OS temp dir, and if that also fails we keep
|
|
47
|
-
* logging to the console. A logging failure must never take a plugin down.
|
|
48
|
-
*
|
|
49
|
-
* ## Safety
|
|
50
|
-
*
|
|
51
|
-
* - Every field passes through `redact()`: credential-shaped keys and values
|
|
52
|
-
* are replaced with `[redacted]`, so the log is safe to share.
|
|
53
|
-
* - `getLogger()` never throws. Neither does any log call.
|
|
38
|
+
* - `getLogger()` and every log call are synchronous, never throw, and never
|
|
39
|
+
* fail plugin business logic because a destination failed;
|
|
40
|
+
* - initialization is idempotent across duplicated package copies (the state
|
|
41
|
+
* lives in a process-wide `globalThis` registry);
|
|
42
|
+
* - a plugin's `fields` can never override identity or level fields;
|
|
43
|
+
* - plugin unload/reload never creates a second transport and never closes
|
|
44
|
+
* the shared one — only DSH shutdown flushes and closes.
|
|
54
45
|
*/
|
|
55
46
|
|
|
56
|
-
import {
|
|
57
|
-
mkdirSync,
|
|
58
|
-
renameSync,
|
|
59
|
-
rmSync,
|
|
60
|
-
statSync,
|
|
61
|
-
} from 'node:fs'
|
|
62
|
-
import { appendFile } from 'node:fs/promises'
|
|
63
|
-
import { tmpdir } from 'node:os'
|
|
64
|
-
import { join } from 'node:path'
|
|
65
|
-
import { getHqEdgeHome, getLogDir } from './paths.js'
|
|
47
|
+
import { existsSync, mkdirSync } from 'node:fs'
|
|
66
48
|
|
|
67
49
|
import { isEnabled, parseLevel, type LogLevel } from './levels.js'
|
|
68
50
|
import { redact } from './redact.js'
|
|
51
|
+
import { getDshLogRoot, getLogBaseDir, getHqEdgeHome } from './paths.js'
|
|
52
|
+
import { RESERVED_FIELDS } from './fields.js'
|
|
53
|
+
import {
|
|
54
|
+
awaitRuntimeReady,
|
|
55
|
+
enqueueRecord,
|
|
56
|
+
flushRuntime,
|
|
57
|
+
getDshIdentity,
|
|
58
|
+
getRuntimeSnapshot,
|
|
59
|
+
initializeDshRuntime,
|
|
60
|
+
resetRuntime,
|
|
61
|
+
runRuntimeMaintenance,
|
|
62
|
+
shutdownRuntime,
|
|
63
|
+
type DshLogRuntimeConfig,
|
|
64
|
+
type DshRuntimeSnapshot,
|
|
65
|
+
} from './runtime.js'
|
|
66
|
+
import type { DshRotationFaults, LoggingHealth, LoggingHealthState } from './rotation.js'
|
|
69
67
|
|
|
70
68
|
export type { LogLevel } from './levels.js'
|
|
71
69
|
export { LOG_LEVELS, levelRank, parseLevel } from './levels.js'
|
|
72
70
|
export { redact, REDACTED } from './redact.js'
|
|
71
|
+
export type { DshRotationConfig, DshRotationFaults, LoggingHealth, LoggingHealthState } from './rotation.js'
|
|
72
|
+
export { DSH_ROTATION, parseSize, todayString } from './rotation.js'
|
|
73
|
+
export type { DshInstanceMetadata, DshLogContext } from './identity.js'
|
|
74
|
+
export { INSTANCE_METADATA_FILENAME, OWNER_LOCK_FILENAME, RESERVED_FIELDS } from './identity.js'
|
|
75
|
+
export type { DshOwnershipHandle } from './ownership.js'
|
|
76
|
+
export { acquireDshOwnership, probeDshOwnership } from './ownership.js'
|
|
77
|
+
export type { DshMaintenanceOptions, DshMaintenanceReport, LegacyPluginLogReport } from './recovery.js'
|
|
78
|
+
export { cleanupExpiredDshInstances, recoverDshInstances, reportLegacyPluginLogs } from './recovery.js'
|
|
79
|
+
export type { HostLogSink } from './runtime.js'
|
|
80
|
+
export { installHostLogSink } from './runtime.js'
|
|
73
81
|
|
|
74
82
|
/** Arbitrary structured context attached to a log record. */
|
|
75
83
|
export type LogFields = Record<string, unknown>
|
|
76
84
|
|
|
77
85
|
/** The logger surface every plugin codes against. */
|
|
78
86
|
export interface PluginLogger {
|
|
87
|
+
/** Plugin that owns these records (`pluginId`, e.g. `dsh-auth`). */
|
|
88
|
+
readonly pluginId: string
|
|
89
|
+
/** @deprecated Legacy alias for `pluginId`; kept for existing call sites. */
|
|
79
90
|
readonly component: string
|
|
80
91
|
debug(message: string, fields?: LogFields): void
|
|
81
92
|
info(message: string, fields?: LogFields): void
|
|
@@ -86,94 +97,81 @@ export interface PluginLogger {
|
|
|
86
97
|
}
|
|
87
98
|
|
|
88
99
|
export interface LoggingOptions {
|
|
89
|
-
/**
|
|
100
|
+
/**
|
|
101
|
+
* DSH log ROOT. The per-process instance directory is always appended, so a
|
|
102
|
+
* shared directory can never be written directly. Highest precedence, beats
|
|
103
|
+
* `$DSH_LOG_ROOT` and `$HQ_EDGE_INSTANCE_ID`.
|
|
104
|
+
*/
|
|
90
105
|
dir?: string
|
|
91
|
-
/**
|
|
92
|
-
|
|
106
|
+
/** Alias for {@link dir}, with a name that says what it is. */
|
|
107
|
+
dshLogRoot?: string
|
|
108
|
+
/** Test/host injection of `dsh_instance_id`. Production generates one. */
|
|
109
|
+
dshInstanceId?: string
|
|
93
110
|
/** Minimum file level. Default from `$DSH_PLUGIN_LOG_LEVEL`, else `info`. */
|
|
94
111
|
level?: LogLevel
|
|
95
112
|
/**
|
|
96
|
-
* Minimum level mirrored to
|
|
113
|
+
* Minimum level mirrored to DSH's stdout. HQ Edge captures that stream, so
|
|
97
114
|
* this is how a plugin surfaces a problem without anyone opening a file.
|
|
98
115
|
* Default from `$DSH_PLUGIN_LOG_CONSOLE`, else `warn`.
|
|
99
116
|
*/
|
|
100
117
|
consoleLevel?: LogLevel | 'off'
|
|
101
|
-
/** Rotate once the
|
|
118
|
+
/** Rotate once the active file exceeds this size. Default 10 MiB. */
|
|
119
|
+
maxSize?: string
|
|
120
|
+
/** @deprecated Use {@link maxSize}. Converted to a byte count. */
|
|
102
121
|
maxBytes?: number
|
|
103
|
-
/**
|
|
122
|
+
/** @deprecated Retained for source compatibility; superseded by date+size rotation. */
|
|
104
123
|
maxFiles?: number
|
|
124
|
+
/** Days of compressed history to keep. Default 14. */
|
|
125
|
+
retentionDays?: number
|
|
126
|
+
/** Total bytes this instance directory may consume. Default 256 MiB. */
|
|
127
|
+
maxStorageBytes?: number
|
|
128
|
+
/** Gzip rotated files. Default true. */
|
|
129
|
+
compress?: boolean
|
|
130
|
+
/** Test-only fault injection for rotation. */
|
|
131
|
+
faults?: DshRotationFaults
|
|
132
|
+
/** Test-only: bypass the OS ownership lock. */
|
|
133
|
+
skipOwnership?: boolean
|
|
134
|
+
/** Clock override (tests). */
|
|
135
|
+
now?: () => Date
|
|
136
|
+
/** Internal diagnostic sink (tests). */
|
|
137
|
+
onDiagnostic?: (record: Record<string, unknown>) => void
|
|
105
138
|
}
|
|
106
139
|
|
|
107
|
-
const DEFAULT_FILE_NAME = 'dsh-plugins.log'
|
|
108
|
-
const DEFAULT_MAX_BYTES = 5 * 1024 * 1024
|
|
109
|
-
const DEFAULT_MAX_FILES = 4
|
|
110
140
|
const DEFAULT_LEVEL: LogLevel = 'info'
|
|
111
141
|
const DEFAULT_CONSOLE_LEVEL: LogLevel = 'warn'
|
|
112
142
|
|
|
113
143
|
// ── configuration ───────────────────────────────────────────────────────────
|
|
114
144
|
|
|
115
145
|
interface ResolvedConfig {
|
|
116
|
-
|
|
117
|
-
|
|
146
|
+
dshLogRoot: string | undefined
|
|
147
|
+
dshInstanceId: string | undefined
|
|
118
148
|
level: LogLevel
|
|
119
149
|
consoleLevel: LogLevel | 'off'
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
* this module. Without a shared home, "one unified log" would degrade into one
|
|
129
|
-
* sink (and one rotation counter) per plugin. Keying the state off a
|
|
130
|
-
* `Symbol.for` on `globalThis` makes every copy — bundled, external, or
|
|
131
|
-
* duplicated across installs — cooperate inside the same DSH process.
|
|
132
|
-
*/
|
|
133
|
-
const STATE_KEY = Symbol.for('@huaqiu/dsh-plugin-log/state')
|
|
134
|
-
|
|
135
|
-
interface LogState {
|
|
136
|
-
override: Partial<LoggingOptions> | null
|
|
137
|
-
resolved: ResolvedConfig | null
|
|
138
|
-
sink: FileSink | null
|
|
139
|
-
bootstrapped: boolean
|
|
140
|
-
}
|
|
141
|
-
|
|
142
|
-
function state(): LogState {
|
|
143
|
-
const g = globalThis as Record<symbol, unknown>
|
|
144
|
-
const existing = g[STATE_KEY] as LogState | undefined
|
|
145
|
-
if (existing) return existing
|
|
146
|
-
const fresh: LogState = { override: null, resolved: null, sink: null, bootstrapped: false }
|
|
147
|
-
g[STATE_KEY] = fresh
|
|
148
|
-
return fresh
|
|
150
|
+
maxSize: string
|
|
151
|
+
retentionDays: number
|
|
152
|
+
maxStorageBytes: number
|
|
153
|
+
compress: boolean
|
|
154
|
+
faults: DshRotationFaults | undefined
|
|
155
|
+
skipOwnership: boolean
|
|
156
|
+
now: (() => Date) | undefined
|
|
157
|
+
onDiagnostic: ((record: Record<string, unknown>) => void) | undefined
|
|
149
158
|
}
|
|
150
159
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
const setSink = (value: FileSink | null): void => { state().sink = value }
|
|
155
|
-
|
|
160
|
+
let override: LoggingOptions | null = null
|
|
161
|
+
let resolved: ResolvedConfig | null = null
|
|
162
|
+
let bootstrapped = false
|
|
156
163
|
/**
|
|
157
|
-
*
|
|
158
|
-
*
|
|
164
|
+
* Pending boot-banner emission. `flushLogs()` must await it: the banner is
|
|
165
|
+
* written once the destination is decided, so without this barrier a flush
|
|
166
|
+
* could return before the banner (and any rotation it triggers) had landed.
|
|
159
167
|
*/
|
|
160
|
-
|
|
161
|
-
setOverride({ ...(getOverride() ?? {}), ...options })
|
|
162
|
-
state().resolved = null
|
|
163
|
-
}
|
|
164
|
-
|
|
165
|
-
/** Forget all configuration and cached loggers. Test/teardown helper. */
|
|
166
|
-
export function resetLogging(): void {
|
|
167
|
-
const s = state()
|
|
168
|
-
s.override = null
|
|
169
|
-
s.resolved = null
|
|
170
|
-
s.sink = null
|
|
171
|
-
s.bootstrapped = false
|
|
172
|
-
}
|
|
168
|
+
let bootPromise: Promise<void> | null = null
|
|
173
169
|
|
|
174
170
|
function env(name: string): string | undefined {
|
|
175
171
|
const value = process.env[name]
|
|
176
|
-
|
|
172
|
+
if (value === undefined) return undefined
|
|
173
|
+
const trimmed = value.trim()
|
|
174
|
+
return trimmed.length > 0 ? trimmed : undefined
|
|
177
175
|
}
|
|
178
176
|
|
|
179
177
|
function readInt(value: string | undefined, fallback: number): number {
|
|
@@ -182,176 +180,132 @@ function readInt(value: string | undefined, fallback: number): number {
|
|
|
182
180
|
return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
|
|
183
181
|
}
|
|
184
182
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
if (explicit !== undefined && explicit.length > 0) candidates.push(explicit)
|
|
193
|
-
const fromEnv = env('DSH_PLUGIN_LOG_DIR')
|
|
194
|
-
if (fromEnv) candidates.push(fromEnv)
|
|
195
|
-
// Inside the current HQ Edge log tree (honours $HQ_EDGE_HOME / $HQ_EDGE_LOG_DIR
|
|
196
|
-
// through the inlined paths resolver), so plugin logs follow the host install.
|
|
197
|
-
candidates.push(getLogDir('dsh-plugins'))
|
|
198
|
-
candidates.push(join(tmpdir(), 'hq-dsh-plugins', 'logs'))
|
|
199
|
-
|
|
200
|
-
for (let i = 0; i < candidates.length; i += 1) {
|
|
201
|
-
const dir = candidates[i]
|
|
202
|
-
if (!dir) continue
|
|
203
|
-
try {
|
|
204
|
-
mkdirSync(dir, { recursive: true })
|
|
205
|
-
return { dir, fallback: i > 0 }
|
|
206
|
-
} catch {
|
|
207
|
-
/* read-only or locked-down — try the next candidate */
|
|
208
|
-
}
|
|
209
|
-
}
|
|
183
|
+
function readBool(value: string | undefined, fallback: boolean): boolean {
|
|
184
|
+
if (value === undefined) return fallback
|
|
185
|
+
const normalized = value.trim().toLowerCase()
|
|
186
|
+
if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
|
|
187
|
+
if (['0', 'false', 'no', 'off'].includes(normalized)) return false
|
|
188
|
+
return fallback
|
|
189
|
+
}
|
|
210
190
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
191
|
+
function consoleLevelFrom(raw: string | undefined, explicit?: LogLevel | 'off'): LogLevel | 'off' {
|
|
192
|
+
if (explicit === 'off') return 'off'
|
|
193
|
+
if (explicit !== undefined) return explicit
|
|
194
|
+
if (raw === 'off' || raw === 'none' || raw === '0') return 'off'
|
|
195
|
+
if (raw === 'all' || raw === '1' || raw === 'true') return 'debug'
|
|
196
|
+
return parseLevel(raw, DEFAULT_CONSOLE_LEVEL)
|
|
215
197
|
}
|
|
216
198
|
|
|
217
199
|
function currentConfig(): ResolvedConfig {
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
const
|
|
221
|
-
const
|
|
222
|
-
const
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
200
|
+
if (resolved) return resolved
|
|
201
|
+
const o: LoggingOptions = override ?? {}
|
|
202
|
+
const rootFromOption = o.dshLogRoot ?? o.dir
|
|
203
|
+
const rootFromEnv = env('DSH_LOG_ROOT') ?? env('DSH_PLUGIN_LOG_DIR')
|
|
204
|
+
const maxSize =
|
|
205
|
+
o.maxSize ?? (o.maxBytes !== undefined ? `${Math.max(1, Math.floor(o.maxBytes / (1024 * 1024)))}m` : undefined)
|
|
206
|
+
resolved = {
|
|
207
|
+
dshLogRoot: rootFromOption ?? rootFromEnv,
|
|
208
|
+
dshInstanceId: o.dshInstanceId,
|
|
209
|
+
level: o.level ?? parseLevel(env('DSH_PLUGIN_LOG_LEVEL'), DEFAULT_LEVEL),
|
|
210
|
+
consoleLevel: consoleLevelFrom(env('DSH_PLUGIN_LOG_CONSOLE'), o.consoleLevel),
|
|
211
|
+
maxSize: maxSize ?? env('DSH_PLUGIN_LOG_MAX_BYTES_SIZE') ?? '10m',
|
|
212
|
+
retentionDays: o.retentionDays ?? readInt(env('DSH_PLUGIN_LOG_RETENTION_DAYS'), 14),
|
|
213
|
+
maxStorageBytes: o.maxStorageBytes ?? readInt(env('DSH_PLUGIN_LOG_MAX_STORAGE_BYTES'), 256 * 1024 * 1024),
|
|
214
|
+
compress: o.compress ?? readBool(env('DSH_PLUGIN_LOG_COMPRESS'), true),
|
|
215
|
+
faults: o.faults,
|
|
216
|
+
skipOwnership: o.skipOwnership === true,
|
|
217
|
+
now: o.now,
|
|
218
|
+
onDiagnostic: o.onDiagnostic,
|
|
237
219
|
}
|
|
238
|
-
return
|
|
220
|
+
return resolved
|
|
239
221
|
}
|
|
240
222
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
223
|
+
function runtimeConfig(cfg: ResolvedConfig): DshLogRuntimeConfig {
|
|
224
|
+
return {
|
|
225
|
+
dshLogRoot: cfg.dshLogRoot,
|
|
226
|
+
dshInstanceId: cfg.dshInstanceId,
|
|
227
|
+
rotation: {
|
|
228
|
+
frequency: 'daily',
|
|
229
|
+
maxSize: cfg.maxSize,
|
|
230
|
+
retentionDays: cfg.retentionDays,
|
|
231
|
+
maxStorageBytes: cfg.maxStorageBytes,
|
|
232
|
+
compress: cfg.compress,
|
|
233
|
+
},
|
|
234
|
+
faults: cfg.faults,
|
|
235
|
+
skipOwnership: cfg.skipOwnership,
|
|
236
|
+
now: cfg.now,
|
|
237
|
+
onDiagnostic: cfg.onDiagnostic,
|
|
238
|
+
}
|
|
250
239
|
}
|
|
251
240
|
|
|
252
|
-
// ── file sink ───────────────────────────────────────────────────────────────
|
|
253
|
-
|
|
254
241
|
/**
|
|
255
|
-
*
|
|
256
|
-
*
|
|
257
|
-
*
|
|
258
|
-
* plugins in the same process can never interleave or race the rotation.
|
|
242
|
+
* Programmatically configure logging. Call before the first `getLogger()`;
|
|
243
|
+
* once the destination is established a later call only takes effect after
|
|
244
|
+
* {@link shutdownLogging} + {@link resetLogging} (tests, host re-init).
|
|
259
245
|
*/
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
return statSync(this.path).size
|
|
278
|
-
} catch {
|
|
279
|
-
return 0
|
|
280
|
-
}
|
|
281
|
-
}
|
|
282
|
-
|
|
283
|
-
/** Rotate when appending `next` bytes would exceed the cap. */
|
|
284
|
-
private rotateIfNeeded(next: number): void {
|
|
285
|
-
if (this.maxBytes <= 0) return
|
|
286
|
-
if (this.bytes + next <= this.maxBytes) return
|
|
287
|
-
try {
|
|
288
|
-
// Shift: .2 -> .3, .1 -> .2, current -> .1 (oldest is dropped).
|
|
289
|
-
for (let i = this.maxFiles - 1; i >= 1; i -= 1) {
|
|
290
|
-
const from = i === 1 ? join(this.dir, this.fileName) : this.rotated(i - 1)
|
|
291
|
-
const to = this.rotated(i)
|
|
292
|
-
if (!exists(from)) continue
|
|
293
|
-
// Windows cannot rename over an existing file — remove the target first.
|
|
294
|
-
if (exists(to)) rmSync(to, { force: true })
|
|
295
|
-
renameSync(from, to)
|
|
296
|
-
}
|
|
297
|
-
this.bytes = this.currentSize()
|
|
298
|
-
} catch {
|
|
299
|
-
// Rotation is best-effort: never lose the write because of it.
|
|
300
|
-
}
|
|
246
|
+
export function configureLogging(options: LoggingOptions): void {
|
|
247
|
+
override = { ...(override ?? {}), ...options }
|
|
248
|
+
resolved = null
|
|
249
|
+
if (getDshIdentity() !== null) {
|
|
250
|
+
// The destination is already established. Say so in the current log
|
|
251
|
+
// instead of silently pretending the new configuration applies.
|
|
252
|
+
enqueueRecord(
|
|
253
|
+
serialize({
|
|
254
|
+
time: Date.now(),
|
|
255
|
+
ts: new Date().toISOString(),
|
|
256
|
+
level: 'warn',
|
|
257
|
+
msg: 'configureLogging called after logging started; restart required for it to take effect',
|
|
258
|
+
pluginId: 'dsh-plugin-log',
|
|
259
|
+
component: 'dsh-plugin-log',
|
|
260
|
+
pid: process.pid,
|
|
261
|
+
}),
|
|
262
|
+
)
|
|
301
263
|
}
|
|
264
|
+
}
|
|
302
265
|
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
266
|
+
/** Forgets all configuration and cached state. Test/teardown helper. */
|
|
267
|
+
export async function resetLogging(): Promise<void> {
|
|
268
|
+
if (bootPromise) await bootPromise
|
|
269
|
+
await resetRuntime()
|
|
270
|
+
override = null
|
|
271
|
+
resolved = null
|
|
272
|
+
bootstrapped = false
|
|
273
|
+
bootPromise = null
|
|
274
|
+
}
|
|
309
275
|
|
|
310
|
-
|
|
311
|
-
write(line: string): void {
|
|
312
|
-
const size = Buffer.byteLength(line, 'utf8')
|
|
313
|
-
this.bytes += size
|
|
314
|
-
this.queue = this.queue
|
|
315
|
-
.then(async () => {
|
|
316
|
-
this.rotateIfNeeded(size)
|
|
317
|
-
await appendFile(this.path, line, 'utf8')
|
|
318
|
-
})
|
|
319
|
-
.catch(() => {
|
|
320
|
-
/* a full or locked disk must never surface as a plugin failure */
|
|
321
|
-
})
|
|
322
|
-
}
|
|
276
|
+
// ── record building ─────────────────────────────────────────────────────────
|
|
323
277
|
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
278
|
+
/** Drops reserved keys so a plugin cannot spoof identity or level. */
|
|
279
|
+
function sanitize(fields: LogFields | undefined): LogFields {
|
|
280
|
+
if (!fields) return {}
|
|
281
|
+
const out: LogFields = {}
|
|
282
|
+
for (const [key, value] of Object.entries(fields)) {
|
|
283
|
+
if (RESERVED_FIELDS.has(key)) continue
|
|
284
|
+
out[key] = value
|
|
327
285
|
}
|
|
286
|
+
return out
|
|
328
287
|
}
|
|
329
288
|
|
|
330
|
-
|
|
289
|
+
/** JSON.stringify that can never throw (BigInt, cycles in exotic values). */
|
|
290
|
+
function serialize(record: Record<string, unknown>): string {
|
|
331
291
|
try {
|
|
332
|
-
|
|
333
|
-
return true
|
|
292
|
+
return JSON.stringify(record)
|
|
334
293
|
} catch {
|
|
335
|
-
|
|
294
|
+
try {
|
|
295
|
+
return JSON.stringify({
|
|
296
|
+
time: Date.now(),
|
|
297
|
+
ts: new Date().toISOString(),
|
|
298
|
+
level: 'error',
|
|
299
|
+
msg: '[unserializable log record]',
|
|
300
|
+
pluginId: typeof record.pluginId === 'string' ? record.pluginId : 'unknown',
|
|
301
|
+
pid: process.pid,
|
|
302
|
+
})
|
|
303
|
+
} catch {
|
|
304
|
+
return '{"level":"error","msg":"[unserializable log record]"}'
|
|
305
|
+
}
|
|
336
306
|
}
|
|
337
307
|
}
|
|
338
308
|
|
|
339
|
-
function currentSink(): FileSink {
|
|
340
|
-
const existing = getSink()
|
|
341
|
-
if (existing) return existing
|
|
342
|
-
const cfg = currentConfig()
|
|
343
|
-
const created = new FileSink(cfg.dir, cfg.fileName, cfg.maxBytes, cfg.maxFiles)
|
|
344
|
-
setSink(created)
|
|
345
|
-
return created
|
|
346
|
-
}
|
|
347
|
-
|
|
348
|
-
/** Wait for all pending writes to land (shutdown hooks, tests). */
|
|
349
|
-
export async function flushLogs(): Promise<void> {
|
|
350
|
-
await getSink()?.flush()
|
|
351
|
-
}
|
|
352
|
-
|
|
353
|
-
// ── logger ──────────────────────────────────────────────────────────────────
|
|
354
|
-
|
|
355
309
|
function consoleMethod(level: LogLevel): 'log' | 'info' | 'warn' | 'error' {
|
|
356
310
|
if (level === 'error') return 'error'
|
|
357
311
|
if (level === 'warn') return 'warn'
|
|
@@ -359,92 +313,232 @@ function consoleMethod(level: LogLevel): 'log' | 'info' | 'warn' | 'error' {
|
|
|
359
313
|
return 'log'
|
|
360
314
|
}
|
|
361
315
|
|
|
362
|
-
function
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
316
|
+
function emit(pluginId: string, defaults: LogFields, level: LogLevel, message: string, fields?: LogFields): void {
|
|
317
|
+
try {
|
|
318
|
+
const cfg = currentConfig()
|
|
319
|
+
const fileEnabled = isEnabled(level, cfg.level)
|
|
320
|
+
const consoleEnabled = cfg.consoleLevel !== 'off' && isEnabled(level, cfg.consoleLevel)
|
|
321
|
+
if (!fileEnabled && !consoleEnabled) return
|
|
322
|
+
|
|
323
|
+
ensureInitialized()
|
|
324
|
+
|
|
325
|
+
const identity = getDshIdentity()
|
|
326
|
+
const record: LogFields = {
|
|
327
|
+
time: Date.now(),
|
|
328
|
+
// Legacy ISO timestamp; `time` is the canonical field.
|
|
329
|
+
ts: new Date().toISOString(),
|
|
330
|
+
level,
|
|
331
|
+
msg: message,
|
|
332
|
+
pluginId,
|
|
333
|
+
// Legacy alias, still emitted so existing `grep '"component"'` recipes
|
|
334
|
+
// keep working. Never settable by the caller (see RESERVED_FIELDS).
|
|
335
|
+
component: pluginId,
|
|
336
|
+
installationId: identity?.installationId ?? null,
|
|
337
|
+
hostType: identity?.hostType ?? null,
|
|
338
|
+
hostInstanceId: identity?.hostInstanceId ?? null,
|
|
339
|
+
edgeInstanceId: identity?.edgeInstanceId ?? null,
|
|
340
|
+
dshInstanceId: identity?.dshInstanceId ?? null,
|
|
341
|
+
pid: identity?.pid ?? process.pid,
|
|
342
|
+
}
|
|
343
|
+
Object.assign(record, sanitize(defaults))
|
|
344
|
+
Object.assign(record, sanitize(fields))
|
|
369
345
|
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
}
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
const safe = redact(record) as LogFields
|
|
381
|
-
|
|
382
|
-
if (isEnabled(level, cfg.level)) {
|
|
383
|
-
currentSink().write(`${JSON.stringify(safe)}\n`)
|
|
384
|
-
}
|
|
385
|
-
if (cfg.consoleLevel !== 'off' && isEnabled(level, cfg.consoleLevel)) {
|
|
386
|
-
const { msg, ...rest } = safe
|
|
387
|
-
// eslint-disable-next-line no-console
|
|
388
|
-
console[consoleMethod(level)](`[${component}] ${String(msg)}`, rest)
|
|
389
|
-
}
|
|
390
|
-
} catch {
|
|
391
|
-
/* logging must never throw */
|
|
346
|
+
const safe = redact(record) as LogFields
|
|
347
|
+
|
|
348
|
+
if (fileEnabled) {
|
|
349
|
+
enqueueRecord(`${serialize(safe)}\n`)
|
|
350
|
+
}
|
|
351
|
+
if (consoleEnabled) {
|
|
352
|
+
const { msg, ...rest } = safe
|
|
353
|
+
// eslint-disable-next-line no-console
|
|
354
|
+
console[consoleMethod(level)](`[${pluginId}] ${String(msg)}`, rest)
|
|
392
355
|
}
|
|
356
|
+
} catch {
|
|
357
|
+
/* logging must never throw into plugin business logic */
|
|
393
358
|
}
|
|
359
|
+
}
|
|
394
360
|
|
|
361
|
+
function createLoggerFor(pluginId: string, defaults: LogFields): PluginLogger {
|
|
395
362
|
return {
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
363
|
+
pluginId,
|
|
364
|
+
component: pluginId,
|
|
365
|
+
debug: (message, fields) => emit(pluginId, defaults, 'debug', message, fields),
|
|
366
|
+
info: (message, fields) => emit(pluginId, defaults, 'info', message, fields),
|
|
367
|
+
warn: (message, fields) => emit(pluginId, defaults, 'warn', message, fields),
|
|
368
|
+
error: (message, fields) => emit(pluginId, defaults, 'error', message, fields),
|
|
369
|
+
child: (fields) => createLoggerFor(pluginId, { ...defaults, ...fields }),
|
|
402
370
|
}
|
|
403
371
|
}
|
|
404
372
|
|
|
405
373
|
/**
|
|
406
|
-
*
|
|
374
|
+
* Gets (or creates) the logger for `pluginId`.
|
|
407
375
|
*
|
|
408
|
-
* `
|
|
409
|
-
*
|
|
410
|
-
*
|
|
376
|
+
* `pluginId` should be the value used everywhere else in that plugin's output —
|
|
377
|
+
* `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen`, or the full package name
|
|
378
|
+
* (`@huaqiu/dsh-plugin-eda`) when that is less ambiguous. It is attached to
|
|
379
|
+
* every record, which is what makes per-plugin filtering possible without a
|
|
380
|
+
* file per plugin.
|
|
411
381
|
*/
|
|
412
|
-
export function getLogger(
|
|
382
|
+
export function getLogger(pluginId: string, defaults: LogFields = {}): PluginLogger {
|
|
383
|
+
ensureInitialized()
|
|
413
384
|
bootstrap()
|
|
414
|
-
return
|
|
385
|
+
return createLoggerFor(pluginId, defaults)
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/** Spec-shaped factory: `createLogger({ pluginId })`. Equivalent to `getLogger`. */
|
|
389
|
+
export function createLogger(options: { pluginId: string }): PluginLogger {
|
|
390
|
+
return getLogger(options.pluginId)
|
|
415
391
|
}
|
|
416
392
|
|
|
417
|
-
// ── boot banner
|
|
393
|
+
// ── initialization / boot banner ────────────────────────────────────────────
|
|
394
|
+
|
|
395
|
+
function ensureInitialized(): void {
|
|
396
|
+
if (getDshIdentity() !== null) return
|
|
397
|
+
initializeDshRuntime(runtimeConfig(currentConfig()))
|
|
398
|
+
}
|
|
418
399
|
|
|
419
400
|
/**
|
|
420
|
-
*
|
|
401
|
+
* One record describing where this process logs and which identities it
|
|
402
|
+
* carries. This is the line that makes the next "one editor logged, the other
|
|
403
|
+
* did not" investigation cheap.
|
|
421
404
|
*
|
|
422
|
-
*
|
|
423
|
-
*
|
|
424
|
-
*
|
|
425
|
-
* moment the first plugin touched the log.
|
|
405
|
+
* Emitted AFTER the destination is decided, so `ownership` and `logFile` in the
|
|
406
|
+
* banner describe reality instead of the transient "pending" state. Records
|
|
407
|
+
* logged before then are buffered and appear before it in the file.
|
|
426
408
|
*/
|
|
427
409
|
function bootstrap(): void {
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
410
|
+
if (bootstrapped) return
|
|
411
|
+
bootstrapped = true
|
|
412
|
+
bootPromise = awaitRuntimeReady().then(() => emitBootRecord())
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
function emitBootRecord(): void {
|
|
416
|
+
const snapshot = getRuntimeSnapshot()
|
|
417
|
+
const identity = getDshIdentity()
|
|
433
418
|
let hqEdgeHome: string | null = null
|
|
434
419
|
try {
|
|
435
420
|
hqEdgeHome = getHqEdgeHome()
|
|
436
421
|
} catch {
|
|
437
422
|
hqEdgeHome = null
|
|
438
423
|
}
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
424
|
+
emit('dsh-plugin-log', {}, 'info', 'dsh plugin log ready', {
|
|
425
|
+
logRoot: snapshot.logRoot,
|
|
426
|
+
instanceDir: snapshot.instanceDir,
|
|
427
|
+
logFile: snapshot.logFile,
|
|
428
|
+
ownership: snapshot.ownership,
|
|
429
|
+
degradedReason: snapshot.degradedReason,
|
|
430
|
+
version: identity?.version ?? null,
|
|
431
|
+
targetHost: identity?.targetHost ?? null,
|
|
432
|
+
dshHome: identity?.dshHome ?? null,
|
|
442
433
|
hqEdgeHome,
|
|
443
|
-
level:
|
|
444
|
-
consoleLevel:
|
|
445
|
-
pid: process.pid,
|
|
434
|
+
level: currentConfig().level,
|
|
435
|
+
consoleLevel: currentConfig().consoleLevel,
|
|
446
436
|
node: process.version,
|
|
447
437
|
platform: process.platform,
|
|
448
438
|
arch: process.arch,
|
|
449
439
|
})
|
|
450
440
|
}
|
|
441
|
+
|
|
442
|
+
// ── introspection ───────────────────────────────────────────────────────────
|
|
443
|
+
|
|
444
|
+
/** Absolute directory this DSH process exclusively owns, or null before init. */
|
|
445
|
+
export function logDir(): string | null {
|
|
446
|
+
ensureInitialized()
|
|
447
|
+
return getRuntimeSnapshot().instanceDir
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/** Absolute path of the active log file, or null before it is open. */
|
|
451
|
+
export function logFilePath(): string | null {
|
|
452
|
+
return getRuntimeSnapshot().logFile
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
/** Root that contains one directory per DSH instance. */
|
|
456
|
+
export function logRoot(): string | null {
|
|
457
|
+
ensureInitialized()
|
|
458
|
+
return getRuntimeSnapshot().logRoot
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
/** Identity of this DSH process (null before initialization). */
|
|
462
|
+
export function dshInstanceInfo(): DshRuntimeSnapshot {
|
|
463
|
+
return getRuntimeSnapshot()
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
export interface LoggingHealthReport extends LoggingHealth {
|
|
467
|
+
instanceDir: string | null
|
|
468
|
+
logFile: string | null
|
|
469
|
+
ownership: DshRuntimeSnapshot['ownership']
|
|
470
|
+
degradedReason: string | null
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
/** Destination health, for a diagnostics/health endpoint or a support bundle. */
|
|
474
|
+
export function getLoggingHealth(): LoggingHealthReport {
|
|
475
|
+
const snapshot = getRuntimeSnapshot()
|
|
476
|
+
const health = snapshot.health
|
|
477
|
+
const state: LoggingHealthState = health
|
|
478
|
+
? health.state
|
|
479
|
+
: snapshot.degradedReason !== null
|
|
480
|
+
? 'unavailable'
|
|
481
|
+
: snapshot.ready
|
|
482
|
+
? 'healthy'
|
|
483
|
+
: 'initializing'
|
|
484
|
+
return {
|
|
485
|
+
state,
|
|
486
|
+
reason: health?.reason ?? snapshot.degradedReason ?? (snapshot.ready ? 'destination open' : 'not initialized'),
|
|
487
|
+
droppedRecords: (health?.droppedRecords ?? 0) + snapshot.droppedBeforeReady,
|
|
488
|
+
rotationCount: health?.rotationCount ?? 0,
|
|
489
|
+
lastError: health?.lastError ?? null,
|
|
490
|
+
instanceDir: snapshot.instanceDir,
|
|
491
|
+
logFile: snapshot.logFile,
|
|
492
|
+
ownership: snapshot.ownership,
|
|
493
|
+
degradedReason: snapshot.degradedReason,
|
|
494
|
+
}
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
// ── lifecycle ───────────────────────────────────────────────────────────────
|
|
498
|
+
|
|
499
|
+
/** Waits until the destination is decided. For tests and startup diagnostics. */
|
|
500
|
+
export function ready(): Promise<boolean> {
|
|
501
|
+
ensureInitialized()
|
|
502
|
+
return awaitRuntimeReady()
|
|
503
|
+
}
|
|
504
|
+
|
|
505
|
+
/** Waits for all pending records (and any rotation they triggered) to land. */
|
|
506
|
+
export async function flushLogs(): Promise<void> {
|
|
507
|
+
if (bootPromise) await bootPromise
|
|
508
|
+
await flushRuntime()
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
/**
|
|
512
|
+
* Final flush + close + ownership release.
|
|
513
|
+
*
|
|
514
|
+
* Owned by the DSH host. A plugin must NEVER call this: it would close the
|
|
515
|
+
* shared destination for every other plugin in the process.
|
|
516
|
+
*/
|
|
517
|
+
export async function shutdownLogging(): Promise<void> {
|
|
518
|
+
if (bootPromise) await bootPromise
|
|
519
|
+
await shutdownRuntime()
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
/** Runs historical recovery/retention now (tests, or a DSH maintenance hook). */
|
|
523
|
+
export async function runMaintenance(
|
|
524
|
+
options: { timeBudgetMs?: number; retentionDays?: number; minAgeMs?: number } = {},
|
|
525
|
+
): Promise<void> {
|
|
526
|
+
ensureInitialized()
|
|
527
|
+
await awaitRuntimeReady()
|
|
528
|
+
await runRuntimeMaintenance(options)
|
|
529
|
+
}
|
|
530
|
+
|
|
531
|
+
/**
|
|
532
|
+
* Creates the log root if it does not exist. Exposed for the DSH host's
|
|
533
|
+
* startup path, which may want to validate the destination before plugins load.
|
|
534
|
+
*/
|
|
535
|
+
export function ensureLogRoot(): string {
|
|
536
|
+
const cfg = currentConfig()
|
|
537
|
+
const root = cfg.dshLogRoot ?? getDshLogRoot(getDshIdentity()?.edgeInstanceId ?? null)
|
|
538
|
+
try {
|
|
539
|
+
if (!existsSync(root)) mkdirSync(root, { recursive: true })
|
|
540
|
+
} catch {
|
|
541
|
+
/* the runtime reports the failure with full context */
|
|
542
|
+
}
|
|
543
|
+
return root
|
|
544
|
+
}
|