@huaqiu/dsh-plugin-log 0.6.23 → 0.6.25
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +118 -0
- package/lib/client.d.ts +9 -3
- package/lib/client.js +73 -17
- package/lib/index.d.mts +303 -19
- package/lib/index.mjs +2376 -350
- package/package.json +1 -1
- package/src/client.ts +39 -16
- package/src/fields.ts +31 -0
- package/src/fs-utils.ts +245 -0
- package/src/identity.ts +263 -0
- package/src/index.ts +408 -314
- package/src/ownership.ts +268 -0
- package/src/paths.ts +88 -41
- package/src/recovery.ts +433 -0
- package/src/redact.ts +9 -0
- package/src/rotation.ts +724 -0
- package/src/runtime.ts +633 -0
package/package.json
CHANGED
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
|
|
5
|
-
* keeps the *same* `PluginLogger` surface
|
|
6
|
-
*
|
|
7
|
-
* `[
|
|
8
|
-
* argument — which is what the existing
|
|
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
|
|
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
|
-
|
|
74
|
+
pluginId,
|
|
75
|
+
component: pluginId,
|
|
59
76
|
msg: message,
|
|
60
77
|
}
|
|
61
|
-
|
|
62
|
-
|
|
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)](`[${
|
|
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
|
-
|
|
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) =>
|
|
100
|
+
child: (fields) => createLoggerFor(pluginId, { ...defaults, ...fields }),
|
|
83
101
|
}
|
|
84
102
|
}
|
|
85
103
|
|
|
86
|
-
/** Get (or create) the browser logger for `
|
|
87
|
-
export function getLogger(
|
|
88
|
-
return
|
|
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
|
+
])
|
package/src/fs-utils.ts
ADDED
|
@@ -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
|
+
}
|
package/src/identity.ts
ADDED
|
@@ -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
|
+
}
|