@huaqiu/dsh-plugin-log 0.6.23 → 0.6.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@huaqiu/dsh-plugin-log",
3
- "version": "0.6.23",
3
+ "version": "0.6.25",
4
4
  "type": "module",
5
5
  "main": "./lib/index.mjs",
6
6
  "types": "./lib/index.d.mts",
package/src/client.ts CHANGED
@@ -1,27 +1,33 @@
1
1
  /**
2
2
  * `@huaqiu/dsh-plugin-log/client` — browser half of the shared plugin log.
3
3
  *
4
- * The browser has no filesystem, so there is nothing to unify: this module
5
- * keeps the *same* `PluginLogger` surface as the node half (so a plugin can log
6
- * identically from either half) but writes to the console with a stable
7
- * `[component] message` prefix and a structured payload as the second
8
- * argument — which is what the existing client-side debugging already relies on.
4
+ * The browser has no filesystem and no DSH process identity, so there is no
5
+ * destination to isolate: this module keeps the *same* `PluginLogger` surface
6
+ * as the node half (so a plugin can log identically from either half) but
7
+ * writes to the console with a stable `[pluginId] message` prefix and a
8
+ * structured payload as the second argument — which is what the existing
9
+ * client-side debugging already relies on.
9
10
  *
10
11
  * It also keeps a small in-memory ring of the most recent records. That costs
11
12
  * nothing and gives a user something to copy out of the devtools console
12
13
  * (`dumpPluginLogs()`) when a file is not available.
13
14
  *
14
15
  * Redaction is shared with the node half, so a credential can never reach the
15
- * browser console through this logger either.
16
+ * browser console through this logger either. The reserved-field rule is shared
17
+ * too: a caller cannot rewrite `level`/`msg`/`pluginId` by passing them as
18
+ * context.
16
19
  */
17
20
 
18
21
  import { isEnabled, parseLevel, type LogLevel } from './levels.js'
19
22
  import { redact } from './redact.js'
23
+ import { RESERVED_FIELDS } from './fields.js'
20
24
 
21
25
  export type { LogLevel } from './levels.js'
22
26
  export type LogFields = Record<string, unknown>
23
27
 
24
28
  export interface PluginLogger {
29
+ readonly pluginId: string
30
+ /** @deprecated Legacy alias for `pluginId`. */
25
31
  readonly component: string
26
32
  debug(message: string, fields?: LogFields): void
27
33
  info(message: string, fields?: LogFields): void
@@ -48,18 +54,29 @@ function consoleMethod(level: LogLevel): 'log' | 'info' | 'warn' | 'error' {
48
54
  return 'log'
49
55
  }
50
56
 
51
- function createLogger(component: string, defaults: LogFields): PluginLogger {
57
+ function sanitize(fields: LogFields | undefined): LogFields {
58
+ if (!fields) return {}
59
+ const out: LogFields = {}
60
+ for (const [key, value] of Object.entries(fields)) {
61
+ if (RESERVED_FIELDS.has(key)) continue
62
+ out[key] = value
63
+ }
64
+ return out
65
+ }
66
+
67
+ function createLoggerFor(pluginId: string, defaults: LogFields): PluginLogger {
52
68
  const emit = (level: LogLevel, message: string, fields?: LogFields): void => {
53
69
  try {
54
70
  if (!isEnabled(level, currentLevel())) return
55
71
  const record: Record<string, unknown> = {
56
72
  ts: new Date().toISOString(),
57
73
  level,
58
- component,
74
+ pluginId,
75
+ component: pluginId,
59
76
  msg: message,
60
77
  }
61
- if (Object.keys(defaults).length > 0) Object.assign(record, defaults)
62
- if (fields && Object.keys(fields).length > 0) Object.assign(record, fields)
78
+ Object.assign(record, sanitize(defaults))
79
+ Object.assign(record, sanitize(fields))
63
80
 
64
81
  const safe = redact(record) as Record<string, unknown>
65
82
  ring.push(safe)
@@ -67,25 +84,31 @@ function createLogger(component: string, defaults: LogFields): PluginLogger {
67
84
 
68
85
  const { msg, ...rest } = safe
69
86
  // eslint-disable-next-line no-console
70
- console[consoleMethod(level)](`[${component}] ${String(msg)}`, rest)
87
+ console[consoleMethod(level)](`[${pluginId}] ${String(msg)}`, rest)
71
88
  } catch {
72
89
  /* logging must never throw */
73
90
  }
74
91
  }
75
92
 
76
93
  return {
77
- component,
94
+ pluginId,
95
+ component: pluginId,
78
96
  debug: (message, fields) => emit('debug', message, fields),
79
97
  info: (message, fields) => emit('info', message, fields),
80
98
  warn: (message, fields) => emit('warn', message, fields),
81
99
  error: (message, fields) => emit('error', message, fields),
82
- child: (fields) => createLogger(component, { ...defaults, ...fields }),
100
+ child: (fields) => createLoggerFor(pluginId, { ...defaults, ...fields }),
83
101
  }
84
102
  }
85
103
 
86
- /** Get (or create) the browser logger for `component`. */
87
- export function getLogger(component: string, defaults: LogFields = {}): PluginLogger {
88
- return createLogger(component, defaults)
104
+ /** Get (or create) the browser logger for `pluginId`. */
105
+ export function getLogger(pluginId: string, defaults: LogFields = {}): PluginLogger {
106
+ return createLoggerFor(pluginId, defaults)
107
+ }
108
+
109
+ /** Spec-shaped factory: `createLogger({ pluginId })`. */
110
+ export function createLogger(options: { pluginId: string }): PluginLogger {
111
+ return createLoggerFor(options.pluginId, {})
89
112
  }
90
113
 
91
114
  /** Snapshot of the in-memory ring — handy from the devtools console. */
package/src/fields.ts ADDED
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Record fields owned by `@huaqiu/dsh-plugin-log`.
3
+ *
4
+ * Kept in a leaf module with NO runtime imports so the browser half can share
5
+ * the exact same reserved-field rule without pulling `node:fs` / `node:os`
6
+ * into a browser bundle.
7
+ */
8
+
9
+ /**
10
+ * A plugin's `fields` object may not override any of these. Without the rule a
11
+ * plugin could rewrite its own `pluginId` (mis-attributing records to another
12
+ * plugin) or promote a `debug` line to `error` — and the log would stop being
13
+ * evidence.
14
+ */
15
+ export const RESERVED_FIELDS: ReadonlySet<string> = new Set([
16
+ 'time',
17
+ 'ts',
18
+ 'level',
19
+ 'msg',
20
+ 'pid',
21
+ 'schemaVersion',
22
+ 'installationId',
23
+ 'hostType',
24
+ 'hostInstanceId',
25
+ 'edgeInstanceId',
26
+ 'dshInstanceId',
27
+ 'pluginId',
28
+ // Legacy alias for `pluginId`; still reserved so one plugin cannot
29
+ // mis-attribute records to another.
30
+ 'component',
31
+ ])
@@ -0,0 +1,245 @@
1
+ /**
2
+ * Small, dependency-free filesystem primitives shared by identity, ownership,
3
+ * rotation and historical recovery.
4
+ *
5
+ * The DSH log tree is written by several DSH processes that may share one HQ
6
+ * Edge installation, so every mutation here follows the same rules as the HQ
7
+ * Edge logging subsystem (docs/tasks/dsh-plugin-log-isolation.md §5):
8
+ *
9
+ * - publication is ATOMIC and NEVER overwrites an existing destination;
10
+ * - temporary files are unique and live on the same filesystem as the
11
+ * destination, so a rename can never cross volumes;
12
+ * - Windows sharing violations get bounded, classified retries;
13
+ * - every helper is safe to call from an error path: it never throws past a
14
+ * guarded boundary and never buffers without a bound.
15
+ */
16
+ import {
17
+ closeSync,
18
+ existsSync,
19
+ fsyncSync,
20
+ linkSync,
21
+ mkdirSync,
22
+ openSync,
23
+ readFileSync,
24
+ renameSync,
25
+ statSync,
26
+ unlinkSync,
27
+ writeSync,
28
+ } from 'node:fs'
29
+ import { randomUUID } from 'node:crypto'
30
+ import { dirname, join } from 'node:path'
31
+
32
+ /** RFC 4122 / RFC 9562 UUID (versions 1–5) — used to validate identity values. */
33
+ export 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
34
+
35
+ export function isUuid(value: unknown): value is string {
36
+ return typeof value === 'string' && UUID_RE.test(value)
37
+ }
38
+
39
+ /** Filesystem errors that a Windows file lock / transient sharing violation can produce. */
40
+ const TRANSIENT_FS_CODES = new Set([
41
+ 'EPERM',
42
+ 'EBUSY',
43
+ 'EACCES',
44
+ 'EAGAIN',
45
+ 'UNKNOWN',
46
+ 'ESTALE',
47
+ 'ETIMEDOUT',
48
+ 'ELOCKED',
49
+ ])
50
+
51
+ /** Errors that must NOT be retried (permanent permission / invalid path / disk full). */
52
+ const PERMANENT_FS_CODES = new Set([
53
+ 'ENOENT',
54
+ 'ENOSPC',
55
+ 'EISDIR',
56
+ 'ENOTDIR',
57
+ 'EINVAL',
58
+ 'ENAMETOOLONG',
59
+ 'EROFS',
60
+ 'EMFILE',
61
+ 'ENFILE',
62
+ ])
63
+
64
+ export function isTransientFsError(err: unknown): boolean {
65
+ const code = (err as NodeJS.ErrnoException | undefined)?.code ?? ''
66
+ if (PERMANENT_FS_CODES.has(code)) return false
67
+ return TRANSIENT_FS_CODES.has(code)
68
+ }
69
+
70
+ export function errorCode(err: unknown): string {
71
+ return (err as NodeJS.ErrnoException | undefined)?.code ?? 'UNKNOWN'
72
+ }
73
+
74
+ export function errorMessage(err: unknown): string {
75
+ return err instanceof Error ? err.message : String(err)
76
+ }
77
+
78
+ /** Bounded async delay used by filesystem retry backoff. */
79
+ export function delay(ms: number): Promise<void> {
80
+ return new Promise((resolve) => setTimeout(resolve, ms))
81
+ }
82
+
83
+ export interface RetryOptions {
84
+ attempts?: number
85
+ baseDelayMs?: number
86
+ maxDelayMs?: number
87
+ totalTimeoutMs?: number
88
+ /** Defaults to {@link isTransientFsError}. */
89
+ isRetryable?: (err: unknown) => boolean
90
+ }
91
+
92
+ /**
93
+ * Runs `operation` with a bounded exponential backoff for transient Windows
94
+ * file-lock failures. Permanent failures are rethrown immediately. A total
95
+ * time budget keeps a rotation from stalling plugin shutdown indefinitely.
96
+ */
97
+ export async function withFsRetries<T>(
98
+ operation: () => T | Promise<T>,
99
+ options: RetryOptions = {},
100
+ ): Promise<T> {
101
+ const attempts = options.attempts ?? 5
102
+ const baseDelayMs = options.baseDelayMs ?? 25
103
+ const maxDelayMs = options.maxDelayMs ?? 400
104
+ const totalTimeoutMs = options.totalTimeoutMs ?? 5_000
105
+ const isRetryable = options.isRetryable ?? isTransientFsError
106
+ const deadline = Date.now() + totalTimeoutMs
107
+
108
+ let lastError: unknown
109
+ for (let attempt = 0; attempt < attempts; attempt += 1) {
110
+ try {
111
+ return await operation()
112
+ } catch (err) {
113
+ lastError = err
114
+ if (!isRetryable(err) || attempt === attempts - 1 || Date.now() >= deadline) throw err
115
+ const wait = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs, Math.max(0, deadline - Date.now()))
116
+ if (wait > 0) await delay(wait)
117
+ }
118
+ }
119
+ throw lastError
120
+ }
121
+
122
+ /**
123
+ * Publishes `src` as `dst` without ever overwriting an existing file.
124
+ *
125
+ * Hard-link creation is the primary mechanism: it is atomic on NTFS and POSIX
126
+ * and fails with EEXIST when the destination already exists. Where hard links
127
+ * are unavailable (some network/virtual filesystems), a guarded rename is used
128
+ * inside the caller's exclusively-owned directory.
129
+ *
130
+ * Returns true when this call created `dst`, false when `dst` already existed.
131
+ */
132
+ export function atomicPublish(src: string, dst: string): boolean {
133
+ if (existsSync(dst)) return false
134
+ try {
135
+ linkSync(src, dst)
136
+ try {
137
+ unlinkSync(src)
138
+ } catch {
139
+ // The hard link is published; leaving the source name is harmless and
140
+ // will be swept by maintenance. Never fail a successful publication.
141
+ }
142
+ return true
143
+ } catch (err) {
144
+ if (errorCode(err) === 'EEXIST') return false
145
+ if (!isLinkUnsupported(err)) throw err
146
+ if (existsSync(dst)) return false
147
+ renameSync(src, dst)
148
+ return true
149
+ }
150
+ }
151
+
152
+ function isLinkUnsupported(err: unknown): boolean {
153
+ const code = errorCode(err)
154
+ return code === 'EPERM' || code === 'EOPNOTSUPP' || code === 'ENOSYS' || code === 'EXDEV' || code === 'ENOTSUP'
155
+ }
156
+
157
+ /**
158
+ * Atomically writes `data` to `path` ONLY if that path does not exist, so a
159
+ * partially-written temp file can never be observed at the destination.
160
+ */
161
+ export function atomicCreateNewFile(path: string, data: string | Buffer, tmpPrefix = '.tmp-'): boolean {
162
+ mkdirSync(dirname(path), { recursive: true })
163
+ const tmp = join(dirname(path), `${tmpPrefix}${randomUUID()}`)
164
+ let fd: number | null = null
165
+ try {
166
+ fd = openSync(tmp, 'wx', 0o600)
167
+ const buf = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data
168
+ writeSync(fd, buf, 0, buf.length, 0)
169
+ fsyncSync(fd)
170
+ closeSync(fd)
171
+ fd = null
172
+ return atomicPublish(tmp, path)
173
+ } finally {
174
+ if (fd !== null) {
175
+ try {
176
+ closeSync(fd)
177
+ } catch {
178
+ /* ignore */
179
+ }
180
+ }
181
+ try {
182
+ if (existsSync(tmp)) unlinkSync(tmp)
183
+ } catch {
184
+ /* ignore */
185
+ }
186
+ }
187
+ }
188
+
189
+ /**
190
+ * Reads a JSON file. Returns `null` on any error (missing, unreadable, NUL
191
+ * corruption, invalid JSON). Callers MUST treat `null` as "preserve, never
192
+ * delete" — a corrupt `instance.json` is evidence, not garbage.
193
+ */
194
+ export function readJsonSafe<T>(path: string): T | null {
195
+ try {
196
+ const raw = readFileSync(path, 'utf-8')
197
+ if (raw.includes('\u0000')) return null
198
+ const value: unknown = JSON.parse(raw)
199
+ return value && typeof value === 'object' ? (value as T) : null
200
+ } catch {
201
+ return null
202
+ }
203
+ }
204
+
205
+ /** Best-effort synchronous append that can never throw. Used by error paths. */
206
+ export function appendDiagnostic(path: string, record: unknown): void {
207
+ try {
208
+ mkdirSync(dirname(path), { recursive: true })
209
+ const line =
210
+ typeof record === 'string'
211
+ ? record
212
+ : JSON.stringify({
213
+ time: new Date().toISOString(),
214
+ ...(record !== null && typeof record === 'object'
215
+ ? (record as Record<string, unknown>)
216
+ : { value: String(record) }),
217
+ })
218
+ const fd = openSync(path, 'a', 0o600)
219
+ try {
220
+ writeSync(fd, Buffer.from(`${line}\n`, 'utf-8'))
221
+ } finally {
222
+ closeSync(fd)
223
+ }
224
+ } catch {
225
+ // A diagnostic must never become the cause of a recursive failure.
226
+ }
227
+ }
228
+
229
+ /** Size of a file, or 0 when it cannot be stat'ed. */
230
+ export function sizeOrZero(path: string): number {
231
+ try {
232
+ return statSync(path).size
233
+ } catch {
234
+ return 0
235
+ }
236
+ }
237
+
238
+ /** True when a file exists and is a regular file. */
239
+ export function isFile(path: string): boolean {
240
+ try {
241
+ return statSync(path).isFile()
242
+ } catch {
243
+ return false
244
+ }
245
+ }
@@ -0,0 +1,263 @@
1
+ /**
2
+ * Identity for ONE DSH process, and the log root it is allowed to write into.
3
+ *
4
+ * This is the fourth level of the ownership hierarchy
5
+ * (docs/tasks/dsh-plugin-log-isolation.md §1):
6
+ *
7
+ * installation_id HQ Edge installation (installation lifetime)
8
+ * host_instance_id EDA Host (host process lifetime)
9
+ * edge_instance_id HQ Edge (Edge process lifetime)
10
+ * dsh_instance_id DSH runtime (DSH process lifetime) ← here
11
+ *
12
+ * Plugins have no process identity of their own. They are attributed to a DSH
13
+ * process through `plugin_id` (see `index.ts`), which is why nothing in this
14
+ * module knows about plugins.
15
+ *
16
+ * Rules encoded here:
17
+ * - `dsh_instance_id` is generated per DSH LAUNCH. A DSH restart produces a
18
+ * new id and therefore a new directory; a plugin reload does not.
19
+ * - HQ Edge passes the parent identities in the environment. It must never
20
+ * generate a `dsh_instance_id` itself and reuse it across restarts.
21
+ * - An absent or malformed parent identity is recorded as `null`, never
22
+ * fabricated: attributing logs to the wrong Edge process is worse than
23
+ * attributing them to none.
24
+ */
25
+ import { randomUUID } from 'node:crypto'
26
+ import { readFileSync } from 'node:fs'
27
+ import { basename, join } from 'node:path'
28
+ import { fileURLToPath } from 'node:url'
29
+
30
+ import { getDshLogRootFrom, getHqEdgeHomeFrom } from './paths.js'
31
+ import { isUuid, readJsonSafe } from './fs-utils.js'
32
+
33
+ /** Written once per DSH process, atomically, never overwritten. */
34
+ export const INSTANCE_METADATA_FILENAME = 'instance.json'
35
+ /** Diagnostic JSONL. Its EXISTENCE never implies ownership. */
36
+ export const OWNER_LOCK_FILENAME = 'owner.lock'
37
+ /** Appended by historical recovery in the recovering process's own directory. */
38
+ export const RECOVERY_LOG_FILENAME = 'recovery.log'
39
+ /** Written when the destination cannot be established at all. */
40
+ export const FATAL_LOG_FILENAME = 'fatal.log'
41
+
42
+ export const DSH_METADATA_SCHEMA_VERSION = 1
43
+
44
+ /**
45
+ * Record fields owned by this package. Re-exported from `fields.ts` (a leaf
46
+ * module) so the browser half can enforce the same rule without importing
47
+ * Node builtins.
48
+ */
49
+ export { RESERVED_FIELDS } from './fields.js'
50
+
51
+ export type DshLogRootSource = 'override' | 'env:DSH_LOG_ROOT' | 'edge-instance' | 'unscoped'
52
+
53
+ /** Everything the environment tells this DSH process about its place in the tree. */
54
+ export interface DshLogContext {
55
+ /** Directory that contains one subdirectory per DSH instance. */
56
+ readonly dshLogRoot: string
57
+ /** Why the root resolved to that path (surfaced in the boot record). */
58
+ readonly dshLogRootSource: DshLogRootSource
59
+ readonly installationId: string | null
60
+ readonly edgeInstanceId: string | null
61
+ readonly hostType: string | null
62
+ readonly hostInstanceId: string | null
63
+ readonly targetHost: string | null
64
+ readonly dshHome: string | null
65
+ readonly hqEdgeHome: string
66
+ /** Non-fatal problems found while reading the environment. */
67
+ readonly warnings: readonly string[]
68
+ }
69
+
70
+ export interface DshInstanceMetadata {
71
+ readonly schemaVersion: number
72
+ readonly dshInstanceId: string
73
+ readonly installationId: string | null
74
+ readonly edgeInstanceId: string | null
75
+ readonly hostType: string | null
76
+ readonly hostInstanceId: string | null
77
+ readonly targetHost: string | null
78
+ readonly pid: number
79
+ readonly startedAt: string
80
+ /** Version of `@huaqiu/dsh-plugin-log` that produced the directory. */
81
+ readonly version: string
82
+ readonly dshHome: string | null
83
+ readonly logRoot: string
84
+ }
85
+
86
+ export interface DshLogContextOverrides {
87
+ /** Explicit DSH log root (beats every environment variable). */
88
+ dshLogRoot?: string
89
+ /** Base log directory used when no explicit root/env root is given. */
90
+ baseDir?: string
91
+ }
92
+
93
+ export interface DshIdentityOptions {
94
+ /** Test/host injection. Production DSH generates its own id. */
95
+ dshInstanceId?: string
96
+ pid?: number
97
+ now?: Date
98
+ version?: string
99
+ }
100
+
101
+ function envValue(env: NodeJS.ProcessEnv, name: string): string | undefined {
102
+ const value = env[name]
103
+ if (value === undefined) return undefined
104
+ const trimmed = value.trim()
105
+ return trimmed.length > 0 ? trimmed : undefined
106
+ }
107
+
108
+ function uuidOrNull(
109
+ env: NodeJS.ProcessEnv,
110
+ name: string,
111
+ warnings: string[],
112
+ ): string | null {
113
+ const value = envValue(env, name)
114
+ if (value === undefined) return null
115
+ if (isUuid(value)) return value
116
+ warnings.push(`${name} is not a valid UUID and was ignored`)
117
+ return null
118
+ }
119
+
120
+ function hostTypeOrNull(env: NodeJS.ProcessEnv, warnings: string[]): string | null {
121
+ const value = envValue(env, 'HQ_HOST_TYPE')
122
+ if (value === undefined) return null
123
+ const normalized = value.toLowerCase()
124
+ if (!/^[a-z][a-z0-9_-]{0,31}$/.test(normalized)) {
125
+ warnings.push('HQ_HOST_TYPE has an unexpected shape and was ignored')
126
+ return null
127
+ }
128
+ return normalized
129
+ }
130
+
131
+ /**
132
+ * Resolves the DSH log root and the parent identities from the environment.
133
+ *
134
+ * Root precedence (§3 / §4):
135
+ * 1. explicit option (`configureLogging({ dir })`)
136
+ * 2. `$DSH_LOG_ROOT` (set by HQ Edge when it launches DSH)
137
+ * 3. `$HQ_EDGE_INSTANCE_ID` → `<logs>/instances/<edge>/dsh`
138
+ * 4. otherwise → `<logs>/dsh` (standalone DSH)
139
+ */
140
+ export function readDshLogContext(
141
+ env: NodeJS.ProcessEnv = process.env,
142
+ overrides: DshLogContextOverrides = {},
143
+ ): DshLogContext {
144
+ const warnings: string[] = []
145
+ const installationId = uuidOrNull(env, 'HQ_EDGE_INSTALLATION_ID', warnings)
146
+ const edgeInstanceId = uuidOrNull(env, 'HQ_EDGE_INSTANCE_ID', warnings)
147
+ const hostInstanceId = uuidOrNull(env, 'HQ_HOST_INSTANCE_ID', warnings)
148
+ const hostType = hostTypeOrNull(env, warnings)
149
+
150
+ let dshLogRoot: string
151
+ let dshLogRootSource: DshLogRootSource
152
+
153
+ if (overrides.dshLogRoot && overrides.dshLogRoot.length > 0) {
154
+ dshLogRoot = overrides.dshLogRoot
155
+ dshLogRootSource = 'override'
156
+ } else {
157
+ const fromEnv = envValue(env, 'DSH_LOG_ROOT')
158
+ if (fromEnv) {
159
+ dshLogRoot = fromEnv
160
+ dshLogRootSource = 'env:DSH_LOG_ROOT'
161
+ } else {
162
+ dshLogRoot = getDshLogRootFrom(env, edgeInstanceId, overrides.baseDir)
163
+ dshLogRootSource = edgeInstanceId ? 'edge-instance' : 'unscoped'
164
+ }
165
+ }
166
+
167
+ return {
168
+ dshLogRoot,
169
+ dshLogRootSource,
170
+ installationId,
171
+ edgeInstanceId,
172
+ hostType,
173
+ hostInstanceId,
174
+ targetHost: envValue(env, 'HQ_TARGET_HOST') ?? null,
175
+ dshHome: envValue(env, 'DSH_HOME') ?? null,
176
+ hqEdgeHome: getHqEdgeHomeFrom(env),
177
+ warnings,
178
+ }
179
+ }
180
+
181
+ let cachedVersion: string | null = null
182
+
183
+ /**
184
+ * Version of this package, used to attribute a log directory to the build that
185
+ * created it. Resolved lazily and cached: `import.meta.url` may point outside
186
+ * the package when a plugin bundle inlines this module, in which case the env
187
+ * override or `unknown` is used instead of failing.
188
+ */
189
+ export function pluginLogVersion(): string {
190
+ if (cachedVersion !== null) return cachedVersion
191
+ const fromEnv = process.env.DSH_PLUGIN_LOG_VERSION?.trim()
192
+ if (fromEnv) {
193
+ cachedVersion = fromEnv
194
+ return cachedVersion
195
+ }
196
+ try {
197
+ const here = fileURLToPath(new URL('.', import.meta.url))
198
+ const raw = readFileSync(join(here, '..', 'package.json'), 'utf-8')
199
+ const parsed = JSON.parse(raw) as { version?: unknown }
200
+ cachedVersion = typeof parsed.version === 'string' ? parsed.version : 'unknown'
201
+ } catch {
202
+ cachedVersion = 'unknown'
203
+ }
204
+ return cachedVersion
205
+ }
206
+
207
+ /**
208
+ * Creates the immutable identity of THIS DSH process.
209
+ *
210
+ * `dsh_instance_id` is taken from an explicit override (tests / host
211
+ * injection), else `$DSH_INSTANCE_ID`, else freshly generated. HQ Edge must
212
+ * not set either variable: a restart has to produce a new directory.
213
+ */
214
+ export function createDshIdentity(
215
+ context: DshLogContext,
216
+ options: DshIdentityOptions = {},
217
+ ): DshInstanceMetadata {
218
+ const injected = options.dshInstanceId ?? envValue(process.env, 'DSH_INSTANCE_ID')
219
+ const dshInstanceId = isUuid(injected) ? injected : randomUUID()
220
+ return {
221
+ schemaVersion: DSH_METADATA_SCHEMA_VERSION,
222
+ dshInstanceId,
223
+ installationId: context.installationId,
224
+ edgeInstanceId: context.edgeInstanceId,
225
+ hostType: context.hostType,
226
+ hostInstanceId: context.hostInstanceId,
227
+ targetHost: context.targetHost,
228
+ pid: options.pid ?? process.pid,
229
+ startedAt: (options.now ?? new Date()).toISOString(),
230
+ version: options.version ?? pluginLogVersion(),
231
+ dshHome: context.dshHome,
232
+ logRoot: context.dshLogRoot,
233
+ }
234
+ }
235
+
236
+ /** Absolute directory this DSH process exclusively owns. */
237
+ export function instanceDirFor(identity: DshInstanceMetadata): string {
238
+ return join(identity.logRoot, identity.dshInstanceId)
239
+ }
240
+
241
+ /** Reads and validates `instance.json` from an (historical) directory. */
242
+ export function readDshInstanceMetadata(dir: string): DshInstanceMetadata | null {
243
+ const value = readJsonSafe<Partial<DshInstanceMetadata>>(join(dir, INSTANCE_METADATA_FILENAME))
244
+ if (!value) return null
245
+ if (!isUuid(value.dshInstanceId)) return null
246
+ // The directory name is authoritative for which instance this is; a
247
+ // mismatched metadata file means the directory was tampered with or copied.
248
+ if (basename(dir).toLowerCase() !== value.dshInstanceId.toLowerCase()) return null
249
+ return {
250
+ schemaVersion: typeof value.schemaVersion === 'number' ? value.schemaVersion : 0,
251
+ dshInstanceId: value.dshInstanceId,
252
+ installationId: isUuid(value.installationId) ? value.installationId : null,
253
+ edgeInstanceId: isUuid(value.edgeInstanceId) ? value.edgeInstanceId : null,
254
+ hostType: typeof value.hostType === 'string' ? value.hostType : null,
255
+ hostInstanceId: isUuid(value.hostInstanceId) ? value.hostInstanceId : null,
256
+ targetHost: typeof value.targetHost === 'string' ? value.targetHost : null,
257
+ pid: typeof value.pid === 'number' ? value.pid : 0,
258
+ startedAt: typeof value.startedAt === 'string' ? value.startedAt : '',
259
+ version: typeof value.version === 'string' ? value.version : 'unknown',
260
+ dshHome: typeof value.dshHome === 'string' ? value.dshHome : null,
261
+ logRoot: typeof value.logRoot === 'string' ? value.logRoot : dir,
262
+ }
263
+ }