@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 ADDED
@@ -0,0 +1,118 @@
1
+ # @huaqiu/dsh-plugin-log
2
+
3
+ One shared log destination per **DSH process**, shared by every plugin loaded into
4
+ that process. Implements `docs/tasks/dsh-plugin-log-isolation.md`
5
+ (repo `hq-edge`); the implementation notes live in
6
+ `docs/dsh-plugin-log-isolation-implementation.md`.
7
+
8
+ The package name says "plugin log" because plugins are its users. The resource it
9
+ manages belongs to the DSH process: one process = one directory = one active file.
10
+
11
+ ## Ownership model
12
+
13
+ ```
14
+ installation_id HQ Edge installation (installation lifetime)
15
+ host_instance_id EDA Host (host process lifetime)
16
+ edge_instance_id HQ Edge (Edge process lifetime)
17
+ dsh_instance_id DSH runtime (DSH process lifetime) ← owned here
18
+ plugin_id attribution only — plugins own no files
19
+ ```
20
+
21
+ `dsh_instance_id` is generated **once per DSH launch**. A DSH restart creates a new
22
+ directory; a plugin reload does not. HQ Edge never generates or reuses a DSH
23
+ identity — it only passes the parent levels down in the environment.
24
+
25
+ ## Directory layout
26
+
27
+ ```
28
+ $HQ_EDGE_HOME/logs/instances/<edge-instance-id>/dsh/ ← DSH log root
29
+ <dsh-instance-id>/ ← owned by ONE DSH process
30
+ instance.json identity of this process (written once, atomically)
31
+ owner.lock diagnostic JSONL — existence NEVER implies ownership
32
+ dsh.2026-11-11.log active log (JSONL)
33
+ dsh.2026-11-11.1.log.gz published archives (atomic, never overwritten)
34
+ recovery.log historical-recovery diagnostics
35
+ fatal.log written only when the destination is unusable
36
+ ```
37
+
38
+ Root precedence: `configureLogging({ dir })` → `$DSH_LOG_ROOT` →
39
+ `$HQ_EDGE_INSTANCE_ID` (`<logs>/instances/<edge>/dsh`) → `<logs>/dsh` (standalone DSH).
40
+ The per-process directory is **always** appended, so no caller can point the package
41
+ at a shared file.
42
+
43
+ ## Usage
44
+
45
+ ```ts
46
+ import { getLogger, createLogger } from '@huaqiu/dsh-plugin-log'
47
+
48
+ const log = getLogger('dsh-auth') // legacy spelling
49
+ const log2 = createLogger({ pluginId: 'dsh-auth' }) // spec spelling, same thing
50
+
51
+ log.info('session restored', { user: 'u_1' })
52
+ log.error('token refresh failed', { status: 401 })
53
+ log.child({ module: 'refresh' }).warn('retrying')
54
+ ```
55
+
56
+ Plugins must **not** call `configureLogging`, `flushLogs`, `shutdownLogging` or
57
+ `runMaintenance`. Those belong to the DSH host: a plugin that closed the shared
58
+ destination would silence every other plugin in the process.
59
+
60
+ Every record carries `time`, `ts`, `level`, `msg`, `pluginId`, `component`
61
+ (legacy alias), `installationId`, `hostType`, `hostInstanceId`, `edgeInstanceId`,
62
+ `dshInstanceId`, `pid`. `RESERVED_FIELDS` cannot be overridden by `fields` — a
63
+ plugin cannot spoof its identity, its level or its message.
64
+
65
+ ## Host integration
66
+
67
+ | Call | Purpose |
68
+ | --- | --- |
69
+ | `configureLogging(options)` | DSH host / tests: root, level, rotation policy, clock, fault injection. Must run before the first record. |
70
+ | `installHostLogSink(sink)` | Delegate the transport to the DSH host instead of opening a file. Late installation is diagnosed, not applied. |
71
+ | `ready()` | Resolves once the destination is decided. |
72
+ | `flushLogs()` | Barrier: waits for the boot record and every pending write *and* any rotation they triggered. |
73
+ | `runMaintenance({ minAgeMs, retentionDays })` | Historical recovery + retention for sibling (dead) DSH directories. |
74
+ | `shutdownLogging()` | Final flush, close, release ownership. DSH shutdown only. |
75
+ | `getLoggingHealth()` | `state` (`initializing \| healthy \| degraded \| unavailable`), `droppedRecords`, `rotationCount`, `lastError`, `instanceDir`, `logFile`. |
76
+
77
+ Environment: `$DSH_LOG_ROOT`, `$HQ_EDGE_INSTANCE_ID`, `$HQ_EDGE_INSTALLATION_ID`,
78
+ `$HQ_HOST_TYPE`, `$HQ_HOST_INSTANCE_ID`, `$HQ_TARGET_HOST`, `$DSH_HOME`,
79
+ `$HQ_EDGE_HOME` (must be absolute), `$DSH_PLUGIN_LOG_LEVEL`,
80
+ `$DSH_PLUGIN_LOG_CONSOLE`. `$DSH_INSTANCE_ID` is accepted only as an injection hook
81
+ for tests/locally-driven runs — the parent must not set it in production.
82
+
83
+ ## Safety rules
84
+
85
+ - **Exclusive ownership is OS-backed**: a bound endpoint (Windows named pipe
86
+ `\\.\pipe\hq-edge-dsh-instance-<sha256(dir)>`, POSIX `<dir>/.owner.sock`). The OS
87
+ closes it when the owner dies, including on a crash, so no stale lock, no PID
88
+ heuristics, no heartbeat.
89
+ - **Historical work requires acquiring that directory's lock first.** If
90
+ acquisition fails, the directory is left byte-for-byte alone.
91
+ - **Rotation is asynchronous and streaming**: seal → compress → verify (gzip
92
+ trailer) → atomic publish (`link` + guarded `rename`) → delete source. Nothing
93
+ overwrites an existing archive; every failure keeps the original data and caps
94
+ unresolved artifacts at 6.
95
+ - **Bounded buffering before ownership exists** (2000 records / 1 MiB), replayed on
96
+ acquisition. There is deliberately **no fallback** to a shared writable file.
97
+ - **Logging never throws into plugin business logic.** Destination failures degrade
98
+ (`degraded`/`unavailable`) and count `droppedRecords` instead.
99
+ - **Process-wide state lives on `globalThis`**
100
+ (`Symbol.for('@huaqiu/dsh-plugin-log/runtime')`), so a duplicated or bundled copy
101
+ of this package joins the same destination instead of opening a second one.
102
+
103
+ ## Browser half
104
+
105
+ `@huaqiu/dsh-plugin-log/client` mirrors the same `PluginLogger` surface onto
106
+ `console` with a `[pluginId]` prefix and keeps a 200-record ring for `dumpPluginLogs()`.
107
+ It shares `redact` and `RESERVED_FIELDS` through `fields.ts`, a leaf module with no
108
+ imports, so the browser bundle never pulls `node:fs` / `node:os`.
109
+
110
+ ## Tests
111
+
112
+ ```sh
113
+ pnpm --filter @huaqiu/dsh-plugin-log test
114
+ ```
115
+
116
+ 93 tests / 9 files, including real-subprocess isolation tests
117
+ (`test/fixtures/dsh-probe.ts`) for multi-process, crash-recovery and
118
+ concurrent-write behaviour.
package/lib/client.d.ts CHANGED
@@ -11,6 +11,8 @@ type LogLevel = 'debug' | 'info' | 'warn' | 'error';
11
11
  //#region src/client.d.ts
12
12
  type LogFields = Record<string, unknown>;
13
13
  interface PluginLogger {
14
+ readonly pluginId: string;
15
+ /** @deprecated Legacy alias for `pluginId`. */
14
16
  readonly component: string;
15
17
  debug(message: string, fields?: LogFields): void;
16
18
  info(message: string, fields?: LogFields): void;
@@ -18,9 +20,13 @@ interface PluginLogger {
18
20
  error(message: string, fields?: LogFields): void;
19
21
  child(fields: LogFields): PluginLogger;
20
22
  }
21
- /** Get (or create) the browser logger for `component`. */
22
- declare function getLogger(component: string, defaults?: LogFields): PluginLogger;
23
+ /** Get (or create) the browser logger for `pluginId`. */
24
+ declare function getLogger(pluginId: string, defaults?: LogFields): PluginLogger;
25
+ /** Spec-shaped factory: `createLogger({ pluginId })`. */
26
+ declare function createLogger(options: {
27
+ pluginId: string;
28
+ }): PluginLogger;
23
29
  /** Snapshot of the in-memory ring — handy from the devtools console. */
24
30
  declare function dumpPluginLogs(): Array<Record<string, unknown>>;
25
31
  //#endregion
26
- export { LogFields, type LogLevel, PluginLogger, dumpPluginLogs, getLogger };
32
+ export { LogFields, type LogLevel, PluginLogger, createLogger, dumpPluginLogs, getLogger };
package/lib/client.js CHANGED
@@ -61,6 +61,13 @@ const SENSITIVE_KEY = /(token|secret|password|passwd|pwd|authorization|cookie|ap
61
61
  const BEARER_IN_STRING = /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/i;
62
62
  /** Strings at least this long that look like a single opaque credential blob. */
63
63
  const OPAQUE_SECRET = /^[A-Za-z0-9_-]{32,}$/;
64
+ /**
65
+ * UUIDs are identifiers, not secrets. Every record carries at least
66
+ * `installationId` / `edgeInstanceId` / `dshInstanceId`, all UUID-shaped, so
67
+ * without this exemption the shape-based rule would blank out exactly the
68
+ * fields that make a multi-process log attributable.
69
+ */
70
+ 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;
64
71
  const REDACTED = "[redacted]";
65
72
  /** Maximum object depth walked before the value is collapsed. Cycle-safe. */
66
73
  const MAX_DEPTH = 6;
@@ -109,26 +116,60 @@ function redactInner(value, depth, seen) {
109
116
  /** Redact credentials embedded in an otherwise ordinary string. */
110
117
  function redactString(value) {
111
118
  if (BEARER_IN_STRING.test(value)) return value.replace(BEARER_IN_STRING, "$1 " + REDACTED);
119
+ if (UUID_SHAPE.test(value)) return value;
112
120
  if (OPAQUE_SECRET.test(value)) return REDACTED;
113
121
  return value;
114
122
  }
115
123
  //#endregion
124
+ //#region src/fields.ts
125
+ /**
126
+ * Record fields owned by `@huaqiu/dsh-plugin-log`.
127
+ *
128
+ * Kept in a leaf module with NO runtime imports so the browser half can share
129
+ * the exact same reserved-field rule without pulling `node:fs` / `node:os`
130
+ * into a browser bundle.
131
+ */
132
+ /**
133
+ * A plugin's `fields` object may not override any of these. Without the rule a
134
+ * plugin could rewrite its own `pluginId` (mis-attributing records to another
135
+ * plugin) or promote a `debug` line to `error` — and the log would stop being
136
+ * evidence.
137
+ */
138
+ const RESERVED_FIELDS = /* @__PURE__ */ new Set([
139
+ "time",
140
+ "ts",
141
+ "level",
142
+ "msg",
143
+ "pid",
144
+ "schemaVersion",
145
+ "installationId",
146
+ "hostType",
147
+ "hostInstanceId",
148
+ "edgeInstanceId",
149
+ "dshInstanceId",
150
+ "pluginId",
151
+ "component"
152
+ ]);
153
+ //#endregion
116
154
  //#region src/client.ts
117
155
  /**
118
156
  * `@huaqiu/dsh-plugin-log/client` — browser half of the shared plugin log.
119
157
  *
120
- * The browser has no filesystem, so there is nothing to unify: this module
121
- * keeps the *same* `PluginLogger` surface as the node half (so a plugin can log
122
- * identically from either half) but writes to the console with a stable
123
- * `[component] message` prefix and a structured payload as the second
124
- * argument — which is what the existing client-side debugging already relies on.
158
+ * The browser has no filesystem and no DSH process identity, so there is no
159
+ * destination to isolate: this module keeps the *same* `PluginLogger` surface
160
+ * as the node half (so a plugin can log identically from either half) but
161
+ * writes to the console with a stable `[pluginId] message` prefix and a
162
+ * structured payload as the second argument — which is what the existing
163
+ * client-side debugging already relies on.
125
164
  *
126
165
  * It also keeps a small in-memory ring of the most recent records. That costs
127
166
  * nothing and gives a user something to copy out of the devtools console
128
167
  * (`dumpPluginLogs()`) when a file is not available.
129
168
  *
130
169
  * Redaction is shared with the node half, so a credential can never reach the
131
- * browser console through this logger either.
170
+ * browser console through this logger either. The reserved-field rule is shared
171
+ * too: a caller cannot rewrite `level`/`msg`/`pluginId` by passing them as
172
+ * context.
132
173
  */
133
174
  /** Most recent records kept in memory for `dumpPluginLogs()`. */
134
175
  const RING_SIZE = 200;
@@ -143,44 +184,59 @@ function consoleMethod(level) {
143
184
  if (level === "info") return "info";
144
185
  return "log";
145
186
  }
146
- function createLogger(component, defaults) {
187
+ function sanitize(fields) {
188
+ if (!fields) return {};
189
+ const out = {};
190
+ for (const [key, value] of Object.entries(fields)) {
191
+ if (RESERVED_FIELDS.has(key)) continue;
192
+ out[key] = value;
193
+ }
194
+ return out;
195
+ }
196
+ function createLoggerFor(pluginId, defaults) {
147
197
  const emit = (level, message, fields) => {
148
198
  try {
149
199
  if (!isEnabled(level, currentLevel())) return;
150
200
  const record = {
151
201
  ts: (/* @__PURE__ */ new Date()).toISOString(),
152
202
  level,
153
- component,
203
+ pluginId,
204
+ component: pluginId,
154
205
  msg: message
155
206
  };
156
- if (Object.keys(defaults).length > 0) Object.assign(record, defaults);
157
- if (fields && Object.keys(fields).length > 0) Object.assign(record, fields);
207
+ Object.assign(record, sanitize(defaults));
208
+ Object.assign(record, sanitize(fields));
158
209
  const safe = redact(record);
159
210
  ring.push(safe);
160
211
  if (ring.length > RING_SIZE) ring.shift();
161
212
  const { msg, ...rest } = safe;
162
- console[consoleMethod(level)](`[${component}] ${String(msg)}`, rest);
213
+ console[consoleMethod(level)](`[${pluginId}] ${String(msg)}`, rest);
163
214
  } catch {}
164
215
  };
165
216
  return {
166
- component,
217
+ pluginId,
218
+ component: pluginId,
167
219
  debug: (message, fields) => emit("debug", message, fields),
168
220
  info: (message, fields) => emit("info", message, fields),
169
221
  warn: (message, fields) => emit("warn", message, fields),
170
222
  error: (message, fields) => emit("error", message, fields),
171
- child: (fields) => createLogger(component, {
223
+ child: (fields) => createLoggerFor(pluginId, {
172
224
  ...defaults,
173
225
  ...fields
174
226
  })
175
227
  };
176
228
  }
177
- /** Get (or create) the browser logger for `component`. */
178
- function getLogger(component, defaults = {}) {
179
- return createLogger(component, defaults);
229
+ /** Get (or create) the browser logger for `pluginId`. */
230
+ function getLogger(pluginId, defaults = {}) {
231
+ return createLoggerFor(pluginId, defaults);
232
+ }
233
+ /** Spec-shaped factory: `createLogger({ pluginId })`. */
234
+ function createLogger(options) {
235
+ return createLoggerFor(options.pluginId, {});
180
236
  }
181
237
  /** Snapshot of the in-memory ring — handy from the devtools console. */
182
238
  function dumpPluginLogs() {
183
239
  return ring.slice();
184
240
  }
185
241
  //#endregion
186
- export { dumpPluginLogs, getLogger };
242
+ export { createLogger, dumpPluginLogs, getLogger };
package/lib/index.d.mts CHANGED
@@ -20,6 +20,138 @@ declare function levelRank(level: LogLevel): number;
20
20
  */
21
21
  declare function parseLevel(value: unknown, fallback: LogLevel): LogLevel;
22
22
  //#endregion
23
+ //#region src/fields.d.ts
24
+ /**
25
+ * Record fields owned by `@huaqiu/dsh-plugin-log`.
26
+ *
27
+ * Kept in a leaf module with NO runtime imports so the browser half can share
28
+ * the exact same reserved-field rule without pulling `node:fs` / `node:os`
29
+ * into a browser bundle.
30
+ */
31
+ /**
32
+ * A plugin's `fields` object may not override any of these. Without the rule a
33
+ * plugin could rewrite its own `pluginId` (mis-attributing records to another
34
+ * plugin) or promote a `debug` line to `error` — and the log would stop being
35
+ * evidence.
36
+ */
37
+ declare const RESERVED_FIELDS: ReadonlySet<string>;
38
+ //#endregion
39
+ //#region src/identity.d.ts
40
+ /** Written once per DSH process, atomically, never overwritten. */
41
+ declare const INSTANCE_METADATA_FILENAME = "instance.json";
42
+ /** Diagnostic JSONL. Its EXISTENCE never implies ownership. */
43
+ declare const OWNER_LOCK_FILENAME = "owner.lock";
44
+ type DshLogRootSource = 'override' | 'env:DSH_LOG_ROOT' | 'edge-instance' | 'unscoped';
45
+ /** Everything the environment tells this DSH process about its place in the tree. */
46
+ interface DshLogContext {
47
+ /** Directory that contains one subdirectory per DSH instance. */
48
+ readonly dshLogRoot: string;
49
+ /** Why the root resolved to that path (surfaced in the boot record). */
50
+ readonly dshLogRootSource: DshLogRootSource;
51
+ readonly installationId: string | null;
52
+ readonly edgeInstanceId: string | null;
53
+ readonly hostType: string | null;
54
+ readonly hostInstanceId: string | null;
55
+ readonly targetHost: string | null;
56
+ readonly dshHome: string | null;
57
+ readonly hqEdgeHome: string;
58
+ /** Non-fatal problems found while reading the environment. */
59
+ readonly warnings: readonly string[];
60
+ }
61
+ interface DshInstanceMetadata {
62
+ readonly schemaVersion: number;
63
+ readonly dshInstanceId: string;
64
+ readonly installationId: string | null;
65
+ readonly edgeInstanceId: string | null;
66
+ readonly hostType: string | null;
67
+ readonly hostInstanceId: string | null;
68
+ readonly targetHost: string | null;
69
+ readonly pid: number;
70
+ readonly startedAt: string;
71
+ /** Version of `@huaqiu/dsh-plugin-log` that produced the directory. */
72
+ readonly version: string;
73
+ readonly dshHome: string | null;
74
+ readonly logRoot: string;
75
+ }
76
+ //#endregion
77
+ //#region src/rotation.d.ts
78
+ /** Rotation + retention policy for the DSH log stream. */
79
+ interface DshRotationConfig {
80
+ /** Rotation frequency. Only "daily" is supported. */
81
+ frequency: 'daily';
82
+ /** Max size of a single log file before rotation, e.g. "10m". */
83
+ maxSize: string;
84
+ /** Days to keep rotated (compressed) files. */
85
+ retentionDays: number;
86
+ /** Maximum total bytes this DSH instance directory may consume. */
87
+ maxStorageBytes: number;
88
+ /** Gzip rotated files. */
89
+ compress: boolean;
90
+ }
91
+ /**
92
+ * Defaults for DSH plugin logs: plugin diagnostics are low volume, so 10 MiB
93
+ * per file with 14 days of history is plenty, and 256 MiB caps a pathological
94
+ * plugin without competing with the parent Edge instance's own budget.
95
+ */
96
+ declare const DSH_ROTATION: DshRotationConfig;
97
+ /** Parses a human size string ("10m", "1g", "500k", or "1024") into bytes. */
98
+ declare function parseSize(input: string): number;
99
+ /** Current UTC date as `yyyy-MM-dd`. UTC keeps multi-timezone installs stable. */
100
+ declare function todayString(date?: Date): string;
101
+ type LoggingHealthState = 'initializing' | 'healthy' | 'degraded' | 'unavailable';
102
+ interface LoggingHealth {
103
+ state: LoggingHealthState;
104
+ reason: string;
105
+ droppedRecords: number;
106
+ rotationCount: number;
107
+ lastError: string | null;
108
+ }
109
+ /** Injected faults — production never sets these; tests do. */
110
+ interface DshRotationFaults {
111
+ gzip?: boolean;
112
+ publish?: boolean;
113
+ seal?: boolean;
114
+ unlink?: boolean;
115
+ streamOpen?: boolean;
116
+ /** Delay BEFORE compression — lets a test kill the process mid-compression. */
117
+ gzipDelayMs?: number;
118
+ /** Delay BEFORE publication — lets a test kill the process mid-publication. */
119
+ publishDelayMs?: number;
120
+ /** Simulate ENOSPC on the active write stream. */
121
+ diskFull?: boolean;
122
+ }
123
+ //#endregion
124
+ //#region src/runtime.d.ts
125
+ /**
126
+ * A sink supplied by the DSH host. When present the package delegates the
127
+ * actual transport (and its lifecycle) to DSH instead of opening its own file
128
+ * — the preferred integration when DSH exposes a native logging service.
129
+ */
130
+ interface HostLogSink {
131
+ write(line: string): void;
132
+ flush?(): Promise<void>;
133
+ close?(): void;
134
+ }
135
+ type OwnershipState = 'pending' | 'held' | 'skipped' | 'unavailable';
136
+ /**
137
+ * Installs a DSH-host-provided sink. MUST be called before the first log
138
+ * record: once the package has established its own destination (and taken the
139
+ * ownership lock), silently switching transports would abandon a directory it
140
+ * owns. A late call is ignored and diagnosed rather than throwing.
141
+ */
142
+ declare function installHostLogSink(sink: HostLogSink | null): void;
143
+ interface DshRuntimeSnapshot {
144
+ readonly dshInstanceId: string | null;
145
+ readonly instanceDir: string | null;
146
+ readonly logFile: string | null;
147
+ readonly logRoot: string | null;
148
+ readonly ready: boolean;
149
+ readonly ownership: OwnershipState;
150
+ readonly degradedReason: string | null;
151
+ readonly droppedBeforeReady: number;
152
+ readonly health: LoggingHealth | null;
153
+ }
154
+ //#endregion
23
155
  //#region src/redact.d.ts
24
156
  /**
25
157
  * Credential redaction for `@huaqiu/dsh-plugin-log`.
@@ -51,11 +183,102 @@ declare const REDACTED = "[redacted]";
51
183
  */
52
184
  declare function redact(value: unknown, depth?: number): unknown;
53
185
  //#endregion
186
+ //#region src/ownership.d.ts
187
+ interface DshOwnershipHandle {
188
+ readonly instanceDir: string;
189
+ readonly dshInstanceId: string;
190
+ readonly released: boolean;
191
+ /** Idempotent. Releases the OS handle; never deletes another owner's data. */
192
+ release(): void;
193
+ }
194
+ /**
195
+ * Attempts exclusive ownership. Returns `null` when another live process owns
196
+ * the directory — callers MUST then leave the directory completely alone.
197
+ *
198
+ * Asynchronous because a socket bind resolves on the event loop. The runtime
199
+ * gates opening the active log file on this promise, so no active file is ever
200
+ * written before ownership is established.
201
+ */
202
+ declare function acquireDshOwnership(instanceDir: string, dshInstanceId: string, options?: {
203
+ diagnostics?: boolean;
204
+ }): Promise<DshOwnershipHandle | null>;
205
+ /** Non-destructive probe: true when nobody currently owns the directory. */
206
+ declare function probeDshOwnership(instanceDir: string): Promise<boolean>;
207
+ //#endregion
208
+ //#region src/recovery.d.ts
209
+ interface DshMaintenanceOptions {
210
+ /** The DSH log root (`<edge>/dsh`). Each child directory is one DSH instance. */
211
+ instancesRoot: string;
212
+ /** This process's own directory — never touched by maintenance. */
213
+ ownInstanceDir: string;
214
+ maxDirectories?: number;
215
+ maxFilesPerDirectory?: number;
216
+ timeBudgetMs?: number;
217
+ /** A directory younger than this is assumed to be a live, just-started process. */
218
+ minAgeMs?: number;
219
+ now?: () => number;
220
+ /** Structured sink into the CURRENT process's log (never a historical one). */
221
+ report?: (record: Record<string, unknown>) => void;
222
+ }
223
+ interface DshMaintenanceReport {
224
+ scanned: number;
225
+ skippedLive: number;
226
+ skippedInvalid: number;
227
+ skippedRecent: number;
228
+ recovered: number;
229
+ preserved: number;
230
+ quarantined: number;
231
+ deletedFiles: number;
232
+ deletedDirectories: number;
233
+ truncated: boolean;
234
+ details: Array<{
235
+ dir: string;
236
+ action: string;
237
+ detail?: string;
238
+ }>;
239
+ }
240
+ /**
241
+ * Repairs incomplete rotation artifacts left by a previous DSH process.
242
+ * Safe to run repeatedly and safe to run while other DSH processes are active
243
+ * (their directories are skipped because their ownership lock is held).
244
+ */
245
+ declare function recoverDshInstances(options: DshMaintenanceOptions): Promise<DshMaintenanceReport>;
246
+ /**
247
+ * Per-instance retention. Never deletes an active directory: ownership
248
+ * acquisition fails while the owner is alive. Never deletes a directory that
249
+ * still has incomplete recovery artifacts.
250
+ */
251
+ declare function cleanupExpiredDshInstances(options: DshMaintenanceOptions & {
252
+ retentionDays?: number;
253
+ }): Promise<DshMaintenanceReport>;
254
+ interface LegacyPluginLogReport {
255
+ files: Array<{
256
+ path: string;
257
+ size: number;
258
+ action: 'preserved';
259
+ }>;
260
+ totalBytes: number;
261
+ note: string;
262
+ }
263
+ /**
264
+ * Conservative handling of the pre-isolation shared plugin log (§3).
265
+ *
266
+ * Old builds wrote `<HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log[.N]` from
267
+ * every plugin in every DSH process. Those files have no ownership metadata
268
+ * and may still be written by an older build during a rolling upgrade, so this
269
+ * function only REPORTS them. Nothing is moved, compressed or deleted: a
270
+ * one-time, operator-reviewed migration is the only safe way to retire them.
271
+ */
272
+ declare function reportLegacyPluginLogs(logBaseDir: string): Promise<LegacyPluginLogReport>;
273
+ //#endregion
54
274
  //#region src/index.d.ts
55
275
  /** Arbitrary structured context attached to a log record. */
56
276
  type LogFields = Record<string, unknown>;
57
277
  /** The logger surface every plugin codes against. */
58
278
  interface PluginLogger {
279
+ /** Plugin that owns these records (`pluginId`, e.g. `dsh-auth`). */
280
+ readonly pluginId: string;
281
+ /** @deprecated Legacy alias for `pluginId`; kept for existing call sites. */
59
282
  readonly component: string;
60
283
  debug(message: string, fields?: LogFields): void;
61
284
  info(message: string, fields?: LogFields): void;
@@ -65,43 +288,104 @@ interface PluginLogger {
65
288
  child(fields: LogFields): PluginLogger;
66
289
  }
67
290
  interface LoggingOptions {
68
- /** Override the log directory (highest precedence, beats every env var). */
291
+ /**
292
+ * DSH log ROOT. The per-process instance directory is always appended, so a
293
+ * shared directory can never be written directly. Highest precedence, beats
294
+ * `$DSH_LOG_ROOT` and `$HQ_EDGE_INSTANCE_ID`.
295
+ */
69
296
  dir?: string;
70
- /** Base file name inside the directory. Default `dsh-plugins.log`. */
71
- fileName?: string;
297
+ /** Alias for {@link dir}, with a name that says what it is. */
298
+ dshLogRoot?: string;
299
+ /** Test/host injection of `dsh_instance_id`. Production generates one. */
300
+ dshInstanceId?: string;
72
301
  /** Minimum file level. Default from `$DSH_PLUGIN_LOG_LEVEL`, else `info`. */
73
302
  level?: LogLevel;
74
303
  /**
75
- * Minimum level mirrored to the console. HQ Edge captures DSH's stdout, so
304
+ * Minimum level mirrored to DSH's stdout. HQ Edge captures that stream, so
76
305
  * this is how a plugin surfaces a problem without anyone opening a file.
77
306
  * Default from `$DSH_PLUGIN_LOG_CONSOLE`, else `warn`.
78
307
  */
79
308
  consoleLevel?: LogLevel | 'off';
80
- /** Rotate once the current file exceeds this many bytes. Default 5 MiB. */
309
+ /** Rotate once the active file exceeds this size. Default 10 MiB. */
310
+ maxSize?: string;
311
+ /** @deprecated Use {@link maxSize}. Converted to a byte count. */
81
312
  maxBytes?: number;
82
- /** Number of files kept (current + rotated). Default 4. */
313
+ /** @deprecated Retained for source compatibility; superseded by date+size rotation. */
83
314
  maxFiles?: number;
315
+ /** Days of compressed history to keep. Default 14. */
316
+ retentionDays?: number;
317
+ /** Total bytes this instance directory may consume. Default 256 MiB. */
318
+ maxStorageBytes?: number;
319
+ /** Gzip rotated files. Default true. */
320
+ compress?: boolean;
321
+ /** Test-only fault injection for rotation. */
322
+ faults?: DshRotationFaults;
323
+ /** Test-only: bypass the OS ownership lock. */
324
+ skipOwnership?: boolean;
325
+ /** Clock override (tests). */
326
+ now?: () => Date;
327
+ /** Internal diagnostic sink (tests). */
328
+ onDiagnostic?: (record: Record<string, unknown>) => void;
84
329
  }
85
330
  /**
86
331
  * Programmatically configure logging. Call before the first `getLogger()`;
87
- * later calls take effect on the next `resetLogging()` (tests, host re-init).
332
+ * once the destination is established a later call only takes effect after
333
+ * {@link shutdownLogging} + {@link resetLogging} (tests, host re-init).
88
334
  */
89
335
  declare function configureLogging(options: LoggingOptions): void;
90
- /** Forget all configuration and cached loggers. Test/teardown helper. */
91
- declare function resetLogging(): void;
92
- /** Absolute path of the current log file, or `null` before first use. */
336
+ /** Forgets all configuration and cached state. Test/teardown helper. */
337
+ declare function resetLogging(): Promise<void>;
338
+ /**
339
+ * Gets (or creates) the logger for `pluginId`.
340
+ *
341
+ * `pluginId` should be the value used everywhere else in that plugin's output —
342
+ * `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen`, or the full package name
343
+ * (`@huaqiu/dsh-plugin-eda`) when that is less ambiguous. It is attached to
344
+ * every record, which is what makes per-plugin filtering possible without a
345
+ * file per plugin.
346
+ */
347
+ declare function getLogger(pluginId: string, defaults?: LogFields): PluginLogger;
348
+ /** Spec-shaped factory: `createLogger({ pluginId })`. Equivalent to `getLogger`. */
349
+ declare function createLogger(options: {
350
+ pluginId: string;
351
+ }): PluginLogger;
352
+ /** Absolute directory this DSH process exclusively owns, or null before init. */
353
+ declare function logDir(): string | null;
354
+ /** Absolute path of the active log file, or null before it is open. */
93
355
  declare function logFilePath(): string | null;
94
- /** Absolute directory plugin logs are written to. */
95
- declare function logDir(): string;
96
- /** Wait for all pending writes to land (shutdown hooks, tests). */
356
+ /** Root that contains one directory per DSH instance. */
357
+ declare function logRoot(): string | null;
358
+ /** Identity of this DSH process (null before initialization). */
359
+ declare function dshInstanceInfo(): DshRuntimeSnapshot;
360
+ interface LoggingHealthReport extends LoggingHealth {
361
+ instanceDir: string | null;
362
+ logFile: string | null;
363
+ ownership: DshRuntimeSnapshot['ownership'];
364
+ degradedReason: string | null;
365
+ }
366
+ /** Destination health, for a diagnostics/health endpoint or a support bundle. */
367
+ declare function getLoggingHealth(): LoggingHealthReport;
368
+ /** Waits until the destination is decided. For tests and startup diagnostics. */
369
+ declare function ready(): Promise<boolean>;
370
+ /** Waits for all pending records (and any rotation they triggered) to land. */
97
371
  declare function flushLogs(): Promise<void>;
98
372
  /**
99
- * Get (or create) the logger for `component`.
373
+ * Final flush + close + ownership release.
100
374
  *
101
- * `component` should be the short plugin name used everywhere else in its
102
- * output — `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen` — so the unified
103
- * file can be filtered with a single grep.
375
+ * Owned by the DSH host. A plugin must NEVER call this: it would close the
376
+ * shared destination for every other plugin in the process.
377
+ */
378
+ declare function shutdownLogging(): Promise<void>;
379
+ /** Runs historical recovery/retention now (tests, or a DSH maintenance hook). */
380
+ declare function runMaintenance(options?: {
381
+ timeBudgetMs?: number;
382
+ retentionDays?: number;
383
+ minAgeMs?: number;
384
+ }): Promise<void>;
385
+ /**
386
+ * Creates the log root if it does not exist. Exposed for the DSH host's
387
+ * startup path, which may want to validate the destination before plugins load.
104
388
  */
105
- declare function getLogger(component: string, defaults?: LogFields): PluginLogger;
389
+ declare function ensureLogRoot(): string;
106
390
  //#endregion
107
- export { LOG_LEVELS, LogFields, type LogLevel, LoggingOptions, PluginLogger, REDACTED, configureLogging, flushLogs, getLogger, levelRank, logDir, logFilePath, parseLevel, redact, resetLogging };
391
+ export { DSH_ROTATION, type DshInstanceMetadata, type DshLogContext, type DshMaintenanceOptions, type DshMaintenanceReport, type DshOwnershipHandle, type DshRotationConfig, type DshRotationFaults, type HostLogSink, INSTANCE_METADATA_FILENAME, LOG_LEVELS, type LegacyPluginLogReport, LogFields, type LogLevel, type LoggingHealth, LoggingHealthReport, type LoggingHealthState, LoggingOptions, OWNER_LOCK_FILENAME, PluginLogger, REDACTED, RESERVED_FIELDS, acquireDshOwnership, cleanupExpiredDshInstances, configureLogging, createLogger, dshInstanceInfo, ensureLogRoot, flushLogs, getLogger, getLoggingHealth, installHostLogSink, levelRank, logDir, logFilePath, logRoot, parseLevel, parseSize, probeDshOwnership, ready, recoverDshInstances, redact, reportLegacyPluginLogs, resetLogging, runMaintenance, shutdownLogging, todayString };