@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/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 `
|
|
22
|
-
declare function getLogger(
|
|
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
|
|
121
|
-
* keeps the *same* `PluginLogger` surface
|
|
122
|
-
*
|
|
123
|
-
* `[
|
|
124
|
-
* argument — which is what the existing
|
|
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
|
|
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
|
-
|
|
203
|
+
pluginId,
|
|
204
|
+
component: pluginId,
|
|
154
205
|
msg: message
|
|
155
206
|
};
|
|
156
|
-
|
|
157
|
-
|
|
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)](`[${
|
|
213
|
+
console[consoleMethod(level)](`[${pluginId}] ${String(msg)}`, rest);
|
|
163
214
|
} catch {}
|
|
164
215
|
};
|
|
165
216
|
return {
|
|
166
|
-
|
|
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) =>
|
|
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 `
|
|
178
|
-
function getLogger(
|
|
179
|
-
return
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
71
|
-
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
91
|
-
declare function resetLogging(): void
|
|
92
|
-
/**
|
|
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
|
-
/**
|
|
95
|
-
declare function
|
|
96
|
-
/**
|
|
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
|
-
*
|
|
373
|
+
* Final flush + close + ownership release.
|
|
100
374
|
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
|
|
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
|
|
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 };
|