@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/lib/index.mjs
CHANGED
|
@@ -1,83 +1,12 @@
|
|
|
1
|
-
import { mkdirSync,
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
*
|
|
11
|
-
* ────────────────────────────────────────────────────────────────────────────
|
|
12
|
-
* Shared path resolution for HQ Edge runtimes.
|
|
13
|
-
*
|
|
14
|
-
* The single source of truth for where HQ Edge places per-user directories.
|
|
15
|
-
* `getHqEdgeHome()` is the root: every other path getter (`getLogBaseDir`,
|
|
16
|
-
* `getLogDir`) is derived from it, so all HQ Edge user directories live under
|
|
17
|
-
* one self-contained tree and every consumer resolves the same location.
|
|
18
|
-
*
|
|
19
|
-
* The home is **the same on every platform** — `~/.hq-edge/` — because HQ Edge
|
|
20
|
-
* is a developer/EDA runtime environment rather than a conventional desktop
|
|
21
|
-
* app: a single dotfile under `$HOME` keeps logging, diagnostics, DSH
|
|
22
|
-
* integration, CLI behavior and documentation identical on macOS / Linux /
|
|
23
|
-
* Windows, instead of introducing a second filesystem convention
|
|
24
|
-
* (`%LOCALAPPDATA%\hq-edge` or `~/.local/share/hq-edge`) per platform.
|
|
25
|
-
* `HQ_EDGE_HOME` is the universal escape hatch (tests, bundling, portable
|
|
26
|
-
* installs, CI).
|
|
27
|
-
*
|
|
28
|
-
* Note: the immutable HQ Edge runtime (`<installRoot>/dsh`,
|
|
29
|
-
* `<installRoot>/dsh-plugins`) and `<KiCad installation>/` (application
|
|
30
|
-
* install) are deliberately NOT this home — user data, managed runtime and
|
|
31
|
-
* installation stay distinct. Mutable per-version DSH state lives UNDER this
|
|
32
|
-
* home at `<home>/<version>/dsh-home` (see dshHome.ts). The
|
|
33
|
-
* `~/.hq/hq-edge/<version>/` path from an earlier design draft never landed.
|
|
34
|
-
*/
|
|
35
|
-
/**
|
|
36
|
-
* Resolves the per-user data home directory for HQ Edge — the single root from
|
|
37
|
-
* which every other HQ Edge path getter is derived.
|
|
38
|
-
*
|
|
39
|
-
* macOS / Linux / Windows: ~/.hq-edge/
|
|
40
|
-
*
|
|
41
|
-
* Unconditional across platforms (see the file header for the rationale). The
|
|
42
|
-
* path may be overridden explicitly via `override` or the `HQ_EDGE_HOME`
|
|
43
|
-
* environment variable (useful for tests / bundling / portable installs).
|
|
44
|
-
*/
|
|
45
|
-
function getHqEdgeHome(override) {
|
|
46
|
-
if (override) return override;
|
|
47
|
-
if (process.env.HQ_EDGE_HOME) return process.env.HQ_EDGE_HOME;
|
|
48
|
-
return join(homedir(), ".hq-edge");
|
|
49
|
-
}
|
|
50
|
-
/**
|
|
51
|
-
* Resolves the base log directory for HQ Edge.
|
|
52
|
-
*
|
|
53
|
-
* Built on top of `getHqEdgeHome()` as `<home>/logs` on every platform, so
|
|
54
|
-
* logs live inside the HQ Edge home tree:
|
|
55
|
-
*
|
|
56
|
-
* macOS / Linux / Windows: ~/.hq-edge/logs/
|
|
57
|
-
*
|
|
58
|
-
* The path may be overridden explicitly via `override` or the
|
|
59
|
-
* `HQ_EDGE_LOG_DIR` environment variable.
|
|
60
|
-
*/
|
|
61
|
-
function getLogBaseDir(override) {
|
|
62
|
-
if (override) return override;
|
|
63
|
-
if (process.env.HQ_EDGE_LOG_DIR) return process.env.HQ_EDGE_LOG_DIR;
|
|
64
|
-
return join(getHqEdgeHome(), "logs");
|
|
65
|
-
}
|
|
66
|
-
/**
|
|
67
|
-
* Resolves the per-component log directory, e.g. `<base>/dsh-plugins/`.
|
|
68
|
-
*
|
|
69
|
-
* The directory is created on demand by the rotating file stream.
|
|
70
|
-
*
|
|
71
|
-
* Note: the directory name is the component verbatim — there is no implicit
|
|
72
|
-
* version scoping. Callers that need version isolation (e.g. the DSH home,
|
|
73
|
-
* which keeps one tree per HQ Edge release) must layer it on top of
|
|
74
|
-
* `getHqEdgeHome()` themselves. Cross-version logs (server, plugin diagnostics)
|
|
75
|
-
* intentionally share a tree so a single `tail -F` follows them across upgrades.
|
|
76
|
-
*/
|
|
77
|
-
function getLogDir(component, baseDirOverride) {
|
|
78
|
-
return join(getLogBaseDir(baseDirOverride), component);
|
|
79
|
-
}
|
|
80
|
-
//#endregion
|
|
1
|
+
import { closeSync, createReadStream, createWriteStream, existsSync, fsyncSync, linkSync, mkdirSync, openSync, promises, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
4
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
5
|
+
import { fileURLToPath } from "node:url";
|
|
6
|
+
import { createConnection, createServer } from "node:net";
|
|
7
|
+
import { createGunzip, createGzip } from "node:zlib";
|
|
8
|
+
import { pipeline } from "node:stream/promises";
|
|
9
|
+
import { Writable } from "node:stream";
|
|
81
10
|
//#region src/levels.ts
|
|
82
11
|
/** Levels ordered from most to least verbose. */
|
|
83
12
|
const LOG_LEVELS = [
|
|
@@ -141,6 +70,13 @@ const SENSITIVE_KEY = /(token|secret|password|passwd|pwd|authorization|cookie|ap
|
|
|
141
70
|
const BEARER_IN_STRING = /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/i;
|
|
142
71
|
/** Strings at least this long that look like a single opaque credential blob. */
|
|
143
72
|
const OPAQUE_SECRET = /^[A-Za-z0-9_-]{32,}$/;
|
|
73
|
+
/**
|
|
74
|
+
* UUIDs are identifiers, not secrets. Every record carries at least
|
|
75
|
+
* `installationId` / `edgeInstanceId` / `dshInstanceId`, all UUID-shaped, so
|
|
76
|
+
* without this exemption the shape-based rule would blank out exactly the
|
|
77
|
+
* fields that make a multi-process log attributable.
|
|
78
|
+
*/
|
|
79
|
+
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;
|
|
144
80
|
const REDACTED = "[redacted]";
|
|
145
81
|
/** Maximum object depth walked before the value is collapsed. Cycle-safe. */
|
|
146
82
|
const MAX_DEPTH = 6;
|
|
@@ -189,348 +125,2438 @@ function redactInner(value, depth, seen) {
|
|
|
189
125
|
/** Redact credentials embedded in an otherwise ordinary string. */
|
|
190
126
|
function redactString(value) {
|
|
191
127
|
if (BEARER_IN_STRING.test(value)) return value.replace(BEARER_IN_STRING, "$1 " + REDACTED);
|
|
128
|
+
if (UUID_SHAPE.test(value)) return value;
|
|
192
129
|
if (OPAQUE_SECRET.test(value)) return REDACTED;
|
|
193
130
|
return value;
|
|
194
131
|
}
|
|
195
132
|
//#endregion
|
|
196
|
-
//#region src/
|
|
133
|
+
//#region src/paths.ts
|
|
197
134
|
/**
|
|
198
|
-
* `@
|
|
135
|
+
* Inlined from `@hqedge/paths` (hq-edge/packages/paths/src/index.ts) so this
|
|
136
|
+
* package stays fully self-contained — no runtime dependency on the published
|
|
137
|
+
* package. Keep in sync when `@hqedge/paths` changes its path conventions.
|
|
199
138
|
*
|
|
200
|
-
*
|
|
139
|
+
* ────────────────────────────────────────────────────────────────────────────
|
|
140
|
+
* Shared path resolution for HQ Edge runtimes.
|
|
201
141
|
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
*
|
|
205
|
-
*
|
|
206
|
-
*
|
|
207
|
-
* propagation, the only way to see what the node half resolved was to add
|
|
208
|
-
* temporary prints and re-run.
|
|
142
|
+
* The home is **the same on every platform** — `~/.hq-edge/` — because HQ Edge
|
|
143
|
+
* is a developer/EDA runtime environment rather than a conventional desktop
|
|
144
|
+
* app: a single dotfile under `$HOME` keeps logging, diagnostics, DSH
|
|
145
|
+
* integration, CLI behavior and documentation identical on macOS / Linux /
|
|
146
|
+
* Windows.
|
|
209
147
|
*
|
|
210
|
-
*
|
|
211
|
-
* inside the current HQ Edge log tree:
|
|
148
|
+
* ## Log tree layout (docs/tasks/dsh-plugin-log-isolation.md §3)
|
|
212
149
|
*
|
|
213
|
-
* <
|
|
214
|
-
*
|
|
150
|
+
* <home>/logs/instances/<edge-instance-id>/
|
|
151
|
+
* server.<date>.log ← owned by the HQ Edge process
|
|
152
|
+
* dsh/
|
|
153
|
+
* <dsh-instance-id>/
|
|
154
|
+
* instance.json ← this package writes it
|
|
155
|
+
* owner.lock ← diagnostic only
|
|
156
|
+
* dsh.<date>.log ← owned by THIS DSH process
|
|
157
|
+
* dsh.<date>.log.gz ← published archive
|
|
215
158
|
*
|
|
216
|
-
*
|
|
159
|
+
* A DSH process never writes into another DSH process's directory, and never
|
|
160
|
+
* into its parent Edge instance directory: it only appends the
|
|
161
|
+
* `<dsh-instance-id>` level below the `dsh/` root it is handed.
|
|
217
162
|
*
|
|
218
|
-
*
|
|
219
|
-
* (
|
|
220
|
-
*
|
|
163
|
+
* `HQ_EDGE_HOME` / `HQ_EDGE_LOG_DIR` / `DSH_LOG_ROOT` are the escape hatches
|
|
164
|
+
* (tests, portable installs, CI). Per repository convention a relative
|
|
165
|
+
* `HQ_EDGE_HOME` is ignored rather than resolved against the CWD.
|
|
166
|
+
*/
|
|
167
|
+
/** True for a non-empty absolute path — the only accepted override shape. */
|
|
168
|
+
function absoluteOverride(value) {
|
|
169
|
+
if (value === void 0) return void 0;
|
|
170
|
+
const trimmed = value.trim();
|
|
171
|
+
if (trimmed.length === 0) return void 0;
|
|
172
|
+
return isAbsolute(trimmed) ? trimmed : void 0;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Resolves the per-user data home directory for HQ Edge — the single root from
|
|
176
|
+
* which every other HQ Edge path getter is derived.
|
|
221
177
|
*
|
|
222
|
-
*
|
|
223
|
-
* <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log (previous, after rotation)
|
|
178
|
+
* macOS / Linux / Windows: ~/.hq-edge/
|
|
224
179
|
*
|
|
225
|
-
*
|
|
180
|
+
* The path may be overridden explicitly via `override` or the `HQ_EDGE_HOME`
|
|
181
|
+
* environment variable (tests / bundling / portable installs).
|
|
182
|
+
*/
|
|
183
|
+
function getHqEdgeHome(override) {
|
|
184
|
+
return getHqEdgeHomeFrom(process.env, override);
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* Environment-parameterized form of {@link getHqEdgeHome}. Identity resolution
|
|
188
|
+
* uses this so the result depends on the environment it was HANDED, never on
|
|
189
|
+
* whatever `process.env` happens to contain at that moment.
|
|
190
|
+
*/
|
|
191
|
+
function getHqEdgeHomeFrom(env, override) {
|
|
192
|
+
const explicit = absoluteOverride(override);
|
|
193
|
+
if (explicit) return explicit;
|
|
194
|
+
const fromEnv = absoluteOverride(env.HQ_EDGE_HOME);
|
|
195
|
+
if (fromEnv) return fromEnv;
|
|
196
|
+
return join(homedir(), ".hq-edge");
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Resolves the base log directory for HQ Edge: `<home>/logs` on every
|
|
200
|
+
* platform. Overridable via `override` or `HQ_EDGE_LOG_DIR`.
|
|
201
|
+
*/
|
|
202
|
+
function getLogBaseDir(override) {
|
|
203
|
+
return getLogBaseDirFrom(process.env, override);
|
|
204
|
+
}
|
|
205
|
+
/** Environment-parameterized form of {@link getLogBaseDir}. */
|
|
206
|
+
function getLogBaseDirFrom(env, override) {
|
|
207
|
+
const explicit = absoluteOverride(override);
|
|
208
|
+
if (explicit) return explicit;
|
|
209
|
+
const fromEnv = absoluteOverride(env.HQ_EDGE_LOG_DIR);
|
|
210
|
+
if (fromEnv) return fromEnv;
|
|
211
|
+
return join(getHqEdgeHomeFrom(env), "logs");
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* `<base>/instances/<edge-instance-id>/dsh` — the DSH log root owned by one HQ
|
|
215
|
+
* Edge process. Every DSH launch under that process creates its own child
|
|
216
|
+
* directory here.
|
|
226
217
|
*
|
|
227
|
-
*
|
|
218
|
+
* When `edgeInstanceId` is unknown (a standalone `dsh` used in development or a
|
|
219
|
+
* test), the root degrades to `<base>/dsh`, deliberately WITHOUT an
|
|
220
|
+
* `instances/<id>` level: inventing an Edge identity would attribute DSH logs
|
|
221
|
+
* to an HQ Edge process that does not exist.
|
|
222
|
+
*/
|
|
223
|
+
function getDshLogRoot(edgeInstanceId, baseDirOverride) {
|
|
224
|
+
return getDshLogRootFrom(process.env, edgeInstanceId, baseDirOverride);
|
|
225
|
+
}
|
|
226
|
+
/** Environment-parameterized form of {@link getDshLogRoot}. */
|
|
227
|
+
function getDshLogRootFrom(env, edgeInstanceId, baseDirOverride) {
|
|
228
|
+
const base = getLogBaseDirFrom(env, baseDirOverride);
|
|
229
|
+
return edgeInstanceId ? join(base, "instances", edgeInstanceId, "dsh") : join(base, "dsh");
|
|
230
|
+
}
|
|
231
|
+
//#endregion
|
|
232
|
+
//#region src/fields.ts
|
|
233
|
+
/**
|
|
234
|
+
* Record fields owned by `@huaqiu/dsh-plugin-log`.
|
|
228
235
|
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
231
|
-
*
|
|
236
|
+
* Kept in a leaf module with NO runtime imports so the browser half can share
|
|
237
|
+
* the exact same reserved-field rule without pulling `node:fs` / `node:os`
|
|
238
|
+
* into a browser bundle.
|
|
239
|
+
*/
|
|
240
|
+
/**
|
|
241
|
+
* A plugin's `fields` object may not override any of these. Without the rule a
|
|
242
|
+
* plugin could rewrite its own `pluginId` (mis-attributing records to another
|
|
243
|
+
* plugin) or promote a `debug` line to `error` — and the log would stop being
|
|
244
|
+
* evidence.
|
|
245
|
+
*/
|
|
246
|
+
const RESERVED_FIELDS = /* @__PURE__ */ new Set([
|
|
247
|
+
"time",
|
|
248
|
+
"ts",
|
|
249
|
+
"level",
|
|
250
|
+
"msg",
|
|
251
|
+
"pid",
|
|
252
|
+
"schemaVersion",
|
|
253
|
+
"installationId",
|
|
254
|
+
"hostType",
|
|
255
|
+
"hostInstanceId",
|
|
256
|
+
"edgeInstanceId",
|
|
257
|
+
"dshInstanceId",
|
|
258
|
+
"pluginId",
|
|
259
|
+
"component"
|
|
260
|
+
]);
|
|
261
|
+
//#endregion
|
|
262
|
+
//#region src/fs-utils.ts
|
|
263
|
+
/**
|
|
264
|
+
* Small, dependency-free filesystem primitives shared by identity, ownership,
|
|
265
|
+
* rotation and historical recovery.
|
|
232
266
|
*
|
|
233
|
-
*
|
|
267
|
+
* The DSH log tree is written by several DSH processes that may share one HQ
|
|
268
|
+
* Edge installation, so every mutation here follows the same rules as the HQ
|
|
269
|
+
* Edge logging subsystem (docs/tasks/dsh-plugin-log-isolation.md §5):
|
|
234
270
|
*
|
|
235
|
-
*
|
|
236
|
-
*
|
|
237
|
-
*
|
|
238
|
-
*
|
|
239
|
-
*
|
|
240
|
-
*
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
271
|
+
* - publication is ATOMIC and NEVER overwrites an existing destination;
|
|
272
|
+
* - temporary files are unique and live on the same filesystem as the
|
|
273
|
+
* destination, so a rename can never cross volumes;
|
|
274
|
+
* - Windows sharing violations get bounded, classified retries;
|
|
275
|
+
* - every helper is safe to call from an error path: it never throws past a
|
|
276
|
+
* guarded boundary and never buffers without a bound.
|
|
277
|
+
*/
|
|
278
|
+
/** RFC 4122 / RFC 9562 UUID (versions 1–5) — used to validate identity values. */
|
|
279
|
+
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
|
|
280
|
+
function isUuid(value) {
|
|
281
|
+
return typeof value === "string" && UUID_RE.test(value);
|
|
282
|
+
}
|
|
283
|
+
/** Filesystem errors that a Windows file lock / transient sharing violation can produce. */
|
|
284
|
+
const TRANSIENT_FS_CODES = /* @__PURE__ */ new Set([
|
|
285
|
+
"EPERM",
|
|
286
|
+
"EBUSY",
|
|
287
|
+
"EACCES",
|
|
288
|
+
"EAGAIN",
|
|
289
|
+
"UNKNOWN",
|
|
290
|
+
"ESTALE",
|
|
291
|
+
"ETIMEDOUT",
|
|
292
|
+
"ELOCKED"
|
|
293
|
+
]);
|
|
294
|
+
/** Errors that must NOT be retried (permanent permission / invalid path / disk full). */
|
|
295
|
+
const PERMANENT_FS_CODES = /* @__PURE__ */ new Set([
|
|
296
|
+
"ENOENT",
|
|
297
|
+
"ENOSPC",
|
|
298
|
+
"EISDIR",
|
|
299
|
+
"ENOTDIR",
|
|
300
|
+
"EINVAL",
|
|
301
|
+
"ENAMETOOLONG",
|
|
302
|
+
"EROFS",
|
|
303
|
+
"EMFILE",
|
|
304
|
+
"ENFILE"
|
|
305
|
+
]);
|
|
306
|
+
function isTransientFsError(err) {
|
|
307
|
+
const code = err?.code ?? "";
|
|
308
|
+
if (PERMANENT_FS_CODES.has(code)) return false;
|
|
309
|
+
return TRANSIENT_FS_CODES.has(code);
|
|
310
|
+
}
|
|
311
|
+
function errorCode(err) {
|
|
312
|
+
return err?.code ?? "UNKNOWN";
|
|
313
|
+
}
|
|
314
|
+
function errorMessage(err) {
|
|
315
|
+
return err instanceof Error ? err.message : String(err);
|
|
316
|
+
}
|
|
317
|
+
/** Bounded async delay used by filesystem retry backoff. */
|
|
318
|
+
function delay$1(ms) {
|
|
319
|
+
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
320
|
+
}
|
|
321
|
+
/**
|
|
322
|
+
* Runs `operation` with a bounded exponential backoff for transient Windows
|
|
323
|
+
* file-lock failures. Permanent failures are rethrown immediately. A total
|
|
324
|
+
* time budget keeps a rotation from stalling plugin shutdown indefinitely.
|
|
325
|
+
*/
|
|
326
|
+
async function withFsRetries(operation, options = {}) {
|
|
327
|
+
const attempts = options.attempts ?? 5;
|
|
328
|
+
const baseDelayMs = options.baseDelayMs ?? 25;
|
|
329
|
+
const maxDelayMs = options.maxDelayMs ?? 400;
|
|
330
|
+
const totalTimeoutMs = options.totalTimeoutMs ?? 5e3;
|
|
331
|
+
const isRetryable = options.isRetryable ?? isTransientFsError;
|
|
332
|
+
const deadline = Date.now() + totalTimeoutMs;
|
|
333
|
+
let lastError;
|
|
334
|
+
for (let attempt = 0; attempt < attempts; attempt += 1) try {
|
|
335
|
+
return await operation();
|
|
336
|
+
} catch (err) {
|
|
337
|
+
lastError = err;
|
|
338
|
+
if (!isRetryable(err) || attempt === attempts - 1 || Date.now() >= deadline) throw err;
|
|
339
|
+
const wait = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs, Math.max(0, deadline - Date.now()));
|
|
340
|
+
if (wait > 0) await delay$1(wait);
|
|
341
|
+
}
|
|
342
|
+
throw lastError;
|
|
343
|
+
}
|
|
344
|
+
/**
|
|
345
|
+
* Publishes `src` as `dst` without ever overwriting an existing file.
|
|
244
346
|
*
|
|
245
|
-
*
|
|
347
|
+
* Hard-link creation is the primary mechanism: it is atomic on NTFS and POSIX
|
|
348
|
+
* and fails with EEXIST when the destination already exists. Where hard links
|
|
349
|
+
* are unavailable (some network/virtual filesystems), a guarded rename is used
|
|
350
|
+
* inside the caller's exclusively-owned directory.
|
|
246
351
|
*
|
|
247
|
-
*
|
|
248
|
-
* are replaced with `[redacted]`, so the log is safe to share.
|
|
249
|
-
* - `getLogger()` never throws. Neither does any log call.
|
|
352
|
+
* Returns true when this call created `dst`, false when `dst` already existed.
|
|
250
353
|
*/
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
354
|
+
function atomicPublish(src, dst) {
|
|
355
|
+
if (existsSync(dst)) return false;
|
|
356
|
+
try {
|
|
357
|
+
linkSync(src, dst);
|
|
358
|
+
try {
|
|
359
|
+
unlinkSync(src);
|
|
360
|
+
} catch {}
|
|
361
|
+
return true;
|
|
362
|
+
} catch (err) {
|
|
363
|
+
if (errorCode(err) === "EEXIST") return false;
|
|
364
|
+
if (!isLinkUnsupported(err)) throw err;
|
|
365
|
+
if (existsSync(dst)) return false;
|
|
366
|
+
renameSync(src, dst);
|
|
367
|
+
return true;
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
function isLinkUnsupported(err) {
|
|
371
|
+
const code = errorCode(err);
|
|
372
|
+
return code === "EPERM" || code === "EOPNOTSUPP" || code === "ENOSYS" || code === "EXDEV" || code === "ENOTSUP";
|
|
373
|
+
}
|
|
256
374
|
/**
|
|
257
|
-
*
|
|
258
|
-
*
|
|
259
|
-
* Plugins are built independently, so each one gets its OWN bundled copy of
|
|
260
|
-
* this module. Without a shared home, "one unified log" would degrade into one
|
|
261
|
-
* sink (and one rotation counter) per plugin. Keying the state off a
|
|
262
|
-
* `Symbol.for` on `globalThis` makes every copy — bundled, external, or
|
|
263
|
-
* duplicated across installs — cooperate inside the same DSH process.
|
|
375
|
+
* Atomically writes `data` to `path` ONLY if that path does not exist, so a
|
|
376
|
+
* partially-written temp file can never be observed at the destination.
|
|
264
377
|
*/
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
const
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
378
|
+
function atomicCreateNewFile(path, data, tmpPrefix = ".tmp-") {
|
|
379
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
380
|
+
const tmp = join(dirname(path), `${tmpPrefix}${randomUUID()}`);
|
|
381
|
+
let fd = null;
|
|
382
|
+
try {
|
|
383
|
+
fd = openSync(tmp, "wx", 384);
|
|
384
|
+
const buf = typeof data === "string" ? Buffer.from(data, "utf-8") : data;
|
|
385
|
+
writeSync(fd, buf, 0, buf.length, 0);
|
|
386
|
+
fsyncSync(fd);
|
|
387
|
+
closeSync(fd);
|
|
388
|
+
fd = null;
|
|
389
|
+
return atomicPublish(tmp, path);
|
|
390
|
+
} finally {
|
|
391
|
+
if (fd !== null) try {
|
|
392
|
+
closeSync(fd);
|
|
393
|
+
} catch {}
|
|
394
|
+
try {
|
|
395
|
+
if (existsSync(tmp)) unlinkSync(tmp);
|
|
396
|
+
} catch {}
|
|
397
|
+
}
|
|
278
398
|
}
|
|
279
|
-
const getOverride = () => state().override;
|
|
280
|
-
const setOverride = (value) => {
|
|
281
|
-
state().override = value;
|
|
282
|
-
};
|
|
283
|
-
const getSink = () => state().sink;
|
|
284
|
-
const setSink = (value) => {
|
|
285
|
-
state().sink = value;
|
|
286
|
-
};
|
|
287
399
|
/**
|
|
288
|
-
*
|
|
289
|
-
*
|
|
400
|
+
* Reads a JSON file. Returns `null` on any error (missing, unreadable, NUL
|
|
401
|
+
* corruption, invalid JSON). Callers MUST treat `null` as "preserve, never
|
|
402
|
+
* delete" — a corrupt `instance.json` is evidence, not garbage.
|
|
290
403
|
*/
|
|
291
|
-
function
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
404
|
+
function readJsonSafe(path) {
|
|
405
|
+
try {
|
|
406
|
+
const raw = readFileSync(path, "utf-8");
|
|
407
|
+
if (raw.includes("\0")) return null;
|
|
408
|
+
const value = JSON.parse(raw);
|
|
409
|
+
return value && typeof value === "object" ? value : null;
|
|
410
|
+
} catch {
|
|
411
|
+
return null;
|
|
412
|
+
}
|
|
297
413
|
}
|
|
298
|
-
/**
|
|
299
|
-
function
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
414
|
+
/** Best-effort synchronous append that can never throw. Used by error paths. */
|
|
415
|
+
function appendDiagnostic(path, record) {
|
|
416
|
+
try {
|
|
417
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
418
|
+
const line = typeof record === "string" ? record : JSON.stringify({
|
|
419
|
+
time: (/* @__PURE__ */ new Date()).toISOString(),
|
|
420
|
+
...record !== null && typeof record === "object" ? record : { value: String(record) }
|
|
421
|
+
});
|
|
422
|
+
const fd = openSync(path, "a", 384);
|
|
423
|
+
try {
|
|
424
|
+
writeSync(fd, Buffer.from(`${line}\n`, "utf-8"));
|
|
425
|
+
} finally {
|
|
426
|
+
closeSync(fd);
|
|
427
|
+
}
|
|
428
|
+
} catch {}
|
|
305
429
|
}
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
430
|
+
/** Size of a file, or 0 when it cannot be stat'ed. */
|
|
431
|
+
function sizeOrZero(path) {
|
|
432
|
+
try {
|
|
433
|
+
return statSync(path).size;
|
|
434
|
+
} catch {
|
|
435
|
+
return 0;
|
|
436
|
+
}
|
|
309
437
|
}
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
438
|
+
//#endregion
|
|
439
|
+
//#region src/identity.ts
|
|
440
|
+
/**
|
|
441
|
+
* Identity for ONE DSH process, and the log root it is allowed to write into.
|
|
442
|
+
*
|
|
443
|
+
* This is the fourth level of the ownership hierarchy
|
|
444
|
+
* (docs/tasks/dsh-plugin-log-isolation.md §1):
|
|
445
|
+
*
|
|
446
|
+
* installation_id HQ Edge installation (installation lifetime)
|
|
447
|
+
* host_instance_id EDA Host (host process lifetime)
|
|
448
|
+
* edge_instance_id HQ Edge (Edge process lifetime)
|
|
449
|
+
* dsh_instance_id DSH runtime (DSH process lifetime) ← here
|
|
450
|
+
*
|
|
451
|
+
* Plugins have no process identity of their own. They are attributed to a DSH
|
|
452
|
+
* process through `plugin_id` (see `index.ts`), which is why nothing in this
|
|
453
|
+
* module knows about plugins.
|
|
454
|
+
*
|
|
455
|
+
* Rules encoded here:
|
|
456
|
+
* - `dsh_instance_id` is generated per DSH LAUNCH. A DSH restart produces a
|
|
457
|
+
* new id and therefore a new directory; a plugin reload does not.
|
|
458
|
+
* - HQ Edge passes the parent identities in the environment. It must never
|
|
459
|
+
* generate a `dsh_instance_id` itself and reuse it across restarts.
|
|
460
|
+
* - An absent or malformed parent identity is recorded as `null`, never
|
|
461
|
+
* fabricated: attributing logs to the wrong Edge process is worse than
|
|
462
|
+
* attributing them to none.
|
|
463
|
+
*/
|
|
464
|
+
/** Written once per DSH process, atomically, never overwritten. */
|
|
465
|
+
const INSTANCE_METADATA_FILENAME = "instance.json";
|
|
466
|
+
/** Diagnostic JSONL. Its EXISTENCE never implies ownership. */
|
|
467
|
+
const OWNER_LOCK_FILENAME = "owner.lock";
|
|
468
|
+
/** Appended by historical recovery in the recovering process's own directory. */
|
|
469
|
+
const RECOVERY_LOG_FILENAME = "recovery.log";
|
|
470
|
+
/** Written when the destination cannot be established at all. */
|
|
471
|
+
const FATAL_LOG_FILENAME = "fatal.log";
|
|
472
|
+
function envValue(env, name) {
|
|
473
|
+
const value = env[name];
|
|
474
|
+
if (value === void 0) return void 0;
|
|
475
|
+
const trimmed = value.trim();
|
|
476
|
+
return trimmed.length > 0 ? trimmed : void 0;
|
|
477
|
+
}
|
|
478
|
+
function uuidOrNull(env, name, warnings) {
|
|
479
|
+
const value = envValue(env, name);
|
|
480
|
+
if (value === void 0) return null;
|
|
481
|
+
if (isUuid(value)) return value;
|
|
482
|
+
warnings.push(`${name} is not a valid UUID and was ignored`);
|
|
483
|
+
return null;
|
|
484
|
+
}
|
|
485
|
+
function hostTypeOrNull(env, warnings) {
|
|
486
|
+
const value = envValue(env, "HQ_HOST_TYPE");
|
|
487
|
+
if (value === void 0) return null;
|
|
488
|
+
const normalized = value.toLowerCase();
|
|
489
|
+
if (!/^[a-z][a-z0-9_-]{0,31}$/.test(normalized)) {
|
|
490
|
+
warnings.push("HQ_HOST_TYPE has an unexpected shape and was ignored");
|
|
491
|
+
return null;
|
|
492
|
+
}
|
|
493
|
+
return normalized;
|
|
314
494
|
}
|
|
315
495
|
/**
|
|
316
|
-
*
|
|
317
|
-
*
|
|
318
|
-
*
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
496
|
+
* Resolves the DSH log root and the parent identities from the environment.
|
|
497
|
+
*
|
|
498
|
+
* Root precedence (§3 / §4):
|
|
499
|
+
* 1. explicit option (`configureLogging({ dir })`)
|
|
500
|
+
* 2. `$DSH_LOG_ROOT` (set by HQ Edge when it launches DSH)
|
|
501
|
+
* 3. `$HQ_EDGE_INSTANCE_ID` → `<logs>/instances/<edge>/dsh`
|
|
502
|
+
* 4. otherwise → `<logs>/dsh` (standalone DSH)
|
|
503
|
+
*/
|
|
504
|
+
function readDshLogContext(env = process.env, overrides = {}) {
|
|
505
|
+
const warnings = [];
|
|
506
|
+
const installationId = uuidOrNull(env, "HQ_EDGE_INSTALLATION_ID", warnings);
|
|
507
|
+
const edgeInstanceId = uuidOrNull(env, "HQ_EDGE_INSTANCE_ID", warnings);
|
|
508
|
+
const hostInstanceId = uuidOrNull(env, "HQ_HOST_INSTANCE_ID", warnings);
|
|
509
|
+
const hostType = hostTypeOrNull(env, warnings);
|
|
510
|
+
let dshLogRoot;
|
|
511
|
+
let dshLogRootSource;
|
|
512
|
+
if (overrides.dshLogRoot && overrides.dshLogRoot.length > 0) {
|
|
513
|
+
dshLogRoot = overrides.dshLogRoot;
|
|
514
|
+
dshLogRootSource = "override";
|
|
515
|
+
} else {
|
|
516
|
+
const fromEnv = envValue(env, "DSH_LOG_ROOT");
|
|
517
|
+
if (fromEnv) {
|
|
518
|
+
dshLogRoot = fromEnv;
|
|
519
|
+
dshLogRootSource = "env:DSH_LOG_ROOT";
|
|
520
|
+
} else {
|
|
521
|
+
dshLogRoot = getDshLogRootFrom(env, edgeInstanceId, overrides.baseDir);
|
|
522
|
+
dshLogRootSource = edgeInstanceId ? "edge-instance" : "unscoped";
|
|
523
|
+
}
|
|
337
524
|
}
|
|
338
525
|
return {
|
|
339
|
-
|
|
340
|
-
|
|
526
|
+
dshLogRoot,
|
|
527
|
+
dshLogRootSource,
|
|
528
|
+
installationId,
|
|
529
|
+
edgeInstanceId,
|
|
530
|
+
hostType,
|
|
531
|
+
hostInstanceId,
|
|
532
|
+
targetHost: envValue(env, "HQ_TARGET_HOST") ?? null,
|
|
533
|
+
dshHome: envValue(env, "DSH_HOME") ?? null,
|
|
534
|
+
hqEdgeHome: getHqEdgeHomeFrom(env),
|
|
535
|
+
warnings
|
|
341
536
|
};
|
|
342
537
|
}
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
538
|
+
let cachedVersion = null;
|
|
539
|
+
/**
|
|
540
|
+
* Version of this package, used to attribute a log directory to the build that
|
|
541
|
+
* created it. Resolved lazily and cached: `import.meta.url` may point outside
|
|
542
|
+
* the package when a plugin bundle inlines this module, in which case the env
|
|
543
|
+
* override or `unknown` is used instead of failing.
|
|
544
|
+
*/
|
|
545
|
+
function pluginLogVersion() {
|
|
546
|
+
if (cachedVersion !== null) return cachedVersion;
|
|
547
|
+
const fromEnv = process.env.DSH_PLUGIN_LOG_VERSION?.trim();
|
|
548
|
+
if (fromEnv) {
|
|
549
|
+
cachedVersion = fromEnv;
|
|
550
|
+
return cachedVersion;
|
|
551
|
+
}
|
|
552
|
+
try {
|
|
553
|
+
const here = fileURLToPath(new URL(".", import.meta.url));
|
|
554
|
+
const raw = readFileSync(join(here, "..", "package.json"), "utf-8");
|
|
555
|
+
const parsed = JSON.parse(raw);
|
|
556
|
+
cachedVersion = typeof parsed.version === "string" ? parsed.version : "unknown";
|
|
557
|
+
} catch {
|
|
558
|
+
cachedVersion = "unknown";
|
|
559
|
+
}
|
|
560
|
+
return cachedVersion;
|
|
561
|
+
}
|
|
562
|
+
/**
|
|
563
|
+
* Creates the immutable identity of THIS DSH process.
|
|
564
|
+
*
|
|
565
|
+
* `dsh_instance_id` is taken from an explicit override (tests / host
|
|
566
|
+
* injection), else `$DSH_INSTANCE_ID`, else freshly generated. HQ Edge must
|
|
567
|
+
* not set either variable: a restart has to produce a new directory.
|
|
568
|
+
*/
|
|
569
|
+
function createDshIdentity(context, options = {}) {
|
|
570
|
+
const injected = options.dshInstanceId ?? envValue(process.env, "DSH_INSTANCE_ID");
|
|
571
|
+
return {
|
|
572
|
+
schemaVersion: 1,
|
|
573
|
+
dshInstanceId: isUuid(injected) ? injected : randomUUID(),
|
|
574
|
+
installationId: context.installationId,
|
|
575
|
+
edgeInstanceId: context.edgeInstanceId,
|
|
576
|
+
hostType: context.hostType,
|
|
577
|
+
hostInstanceId: context.hostInstanceId,
|
|
578
|
+
targetHost: context.targetHost,
|
|
579
|
+
pid: options.pid ?? process.pid,
|
|
580
|
+
startedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
|
|
581
|
+
version: options.version ?? pluginLogVersion(),
|
|
582
|
+
dshHome: context.dshHome,
|
|
583
|
+
logRoot: context.dshLogRoot
|
|
356
584
|
};
|
|
357
|
-
return s.resolved;
|
|
358
585
|
}
|
|
359
|
-
/** Absolute
|
|
360
|
-
function
|
|
361
|
-
|
|
362
|
-
return s ? s.path : null;
|
|
586
|
+
/** Absolute directory this DSH process exclusively owns. */
|
|
587
|
+
function instanceDirFor(identity) {
|
|
588
|
+
return join(identity.logRoot, identity.dshInstanceId);
|
|
363
589
|
}
|
|
364
|
-
/**
|
|
365
|
-
function
|
|
366
|
-
|
|
590
|
+
/** Reads and validates `instance.json` from an (historical) directory. */
|
|
591
|
+
function readDshInstanceMetadata(dir) {
|
|
592
|
+
const value = readJsonSafe(join(dir, INSTANCE_METADATA_FILENAME));
|
|
593
|
+
if (!value) return null;
|
|
594
|
+
if (!isUuid(value.dshInstanceId)) return null;
|
|
595
|
+
if (basename(dir).toLowerCase() !== value.dshInstanceId.toLowerCase()) return null;
|
|
596
|
+
return {
|
|
597
|
+
schemaVersion: typeof value.schemaVersion === "number" ? value.schemaVersion : 0,
|
|
598
|
+
dshInstanceId: value.dshInstanceId,
|
|
599
|
+
installationId: isUuid(value.installationId) ? value.installationId : null,
|
|
600
|
+
edgeInstanceId: isUuid(value.edgeInstanceId) ? value.edgeInstanceId : null,
|
|
601
|
+
hostType: typeof value.hostType === "string" ? value.hostType : null,
|
|
602
|
+
hostInstanceId: isUuid(value.hostInstanceId) ? value.hostInstanceId : null,
|
|
603
|
+
targetHost: typeof value.targetHost === "string" ? value.targetHost : null,
|
|
604
|
+
pid: typeof value.pid === "number" ? value.pid : 0,
|
|
605
|
+
startedAt: typeof value.startedAt === "string" ? value.startedAt : "",
|
|
606
|
+
version: typeof value.version === "string" ? value.version : "unknown",
|
|
607
|
+
dshHome: typeof value.dshHome === "string" ? value.dshHome : null,
|
|
608
|
+
logRoot: typeof value.logRoot === "string" ? value.logRoot : dir
|
|
609
|
+
};
|
|
367
610
|
}
|
|
611
|
+
//#endregion
|
|
612
|
+
//#region src/ownership.ts
|
|
368
613
|
/**
|
|
369
|
-
*
|
|
614
|
+
* Exclusive, OS-backed ownership of ONE DSH instance log directory.
|
|
615
|
+
*
|
|
616
|
+
* The lock is a **bound IPC endpoint held open by the owning DSH process**:
|
|
617
|
+
*
|
|
618
|
+
* Windows : named pipe \\.\pipe\hq-edge-dsh-instance-<sha256(dir)>
|
|
619
|
+
* POSIX : unix socket <dir>/.owner.sock
|
|
620
|
+
*
|
|
621
|
+
* Creating a second server on the same endpoint fails with EADDRINUSE while
|
|
622
|
+
* the owner is alive, and the OS closes the handle — releasing the lock — the
|
|
623
|
+
* instant the owner terminates, including abnormal termination. There is no
|
|
624
|
+
* PID check, no heartbeat and no stale-timestamp heuristic: a DSH process that
|
|
625
|
+
* crashes must not leave a lock that a later process has to guess about.
|
|
370
626
|
*
|
|
371
|
-
*
|
|
372
|
-
*
|
|
627
|
+
* The endpoint is keyed by the INSTANCE DIRECTORY, so two DSH processes under
|
|
628
|
+
* the same HQ Edge process, two DSH processes under different Edge processes,
|
|
629
|
+
* and a DSH process plus the Edge maintenance job never contend for the same
|
|
630
|
+
* lock unless they genuinely target the same directory.
|
|
631
|
+
*
|
|
632
|
+
* `owner.lock` is a diagnostic JSONL file only. Its existence NEVER implies
|
|
633
|
+
* ownership, and it is intentionally left behind after exit: it is the record
|
|
634
|
+
* of which process last owned the directory and when.
|
|
373
635
|
*/
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
636
|
+
const PIPE_PREFIX = "\\\\.\\pipe\\hq-edge-dsh-instance-";
|
|
637
|
+
const SOCKET_FILENAME = ".owner.sock";
|
|
638
|
+
function normalizedDir(dir) {
|
|
639
|
+
const absolute = resolve(dir);
|
|
640
|
+
return process.platform === "win32" ? absolute.toLowerCase() : absolute;
|
|
641
|
+
}
|
|
642
|
+
/** Deterministic, filesystem-safe lock key. Not an identity — a lookup key. */
|
|
643
|
+
function ownershipKey(dir) {
|
|
644
|
+
return createHash("sha256").update(normalizedDir(dir)).digest("hex").slice(0, 32);
|
|
645
|
+
}
|
|
646
|
+
function endpointFor(dir) {
|
|
647
|
+
return process.platform === "win32" ? `${PIPE_PREFIX}${ownershipKey(dir)}` : join(resolve(dir), SOCKET_FILENAME);
|
|
648
|
+
}
|
|
649
|
+
function recordOwnerClaim(dir, dshInstanceId) {
|
|
650
|
+
appendDiagnostic(join(dir, OWNER_LOCK_FILENAME), {
|
|
651
|
+
event: "ownership-claimed",
|
|
652
|
+
pid: process.pid,
|
|
653
|
+
dshInstanceId,
|
|
654
|
+
acquiredAt: (/* @__PURE__ */ new Date()).toISOString()
|
|
655
|
+
});
|
|
656
|
+
}
|
|
657
|
+
var DshOwnershipHandleImpl = class {
|
|
658
|
+
instanceDir;
|
|
659
|
+
dshInstanceId;
|
|
660
|
+
server;
|
|
661
|
+
socketFile;
|
|
662
|
+
diagnostics;
|
|
663
|
+
_released = false;
|
|
664
|
+
constructor(instanceDir, dshInstanceId, server, socketFile, diagnostics) {
|
|
665
|
+
this.instanceDir = instanceDir;
|
|
666
|
+
this.dshInstanceId = dshInstanceId;
|
|
667
|
+
this.server = server;
|
|
668
|
+
this.socketFile = socketFile;
|
|
669
|
+
this.diagnostics = diagnostics;
|
|
670
|
+
}
|
|
671
|
+
get released() {
|
|
672
|
+
return this._released;
|
|
396
673
|
}
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
if (this.bytes + next <= this.maxBytes) return;
|
|
674
|
+
release() {
|
|
675
|
+
if (this._released) return;
|
|
676
|
+
this._released = true;
|
|
401
677
|
try {
|
|
402
|
-
|
|
403
|
-
const from = i === 1 ? join(this.dir, this.fileName) : this.rotated(i - 1);
|
|
404
|
-
const to = this.rotated(i);
|
|
405
|
-
if (!exists(from)) continue;
|
|
406
|
-
if (exists(to)) rmSync(to, { force: true });
|
|
407
|
-
renameSync(from, to);
|
|
408
|
-
}
|
|
409
|
-
this.bytes = this.currentSize();
|
|
678
|
+
this.server.close();
|
|
410
679
|
} catch {}
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
const size = Buffer.byteLength(line, "utf8");
|
|
421
|
-
this.bytes += size;
|
|
422
|
-
this.queue = this.queue.then(async () => {
|
|
423
|
-
this.rotateIfNeeded(size);
|
|
424
|
-
await appendFile(this.path, line, "utf8");
|
|
425
|
-
}).catch(() => {});
|
|
426
|
-
}
|
|
427
|
-
/** Wait for everything enqueued so far to reach the file. */
|
|
428
|
-
flush() {
|
|
429
|
-
return this.queue;
|
|
680
|
+
if (this.socketFile) try {
|
|
681
|
+
unlinkSync(this.socketFile);
|
|
682
|
+
} catch {}
|
|
683
|
+
if (this.diagnostics) appendDiagnostic(join(this.instanceDir, OWNER_LOCK_FILENAME), {
|
|
684
|
+
event: "ownership-released",
|
|
685
|
+
pid: process.pid,
|
|
686
|
+
dshInstanceId: this.dshInstanceId,
|
|
687
|
+
releasedAt: (/* @__PURE__ */ new Date()).toISOString()
|
|
688
|
+
});
|
|
430
689
|
}
|
|
431
690
|
};
|
|
432
|
-
function
|
|
691
|
+
function bindServer(endpoint) {
|
|
692
|
+
return new Promise((resolvePromise) => {
|
|
693
|
+
const server = createServer();
|
|
694
|
+
let settled = false;
|
|
695
|
+
const finish = (ok, code) => {
|
|
696
|
+
if (settled) return;
|
|
697
|
+
settled = true;
|
|
698
|
+
resolvePromise({
|
|
699
|
+
server,
|
|
700
|
+
ok,
|
|
701
|
+
code
|
|
702
|
+
});
|
|
703
|
+
};
|
|
704
|
+
server.once("error", (err) => finish(false, err.code ?? "UNKNOWN"));
|
|
705
|
+
server.once("listening", () => finish(true));
|
|
706
|
+
try {
|
|
707
|
+
server.listen(endpoint);
|
|
708
|
+
} catch (err) {
|
|
709
|
+
finish(false, errorCode(err));
|
|
710
|
+
}
|
|
711
|
+
});
|
|
712
|
+
}
|
|
713
|
+
function delay(ms) {
|
|
714
|
+
return new Promise((resolve) => {
|
|
715
|
+
setTimeout(resolve, ms).unref();
|
|
716
|
+
});
|
|
717
|
+
}
|
|
718
|
+
/**
|
|
719
|
+
* Binds the endpoint, retrying briefly while it reports EADDRINUSE.
|
|
720
|
+
*
|
|
721
|
+
* A process that has JUST released the endpoint can take a few milliseconds to
|
|
722
|
+
* disappear (Windows closes the named-pipe instance asynchronously). Without
|
|
723
|
+
* the retry, a recovery pass that runs immediately after a release mistakes a
|
|
724
|
+
* dying owner for a live one and skips the directory. A genuinely live owner
|
|
725
|
+
* keeps failing every attempt, so this only removes the race — it never steals
|
|
726
|
+
* a held lock.
|
|
727
|
+
*/
|
|
728
|
+
async function bindWithRetry(endpoint) {
|
|
729
|
+
let bound = await bindServer(endpoint);
|
|
730
|
+
for (let attempt = 0; attempt < 4 && !bound.ok && bound.code === "EADDRINUSE"; attempt += 1) {
|
|
731
|
+
try {
|
|
732
|
+
bound.server.close();
|
|
733
|
+
} catch {}
|
|
734
|
+
await delay(15 * (attempt + 1));
|
|
735
|
+
bound = await bindServer(endpoint);
|
|
736
|
+
}
|
|
737
|
+
return bound;
|
|
738
|
+
}
|
|
739
|
+
/** POSIX only: is the socket file a live owner or a stale crash leftover? */
|
|
740
|
+
function socketIsLive(socketFile) {
|
|
741
|
+
return new Promise((resolvePromise) => {
|
|
742
|
+
const socket = createConnection(socketFile);
|
|
743
|
+
const done = (live) => {
|
|
744
|
+
socket.destroy();
|
|
745
|
+
resolvePromise(live);
|
|
746
|
+
};
|
|
747
|
+
socket.once("connect", () => done(true));
|
|
748
|
+
socket.once("error", () => done(false));
|
|
749
|
+
socket.setTimeout(250, () => done(false));
|
|
750
|
+
});
|
|
751
|
+
}
|
|
752
|
+
/**
|
|
753
|
+
* Attempts exclusive ownership. Returns `null` when another live process owns
|
|
754
|
+
* the directory — callers MUST then leave the directory completely alone.
|
|
755
|
+
*
|
|
756
|
+
* Asynchronous because a socket bind resolves on the event loop. The runtime
|
|
757
|
+
* gates opening the active log file on this promise, so no active file is ever
|
|
758
|
+
* written before ownership is established.
|
|
759
|
+
*/
|
|
760
|
+
async function acquireDshOwnership(instanceDir, dshInstanceId, options = {}) {
|
|
761
|
+
const diagnostics = options.diagnostics !== false;
|
|
433
762
|
try {
|
|
434
|
-
|
|
435
|
-
return true;
|
|
763
|
+
mkdirSync(instanceDir, { recursive: true });
|
|
436
764
|
} catch {
|
|
437
|
-
return
|
|
765
|
+
return null;
|
|
438
766
|
}
|
|
767
|
+
const endpoint = endpointFor(instanceDir);
|
|
768
|
+
let bound = await bindWithRetry(endpoint);
|
|
769
|
+
if (!bound.ok && process.platform !== "win32" && bound.code === "EADDRINUSE") {
|
|
770
|
+
if (existsSync(endpoint) && !await socketIsLive(endpoint)) {
|
|
771
|
+
try {
|
|
772
|
+
unlinkSync(endpoint);
|
|
773
|
+
} catch {}
|
|
774
|
+
bound = await bindWithRetry(endpoint);
|
|
775
|
+
}
|
|
776
|
+
}
|
|
777
|
+
if (!bound.ok) {
|
|
778
|
+
try {
|
|
779
|
+
bound.server.close();
|
|
780
|
+
} catch {}
|
|
781
|
+
return null;
|
|
782
|
+
}
|
|
783
|
+
if (diagnostics) recordOwnerClaim(instanceDir, dshInstanceId);
|
|
784
|
+
bound.server.unref();
|
|
785
|
+
return new DshOwnershipHandleImpl(instanceDir, dshInstanceId, bound.server, process.platform === "win32" ? null : endpoint, diagnostics);
|
|
439
786
|
}
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
return
|
|
447
|
-
}
|
|
448
|
-
/** Wait for all pending writes to land (shutdown hooks, tests). */
|
|
449
|
-
async function flushLogs() {
|
|
450
|
-
await getSink()?.flush();
|
|
787
|
+
/**
|
|
788
|
+
* Historical recovery / cleanup entry point. Stricter than
|
|
789
|
+
* {@link acquireDshOwnership}: it refuses to create the directory (a deleted
|
|
790
|
+
* directory must stay deleted) and writes no diagnostics into it.
|
|
791
|
+
*/
|
|
792
|
+
async function acquireHistoricalDshOwnership(instanceDir, dshInstanceId) {
|
|
793
|
+
if (!existsSync(instanceDir)) return null;
|
|
794
|
+
return acquireDshOwnership(instanceDir, dshInstanceId, { diagnostics: false });
|
|
451
795
|
}
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
if (
|
|
455
|
-
|
|
456
|
-
return
|
|
796
|
+
/** Non-destructive probe: true when nobody currently owns the directory. */
|
|
797
|
+
async function probeDshOwnership(instanceDir) {
|
|
798
|
+
if (!existsSync(instanceDir)) return false;
|
|
799
|
+
const handle = await acquireDshOwnership(instanceDir, "ownership-probe", { diagnostics: false });
|
|
800
|
+
if (!handle) return false;
|
|
801
|
+
handle.release();
|
|
802
|
+
return true;
|
|
457
803
|
}
|
|
458
|
-
|
|
459
|
-
|
|
804
|
+
/** Writes a recovery diagnostic without touching a live owner's data. */
|
|
805
|
+
function recordRecoveryDiagnostic(instanceDir, record) {
|
|
806
|
+
try {
|
|
807
|
+
const fd = openSync(join(instanceDir, RECOVERY_LOG_FILENAME), "a", 384);
|
|
460
808
|
try {
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
};
|
|
470
|
-
if (Object.keys(defaults).length > 0) Object.assign(record, defaults);
|
|
471
|
-
if (fields && Object.keys(fields).length > 0) Object.assign(record, fields);
|
|
472
|
-
const safe = redact(record);
|
|
473
|
-
if (isEnabled(level, cfg.level)) currentSink().write(`${JSON.stringify(safe)}\n`);
|
|
474
|
-
if (cfg.consoleLevel !== "off" && isEnabled(level, cfg.consoleLevel)) {
|
|
475
|
-
const { msg, ...rest } = safe;
|
|
476
|
-
console[consoleMethod(level)](`[${component}] ${String(msg)}`, rest);
|
|
477
|
-
}
|
|
478
|
-
} catch {}
|
|
479
|
-
};
|
|
480
|
-
return {
|
|
481
|
-
component,
|
|
482
|
-
debug: (message, fields) => emit("debug", message, fields),
|
|
483
|
-
info: (message, fields) => emit("info", message, fields),
|
|
484
|
-
warn: (message, fields) => emit("warn", message, fields),
|
|
485
|
-
error: (message, fields) => emit("error", message, fields),
|
|
486
|
-
child: (fields) => createLogger(component, {
|
|
487
|
-
...defaults,
|
|
488
|
-
...fields
|
|
489
|
-
})
|
|
490
|
-
};
|
|
809
|
+
writeSync(fd, Buffer.from(`${JSON.stringify({
|
|
810
|
+
time: (/* @__PURE__ */ new Date()).toISOString(),
|
|
811
|
+
...record
|
|
812
|
+
})}\n`));
|
|
813
|
+
} finally {
|
|
814
|
+
closeSync(fd);
|
|
815
|
+
}
|
|
816
|
+
} catch {}
|
|
491
817
|
}
|
|
818
|
+
//#endregion
|
|
819
|
+
//#region src/rotation.ts
|
|
492
820
|
/**
|
|
493
|
-
*
|
|
821
|
+
* Asynchronous, fault-tolerant rotation + retention for ONE DSH process's log
|
|
822
|
+
* file inside the directory that process exclusively owns.
|
|
823
|
+
*
|
|
824
|
+
* The previous `@huaqiu/dsh-plugin-log` rotation was a synchronous
|
|
825
|
+
* `rename`-shift chain that (a) assumed the process could rename files another
|
|
826
|
+
* DSH process might hold open and (b) produced `.1 .2 .3` siblings with no
|
|
827
|
+
* ownership metadata. Both are wrong once several DSH processes share an
|
|
828
|
+
* installation, so this implementation follows the same rules as the HQ Edge
|
|
829
|
+
* logging subsystem (docs/tasks/dsh-plugin-log-isolation.md §5):
|
|
494
830
|
*
|
|
495
|
-
*
|
|
496
|
-
*
|
|
497
|
-
*
|
|
831
|
+
* - compression is streamed and asynchronous: no whole-file sync gzip;
|
|
832
|
+
* - the closing file is SEALED under a unique name first, so a crash leaves
|
|
833
|
+
* a recoverable artifact rather than a half-renamed member of a chain;
|
|
834
|
+
* - the archive is VERIFIED (gzip trailer included) before publication;
|
|
835
|
+
* - publication is atomic and NEVER overwrites an existing archive;
|
|
836
|
+
* - the sealed source is deleted only after successful publication;
|
|
837
|
+
* - unresolved artifacts are capped, so a filesystem that keeps rejecting
|
|
838
|
+
* publication cannot accumulate temp files without bound.
|
|
839
|
+
*
|
|
840
|
+
* Lifecycle:
|
|
841
|
+
* ACTIVE → ROTATION_REQUESTED → SEALING → ARCHIVING → VERIFYING
|
|
842
|
+
* → PUBLISHING → COMPLETED
|
|
843
|
+
* Every failure state preserves the original data for historical recovery.
|
|
498
844
|
*/
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
845
|
+
/**
|
|
846
|
+
* Defaults for DSH plugin logs: plugin diagnostics are low volume, so 10 MiB
|
|
847
|
+
* per file with 14 days of history is plenty, and 256 MiB caps a pathological
|
|
848
|
+
* plugin without competing with the parent Edge instance's own budget.
|
|
849
|
+
*/
|
|
850
|
+
const DSH_ROTATION = {
|
|
851
|
+
frequency: "daily",
|
|
852
|
+
maxSize: "10m",
|
|
853
|
+
retentionDays: 14,
|
|
854
|
+
maxStorageBytes: 268435456,
|
|
855
|
+
compress: true
|
|
856
|
+
};
|
|
857
|
+
/** Parses a human size string ("10m", "1g", "500k", or "1024") into bytes. */
|
|
858
|
+
function parseSize(input) {
|
|
859
|
+
const match = /^(\d+(?:\.\d+)?)\s*([kmg]?b?)?$/i.exec(input.trim());
|
|
860
|
+
if (!match) return 10485760;
|
|
861
|
+
const value = Number.parseFloat(match[1] ?? "");
|
|
862
|
+
if (!Number.isFinite(value)) return 10485760;
|
|
863
|
+
switch ((match[2] || "m").toLowerCase()[0]) {
|
|
864
|
+
case "k": return Math.floor(value * 1024);
|
|
865
|
+
case "g": return Math.floor(value * 1024 * 1024 * 1024);
|
|
866
|
+
default: return Math.floor(value * 1024 * 1024);
|
|
867
|
+
}
|
|
868
|
+
}
|
|
869
|
+
/** Current UTC date as `yyyy-MM-dd`. UTC keeps multi-timezone installs stable. */
|
|
870
|
+
function todayString(date = /* @__PURE__ */ new Date()) {
|
|
871
|
+
return date.toISOString().slice(0, 10);
|
|
872
|
+
}
|
|
873
|
+
const SEALED_MARKER = ".log.sealed-";
|
|
874
|
+
const TEMP_MARKER = ".gz.tmp-";
|
|
875
|
+
const QUARANTINE_MARKER = ".quarantine-";
|
|
876
|
+
const ARCHIVE_SUFFIX = ".log.gz";
|
|
877
|
+
/** Canonical name for an in-progress gzip archive, e.g. `dsh.<date>.log.gz.tmp-<uuid>`. */
|
|
878
|
+
function tempArchivePathFor(archivePath) {
|
|
879
|
+
return `${archivePath.slice(0, -3)}${TEMP_MARKER}${randomUUID()}`;
|
|
880
|
+
}
|
|
881
|
+
/** Inverse of {@link tempArchivePathFor}, for a TEMP_MARKER-bearing name. */
|
|
882
|
+
function archivePathFromTempName(dir, name) {
|
|
883
|
+
return join(dir, `${name.slice(0, name.indexOf(TEMP_MARKER))}.gz`);
|
|
884
|
+
}
|
|
885
|
+
/** True for names that are published or legacy archives. */
|
|
886
|
+
function isArchiveName(name) {
|
|
887
|
+
return name.endsWith(".gz") || /\.gz\.\d+$/.test(name);
|
|
888
|
+
}
|
|
889
|
+
/** True for names that are incomplete rotation artifacts. */
|
|
890
|
+
function isRecoveryArtifactName(name) {
|
|
891
|
+
return name.includes(".log.sealed-") || name.includes(".gz.tmp-");
|
|
892
|
+
}
|
|
893
|
+
const MAX_PENDING_BYTES$1 = 4194304;
|
|
894
|
+
const MAX_PENDING_RECORDS$1 = 2e4;
|
|
895
|
+
const MAX_DIAGNOSTICS = 40;
|
|
896
|
+
const MAX_DELETES_PER_SWEEP = 64;
|
|
897
|
+
const MAX_OPEN_ATTEMPTS = 3;
|
|
898
|
+
const MAX_UNRESOLVED_ARTIFACTS = 6;
|
|
899
|
+
const STREAM_CLOSE_TIMEOUT_MS = 2e3;
|
|
900
|
+
const DRAIN_TIMEOUT_MS = 2e3;
|
|
901
|
+
const TEMP_MAX_AGE_MS = 864e5;
|
|
902
|
+
/** Streams `src` into a gzip temp file. Never loads the whole log into memory. */
|
|
903
|
+
async function compressFileToArchive(src, tmp, faults) {
|
|
904
|
+
if (faults?.gzipDelayMs) await new Promise((resolve) => setTimeout(resolve, faults.gzipDelayMs));
|
|
905
|
+
if (faults?.gzip) throw new Error("injected gzip failure");
|
|
906
|
+
await pipeline(createReadStream(src), createGzip({ level: 6 }), createWriteStream(tmp, { flags: "wx" }));
|
|
907
|
+
}
|
|
908
|
+
/** Verifies a gzip archive is complete and readable (trailer included). */
|
|
909
|
+
async function verifyGzipArchive(path) {
|
|
910
|
+
let bytes = 0;
|
|
911
|
+
const counter = new Writable({ write(chunk, _encoding, callback) {
|
|
912
|
+
bytes += chunk.length;
|
|
913
|
+
callback();
|
|
914
|
+
} });
|
|
915
|
+
await pipeline(createReadStream(path), createGunzip(), counter);
|
|
916
|
+
return bytes;
|
|
502
917
|
}
|
|
503
918
|
/**
|
|
504
|
-
*
|
|
919
|
+
* Serialized writer for one DSH log stream.
|
|
505
920
|
*
|
|
506
|
-
*
|
|
507
|
-
*
|
|
508
|
-
*
|
|
509
|
-
*
|
|
921
|
+
* Every mutation — append, seal, compress, publish, sweep — runs on ONE promise
|
|
922
|
+
* chain, so two plugins logging concurrently can never interleave a rotation
|
|
923
|
+
* with a write, and `flush()` has a single, exact meaning: "everything enqueued
|
|
924
|
+
* so far, including any rotation it triggered, has finished".
|
|
510
925
|
*/
|
|
511
|
-
|
|
926
|
+
var DshLogWriter = class {
|
|
927
|
+
dir;
|
|
928
|
+
baseName;
|
|
929
|
+
cfg;
|
|
930
|
+
maxSizeBytes;
|
|
931
|
+
now;
|
|
932
|
+
faults;
|
|
933
|
+
onDiagnostic;
|
|
934
|
+
stream = null;
|
|
935
|
+
currentDate;
|
|
936
|
+
currentPath;
|
|
937
|
+
bytesWritten = 0;
|
|
938
|
+
queue = Promise.resolve();
|
|
939
|
+
pendingBytes = 0;
|
|
940
|
+
pendingRecords = 0;
|
|
941
|
+
droppedRecords = 0;
|
|
942
|
+
openAttempts = 0;
|
|
943
|
+
rotationCount = 0;
|
|
944
|
+
deletions = 0;
|
|
945
|
+
protectedFiles = /* @__PURE__ */ new Set();
|
|
946
|
+
diagnosticsEmitted = 0;
|
|
947
|
+
closing = false;
|
|
948
|
+
opened = false;
|
|
949
|
+
health = "initializing";
|
|
950
|
+
healthReason = "awaiting instance ownership";
|
|
951
|
+
lastError = null;
|
|
952
|
+
constructor(options) {
|
|
953
|
+
this.dir = options.dir;
|
|
954
|
+
this.baseName = options.baseName ?? "dsh";
|
|
955
|
+
this.cfg = options.cfg ?? DSH_ROTATION;
|
|
956
|
+
this.maxSizeBytes = parseSize(this.cfg.maxSize);
|
|
957
|
+
this.now = options.now ?? (() => /* @__PURE__ */ new Date());
|
|
958
|
+
this.faults = options.faults ?? {};
|
|
959
|
+
this.onDiagnostic = options.onDiagnostic;
|
|
960
|
+
this.currentDate = todayString(this.now());
|
|
961
|
+
this.currentPath = this.pathForDate(this.currentDate);
|
|
962
|
+
}
|
|
963
|
+
/** Absolute path of the active file (whether or not it is open yet). */
|
|
964
|
+
get path() {
|
|
965
|
+
return this.currentPath;
|
|
966
|
+
}
|
|
967
|
+
getHealth() {
|
|
968
|
+
return {
|
|
969
|
+
state: this.health,
|
|
970
|
+
reason: this.healthReason,
|
|
971
|
+
droppedRecords: this.droppedRecords,
|
|
972
|
+
rotationCount: this.rotationCount,
|
|
973
|
+
lastError: this.lastError
|
|
974
|
+
};
|
|
975
|
+
}
|
|
976
|
+
/** Opens the active file. Called only after the directory is owned. */
|
|
977
|
+
open() {
|
|
978
|
+
if (this.closing || this.opened) return;
|
|
979
|
+
this.opened = true;
|
|
980
|
+
this.openStream();
|
|
981
|
+
this.queue = this.queue.then(() => this.runSweepSafely());
|
|
982
|
+
}
|
|
983
|
+
pathForDate(date) {
|
|
984
|
+
return join(this.dir, `${this.baseName}.${date}.log`);
|
|
985
|
+
}
|
|
986
|
+
diagnose(event, err, extra = {}) {
|
|
987
|
+
if (this.diagnosticsEmitted >= MAX_DIAGNOSTICS) return;
|
|
988
|
+
this.diagnosticsEmitted += 1;
|
|
989
|
+
const record = {
|
|
990
|
+
event: `dsh-logging-${event}`,
|
|
991
|
+
instanceDir: this.dir,
|
|
992
|
+
...extra
|
|
993
|
+
};
|
|
994
|
+
if (err !== void 0) {
|
|
995
|
+
record.code = errorCode(err);
|
|
996
|
+
record.message = errorMessage(err).slice(0, 500);
|
|
997
|
+
this.lastError = errorMessage(err).slice(0, 500);
|
|
998
|
+
}
|
|
999
|
+
if (this.onDiagnostic) try {
|
|
1000
|
+
this.onDiagnostic(record);
|
|
1001
|
+
return;
|
|
1002
|
+
} catch {}
|
|
1003
|
+
appendDiagnostic(join(this.dir, "logging-health.log"), record);
|
|
1004
|
+
}
|
|
1005
|
+
setHealth(state, reason, err) {
|
|
1006
|
+
this.health = state;
|
|
1007
|
+
this.healthReason = reason;
|
|
1008
|
+
if (err !== void 0) this.lastError = errorMessage(err).slice(0, 500);
|
|
1009
|
+
}
|
|
1010
|
+
openStream() {
|
|
1011
|
+
if (this.closing) return;
|
|
1012
|
+
if (this.faults.streamOpen) {
|
|
1013
|
+
this.setHealth("unavailable", "injected stream-open failure");
|
|
1014
|
+
this.diagnose("open-failed", /* @__PURE__ */ new Error("injected stream-open failure"));
|
|
1015
|
+
return;
|
|
1016
|
+
}
|
|
1017
|
+
try {
|
|
1018
|
+
const stream = createWriteStream(this.currentPath, { flags: "a" });
|
|
1019
|
+
stream.on("error", (err) => {
|
|
1020
|
+
this.diagnose("write-stream-error", err);
|
|
1021
|
+
this.setHealth("degraded", "active write stream error", err);
|
|
1022
|
+
if (this.stream !== stream) return;
|
|
1023
|
+
this.stream = null;
|
|
1024
|
+
stream.destroy();
|
|
1025
|
+
});
|
|
1026
|
+
this.stream = stream;
|
|
1027
|
+
this.bytesWritten = sizeOrZero(this.currentPath);
|
|
1028
|
+
this.setHealth("healthy", "active log stream open");
|
|
1029
|
+
if (this.faults.diskFull) {
|
|
1030
|
+
const err = Object.assign(/* @__PURE__ */ new Error("ENOSPC: no space left on device"), { code: "ENOSPC" });
|
|
1031
|
+
setImmediate(() => stream.emit("error", err));
|
|
1032
|
+
}
|
|
1033
|
+
} catch (err) {
|
|
1034
|
+
this.setHealth("degraded", "cannot open active log file", err);
|
|
1035
|
+
this.diagnose("open-failed", err);
|
|
1036
|
+
}
|
|
1037
|
+
}
|
|
1038
|
+
/** Total in-memory queue pressure, used to reject unbounded buffering. */
|
|
1039
|
+
canEnqueue(bytes) {
|
|
1040
|
+
if (this.pendingBytes + bytes <= MAX_PENDING_BYTES$1 && this.pendingRecords < MAX_PENDING_RECORDS$1) return true;
|
|
1041
|
+
this.droppedRecords += 1;
|
|
1042
|
+
this.diagnose("pending-overflow", void 0, { droppedTotal: this.droppedRecords });
|
|
1043
|
+
return false;
|
|
1044
|
+
}
|
|
1045
|
+
/**
|
|
1046
|
+
* Enqueues one already-serialized JSONL record. Never throws and never
|
|
1047
|
+
* blocks the caller: a plugin's business call returns immediately.
|
|
1048
|
+
*/
|
|
1049
|
+
write(line) {
|
|
1050
|
+
if (this.closing) {
|
|
1051
|
+
this.droppedRecords += 1;
|
|
1052
|
+
return;
|
|
1053
|
+
}
|
|
1054
|
+
const bytes = Buffer.byteLength(line, "utf8");
|
|
1055
|
+
if (!this.canEnqueue(bytes)) return;
|
|
1056
|
+
this.pendingBytes += bytes;
|
|
1057
|
+
this.pendingRecords += 1;
|
|
1058
|
+
this.queue = this.queue.then(async () => {
|
|
1059
|
+
this.pendingBytes -= bytes;
|
|
1060
|
+
this.pendingRecords -= 1;
|
|
1061
|
+
await this.append(line);
|
|
1062
|
+
}).catch((err) => {
|
|
1063
|
+
this.diagnose("append-failed", err);
|
|
1064
|
+
this.setHealth("degraded", "append failed", err);
|
|
1065
|
+
});
|
|
1066
|
+
}
|
|
1067
|
+
async append(line) {
|
|
1068
|
+
if (this.closing || this.health === "unavailable") {
|
|
1069
|
+
this.droppedRecords += 1;
|
|
1070
|
+
return;
|
|
1071
|
+
}
|
|
1072
|
+
if (todayString(this.now()) !== this.currentDate) await this.rotate("date");
|
|
1073
|
+
if (!this.stream) {
|
|
1074
|
+
if (this.openAttempts >= MAX_OPEN_ATTEMPTS) {
|
|
1075
|
+
this.droppedRecords += 1;
|
|
1076
|
+
return;
|
|
1077
|
+
}
|
|
1078
|
+
this.openAttempts += 1;
|
|
1079
|
+
this.openStream();
|
|
1080
|
+
if (!this.stream) {
|
|
1081
|
+
this.droppedRecords += 1;
|
|
1082
|
+
return;
|
|
1083
|
+
}
|
|
1084
|
+
}
|
|
1085
|
+
const stream = this.stream;
|
|
1086
|
+
try {
|
|
1087
|
+
await this.writeChunk(stream, line);
|
|
1088
|
+
this.bytesWritten += Buffer.byteLength(line, "utf8");
|
|
1089
|
+
this.openAttempts = 0;
|
|
1090
|
+
} catch (err) {
|
|
1091
|
+
this.diagnose("write-failed", err);
|
|
1092
|
+
this.setHealth("degraded", "write failed", err);
|
|
1093
|
+
this.droppedRecords += 1;
|
|
1094
|
+
return;
|
|
1095
|
+
}
|
|
1096
|
+
if (this.bytesWritten >= this.maxSizeBytes) await this.rotate("size");
|
|
1097
|
+
}
|
|
1098
|
+
/**
|
|
1099
|
+
* Writes one chunk and resolves only once the stream has flushed it, so
|
|
1100
|
+
* `flush()` is a real durability boundary (not just "handed to the stream").
|
|
1101
|
+
* A bounded timeout keeps a wedged stream from stalling shutdown forever.
|
|
1102
|
+
*/
|
|
1103
|
+
writeChunk(stream, chunk) {
|
|
1104
|
+
return new Promise((resolve, reject) => {
|
|
1105
|
+
let settled = false;
|
|
1106
|
+
let timer = null;
|
|
1107
|
+
const cleanup = () => {
|
|
1108
|
+
if (timer) clearTimeout(timer);
|
|
1109
|
+
stream.removeListener("error", onError);
|
|
1110
|
+
};
|
|
1111
|
+
const finish = (err) => {
|
|
1112
|
+
if (settled) return;
|
|
1113
|
+
settled = true;
|
|
1114
|
+
cleanup();
|
|
1115
|
+
if (err) reject(err);
|
|
1116
|
+
else resolve();
|
|
1117
|
+
};
|
|
1118
|
+
const onError = (err) => finish(err);
|
|
1119
|
+
stream.once("error", onError);
|
|
1120
|
+
try {
|
|
1121
|
+
if (!stream.write(chunk, (err) => {
|
|
1122
|
+
if (err) finish(err);
|
|
1123
|
+
else finish();
|
|
1124
|
+
})) {
|
|
1125
|
+
timer = setTimeout(() => finish(), DRAIN_TIMEOUT_MS);
|
|
1126
|
+
timer.unref();
|
|
1127
|
+
}
|
|
1128
|
+
} catch (err) {
|
|
1129
|
+
finish(err instanceof Error ? err : new Error(String(err)));
|
|
1130
|
+
}
|
|
1131
|
+
});
|
|
1132
|
+
}
|
|
1133
|
+
sealedPathFor(date, reason, sequence) {
|
|
1134
|
+
const stem = reason === "date" ? `${this.baseName}.${date}` : `${this.baseName}.${date}.${sequence}`;
|
|
1135
|
+
return join(this.dir, `${stem}${SEALED_MARKER}${randomUUID()}`);
|
|
1136
|
+
}
|
|
1137
|
+
archivePathFor(sealedPath) {
|
|
1138
|
+
const name = basename(sealedPath);
|
|
1139
|
+
const marker = name.indexOf(SEALED_MARKER);
|
|
1140
|
+
const stem = marker > 0 ? name.slice(0, marker) : name;
|
|
1141
|
+
return join(this.dir, `${stem}${ARCHIVE_SUFFIX}`);
|
|
1142
|
+
}
|
|
1143
|
+
/** Never overwrite: pick the first free sequence, never append `.gz.N`. */
|
|
1144
|
+
chooseArchivePath(preferred, startSeq = 1) {
|
|
1145
|
+
if (startSeq === 1 && !existsSync(preferred)) return preferred;
|
|
1146
|
+
const stem = (preferred.endsWith(".log.gz") ? preferred.slice(0, -7) : preferred).replace(/\.\d+$/, "");
|
|
1147
|
+
for (let seq = startSeq; seq < 1e4; seq += 1) {
|
|
1148
|
+
const candidate = `${stem}.${seq}${ARCHIVE_SUFFIX}`;
|
|
1149
|
+
if (!existsSync(candidate)) return candidate;
|
|
1150
|
+
}
|
|
1151
|
+
return `${stem}.${randomUUID()}${ARCHIVE_SUFFIX}`;
|
|
1152
|
+
}
|
|
1153
|
+
unresolvedArtifactCount() {
|
|
1154
|
+
try {
|
|
1155
|
+
return readdirSync(this.dir).filter((name) => isRecoveryArtifactName(name)).length;
|
|
1156
|
+
} catch {
|
|
1157
|
+
return 0;
|
|
1158
|
+
}
|
|
1159
|
+
}
|
|
1160
|
+
closeStream() {
|
|
1161
|
+
const stream = this.stream;
|
|
1162
|
+
this.stream = null;
|
|
1163
|
+
if (!stream) return Promise.resolve();
|
|
1164
|
+
return new Promise((resolve) => {
|
|
1165
|
+
let settled = false;
|
|
1166
|
+
const done = () => {
|
|
1167
|
+
if (settled) return;
|
|
1168
|
+
settled = true;
|
|
1169
|
+
resolve();
|
|
1170
|
+
};
|
|
1171
|
+
stream.once("finish", done);
|
|
1172
|
+
stream.once("error", done);
|
|
1173
|
+
stream.once("close", done);
|
|
1174
|
+
try {
|
|
1175
|
+
stream.end();
|
|
1176
|
+
} catch {
|
|
1177
|
+
done();
|
|
1178
|
+
}
|
|
1179
|
+
setTimeout(done, STREAM_CLOSE_TIMEOUT_MS).unref();
|
|
1180
|
+
});
|
|
1181
|
+
}
|
|
1182
|
+
async rotate(reason) {
|
|
1183
|
+
if (this.closing || this.health === "unavailable") return;
|
|
1184
|
+
const unresolved = this.unresolvedArtifactCount();
|
|
1185
|
+
if (reason === "size" && unresolved >= MAX_UNRESOLVED_ARTIFACTS) {
|
|
1186
|
+
this.diagnose("rotation-deferred", void 0, {
|
|
1187
|
+
unresolved,
|
|
1188
|
+
cap: MAX_UNRESOLVED_ARTIFACTS
|
|
1189
|
+
});
|
|
1190
|
+
this.setHealth("degraded", "unresolved rotation artifacts at cap; continuing on active file");
|
|
1191
|
+
return;
|
|
1192
|
+
}
|
|
1193
|
+
this.rotationCount += 1;
|
|
1194
|
+
const closingDate = this.currentDate;
|
|
1195
|
+
const closingPath = this.currentPath;
|
|
1196
|
+
await this.closeStream();
|
|
1197
|
+
this.currentDate = todayString(this.now());
|
|
1198
|
+
this.currentPath = this.pathForDate(this.currentDate);
|
|
1199
|
+
if (!existsSync(closingPath) || sizeOrZero(closingPath) === 0) {
|
|
1200
|
+
try {
|
|
1201
|
+
if (existsSync(closingPath)) unlinkSync(closingPath);
|
|
1202
|
+
} catch {}
|
|
1203
|
+
this.openStream();
|
|
1204
|
+
return;
|
|
1205
|
+
}
|
|
1206
|
+
const sequence = reason === "size" ? this.rotationCount : 0;
|
|
1207
|
+
const sealedPath = this.sealedPathFor(closingDate, reason, sequence);
|
|
1208
|
+
try {
|
|
1209
|
+
if (this.faults.seal) throw new Error("injected seal failure");
|
|
1210
|
+
await withFsRetries(() => renameSync(closingPath, sealedPath), {
|
|
1211
|
+
attempts: 5,
|
|
1212
|
+
baseDelayMs: 25,
|
|
1213
|
+
totalTimeoutMs: 2e3
|
|
1214
|
+
});
|
|
1215
|
+
} catch (err) {
|
|
1216
|
+
this.diagnose("seal-failed", err, { closingPath });
|
|
1217
|
+
this.setHealth("degraded", "seal failed; continuing on active file", err);
|
|
1218
|
+
this.currentDate = closingDate;
|
|
1219
|
+
this.currentPath = closingPath;
|
|
1220
|
+
this.openStream();
|
|
1221
|
+
return;
|
|
1222
|
+
}
|
|
1223
|
+
this.protectedFiles.add(sealedPath);
|
|
1224
|
+
this.openStream();
|
|
1225
|
+
if (!this.cfg.compress) {
|
|
1226
|
+
this.protectedFiles.delete(sealedPath);
|
|
1227
|
+
return;
|
|
1228
|
+
}
|
|
1229
|
+
const preferredArchive = this.chooseArchivePath(this.archivePathFor(sealedPath));
|
|
1230
|
+
const tmpPath = tempArchivePathFor(preferredArchive);
|
|
1231
|
+
this.protectedFiles.add(tmpPath);
|
|
1232
|
+
let archiveVerified = false;
|
|
1233
|
+
try {
|
|
1234
|
+
await compressFileToArchive(sealedPath, tmpPath, this.faults);
|
|
1235
|
+
await verifyGzipArchive(tmpPath);
|
|
1236
|
+
archiveVerified = true;
|
|
1237
|
+
if (this.faults.publishDelayMs) await new Promise((resolve) => setTimeout(resolve, this.faults.publishDelayMs));
|
|
1238
|
+
if (this.faults.publish) throw new Error("injected publish failure");
|
|
1239
|
+
let published = false;
|
|
1240
|
+
let archivePath = preferredArchive;
|
|
1241
|
+
for (let attempt = 0; attempt < 32 && !published; attempt += 1) {
|
|
1242
|
+
try {
|
|
1243
|
+
published = await withFsRetries(() => atomicPublish(tmpPath, archivePath), {
|
|
1244
|
+
attempts: 4,
|
|
1245
|
+
baseDelayMs: 25,
|
|
1246
|
+
totalTimeoutMs: 2e3,
|
|
1247
|
+
isRetryable: (err) => errorCode(err) !== "EEXIST" && errorCode(err) !== "ENOENT"
|
|
1248
|
+
});
|
|
1249
|
+
} catch (err) {
|
|
1250
|
+
this.diagnose("publish-failed", err, { archivePath });
|
|
1251
|
+
break;
|
|
1252
|
+
}
|
|
1253
|
+
if (!published) archivePath = this.chooseArchivePath(preferredArchive, attempt + 2);
|
|
1254
|
+
}
|
|
1255
|
+
if (!published) {
|
|
1256
|
+
this.diagnose("publish-unresolved", void 0, {
|
|
1257
|
+
sealedPath,
|
|
1258
|
+
tmpPath,
|
|
1259
|
+
archivePath
|
|
1260
|
+
});
|
|
1261
|
+
this.setHealth("degraded", "archive publication deferred to recovery");
|
|
1262
|
+
return;
|
|
1263
|
+
}
|
|
1264
|
+
this.protectedFiles.delete(tmpPath);
|
|
1265
|
+
this.diagnose("archive-published", void 0, { archivePath });
|
|
1266
|
+
try {
|
|
1267
|
+
if (this.faults.unlink) throw new Error("injected unlink failure");
|
|
1268
|
+
await withFsRetries(() => unlinkSync(sealedPath), {
|
|
1269
|
+
attempts: 4,
|
|
1270
|
+
baseDelayMs: 25,
|
|
1271
|
+
totalTimeoutMs: 2e3
|
|
1272
|
+
});
|
|
1273
|
+
} catch (err) {
|
|
1274
|
+
this.diagnose("source-unlink-failed", err, { sealedPath });
|
|
1275
|
+
}
|
|
1276
|
+
this.setHealth("healthy", "rotation completed");
|
|
1277
|
+
} catch (err) {
|
|
1278
|
+
if (archiveVerified) {
|
|
1279
|
+
this.diagnose("publish-failed-after-verify", err, {
|
|
1280
|
+
sealedPath,
|
|
1281
|
+
tmpPath
|
|
1282
|
+
});
|
|
1283
|
+
this.setHealth("degraded", "archive publication deferred to recovery");
|
|
1284
|
+
} else {
|
|
1285
|
+
this.diagnose("compression-failed", err, {
|
|
1286
|
+
sealedPath,
|
|
1287
|
+
tmpPath
|
|
1288
|
+
});
|
|
1289
|
+
this.setHealth("degraded", "rotation failed; sealed source preserved", err);
|
|
1290
|
+
try {
|
|
1291
|
+
if (existsSync(tmpPath)) unlinkSync(tmpPath);
|
|
1292
|
+
} catch {}
|
|
1293
|
+
this.protectedFiles.delete(tmpPath);
|
|
1294
|
+
}
|
|
1295
|
+
} finally {
|
|
1296
|
+
this.protectedFiles.delete(sealedPath);
|
|
1297
|
+
await this.runSweepSafely();
|
|
1298
|
+
}
|
|
1299
|
+
}
|
|
1300
|
+
async runSweepSafely() {
|
|
1301
|
+
try {
|
|
1302
|
+
await this.runSweep();
|
|
1303
|
+
} catch (err) {
|
|
1304
|
+
this.diagnose("sweep-failed", err);
|
|
1305
|
+
}
|
|
1306
|
+
}
|
|
1307
|
+
/**
|
|
1308
|
+
* Capacity + retention. Counts ACTUAL disk consumption of the instance
|
|
1309
|
+
* directory. The active file and any file involved in the current rotation
|
|
1310
|
+
* are never deleted.
|
|
1311
|
+
*/
|
|
1312
|
+
async runSweep() {
|
|
1313
|
+
this.deletions = 0;
|
|
1314
|
+
let entries;
|
|
1315
|
+
try {
|
|
1316
|
+
entries = await promises.readdir(this.dir);
|
|
1317
|
+
} catch {
|
|
1318
|
+
return;
|
|
1319
|
+
}
|
|
1320
|
+
const activeName = `${this.baseName}.${this.currentDate}.log`;
|
|
1321
|
+
const now = Date.now();
|
|
1322
|
+
const retentionMs = this.cfg.retentionDays * 24 * 60 * 60 * 1e3;
|
|
1323
|
+
const candidates = [];
|
|
1324
|
+
let totalSize = 0;
|
|
1325
|
+
for (const name of entries.slice(0, 2e4)) {
|
|
1326
|
+
const path = join(this.dir, name);
|
|
1327
|
+
try {
|
|
1328
|
+
const stat = await promises.stat(path);
|
|
1329
|
+
if (!stat.isFile()) continue;
|
|
1330
|
+
totalSize += stat.size;
|
|
1331
|
+
if (name === activeName || this.protectedFiles.has(path)) continue;
|
|
1332
|
+
if (isArchiveName(name)) candidates.push({
|
|
1333
|
+
name,
|
|
1334
|
+
path,
|
|
1335
|
+
size: stat.size,
|
|
1336
|
+
mtime: stat.mtimeMs
|
|
1337
|
+
});
|
|
1338
|
+
else if (name.includes(".gz.tmp-") && now - stat.mtimeMs > TEMP_MAX_AGE_MS) candidates.push({
|
|
1339
|
+
name,
|
|
1340
|
+
path,
|
|
1341
|
+
size: stat.size,
|
|
1342
|
+
mtime: stat.mtimeMs
|
|
1343
|
+
});
|
|
1344
|
+
} catch {}
|
|
1345
|
+
}
|
|
1346
|
+
for (const file of candidates) {
|
|
1347
|
+
const match = /\.(\d{4}-\d{2}-\d{2})\./.exec(file.name);
|
|
1348
|
+
const stamp = match?.[1] ? Date.parse(match[1]) : NaN;
|
|
1349
|
+
if ((Number.isNaN(stamp) ? now - file.mtime : now - stamp) <= retentionMs) continue;
|
|
1350
|
+
if (await this.deleteEligible(file)) totalSize -= file.size;
|
|
1351
|
+
}
|
|
1352
|
+
if (totalSize > this.cfg.maxStorageBytes) {
|
|
1353
|
+
const sorted = candidates.filter((file) => existsSync(file.path)).sort((a, b) => a.mtime - b.mtime);
|
|
1354
|
+
for (const file of sorted) {
|
|
1355
|
+
if (totalSize <= this.cfg.maxStorageBytes) break;
|
|
1356
|
+
if (await this.deleteEligible(file)) totalSize -= file.size;
|
|
1357
|
+
}
|
|
1358
|
+
}
|
|
1359
|
+
}
|
|
1360
|
+
async deleteEligible(file) {
|
|
1361
|
+
if (this.deletions >= MAX_DELETES_PER_SWEEP) return false;
|
|
1362
|
+
if (!existsSync(file.path)) return false;
|
|
1363
|
+
try {
|
|
1364
|
+
await withFsRetries(() => unlinkSync(file.path), {
|
|
1365
|
+
attempts: 3,
|
|
1366
|
+
baseDelayMs: 25,
|
|
1367
|
+
totalTimeoutMs: 1e3
|
|
1368
|
+
});
|
|
1369
|
+
this.deletions += 1;
|
|
1370
|
+
return true;
|
|
1371
|
+
} catch (err) {
|
|
1372
|
+
this.diagnose("cleanup-failed", err, { file: file.name });
|
|
1373
|
+
return false;
|
|
1374
|
+
}
|
|
1375
|
+
}
|
|
1376
|
+
/**
|
|
1377
|
+
* Waits until everything enqueued so far — including a rotation it
|
|
1378
|
+
* triggered — has completed. Never called from plugin code; only from DSH
|
|
1379
|
+
* shutdown and tests.
|
|
1380
|
+
*/
|
|
1381
|
+
async flush() {
|
|
1382
|
+
await this.queue;
|
|
1383
|
+
}
|
|
1384
|
+
/** Bounded, final close. Deletes nothing and finishes the active file. */
|
|
1385
|
+
async close() {
|
|
1386
|
+
if (this.closing) {
|
|
1387
|
+
await this.queue;
|
|
1388
|
+
return;
|
|
1389
|
+
}
|
|
1390
|
+
this.closing = true;
|
|
1391
|
+
await this.queue;
|
|
1392
|
+
await this.closeStream();
|
|
1393
|
+
}
|
|
1394
|
+
};
|
|
1395
|
+
//#endregion
|
|
1396
|
+
//#region src/recovery.ts
|
|
1397
|
+
/**
|
|
1398
|
+
* Bounded historical recovery + retention for DSH log directories.
|
|
1399
|
+
*
|
|
1400
|
+
* A running DSH process owns ONLY `<dsh-root>/<its own dsh_instance_id>`. It may
|
|
1401
|
+
* inspect sibling (historical) directories — a previous DSH launch under the
|
|
1402
|
+
* same HQ Edge process leaves one behind every time DSH restarts — but every
|
|
1403
|
+
* modification MUST be preceded by successfully acquiring THAT directory's OS
|
|
1404
|
+
* ownership lock.
|
|
1405
|
+
*
|
|
1406
|
+
* That ordering is the whole safety argument (§5):
|
|
1407
|
+
* - the parent HQ Edge process never rotates DSH logs while DSH runs;
|
|
1408
|
+
* - one DSH process never rotates another LIVE DSH process's log;
|
|
1409
|
+
* - a directory whose owner is gone can be repaired by any later DSH process.
|
|
1410
|
+
*
|
|
1411
|
+
* Recovery is idempotent, bounded in time and file count, never rewrites
|
|
1412
|
+
* `instance.json`, never overwrites a published archive, and preserves
|
|
1413
|
+
* anything it cannot verify.
|
|
1414
|
+
*/
|
|
1415
|
+
function emptyReport() {
|
|
1416
|
+
return {
|
|
1417
|
+
scanned: 0,
|
|
1418
|
+
skippedLive: 0,
|
|
1419
|
+
skippedInvalid: 0,
|
|
1420
|
+
skippedRecent: 0,
|
|
1421
|
+
recovered: 0,
|
|
1422
|
+
preserved: 0,
|
|
1423
|
+
quarantined: 0,
|
|
1424
|
+
deletedFiles: 0,
|
|
1425
|
+
deletedDirectories: 0,
|
|
1426
|
+
truncated: false,
|
|
1427
|
+
details: []
|
|
1428
|
+
};
|
|
1429
|
+
}
|
|
1430
|
+
function report(options, record) {
|
|
1431
|
+
appendDiagnostic(join(options.ownInstanceDir, RECOVERY_LOG_FILENAME), record);
|
|
1432
|
+
try {
|
|
1433
|
+
options.report?.(record);
|
|
1434
|
+
} catch {}
|
|
1435
|
+
}
|
|
1436
|
+
function archivePathForArtifact(dir, name) {
|
|
1437
|
+
if (name.includes(".gz.tmp-")) return archivePathFromTempName(dir, name);
|
|
1438
|
+
const stem = name.slice(0, name.indexOf(SEALED_MARKER));
|
|
1439
|
+
return join(dir, `${stem}${ARCHIVE_SUFFIX}`);
|
|
1440
|
+
}
|
|
1441
|
+
function uniqueArchivePath(preferred) {
|
|
1442
|
+
if (!existsSync(preferred)) return preferred;
|
|
1443
|
+
const stem = preferred.slice(0, -7);
|
|
1444
|
+
for (let seq = 1; seq < 1e3; seq += 1) {
|
|
1445
|
+
const candidate = `${stem}.${seq}${ARCHIVE_SUFFIX}`;
|
|
1446
|
+
if (!existsSync(candidate)) return candidate;
|
|
1447
|
+
}
|
|
1448
|
+
return `${stem}.${randomUUID()}${ARCHIVE_SUFFIX}`;
|
|
1449
|
+
}
|
|
1450
|
+
/**
|
|
1451
|
+
* Repairs incomplete rotation artifacts left by a previous DSH process.
|
|
1452
|
+
* Safe to run repeatedly and safe to run while other DSH processes are active
|
|
1453
|
+
* (their directories are skipped because their ownership lock is held).
|
|
1454
|
+
*/
|
|
1455
|
+
async function recoverDshInstances(options) {
|
|
1456
|
+
const now = options.now ?? Date.now;
|
|
1457
|
+
const maxDirectories = options.maxDirectories ?? 64;
|
|
1458
|
+
const maxFiles = options.maxFilesPerDirectory ?? 256;
|
|
1459
|
+
const deadline = now() + (options.timeBudgetMs ?? 3e3);
|
|
1460
|
+
const minAgeMs = options.minAgeMs ?? 5e3;
|
|
1461
|
+
const result = emptyReport();
|
|
1462
|
+
const recentGuard = minAgeMs > 0;
|
|
1463
|
+
const note = (dir, action, detail) => {
|
|
1464
|
+
result.details.push({
|
|
1465
|
+
dir,
|
|
1466
|
+
action,
|
|
1467
|
+
detail
|
|
1468
|
+
});
|
|
1469
|
+
report(options, {
|
|
1470
|
+
event: "dsh-historical-recovery",
|
|
1471
|
+
dir,
|
|
1472
|
+
action,
|
|
1473
|
+
detail
|
|
1474
|
+
});
|
|
1475
|
+
};
|
|
1476
|
+
let names;
|
|
1477
|
+
try {
|
|
1478
|
+
names = await promises.readdir(options.instancesRoot);
|
|
1479
|
+
} catch {
|
|
1480
|
+
return result;
|
|
1481
|
+
}
|
|
1482
|
+
for (const name of names.slice(0, maxDirectories)) {
|
|
1483
|
+
if (now() > deadline) {
|
|
1484
|
+
result.truncated = true;
|
|
1485
|
+
break;
|
|
1486
|
+
}
|
|
1487
|
+
const dir = join(options.instancesRoot, name);
|
|
1488
|
+
if (dir === options.ownInstanceDir) continue;
|
|
1489
|
+
if (!isUuid(name)) {
|
|
1490
|
+
result.skippedInvalid += 1;
|
|
1491
|
+
note(dir, "preserved-invalid-name");
|
|
1492
|
+
continue;
|
|
1493
|
+
}
|
|
1494
|
+
let stat;
|
|
1495
|
+
try {
|
|
1496
|
+
stat = await promises.stat(dir);
|
|
1497
|
+
if (!stat.isDirectory()) continue;
|
|
1498
|
+
} catch {
|
|
1499
|
+
continue;
|
|
1500
|
+
}
|
|
1501
|
+
result.scanned += 1;
|
|
1502
|
+
const metadata = readDshInstanceMetadata(dir);
|
|
1503
|
+
if (!metadata) {
|
|
1504
|
+
result.skippedInvalid += 1;
|
|
1505
|
+
note(dir, "preserved-corrupt-metadata");
|
|
1506
|
+
continue;
|
|
1507
|
+
}
|
|
1508
|
+
if (recentGuard && Math.max(0, now() - stat.mtimeMs) < minAgeMs) {
|
|
1509
|
+
result.skippedRecent += 1;
|
|
1510
|
+
note(dir, "skipped-recent");
|
|
1511
|
+
continue;
|
|
1512
|
+
}
|
|
1513
|
+
const ownership = await acquireHistoricalDshOwnership(dir, metadata.dshInstanceId);
|
|
1514
|
+
if (!ownership) {
|
|
1515
|
+
result.skippedLive += 1;
|
|
1516
|
+
note(dir, "skipped-live-owner");
|
|
1517
|
+
continue;
|
|
1518
|
+
}
|
|
1519
|
+
try {
|
|
1520
|
+
let files;
|
|
1521
|
+
try {
|
|
1522
|
+
files = (await promises.readdir(dir)).slice(0, maxFiles);
|
|
1523
|
+
} catch {
|
|
1524
|
+
continue;
|
|
1525
|
+
}
|
|
1526
|
+
for (const file of files) {
|
|
1527
|
+
if (now() > deadline) {
|
|
1528
|
+
result.truncated = true;
|
|
1529
|
+
break;
|
|
1530
|
+
}
|
|
1531
|
+
if (file.includes(".quarantine-")) continue;
|
|
1532
|
+
if (!file.includes(".gz.tmp-") && !file.includes(".log.sealed-")) continue;
|
|
1533
|
+
const path = join(dir, file);
|
|
1534
|
+
const canonicalArchive = archivePathForArtifact(dir, file);
|
|
1535
|
+
const canonicalExists = existsSync(canonicalArchive);
|
|
1536
|
+
if (file.includes(".gz.tmp-")) {
|
|
1537
|
+
try {
|
|
1538
|
+
await verifyGzipArchive(path);
|
|
1539
|
+
} catch {
|
|
1540
|
+
try {
|
|
1541
|
+
renameSync(path, `${path}${QUARANTINE_MARKER}${randomUUID()}`);
|
|
1542
|
+
result.quarantined += 1;
|
|
1543
|
+
note(dir, "quarantined-invalid-temp", file);
|
|
1544
|
+
} catch {
|
|
1545
|
+
result.preserved += 1;
|
|
1546
|
+
note(dir, "preserved-invalid-temp", file);
|
|
1547
|
+
}
|
|
1548
|
+
continue;
|
|
1549
|
+
}
|
|
1550
|
+
if (canonicalExists) {
|
|
1551
|
+
try {
|
|
1552
|
+
unlinkSync(path);
|
|
1553
|
+
result.deletedFiles += 1;
|
|
1554
|
+
note(dir, "removed-redundant-temp", file);
|
|
1555
|
+
} catch {
|
|
1556
|
+
result.preserved += 1;
|
|
1557
|
+
}
|
|
1558
|
+
continue;
|
|
1559
|
+
}
|
|
1560
|
+
try {
|
|
1561
|
+
if (atomicPublish(path, canonicalArchive)) {
|
|
1562
|
+
result.recovered += 1;
|
|
1563
|
+
note(dir, "published-temp-archive", file);
|
|
1564
|
+
} else {
|
|
1565
|
+
result.preserved += 1;
|
|
1566
|
+
note(dir, "preserved-publish-conflict", file);
|
|
1567
|
+
}
|
|
1568
|
+
} catch {
|
|
1569
|
+
result.preserved += 1;
|
|
1570
|
+
note(dir, "preserved-publish-failure", file);
|
|
1571
|
+
}
|
|
1572
|
+
continue;
|
|
1573
|
+
}
|
|
1574
|
+
if (canonicalExists) {
|
|
1575
|
+
result.preserved += 1;
|
|
1576
|
+
note(dir, "preserved-redundant-sealed", file);
|
|
1577
|
+
continue;
|
|
1578
|
+
}
|
|
1579
|
+
const archivePath = uniqueArchivePath(canonicalArchive);
|
|
1580
|
+
const tmp = tempArchivePathFor(archivePath);
|
|
1581
|
+
try {
|
|
1582
|
+
await compressFileToArchive(path, tmp);
|
|
1583
|
+
await verifyGzipArchive(tmp);
|
|
1584
|
+
if (atomicPublish(tmp, archivePath)) {
|
|
1585
|
+
await withFsRetries(() => unlinkSync(path), {
|
|
1586
|
+
attempts: 3,
|
|
1587
|
+
baseDelayMs: 25,
|
|
1588
|
+
totalTimeoutMs: 800
|
|
1589
|
+
});
|
|
1590
|
+
result.recovered += 1;
|
|
1591
|
+
note(dir, "recovered-sealed-source", file);
|
|
1592
|
+
} else {
|
|
1593
|
+
result.preserved += 1;
|
|
1594
|
+
note(dir, "preserved-archive-conflict", file);
|
|
1595
|
+
}
|
|
1596
|
+
} catch (err) {
|
|
1597
|
+
result.preserved += 1;
|
|
1598
|
+
note(dir, "preserved-compression-failure", `${file}: ${errorMessage(err).slice(0, 160)}`);
|
|
1599
|
+
try {
|
|
1600
|
+
if (existsSync(tmp)) unlinkSync(tmp);
|
|
1601
|
+
} catch {}
|
|
1602
|
+
}
|
|
1603
|
+
}
|
|
1604
|
+
} finally {
|
|
1605
|
+
ownership.release();
|
|
1606
|
+
recordRecoveryDiagnostic(dir, {
|
|
1607
|
+
event: "recovery-lock-released",
|
|
1608
|
+
pid: process.pid
|
|
1609
|
+
});
|
|
1610
|
+
}
|
|
1611
|
+
}
|
|
1612
|
+
return result;
|
|
1613
|
+
}
|
|
1614
|
+
/** Files that may remain in an expired instance directory. */
|
|
1615
|
+
const METADATA_FILES = /* @__PURE__ */ new Set([
|
|
1616
|
+
"instance.json",
|
|
1617
|
+
"owner.lock",
|
|
1618
|
+
"recovery.log",
|
|
1619
|
+
"fatal.log",
|
|
1620
|
+
"logging-health.log"
|
|
1621
|
+
]);
|
|
1622
|
+
/**
|
|
1623
|
+
* Per-instance retention. Never deletes an active directory: ownership
|
|
1624
|
+
* acquisition fails while the owner is alive. Never deletes a directory that
|
|
1625
|
+
* still has incomplete recovery artifacts.
|
|
1626
|
+
*/
|
|
1627
|
+
async function cleanupExpiredDshInstances(options) {
|
|
1628
|
+
const now = options.now ?? Date.now;
|
|
1629
|
+
const retentionMs = (options.retentionDays ?? 30) * 24 * 60 * 60 * 1e3;
|
|
1630
|
+
const deadline = now() + (options.timeBudgetMs ?? 3e3);
|
|
1631
|
+
const result = emptyReport();
|
|
1632
|
+
const note = (dir, action, detail) => {
|
|
1633
|
+
result.details.push({
|
|
1634
|
+
dir,
|
|
1635
|
+
action,
|
|
1636
|
+
detail
|
|
1637
|
+
});
|
|
1638
|
+
report(options, {
|
|
1639
|
+
event: "dsh-historical-cleanup",
|
|
1640
|
+
dir,
|
|
1641
|
+
action,
|
|
1642
|
+
detail
|
|
1643
|
+
});
|
|
1644
|
+
};
|
|
1645
|
+
let names;
|
|
1646
|
+
try {
|
|
1647
|
+
names = await promises.readdir(options.instancesRoot);
|
|
1648
|
+
} catch {
|
|
1649
|
+
return result;
|
|
1650
|
+
}
|
|
1651
|
+
for (const name of names.slice(0, options.maxDirectories ?? 64)) {
|
|
1652
|
+
if (now() > deadline) {
|
|
1653
|
+
result.truncated = true;
|
|
1654
|
+
break;
|
|
1655
|
+
}
|
|
1656
|
+
const dir = join(options.instancesRoot, name);
|
|
1657
|
+
if (dir === options.ownInstanceDir || !isUuid(name)) continue;
|
|
1658
|
+
const metadata = readDshInstanceMetadata(dir);
|
|
1659
|
+
if (!metadata) {
|
|
1660
|
+
result.skippedInvalid += 1;
|
|
1661
|
+
note(dir, "preserved-corrupt-metadata");
|
|
1662
|
+
continue;
|
|
1663
|
+
}
|
|
1664
|
+
let stat;
|
|
1665
|
+
try {
|
|
1666
|
+
stat = await promises.stat(dir);
|
|
1667
|
+
} catch {
|
|
1668
|
+
continue;
|
|
1669
|
+
}
|
|
1670
|
+
if (Math.max(0, now() - stat.mtimeMs) < retentionMs) continue;
|
|
1671
|
+
result.scanned += 1;
|
|
1672
|
+
const ownership = await acquireHistoricalDshOwnership(dir, metadata.dshInstanceId);
|
|
1673
|
+
if (!ownership) {
|
|
1674
|
+
result.skippedLive += 1;
|
|
1675
|
+
note(dir, "skipped-live-owner");
|
|
1676
|
+
continue;
|
|
1677
|
+
}
|
|
1678
|
+
try {
|
|
1679
|
+
let files;
|
|
1680
|
+
try {
|
|
1681
|
+
files = await promises.readdir(dir);
|
|
1682
|
+
} catch {
|
|
1683
|
+
continue;
|
|
1684
|
+
}
|
|
1685
|
+
if (files.some((file) => file.includes(".gz.tmp-") || file.includes(".log.sealed-") || file.includes(".quarantine-"))) {
|
|
1686
|
+
result.preserved += 1;
|
|
1687
|
+
note(dir, "preserved-unrecovered-artifacts");
|
|
1688
|
+
continue;
|
|
1689
|
+
}
|
|
1690
|
+
for (const file of files) {
|
|
1691
|
+
if (METADATA_FILES.has(file)) continue;
|
|
1692
|
+
if (!isArchiveName(file) && !file.endsWith(".log")) {
|
|
1693
|
+
result.preserved += 1;
|
|
1694
|
+
note(dir, "preserved-unknown-file", file);
|
|
1695
|
+
continue;
|
|
1696
|
+
}
|
|
1697
|
+
try {
|
|
1698
|
+
await withFsRetries(() => unlinkSync(join(dir, file)), {
|
|
1699
|
+
attempts: 3,
|
|
1700
|
+
baseDelayMs: 25,
|
|
1701
|
+
totalTimeoutMs: 800
|
|
1702
|
+
});
|
|
1703
|
+
result.deletedFiles += 1;
|
|
1704
|
+
} catch {
|
|
1705
|
+
result.preserved += 1;
|
|
1706
|
+
note(dir, "preserved-delete-failure", file);
|
|
1707
|
+
}
|
|
1708
|
+
}
|
|
1709
|
+
if ((await promises.readdir(dir)).every((file) => METADATA_FILES.has(file))) try {
|
|
1710
|
+
await promises.rm(dir, {
|
|
1711
|
+
recursive: true,
|
|
1712
|
+
force: true
|
|
1713
|
+
});
|
|
1714
|
+
result.deletedDirectories += 1;
|
|
1715
|
+
note(dir, "deleted-expired-dsh-instance");
|
|
1716
|
+
} catch {
|
|
1717
|
+
note(dir, "preserved-delete-directory-failure");
|
|
1718
|
+
}
|
|
1719
|
+
} finally {
|
|
1720
|
+
ownership.release();
|
|
1721
|
+
}
|
|
1722
|
+
}
|
|
1723
|
+
return result;
|
|
1724
|
+
}
|
|
1725
|
+
/**
|
|
1726
|
+
* Conservative handling of the pre-isolation shared plugin log (§3).
|
|
1727
|
+
*
|
|
1728
|
+
* Old builds wrote `<HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log[.N]` from
|
|
1729
|
+
* every plugin in every DSH process. Those files have no ownership metadata
|
|
1730
|
+
* and may still be written by an older build during a rolling upgrade, so this
|
|
1731
|
+
* function only REPORTS them. Nothing is moved, compressed or deleted: a
|
|
1732
|
+
* one-time, operator-reviewed migration is the only safe way to retire them.
|
|
1733
|
+
*/
|
|
1734
|
+
async function reportLegacyPluginLogs(logBaseDir) {
|
|
1735
|
+
const files = [];
|
|
1736
|
+
let totalBytes = 0;
|
|
1737
|
+
const legacyDir = join(logBaseDir, "dsh-plugins");
|
|
1738
|
+
let names;
|
|
1739
|
+
try {
|
|
1740
|
+
names = await promises.readdir(legacyDir);
|
|
1741
|
+
} catch {
|
|
1742
|
+
return {
|
|
1743
|
+
files,
|
|
1744
|
+
totalBytes: 0,
|
|
1745
|
+
note: "no legacy dsh-plugins directory"
|
|
1746
|
+
};
|
|
1747
|
+
}
|
|
1748
|
+
for (const name of names) {
|
|
1749
|
+
if (!name.endsWith(".log") && !isArchiveName(name)) continue;
|
|
1750
|
+
const path = join(legacyDir, name);
|
|
1751
|
+
try {
|
|
1752
|
+
const stat = await promises.stat(path);
|
|
1753
|
+
if (!stat.isFile()) continue;
|
|
1754
|
+
files.push({
|
|
1755
|
+
path,
|
|
1756
|
+
size: stat.size,
|
|
1757
|
+
action: "preserved"
|
|
1758
|
+
});
|
|
1759
|
+
totalBytes += stat.size;
|
|
1760
|
+
} catch {}
|
|
1761
|
+
}
|
|
1762
|
+
return {
|
|
1763
|
+
files,
|
|
1764
|
+
totalBytes,
|
|
1765
|
+
note: `Preserved ${files.length} legacy shared plugin log file(s) (${totalBytes} bytes). No file was moved or deleted: ownership cannot be established from the old naming scheme.`
|
|
1766
|
+
};
|
|
1767
|
+
}
|
|
1768
|
+
//#endregion
|
|
1769
|
+
//#region src/runtime.ts
|
|
1770
|
+
/**
|
|
1771
|
+
* Process-wide logging runtime for ONE DSH process.
|
|
1772
|
+
*
|
|
1773
|
+
* This module is the only place that decides WHERE records go. Plugins never
|
|
1774
|
+
* see it: they call `getLogger()` and get a namespaced logger.
|
|
1775
|
+
*
|
|
1776
|
+
* Startup order (docs/tasks/dsh-plugin-log-isolation.md §4):
|
|
1777
|
+
* 1. read the parent logging context from the environment
|
|
1778
|
+
* 2. generate `dsh_instance_id` (per LAUNCH, never per plugin)
|
|
1779
|
+
* 3. create `<dsh-root>/<dsh_instance_id>/` exclusively
|
|
1780
|
+
* 4. write `instance.json` atomically (never overwrite)
|
|
1781
|
+
* 5. acquire the OS ownership lock for that directory
|
|
1782
|
+
* 6. open `dsh.<date>.log` and replay records buffered during 1–5
|
|
1783
|
+
*
|
|
1784
|
+
* Steps 1–4 are synchronous so that `logDir()` / `logFilePath()` are correct
|
|
1785
|
+
* the instant DSH starts. Step 5 is asynchronous (a socket bind resolves on the
|
|
1786
|
+
* event loop), so records emitted in the meantime are buffered — bounded — and
|
|
1787
|
+
* replayed after ownership is confirmed. If ownership cannot be established the
|
|
1788
|
+
* destination is marked unavailable and the buffer is dropped: there is
|
|
1789
|
+
* deliberately no fallback to a shared writable file.
|
|
1790
|
+
*
|
|
1791
|
+
* ## Why `globalThis`
|
|
1792
|
+
*
|
|
1793
|
+
* A plugin bundle may inline its own copy of this package, so a module-level
|
|
1794
|
+
* singleton would give each copy its own sink, rotation counter and buffer.
|
|
1795
|
+
* The state lives on `globalThis` under a `Symbol.for` key, which is a genuine
|
|
1796
|
+
* process-wide registry: every copy — bundled, external or duplicated —
|
|
1797
|
+
* cooperates on one destination.
|
|
1798
|
+
*/
|
|
1799
|
+
const STATE_KEY = Symbol.for("@huaqiu/dsh-plugin-log/runtime");
|
|
1800
|
+
const HOST_SINK_KEY = Symbol.for("@huaqiu/dsh-plugin-log/host-sink");
|
|
1801
|
+
const MAX_PENDING_RECORDS = 2e3;
|
|
1802
|
+
const MAX_PENDING_BYTES = 1048576;
|
|
1803
|
+
const DEFAULT_OWNERSHIP_TIMEOUT_MS = 5e3;
|
|
1804
|
+
const FLUSH_TIMEOUT_MS = 5e3;
|
|
1805
|
+
const MAINTENANCE_DELAY_MS = 1500;
|
|
1806
|
+
const MAINTENANCE_BUDGET_MS = 3e3;
|
|
1807
|
+
const RETENTION_DAYS = 30;
|
|
1808
|
+
function freshState() {
|
|
1809
|
+
return {
|
|
1810
|
+
schema: 2,
|
|
1811
|
+
config: null,
|
|
1812
|
+
context: null,
|
|
1813
|
+
identity: null,
|
|
1814
|
+
instanceDir: null,
|
|
1815
|
+
ownership: null,
|
|
1816
|
+
ownershipState: "pending",
|
|
1817
|
+
ownershipPromise: null,
|
|
1818
|
+
writer: null,
|
|
1819
|
+
ready: false,
|
|
1820
|
+
degradedReason: null,
|
|
1821
|
+
pending: [],
|
|
1822
|
+
pendingBytes: 0,
|
|
1823
|
+
droppedBeforeReady: 0,
|
|
1824
|
+
shutdown: false,
|
|
1825
|
+
shutdownPromise: null,
|
|
1826
|
+
maintenanceScheduled: false,
|
|
1827
|
+
generation: 0
|
|
1828
|
+
};
|
|
1829
|
+
}
|
|
1830
|
+
function state() {
|
|
1831
|
+
const registry = globalThis;
|
|
1832
|
+
const existing = registry[STATE_KEY];
|
|
1833
|
+
if (existing && existing.schema === 2) return existing;
|
|
1834
|
+
const created = freshState();
|
|
1835
|
+
registry[STATE_KEY] = created;
|
|
1836
|
+
return created;
|
|
1837
|
+
}
|
|
1838
|
+
function hostSink() {
|
|
1839
|
+
return globalThis[HOST_SINK_KEY] ?? null;
|
|
1840
|
+
}
|
|
1841
|
+
/**
|
|
1842
|
+
* Installs a DSH-host-provided sink. MUST be called before the first log
|
|
1843
|
+
* record: once the package has established its own destination (and taken the
|
|
1844
|
+
* ownership lock), silently switching transports would abandon a directory it
|
|
1845
|
+
* owns. A late call is ignored and diagnosed rather than throwing.
|
|
1846
|
+
*/
|
|
1847
|
+
function installHostLogSink(sink) {
|
|
1848
|
+
const registry = globalThis;
|
|
1849
|
+
if (sink === null) {
|
|
1850
|
+
delete registry[HOST_SINK_KEY];
|
|
1851
|
+
return;
|
|
1852
|
+
}
|
|
512
1853
|
const s = state();
|
|
513
|
-
if (s.
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
1854
|
+
if (s.identity !== null) {
|
|
1855
|
+
appendDiagnostic(join(s.instanceDir ?? ".", FATAL_LOG_FILENAME), {
|
|
1856
|
+
event: "host-sink-installed-too-late",
|
|
1857
|
+
detail: "installHostLogSink() must be called before the first log record"
|
|
1858
|
+
});
|
|
1859
|
+
return;
|
|
1860
|
+
}
|
|
1861
|
+
registry[HOST_SINK_KEY] = sink;
|
|
1862
|
+
}
|
|
1863
|
+
function degraded(reason, detail) {
|
|
1864
|
+
const s = state();
|
|
1865
|
+
s.degradedReason = reason;
|
|
1866
|
+
s.ownershipState = "unavailable";
|
|
1867
|
+
if (s.instanceDir && detail) appendDiagnostic(join(s.instanceDir, FATAL_LOG_FILENAME), {
|
|
1868
|
+
event: "logging-degraded",
|
|
1869
|
+
reason,
|
|
1870
|
+
detail,
|
|
1871
|
+
dshInstanceId: s.identity?.dshInstanceId ?? null,
|
|
1872
|
+
pid: process.pid
|
|
1873
|
+
});
|
|
1874
|
+
}
|
|
1875
|
+
/**
|
|
1876
|
+
* Creates the instance directory and metadata, then starts ownership
|
|
1877
|
+
* acquisition in the background. Idempotent: later calls return immediately.
|
|
1878
|
+
*/
|
|
1879
|
+
function initializeDshRuntime(config = {}) {
|
|
1880
|
+
const s = state();
|
|
1881
|
+
if (s.shutdown) return;
|
|
1882
|
+
if (s.identity !== null) return;
|
|
1883
|
+
s.config = config;
|
|
1884
|
+
s.generation += 1;
|
|
1885
|
+
const generation = s.generation;
|
|
1886
|
+
const context = readDshLogContext(process.env, {
|
|
1887
|
+
dshLogRoot: config.dshLogRoot,
|
|
1888
|
+
baseDir: config.baseDir
|
|
1889
|
+
});
|
|
1890
|
+
s.context = context;
|
|
1891
|
+
try {
|
|
1892
|
+
mkdirSync(context.dshLogRoot, { recursive: true });
|
|
1893
|
+
} catch (err) {
|
|
1894
|
+
degraded("dsh-log-root-unavailable", String(err));
|
|
1895
|
+
return;
|
|
1896
|
+
}
|
|
1897
|
+
let identity = null;
|
|
1898
|
+
let instanceDir = null;
|
|
1899
|
+
for (let attempt = 0; attempt < 3 && identity === null; attempt += 1) {
|
|
1900
|
+
const candidate = createDshIdentity(context, {
|
|
1901
|
+
dshInstanceId: config.dshInstanceId,
|
|
1902
|
+
now: config.now?.()
|
|
1903
|
+
});
|
|
1904
|
+
const candidateDir = instanceDirFor(candidate);
|
|
1905
|
+
let created = false;
|
|
1906
|
+
try {
|
|
1907
|
+
mkdirSync(candidateDir);
|
|
1908
|
+
created = true;
|
|
1909
|
+
} catch {
|
|
1910
|
+
created = false;
|
|
1911
|
+
}
|
|
1912
|
+
if (!created) {
|
|
1913
|
+
if (!existsSync(candidateDir)) {
|
|
1914
|
+
degraded("instance-directory-unavailable", candidateDir);
|
|
1915
|
+
return;
|
|
1916
|
+
}
|
|
1917
|
+
const existing = readDshInstanceMetadata(candidateDir);
|
|
1918
|
+
if (existing !== null && existing.dshInstanceId === candidate.dshInstanceId) {
|
|
1919
|
+
identity = candidate;
|
|
1920
|
+
instanceDir = candidateDir;
|
|
1921
|
+
break;
|
|
1922
|
+
}
|
|
1923
|
+
if (config.dshInstanceId !== void 0) {
|
|
1924
|
+
degraded("instance-directory-collision", candidateDir);
|
|
1925
|
+
return;
|
|
1926
|
+
}
|
|
1927
|
+
continue;
|
|
1928
|
+
}
|
|
1929
|
+
const metadataPath = join(candidateDir, INSTANCE_METADATA_FILENAME);
|
|
1930
|
+
const metadata = {
|
|
1931
|
+
...candidate,
|
|
1932
|
+
schemaVersion: 1
|
|
1933
|
+
};
|
|
1934
|
+
if (!atomicCreateNewFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`)) {
|
|
1935
|
+
degraded("instance-metadata-collision", metadataPath);
|
|
1936
|
+
return;
|
|
1937
|
+
}
|
|
1938
|
+
identity = candidate;
|
|
1939
|
+
instanceDir = candidateDir;
|
|
1940
|
+
}
|
|
1941
|
+
if (identity === null || instanceDir === null) {
|
|
1942
|
+
degraded("instance-identity-unavailable");
|
|
1943
|
+
return;
|
|
1944
|
+
}
|
|
1945
|
+
s.identity = identity;
|
|
1946
|
+
s.instanceDir = instanceDir;
|
|
1947
|
+
if (hostSink() !== null) {
|
|
1948
|
+
s.ready = true;
|
|
1949
|
+
s.ownershipState = "skipped";
|
|
1950
|
+
s.writer = null;
|
|
1951
|
+
flushPendingIntoHost();
|
|
1952
|
+
return;
|
|
1953
|
+
}
|
|
1954
|
+
const rotation = config.rotation ?? DSH_ROTATION;
|
|
1955
|
+
const skipOwnership = config.skipOwnership === true;
|
|
1956
|
+
s.ownershipPromise = (async () => {
|
|
1957
|
+
let handle = null;
|
|
1958
|
+
try {
|
|
1959
|
+
handle = await acquireDshOwnership(instanceDir, identity.dshInstanceId, { diagnostics: true });
|
|
1960
|
+
} catch {
|
|
1961
|
+
handle = null;
|
|
1962
|
+
}
|
|
1963
|
+
if (s.generation !== generation) {
|
|
1964
|
+
handle?.release();
|
|
1965
|
+
return;
|
|
1966
|
+
}
|
|
1967
|
+
if (!handle && !skipOwnership) {
|
|
1968
|
+
degraded("ownership-unavailable", instanceDir ?? void 0);
|
|
1969
|
+
dropPending();
|
|
1970
|
+
return;
|
|
1971
|
+
}
|
|
1972
|
+
s.ownership = handle;
|
|
1973
|
+
s.ownershipState = skipOwnership ? "skipped" : "held";
|
|
1974
|
+
const writer = new DshLogWriter({
|
|
1975
|
+
dir: instanceDir,
|
|
1976
|
+
baseName: "dsh",
|
|
1977
|
+
cfg: rotation,
|
|
1978
|
+
faults: config.faults,
|
|
1979
|
+
now: config.now,
|
|
1980
|
+
onDiagnostic: config.onDiagnostic
|
|
1981
|
+
});
|
|
1982
|
+
writer.open();
|
|
1983
|
+
if (s.shutdown) {
|
|
1984
|
+
await writer.close();
|
|
1985
|
+
handle?.release();
|
|
1986
|
+
return;
|
|
1987
|
+
}
|
|
1988
|
+
s.writer = writer;
|
|
1989
|
+
s.ready = true;
|
|
1990
|
+
flushPendingIntoWriter(writer);
|
|
1991
|
+
scheduleMaintenance();
|
|
1992
|
+
})();
|
|
1993
|
+
}
|
|
1994
|
+
function dropPending() {
|
|
1995
|
+
const s = state();
|
|
1996
|
+
s.droppedBeforeReady += s.pending.length;
|
|
1997
|
+
s.pending = [];
|
|
1998
|
+
s.pendingBytes = 0;
|
|
1999
|
+
}
|
|
2000
|
+
function flushPendingIntoWriter(writer) {
|
|
2001
|
+
const s = state();
|
|
2002
|
+
const pending = s.pending;
|
|
2003
|
+
s.pending = [];
|
|
2004
|
+
s.pendingBytes = 0;
|
|
2005
|
+
for (const line of pending) writer.write(line);
|
|
2006
|
+
}
|
|
2007
|
+
function flushPendingIntoHost() {
|
|
2008
|
+
const sink = hostSink();
|
|
2009
|
+
if (!sink) return;
|
|
2010
|
+
const s = state();
|
|
2011
|
+
const pending = s.pending;
|
|
2012
|
+
s.pending = [];
|
|
2013
|
+
s.pendingBytes = 0;
|
|
2014
|
+
for (const line of pending) try {
|
|
2015
|
+
sink.write(line);
|
|
2016
|
+
} catch {
|
|
2017
|
+
s.droppedBeforeReady += 1;
|
|
2018
|
+
}
|
|
2019
|
+
}
|
|
2020
|
+
/**
|
|
2021
|
+
* Accepts one already-serialized JSONL record. Never throws, never blocks.
|
|
2022
|
+
* Before the destination is ready the record is buffered (bounded); if the
|
|
2023
|
+
* destination is unavailable it is dropped — logging must never fail plugin
|
|
2024
|
+
* business logic.
|
|
2025
|
+
*/
|
|
2026
|
+
function enqueueRecord(line) {
|
|
2027
|
+
const s = state();
|
|
2028
|
+
if (s.shutdown) return;
|
|
2029
|
+
const sink = hostSink();
|
|
2030
|
+
if (sink !== null) {
|
|
2031
|
+
try {
|
|
2032
|
+
sink.write(line);
|
|
2033
|
+
} catch {
|
|
2034
|
+
s.droppedBeforeReady += 1;
|
|
2035
|
+
}
|
|
2036
|
+
return;
|
|
2037
|
+
}
|
|
2038
|
+
if (s.writer !== null && s.ready) {
|
|
2039
|
+
s.writer.write(line);
|
|
2040
|
+
return;
|
|
2041
|
+
}
|
|
2042
|
+
if (s.degradedReason !== null && s.ownershipState === "unavailable") {
|
|
2043
|
+
s.droppedBeforeReady += 1;
|
|
2044
|
+
return;
|
|
2045
|
+
}
|
|
2046
|
+
const bytes = Buffer.byteLength(line, "utf8");
|
|
2047
|
+
if (s.pending.length >= MAX_PENDING_RECORDS || s.pendingBytes + bytes > MAX_PENDING_BYTES) {
|
|
2048
|
+
s.droppedBeforeReady += 1;
|
|
2049
|
+
return;
|
|
2050
|
+
}
|
|
2051
|
+
s.pending.push(line);
|
|
2052
|
+
s.pendingBytes += bytes;
|
|
2053
|
+
}
|
|
2054
|
+
function withTimeout(promise, ms, fallback) {
|
|
2055
|
+
return Promise.race([promise, new Promise((resolve) => {
|
|
2056
|
+
setTimeout(() => resolve(fallback), ms).unref();
|
|
2057
|
+
})]);
|
|
2058
|
+
}
|
|
2059
|
+
/** Resolves when the destination is decided (held, skipped or unavailable). */
|
|
2060
|
+
async function awaitRuntimeReady(timeoutMs = DEFAULT_OWNERSHIP_TIMEOUT_MS) {
|
|
2061
|
+
const s = state();
|
|
2062
|
+
if (s.ready) return true;
|
|
2063
|
+
if (s.degradedReason !== null) return false;
|
|
2064
|
+
if (!s.ownershipPromise) return false;
|
|
2065
|
+
return await withTimeout(s.ownershipPromise.then(() => s.ready || s.degradedReason === null), timeoutMs, false) && (s.ready || s.ownershipState === "skipped");
|
|
2066
|
+
}
|
|
2067
|
+
function getRuntimeSnapshot() {
|
|
2068
|
+
const s = state();
|
|
2069
|
+
return {
|
|
2070
|
+
dshInstanceId: s.identity?.dshInstanceId ?? null,
|
|
2071
|
+
instanceDir: s.instanceDir,
|
|
2072
|
+
logFile: s.writer?.path ?? null,
|
|
2073
|
+
logRoot: s.context?.dshLogRoot ?? null,
|
|
2074
|
+
ready: s.ready,
|
|
2075
|
+
ownership: s.ownershipState,
|
|
2076
|
+
degradedReason: s.degradedReason,
|
|
2077
|
+
droppedBeforeReady: s.droppedBeforeReady,
|
|
2078
|
+
health: s.writer?.getHealth() ?? null
|
|
2079
|
+
};
|
|
2080
|
+
}
|
|
2081
|
+
/** Identity of this DSH process, or null before initialization. */
|
|
2082
|
+
function getDshIdentity() {
|
|
2083
|
+
return state().identity;
|
|
2084
|
+
}
|
|
2085
|
+
/**
|
|
2086
|
+
* Repairs and prunes HISTORICAL sibling directories. Runs on the serialized
|
|
2087
|
+
* writer chain's behalf but touches only directories whose ownership lock is
|
|
2088
|
+
* free — i.e. whose DSH process is gone.
|
|
2089
|
+
*/
|
|
2090
|
+
async function runRuntimeMaintenance(options = {}) {
|
|
2091
|
+
const s = state();
|
|
2092
|
+
if (!s.instanceDir || !s.context) return;
|
|
2093
|
+
if (s.shutdown) return;
|
|
2094
|
+
const ownInstanceDir = s.instanceDir;
|
|
2095
|
+
const instancesRoot = s.context.dshLogRoot;
|
|
2096
|
+
const report = (record) => {
|
|
2097
|
+
appendDiagnostic(join(ownInstanceDir, "maintenance.log"), record);
|
|
2098
|
+
};
|
|
2099
|
+
try {
|
|
2100
|
+
await recoverDshInstances({
|
|
2101
|
+
instancesRoot,
|
|
2102
|
+
ownInstanceDir,
|
|
2103
|
+
timeBudgetMs: options.timeBudgetMs ?? MAINTENANCE_BUDGET_MS,
|
|
2104
|
+
minAgeMs: options.minAgeMs,
|
|
2105
|
+
report
|
|
2106
|
+
});
|
|
2107
|
+
await cleanupExpiredDshInstances({
|
|
2108
|
+
instancesRoot,
|
|
2109
|
+
ownInstanceDir,
|
|
2110
|
+
retentionDays: options.retentionDays ?? RETENTION_DAYS,
|
|
2111
|
+
timeBudgetMs: options.timeBudgetMs ?? MAINTENANCE_BUDGET_MS,
|
|
2112
|
+
report
|
|
2113
|
+
});
|
|
2114
|
+
const legacy = await reportLegacyPluginLogs(getLogBaseDir(s.config?.baseDir));
|
|
2115
|
+
if (legacy.files.length > 0) report({
|
|
2116
|
+
event: "legacy-plugin-logs",
|
|
2117
|
+
...legacy
|
|
2118
|
+
});
|
|
2119
|
+
} catch {}
|
|
2120
|
+
}
|
|
2121
|
+
function scheduleMaintenance() {
|
|
2122
|
+
const s = state();
|
|
2123
|
+
if (s.maintenanceScheduled) return;
|
|
2124
|
+
s.maintenanceScheduled = true;
|
|
2125
|
+
setTimeout(() => {
|
|
2126
|
+
runRuntimeMaintenance();
|
|
2127
|
+
}, MAINTENANCE_DELAY_MS).unref();
|
|
2128
|
+
}
|
|
2129
|
+
/** Waits for everything enqueued so far, bounded. */
|
|
2130
|
+
async function flushRuntime() {
|
|
2131
|
+
const s = state();
|
|
2132
|
+
const sink = hostSink();
|
|
2133
|
+
if (sink !== null) {
|
|
2134
|
+
try {
|
|
2135
|
+
await sink.flush?.();
|
|
2136
|
+
} catch {}
|
|
2137
|
+
return;
|
|
2138
|
+
}
|
|
2139
|
+
if (s.ownershipPromise) await withTimeout(s.ownershipPromise, FLUSH_TIMEOUT_MS, void 0);
|
|
2140
|
+
if (s.writer) await withTimeout(s.writer.flush(), FLUSH_TIMEOUT_MS, void 0);
|
|
2141
|
+
}
|
|
2142
|
+
/**
|
|
2143
|
+
* Final flush + close + ownership release. Owned by the DSH host only: a
|
|
2144
|
+
* plugin unload must never call this, because it would close the destination
|
|
2145
|
+
* for every other plugin in the process.
|
|
2146
|
+
*/
|
|
2147
|
+
async function shutdownRuntime() {
|
|
2148
|
+
const s = state();
|
|
2149
|
+
if (s.shutdownPromise) return s.shutdownPromise;
|
|
2150
|
+
s.shutdown = true;
|
|
2151
|
+
s.shutdownPromise = (async () => {
|
|
2152
|
+
const sink = hostSink();
|
|
2153
|
+
if (sink !== null) {
|
|
2154
|
+
try {
|
|
2155
|
+
await sink.flush?.();
|
|
2156
|
+
sink.close?.();
|
|
2157
|
+
} catch {}
|
|
2158
|
+
return;
|
|
2159
|
+
}
|
|
2160
|
+
if (s.ownershipPromise) await withTimeout(s.ownershipPromise, FLUSH_TIMEOUT_MS, void 0);
|
|
2161
|
+
const writer = s.writer;
|
|
2162
|
+
s.writer = null;
|
|
2163
|
+
if (writer) {
|
|
2164
|
+
await withTimeout(writer.flush(), FLUSH_TIMEOUT_MS, void 0);
|
|
2165
|
+
await withTimeout(writer.close(), FLUSH_TIMEOUT_MS, void 0);
|
|
2166
|
+
}
|
|
2167
|
+
const ownership = s.ownership;
|
|
2168
|
+
s.ownership = null;
|
|
2169
|
+
ownership?.release();
|
|
2170
|
+
})();
|
|
2171
|
+
return s.shutdownPromise;
|
|
2172
|
+
}
|
|
2173
|
+
/**
|
|
2174
|
+
* Test/teardown helper: shuts the runtime down and forgets all state so a test
|
|
2175
|
+
* can re-initialize with different configuration. Never called in production.
|
|
2176
|
+
*/
|
|
2177
|
+
async function resetRuntime() {
|
|
2178
|
+
const s = state();
|
|
2179
|
+
await shutdownRuntime();
|
|
2180
|
+
const registry = globalThis;
|
|
2181
|
+
const fresh = freshState();
|
|
2182
|
+
fresh.generation = s.generation + 1;
|
|
2183
|
+
registry[STATE_KEY] = fresh;
|
|
2184
|
+
}
|
|
2185
|
+
//#endregion
|
|
2186
|
+
//#region src/index.ts
|
|
2187
|
+
/**
|
|
2188
|
+
* `@huaqiu/dsh-plugin-log` — one shared, per-DSH-process log for every Huaqiu
|
|
2189
|
+
* DSH plugin.
|
|
2190
|
+
*
|
|
2191
|
+
* ## Why this exists
|
|
2192
|
+
*
|
|
2193
|
+
* Plugin diagnostics used to live only in the browser console: each plugin's
|
|
2194
|
+
* browser half logged to `console.*`, and the node half — the half that
|
|
2195
|
+
* actually owns credentials, HTTP routes and agent tools — logged nothing at
|
|
2196
|
+
* all outside the DSH process's stdout, which HQ Edge only captures as an
|
|
2197
|
+
* opaque text blob.
|
|
2198
|
+
*
|
|
2199
|
+
* ## What changed (docs/tasks/dsh-plugin-log-isolation.md)
|
|
2200
|
+
*
|
|
2201
|
+
* The package is shared by every plugin, but the logging RESOURCE belongs to
|
|
2202
|
+
* the DSH process that loads them. So:
|
|
2203
|
+
*
|
|
2204
|
+
* - one DSH process = one log directory = one active file;
|
|
2205
|
+
* - the directory is `<dsh-root>/<dsh_instance_id>/`, where `dsh-root` is the
|
|
2206
|
+
* parent HQ Edge instance's `dsh/` directory;
|
|
2207
|
+
* - `dsh_instance_id` is generated per DSH LAUNCH — a restart produces a new
|
|
2208
|
+
* directory, a plugin reload does not;
|
|
2209
|
+
* - plugins never configure a destination or a rotation; they only name
|
|
2210
|
+
* themselves (`pluginId`) and get a namespaced logger;
|
|
2211
|
+
* - the DSH process owns rotation, compression, retention and shutdown.
|
|
2212
|
+
*
|
|
2213
|
+
* Layout:
|
|
2214
|
+
*
|
|
2215
|
+
* <HQ_EDGE_HOME>/logs/instances/<edge-instance-id>/dsh/
|
|
2216
|
+
* <dsh-instance-id>/
|
|
2217
|
+
* instance.json ← identity of this DSH process
|
|
2218
|
+
* owner.lock ← diagnostic only; existence ≠ ownership
|
|
2219
|
+
* dsh.2026-11-11.log ← active log (owned by this process)
|
|
2220
|
+
* dsh.2026-11-11.log.gz ← published archive
|
|
2221
|
+
*
|
|
2222
|
+
* ## Guarantees
|
|
2223
|
+
*
|
|
2224
|
+
* - `getLogger()` and every log call are synchronous, never throw, and never
|
|
2225
|
+
* fail plugin business logic because a destination failed;
|
|
2226
|
+
* - initialization is idempotent across duplicated package copies (the state
|
|
2227
|
+
* lives in a process-wide `globalThis` registry);
|
|
2228
|
+
* - a plugin's `fields` can never override identity or level fields;
|
|
2229
|
+
* - plugin unload/reload never creates a second transport and never closes
|
|
2230
|
+
* the shared one — only DSH shutdown flushes and closes.
|
|
2231
|
+
*/
|
|
2232
|
+
const DEFAULT_LEVEL = "info";
|
|
2233
|
+
const DEFAULT_CONSOLE_LEVEL = "warn";
|
|
2234
|
+
let override = null;
|
|
2235
|
+
let resolved = null;
|
|
2236
|
+
let bootstrapped = false;
|
|
2237
|
+
/**
|
|
2238
|
+
* Pending boot-banner emission. `flushLogs()` must await it: the banner is
|
|
2239
|
+
* written once the destination is decided, so without this barrier a flush
|
|
2240
|
+
* could return before the banner (and any rotation it triggers) had landed.
|
|
2241
|
+
*/
|
|
2242
|
+
let bootPromise = null;
|
|
2243
|
+
function env(name) {
|
|
2244
|
+
const value = process.env[name];
|
|
2245
|
+
if (value === void 0) return void 0;
|
|
2246
|
+
const trimmed = value.trim();
|
|
2247
|
+
return trimmed.length > 0 ? trimmed : void 0;
|
|
2248
|
+
}
|
|
2249
|
+
function readInt(value, fallback) {
|
|
2250
|
+
if (value === void 0) return fallback;
|
|
2251
|
+
const parsed = Number.parseInt(value, 10);
|
|
2252
|
+
return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
|
|
2253
|
+
}
|
|
2254
|
+
function readBool(value, fallback) {
|
|
2255
|
+
if (value === void 0) return fallback;
|
|
2256
|
+
const normalized = value.trim().toLowerCase();
|
|
2257
|
+
if ([
|
|
2258
|
+
"1",
|
|
2259
|
+
"true",
|
|
2260
|
+
"yes",
|
|
2261
|
+
"on"
|
|
2262
|
+
].includes(normalized)) return true;
|
|
2263
|
+
if ([
|
|
2264
|
+
"0",
|
|
2265
|
+
"false",
|
|
2266
|
+
"no",
|
|
2267
|
+
"off"
|
|
2268
|
+
].includes(normalized)) return false;
|
|
2269
|
+
return fallback;
|
|
2270
|
+
}
|
|
2271
|
+
function consoleLevelFrom(raw, explicit) {
|
|
2272
|
+
if (explicit === "off") return "off";
|
|
2273
|
+
if (explicit !== void 0) return explicit;
|
|
2274
|
+
if (raw === "off" || raw === "none" || raw === "0") return "off";
|
|
2275
|
+
if (raw === "all" || raw === "1" || raw === "true") return "debug";
|
|
2276
|
+
return parseLevel(raw, DEFAULT_CONSOLE_LEVEL);
|
|
2277
|
+
}
|
|
2278
|
+
function currentConfig() {
|
|
2279
|
+
if (resolved) return resolved;
|
|
2280
|
+
const o = override ?? {};
|
|
2281
|
+
const rootFromOption = o.dshLogRoot ?? o.dir;
|
|
2282
|
+
const rootFromEnv = env("DSH_LOG_ROOT") ?? env("DSH_PLUGIN_LOG_DIR");
|
|
2283
|
+
const maxSize = o.maxSize ?? (o.maxBytes !== void 0 ? `${Math.max(1, Math.floor(o.maxBytes / 1048576))}m` : void 0);
|
|
2284
|
+
resolved = {
|
|
2285
|
+
dshLogRoot: rootFromOption ?? rootFromEnv,
|
|
2286
|
+
dshInstanceId: o.dshInstanceId,
|
|
2287
|
+
level: o.level ?? parseLevel(env("DSH_PLUGIN_LOG_LEVEL"), DEFAULT_LEVEL),
|
|
2288
|
+
consoleLevel: consoleLevelFrom(env("DSH_PLUGIN_LOG_CONSOLE"), o.consoleLevel),
|
|
2289
|
+
maxSize: maxSize ?? env("DSH_PLUGIN_LOG_MAX_BYTES_SIZE") ?? "10m",
|
|
2290
|
+
retentionDays: o.retentionDays ?? readInt(env("DSH_PLUGIN_LOG_RETENTION_DAYS"), 14),
|
|
2291
|
+
maxStorageBytes: o.maxStorageBytes ?? readInt(env("DSH_PLUGIN_LOG_MAX_STORAGE_BYTES"), 268435456),
|
|
2292
|
+
compress: o.compress ?? readBool(env("DSH_PLUGIN_LOG_COMPRESS"), true),
|
|
2293
|
+
faults: o.faults,
|
|
2294
|
+
skipOwnership: o.skipOwnership === true,
|
|
2295
|
+
now: o.now,
|
|
2296
|
+
onDiagnostic: o.onDiagnostic
|
|
2297
|
+
};
|
|
2298
|
+
return resolved;
|
|
2299
|
+
}
|
|
2300
|
+
function runtimeConfig(cfg) {
|
|
2301
|
+
return {
|
|
2302
|
+
dshLogRoot: cfg.dshLogRoot,
|
|
2303
|
+
dshInstanceId: cfg.dshInstanceId,
|
|
2304
|
+
rotation: {
|
|
2305
|
+
frequency: "daily",
|
|
2306
|
+
maxSize: cfg.maxSize,
|
|
2307
|
+
retentionDays: cfg.retentionDays,
|
|
2308
|
+
maxStorageBytes: cfg.maxStorageBytes,
|
|
2309
|
+
compress: cfg.compress
|
|
2310
|
+
},
|
|
2311
|
+
faults: cfg.faults,
|
|
2312
|
+
skipOwnership: cfg.skipOwnership,
|
|
2313
|
+
now: cfg.now,
|
|
2314
|
+
onDiagnostic: cfg.onDiagnostic
|
|
2315
|
+
};
|
|
2316
|
+
}
|
|
2317
|
+
/**
|
|
2318
|
+
* Programmatically configure logging. Call before the first `getLogger()`;
|
|
2319
|
+
* once the destination is established a later call only takes effect after
|
|
2320
|
+
* {@link shutdownLogging} + {@link resetLogging} (tests, host re-init).
|
|
2321
|
+
*/
|
|
2322
|
+
function configureLogging(options) {
|
|
2323
|
+
override = {
|
|
2324
|
+
...override ?? {},
|
|
2325
|
+
...options
|
|
2326
|
+
};
|
|
2327
|
+
resolved = null;
|
|
2328
|
+
if (getDshIdentity() !== null) enqueueRecord(serialize({
|
|
2329
|
+
time: Date.now(),
|
|
2330
|
+
ts: (/* @__PURE__ */ new Date()).toISOString(),
|
|
2331
|
+
level: "warn",
|
|
2332
|
+
msg: "configureLogging called after logging started; restart required for it to take effect",
|
|
2333
|
+
pluginId: "dsh-plugin-log",
|
|
2334
|
+
component: "dsh-plugin-log",
|
|
2335
|
+
pid: process.pid
|
|
2336
|
+
}));
|
|
2337
|
+
}
|
|
2338
|
+
/** Forgets all configuration and cached state. Test/teardown helper. */
|
|
2339
|
+
async function resetLogging() {
|
|
2340
|
+
if (bootPromise) await bootPromise;
|
|
2341
|
+
await resetRuntime();
|
|
2342
|
+
override = null;
|
|
2343
|
+
resolved = null;
|
|
2344
|
+
bootstrapped = false;
|
|
2345
|
+
bootPromise = null;
|
|
2346
|
+
}
|
|
2347
|
+
/** Drops reserved keys so a plugin cannot spoof identity or level. */
|
|
2348
|
+
function sanitize(fields) {
|
|
2349
|
+
if (!fields) return {};
|
|
2350
|
+
const out = {};
|
|
2351
|
+
for (const [key, value] of Object.entries(fields)) {
|
|
2352
|
+
if (RESERVED_FIELDS.has(key)) continue;
|
|
2353
|
+
out[key] = value;
|
|
2354
|
+
}
|
|
2355
|
+
return out;
|
|
2356
|
+
}
|
|
2357
|
+
/** JSON.stringify that can never throw (BigInt, cycles in exotic values). */
|
|
2358
|
+
function serialize(record) {
|
|
2359
|
+
try {
|
|
2360
|
+
return JSON.stringify(record);
|
|
2361
|
+
} catch {
|
|
2362
|
+
try {
|
|
2363
|
+
return JSON.stringify({
|
|
2364
|
+
time: Date.now(),
|
|
2365
|
+
ts: (/* @__PURE__ */ new Date()).toISOString(),
|
|
2366
|
+
level: "error",
|
|
2367
|
+
msg: "[unserializable log record]",
|
|
2368
|
+
pluginId: typeof record.pluginId === "string" ? record.pluginId : "unknown",
|
|
2369
|
+
pid: process.pid
|
|
2370
|
+
});
|
|
2371
|
+
} catch {
|
|
2372
|
+
return "{\"level\":\"error\",\"msg\":\"[unserializable log record]\"}";
|
|
2373
|
+
}
|
|
2374
|
+
}
|
|
2375
|
+
}
|
|
2376
|
+
function consoleMethod(level) {
|
|
2377
|
+
if (level === "error") return "error";
|
|
2378
|
+
if (level === "warn") return "warn";
|
|
2379
|
+
if (level === "info") return "info";
|
|
2380
|
+
return "log";
|
|
2381
|
+
}
|
|
2382
|
+
function emit(pluginId, defaults, level, message, fields) {
|
|
2383
|
+
try {
|
|
2384
|
+
const cfg = currentConfig();
|
|
2385
|
+
const fileEnabled = isEnabled(level, cfg.level);
|
|
2386
|
+
const consoleEnabled = cfg.consoleLevel !== "off" && isEnabled(level, cfg.consoleLevel);
|
|
2387
|
+
if (!fileEnabled && !consoleEnabled) return;
|
|
2388
|
+
ensureInitialized();
|
|
2389
|
+
const identity = getDshIdentity();
|
|
2390
|
+
const record = {
|
|
2391
|
+
time: Date.now(),
|
|
2392
|
+
ts: (/* @__PURE__ */ new Date()).toISOString(),
|
|
2393
|
+
level,
|
|
2394
|
+
msg: message,
|
|
2395
|
+
pluginId,
|
|
2396
|
+
component: pluginId,
|
|
2397
|
+
installationId: identity?.installationId ?? null,
|
|
2398
|
+
hostType: identity?.hostType ?? null,
|
|
2399
|
+
hostInstanceId: identity?.hostInstanceId ?? null,
|
|
2400
|
+
edgeInstanceId: identity?.edgeInstanceId ?? null,
|
|
2401
|
+
dshInstanceId: identity?.dshInstanceId ?? null,
|
|
2402
|
+
pid: identity?.pid ?? process.pid
|
|
2403
|
+
};
|
|
2404
|
+
Object.assign(record, sanitize(defaults));
|
|
2405
|
+
Object.assign(record, sanitize(fields));
|
|
2406
|
+
const safe = redact(record);
|
|
2407
|
+
if (fileEnabled) enqueueRecord(`${serialize(safe)}\n`);
|
|
2408
|
+
if (consoleEnabled) {
|
|
2409
|
+
const { msg, ...rest } = safe;
|
|
2410
|
+
console[consoleMethod(level)](`[${pluginId}] ${String(msg)}`, rest);
|
|
2411
|
+
}
|
|
2412
|
+
} catch {}
|
|
2413
|
+
}
|
|
2414
|
+
function createLoggerFor(pluginId, defaults) {
|
|
2415
|
+
return {
|
|
2416
|
+
pluginId,
|
|
2417
|
+
component: pluginId,
|
|
2418
|
+
debug: (message, fields) => emit(pluginId, defaults, "debug", message, fields),
|
|
2419
|
+
info: (message, fields) => emit(pluginId, defaults, "info", message, fields),
|
|
2420
|
+
warn: (message, fields) => emit(pluginId, defaults, "warn", message, fields),
|
|
2421
|
+
error: (message, fields) => emit(pluginId, defaults, "error", message, fields),
|
|
2422
|
+
child: (fields) => createLoggerFor(pluginId, {
|
|
2423
|
+
...defaults,
|
|
2424
|
+
...fields
|
|
2425
|
+
})
|
|
2426
|
+
};
|
|
2427
|
+
}
|
|
2428
|
+
/**
|
|
2429
|
+
* Gets (or creates) the logger for `pluginId`.
|
|
2430
|
+
*
|
|
2431
|
+
* `pluginId` should be the value used everywhere else in that plugin's output —
|
|
2432
|
+
* `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen`, or the full package name
|
|
2433
|
+
* (`@huaqiu/dsh-plugin-eda`) when that is less ambiguous. It is attached to
|
|
2434
|
+
* every record, which is what makes per-plugin filtering possible without a
|
|
2435
|
+
* file per plugin.
|
|
2436
|
+
*/
|
|
2437
|
+
function getLogger(pluginId, defaults = {}) {
|
|
2438
|
+
ensureInitialized();
|
|
2439
|
+
bootstrap();
|
|
2440
|
+
return createLoggerFor(pluginId, defaults);
|
|
2441
|
+
}
|
|
2442
|
+
/** Spec-shaped factory: `createLogger({ pluginId })`. Equivalent to `getLogger`. */
|
|
2443
|
+
function createLogger(options) {
|
|
2444
|
+
return getLogger(options.pluginId);
|
|
2445
|
+
}
|
|
2446
|
+
function ensureInitialized() {
|
|
2447
|
+
if (getDshIdentity() !== null) return;
|
|
2448
|
+
initializeDshRuntime(runtimeConfig(currentConfig()));
|
|
2449
|
+
}
|
|
2450
|
+
/**
|
|
2451
|
+
* One record describing where this process logs and which identities it
|
|
2452
|
+
* carries. This is the line that makes the next "one editor logged, the other
|
|
2453
|
+
* did not" investigation cheap.
|
|
2454
|
+
*
|
|
2455
|
+
* Emitted AFTER the destination is decided, so `ownership` and `logFile` in the
|
|
2456
|
+
* banner describe reality instead of the transient "pending" state. Records
|
|
2457
|
+
* logged before then are buffered and appear before it in the file.
|
|
2458
|
+
*/
|
|
2459
|
+
function bootstrap() {
|
|
2460
|
+
if (bootstrapped) return;
|
|
2461
|
+
bootstrapped = true;
|
|
2462
|
+
bootPromise = awaitRuntimeReady().then(() => emitBootRecord());
|
|
2463
|
+
}
|
|
2464
|
+
function emitBootRecord() {
|
|
2465
|
+
const snapshot = getRuntimeSnapshot();
|
|
2466
|
+
const identity = getDshIdentity();
|
|
517
2467
|
let hqEdgeHome = null;
|
|
518
2468
|
try {
|
|
519
2469
|
hqEdgeHome = getHqEdgeHome();
|
|
520
2470
|
} catch {
|
|
521
2471
|
hqEdgeHome = null;
|
|
522
2472
|
}
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
2473
|
+
emit("dsh-plugin-log", {}, "info", "dsh plugin log ready", {
|
|
2474
|
+
logRoot: snapshot.logRoot,
|
|
2475
|
+
instanceDir: snapshot.instanceDir,
|
|
2476
|
+
logFile: snapshot.logFile,
|
|
2477
|
+
ownership: snapshot.ownership,
|
|
2478
|
+
degradedReason: snapshot.degradedReason,
|
|
2479
|
+
version: identity?.version ?? null,
|
|
2480
|
+
targetHost: identity?.targetHost ?? null,
|
|
2481
|
+
dshHome: identity?.dshHome ?? null,
|
|
526
2482
|
hqEdgeHome,
|
|
527
|
-
level:
|
|
528
|
-
consoleLevel:
|
|
529
|
-
pid: process.pid,
|
|
2483
|
+
level: currentConfig().level,
|
|
2484
|
+
consoleLevel: currentConfig().consoleLevel,
|
|
530
2485
|
node: process.version,
|
|
531
2486
|
platform: process.platform,
|
|
532
2487
|
arch: process.arch
|
|
533
2488
|
});
|
|
534
2489
|
}
|
|
2490
|
+
/** Absolute directory this DSH process exclusively owns, or null before init. */
|
|
2491
|
+
function logDir() {
|
|
2492
|
+
ensureInitialized();
|
|
2493
|
+
return getRuntimeSnapshot().instanceDir;
|
|
2494
|
+
}
|
|
2495
|
+
/** Absolute path of the active log file, or null before it is open. */
|
|
2496
|
+
function logFilePath() {
|
|
2497
|
+
return getRuntimeSnapshot().logFile;
|
|
2498
|
+
}
|
|
2499
|
+
/** Root that contains one directory per DSH instance. */
|
|
2500
|
+
function logRoot() {
|
|
2501
|
+
ensureInitialized();
|
|
2502
|
+
return getRuntimeSnapshot().logRoot;
|
|
2503
|
+
}
|
|
2504
|
+
/** Identity of this DSH process (null before initialization). */
|
|
2505
|
+
function dshInstanceInfo() {
|
|
2506
|
+
return getRuntimeSnapshot();
|
|
2507
|
+
}
|
|
2508
|
+
/** Destination health, for a diagnostics/health endpoint or a support bundle. */
|
|
2509
|
+
function getLoggingHealth() {
|
|
2510
|
+
const snapshot = getRuntimeSnapshot();
|
|
2511
|
+
const health = snapshot.health;
|
|
2512
|
+
return {
|
|
2513
|
+
state: health ? health.state : snapshot.degradedReason !== null ? "unavailable" : snapshot.ready ? "healthy" : "initializing",
|
|
2514
|
+
reason: health?.reason ?? snapshot.degradedReason ?? (snapshot.ready ? "destination open" : "not initialized"),
|
|
2515
|
+
droppedRecords: (health?.droppedRecords ?? 0) + snapshot.droppedBeforeReady,
|
|
2516
|
+
rotationCount: health?.rotationCount ?? 0,
|
|
2517
|
+
lastError: health?.lastError ?? null,
|
|
2518
|
+
instanceDir: snapshot.instanceDir,
|
|
2519
|
+
logFile: snapshot.logFile,
|
|
2520
|
+
ownership: snapshot.ownership,
|
|
2521
|
+
degradedReason: snapshot.degradedReason
|
|
2522
|
+
};
|
|
2523
|
+
}
|
|
2524
|
+
/** Waits until the destination is decided. For tests and startup diagnostics. */
|
|
2525
|
+
function ready() {
|
|
2526
|
+
ensureInitialized();
|
|
2527
|
+
return awaitRuntimeReady();
|
|
2528
|
+
}
|
|
2529
|
+
/** Waits for all pending records (and any rotation they triggered) to land. */
|
|
2530
|
+
async function flushLogs() {
|
|
2531
|
+
if (bootPromise) await bootPromise;
|
|
2532
|
+
await flushRuntime();
|
|
2533
|
+
}
|
|
2534
|
+
/**
|
|
2535
|
+
* Final flush + close + ownership release.
|
|
2536
|
+
*
|
|
2537
|
+
* Owned by the DSH host. A plugin must NEVER call this: it would close the
|
|
2538
|
+
* shared destination for every other plugin in the process.
|
|
2539
|
+
*/
|
|
2540
|
+
async function shutdownLogging() {
|
|
2541
|
+
if (bootPromise) await bootPromise;
|
|
2542
|
+
await shutdownRuntime();
|
|
2543
|
+
}
|
|
2544
|
+
/** Runs historical recovery/retention now (tests, or a DSH maintenance hook). */
|
|
2545
|
+
async function runMaintenance(options = {}) {
|
|
2546
|
+
ensureInitialized();
|
|
2547
|
+
await awaitRuntimeReady();
|
|
2548
|
+
await runRuntimeMaintenance(options);
|
|
2549
|
+
}
|
|
2550
|
+
/**
|
|
2551
|
+
* Creates the log root if it does not exist. Exposed for the DSH host's
|
|
2552
|
+
* startup path, which may want to validate the destination before plugins load.
|
|
2553
|
+
*/
|
|
2554
|
+
function ensureLogRoot() {
|
|
2555
|
+
const root = currentConfig().dshLogRoot ?? getDshLogRoot(getDshIdentity()?.edgeInstanceId ?? null);
|
|
2556
|
+
try {
|
|
2557
|
+
if (!existsSync(root)) mkdirSync(root, { recursive: true });
|
|
2558
|
+
} catch {}
|
|
2559
|
+
return root;
|
|
2560
|
+
}
|
|
535
2561
|
//#endregion
|
|
536
|
-
export { LOG_LEVELS, REDACTED, configureLogging, flushLogs, getLogger, levelRank, logDir, logFilePath, parseLevel, redact, resetLogging };
|
|
2562
|
+
export { DSH_ROTATION, INSTANCE_METADATA_FILENAME, LOG_LEVELS, OWNER_LOCK_FILENAME, 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 };
|