@mostra/runtime 0.0.0-placeholder → 0.1.0
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/LICENSE +202 -0
- package/README.md +38 -1
- package/dist/bin.d.ts +1 -0
- package/dist/bin.js +236 -0
- package/dist/bin.js.map +1 -0
- package/dist/builder/child/main.d.ts +1 -0
- package/dist/builder/child/main.js +1408 -0
- package/dist/builder/child/main.js.map +1 -0
- package/dist/child-xrHmytks.js +49 -0
- package/dist/child-xrHmytks.js.map +1 -0
- package/dist/deps/child/install.d.ts +1 -0
- package/dist/deps/child/install.js +33 -0
- package/dist/deps/child/install.js.map +1 -0
- package/dist/index.d.ts +221 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/instance-D7_UVdoN.js +15752 -0
- package/dist/instance-D7_UVdoN.js.map +1 -0
- package/dist/types-NjNy7gXX.js +57 -0
- package/dist/types-NjNy7gXX.js.map +1 -0
- package/package.json +87 -4
- package/src/actions/index.ts +622 -0
- package/src/addressing/index.ts +281 -0
- package/src/bin.ts +240 -0
- package/src/builder/child/dev.ts +383 -0
- package/src/builder/child/fields.ts +363 -0
- package/src/builder/child/main.ts +47 -0
- package/src/builder/child/plugins.ts +195 -0
- package/src/builder/child/scan.ts +459 -0
- package/src/builder/child/spa.ts +348 -0
- package/src/builder/coverage.ts +72 -0
- package/src/builder/index.ts +406 -0
- package/src/builder/types.ts +180 -0
- package/src/deps/child/install.ts +30 -0
- package/src/deps/index.ts +918 -0
- package/src/deps/installer.ts +321 -0
- package/src/deps/lock.ts +82 -0
- package/src/deps/scan.ts +266 -0
- package/src/deps/specifier.ts +64 -0
- package/src/deps/warm.ts +57 -0
- package/src/dev/index.ts +518 -0
- package/src/faults.ts +65 -0
- package/src/gate.ts +55 -0
- package/src/gateway/actions.ts +268 -0
- package/src/gateway/browser.ts +650 -0
- package/src/gateway/capabilities.ts +739 -0
- package/src/gateway/controls.ts +91 -0
- package/src/gateway/dev.ts +119 -0
- package/src/gateway/http.ts +229 -0
- package/src/gateway/index.ts +1209 -0
- package/src/gateway/integrity.ts +117 -0
- package/src/gateway/listener.ts +217 -0
- package/src/gateway/routes.ts +197 -0
- package/src/gateway/serve.ts +138 -0
- package/src/gc/index.ts +451 -0
- package/src/home/acquire.ts +276 -0
- package/src/home/index.ts +16 -0
- package/src/home/paths.ts +192 -0
- package/src/home/platform.ts +34 -0
- package/src/home/record.ts +76 -0
- package/src/home/settings.ts +113 -0
- package/src/index.ts +30 -0
- package/src/instance/index.ts +942 -0
- package/src/interaction/ephemeral.ts +300 -0
- package/src/interaction/events.ts +355 -0
- package/src/interaction/fields.ts +392 -0
- package/src/interaction/index.ts +1009 -0
- package/src/interaction/outbox.ts +493 -0
- package/src/interaction/policy.ts +26 -0
- package/src/interaction/results.ts +341 -0
- package/src/interaction/runs.ts +313 -0
- package/src/interaction/signals.ts +120 -0
- package/src/interaction/submissions.ts +585 -0
- package/src/interaction/subscriptions.ts +258 -0
- package/src/interaction/viewers.ts +173 -0
- package/src/interaction/wait.ts +201 -0
- package/src/ledger/index.ts +442 -0
- package/src/ledger/migrations.ts +583 -0
- package/src/ledger/requests.ts +105 -0
- package/src/ledger/types.ts +28 -0
- package/src/live/index.ts +573 -0
- package/src/log.ts +316 -0
- package/src/processes/child.ts +67 -0
- package/src/processes/environment.ts +64 -0
- package/src/processes/identity.ts +191 -0
- package/src/processes/index.ts +19 -0
- package/src/processes/manager.ts +543 -0
- package/src/protocol-server/client.ts +94 -0
- package/src/protocol-server/index.ts +91 -0
- package/src/protocol-server/server.ts +509 -0
- package/src/protocol-server/streams.ts +81 -0
- package/src/publish/checks.ts +92 -0
- package/src/publish/digest.ts +87 -0
- package/src/publish/index.ts +23 -0
- package/src/publish/manifest.ts +409 -0
- package/src/publish/methods.ts +96 -0
- package/src/publish/publisher.ts +913 -0
- package/src/publish/source.ts +272 -0
- package/src/publish/tar.ts +110 -0
- package/src/registry/index.ts +481 -0
- package/src/registry/store.ts +136 -0
- package/src/secrets/index.ts +223 -0
- package/src/service/idle.ts +64 -0
- package/src/service/index.ts +3 -0
- package/src/service/unit.ts +250 -0
- package/src/verify/fields.ts +125 -0
- package/src/verify/index.ts +913 -0
- package/src/verify/regression.ts +157 -0
- package/src/verify/runner.ts +230 -0
- package/src/verify/sandbox.ts +407 -0
- package/src/verify/typecheck.ts +371 -0
- package/src/workers/index.ts +17 -0
- package/src/workers/launcher.ts +260 -0
- package/src/workers/pool.ts +708 -0
package/src/log.ts
ADDED
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The supervisor's log: JSON lines in `<home>/logs/supervisor.log`, rotated by size (DATA_MODEL
|
|
3
|
+
* §1). Every module receives a {@link Log} and writes structured events; nothing here formats
|
|
4
|
+
* for people. Every string written passes through the instance's {@link Redactor}, so secrets and
|
|
5
|
+
* capability tokens never reach the file or its mirror (STANDARDS security).
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
|
|
9
|
+
import { join } from "node:path";
|
|
10
|
+
import { fromBase64, toBase64 } from "@mostra/protocol";
|
|
11
|
+
|
|
12
|
+
/** Structured fields of one log event. Values must be JSON-serializable. */
|
|
13
|
+
export type LogFields = Readonly<Record<string, unknown>>;
|
|
14
|
+
|
|
15
|
+
/** Where modules write what happened. */
|
|
16
|
+
export interface Log {
|
|
17
|
+
info(event: string, fields?: LogFields): void;
|
|
18
|
+
warn(event: string, fields?: LogFields): void;
|
|
19
|
+
error(event: string, fields?: LogFields): void;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** A log that drops everything, for code paths that run before a home exists. */
|
|
23
|
+
export const silentLog: Log = { info() {}, warn() {}, error() {} };
|
|
24
|
+
|
|
25
|
+
/** What replaces a redacted value. */
|
|
26
|
+
export const REDACTED = "[redacted]";
|
|
27
|
+
|
|
28
|
+
/** Query and fragment parameters that carry capability material in Mostra URLs. */
|
|
29
|
+
const CAPABILITY_PARAMS = /([?#&](?:t|token|ticket|capability)=)[^&#\s"']+/gi;
|
|
30
|
+
|
|
31
|
+
/** Environment variable names whose values are treated as secrets. */
|
|
32
|
+
const SECRET_NAME =
|
|
33
|
+
/TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE|CREDENTIAL|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY|AUTH/i;
|
|
34
|
+
|
|
35
|
+
/** The shortest value worth redacting; shorter ones would mangle ordinary text. */
|
|
36
|
+
const MIN_SECRET_LENGTH = 8;
|
|
37
|
+
|
|
38
|
+
/** The shortest named secret redacted (`mostra secret set`). */
|
|
39
|
+
const MIN_NAMED_SECRET_LENGTH = 4;
|
|
40
|
+
|
|
41
|
+
/** The shortest line of a multi-line secret that is protected on its own. */
|
|
42
|
+
const MIN_SECRET_LINE_LENGTH = 8;
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Removes secrets and capability material from text before it is logged or reported: values the
|
|
46
|
+
* instance registered (secrets it hands to children, token secrets) and the token parameters of
|
|
47
|
+
* capability URLs.
|
|
48
|
+
*/
|
|
49
|
+
export class Redactor {
|
|
50
|
+
readonly #values = new Set<string>();
|
|
51
|
+
|
|
52
|
+
/** Registers a value that must never appear in logs or reports. Short values are ignored. */
|
|
53
|
+
protect(value: string): void {
|
|
54
|
+
if (value.length >= MIN_SECRET_LENGTH) this.#values.add(value);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Registers a named secret's value (D44): one a person set on purpose, so it is protected from
|
|
59
|
+
* 4 characters on; a shorter one would match ordinary text everywhere.
|
|
60
|
+
*/
|
|
61
|
+
protectSecret(value: string): void {
|
|
62
|
+
if (value.length < MIN_NAMED_SECRET_LENGTH) return;
|
|
63
|
+
this.#values.add(value);
|
|
64
|
+
// As it appears inside JSON text (an event payload, a log line), escapes and all.
|
|
65
|
+
const escaped = JSON.stringify(value).slice(1, -1);
|
|
66
|
+
if (escaped !== value) this.#values.add(escaped);
|
|
67
|
+
// A multi-line secret (a PEM key, a service account's JSON) also reaches output a line at a
|
|
68
|
+
// time: a child's output is split into lines before it is kept, and `util.inspect` splits
|
|
69
|
+
// long strings (Opus review 8). Each line long enough to be specific is protected too.
|
|
70
|
+
if (/[\r\n]/.test(value)) {
|
|
71
|
+
for (const line of value.split(/\r?\n|\r/)) {
|
|
72
|
+
const trimmed = line.trim();
|
|
73
|
+
if (trimmed.length >= MIN_SECRET_LINE_LENGTH) this.#values.add(trimmed);
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** The UTF-8 bytes of every protected value, for redacting binary output. */
|
|
79
|
+
protectedBytes(): Uint8Array[] {
|
|
80
|
+
const encoder = new TextEncoder();
|
|
81
|
+
return [...this.#values].map((value) => encoder.encode(value));
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Registers the values of variables whose names look like secrets (`*_TOKEN`, `*_SECRET` …). */
|
|
85
|
+
protectEnvironment(env: Environment): void {
|
|
86
|
+
for (const [name, value] of Object.entries(env)) {
|
|
87
|
+
if (value !== undefined && SECRET_NAME.test(name)) this.protect(value);
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** Returns `text` with every registered value and capability parameter replaced. */
|
|
92
|
+
redact(text: string): string {
|
|
93
|
+
let result = text.replace(CAPABILITY_PARAMS, `$1${REDACTED}`);
|
|
94
|
+
// Longest first, so a secret that contains another is replaced whole.
|
|
95
|
+
for (const value of [...this.#values].sort((a, b) => b.length - a.length)) {
|
|
96
|
+
if (result.includes(value)) result = result.split(value).join(REDACTED);
|
|
97
|
+
}
|
|
98
|
+
return result;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Options for {@link openFileLog}. */
|
|
103
|
+
export interface FileLogOptions {
|
|
104
|
+
/** The directory (`<home>/logs`), created with mode 0700. */
|
|
105
|
+
readonly dir: string;
|
|
106
|
+
/** Rotate when the file reaches this size. Default 10 MiB. */
|
|
107
|
+
readonly maxBytes?: number;
|
|
108
|
+
/** How many rotated files to keep (`supervisor.log.1` …). Default 3. */
|
|
109
|
+
readonly keep?: number;
|
|
110
|
+
/** Also mirrors warnings and errors here, such as stderr. */
|
|
111
|
+
readonly mirror?: (line: string) => void;
|
|
112
|
+
/** Applied to every string field. Default: a redactor for capability parameters only. */
|
|
113
|
+
readonly redactor?: Redactor;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Opens the supervisor's file log. Writes are synchronous appends, so the last lines before a
|
|
118
|
+
* crash are on disk. A write that fails (the home was removed) is dropped; the log never throws.
|
|
119
|
+
*/
|
|
120
|
+
export function openFileLog(options: FileLogOptions): Log {
|
|
121
|
+
const maxBytes = options.maxBytes ?? 10 * 1024 * 1024;
|
|
122
|
+
const keep = options.keep ?? 3;
|
|
123
|
+
const redactor = options.redactor ?? new Redactor();
|
|
124
|
+
const replacer = (_key: string, value: unknown): unknown => {
|
|
125
|
+
if (value instanceof Error) {
|
|
126
|
+
return {
|
|
127
|
+
name: value.name,
|
|
128
|
+
message: redactor.redact(value.message),
|
|
129
|
+
stack: value.stack && redactor.redact(value.stack),
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
return typeof value === "string" ? redactor.redact(value) : value;
|
|
133
|
+
};
|
|
134
|
+
const file = join(options.dir, "supervisor.log");
|
|
135
|
+
let size = 0;
|
|
136
|
+
try {
|
|
137
|
+
mkdirSync(options.dir, { recursive: true, mode: 0o700 });
|
|
138
|
+
size = statSync(file).size;
|
|
139
|
+
} catch {
|
|
140
|
+
size = 0;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
const rotate = (): void => {
|
|
144
|
+
for (let index = keep - 1; index >= 1; index--) {
|
|
145
|
+
try {
|
|
146
|
+
renameSync(`${file}.${index}`, `${file}.${index + 1}`);
|
|
147
|
+
} catch {
|
|
148
|
+
// The older file doesn't exist yet.
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
try {
|
|
152
|
+
renameSync(file, `${file}.1`);
|
|
153
|
+
} catch {
|
|
154
|
+
// Nothing to rotate.
|
|
155
|
+
}
|
|
156
|
+
size = 0;
|
|
157
|
+
};
|
|
158
|
+
|
|
159
|
+
const write = (level: "info" | "warn" | "error", event: string, fields?: LogFields): void => {
|
|
160
|
+
const line = `${JSON.stringify({ at: new Date().toISOString(), level, pid: process.pid, event, ...fields }, replacer)}\n`;
|
|
161
|
+
const bytes = Buffer.byteLength(line);
|
|
162
|
+
try {
|
|
163
|
+
if (size + bytes > maxBytes) rotate();
|
|
164
|
+
appendFileSync(file, line, { mode: 0o600 });
|
|
165
|
+
size += bytes;
|
|
166
|
+
} catch {
|
|
167
|
+
// The log must never take the supervisor down.
|
|
168
|
+
}
|
|
169
|
+
if (level !== "info") options.mirror?.(line);
|
|
170
|
+
};
|
|
171
|
+
|
|
172
|
+
return {
|
|
173
|
+
info: (event, fields) => write("info", event, fields),
|
|
174
|
+
warn: (event, fields) => write("warn", event, fields),
|
|
175
|
+
error: (event, fields) => write("error", event, fields),
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** Environment variables, as `process.env` holds them. */
|
|
180
|
+
export type Environment = Readonly<Record<string, string | undefined>>;
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* `value` with every string in it, keys too, passed through `redactor`: what server code hands to
|
|
184
|
+
* Mostra (results, state, live values) never carries a secret Mostra knows (D44, AC-06).
|
|
185
|
+
*/
|
|
186
|
+
export function redactValue<T>(value: T, redactor: { redact(text: string): string }): T {
|
|
187
|
+
const walk = (item: unknown): unknown => {
|
|
188
|
+
if (typeof item === "string") return redactor.redact(item);
|
|
189
|
+
if (Array.isArray(item)) return item.map(walk);
|
|
190
|
+
if (item !== null && typeof item === "object") {
|
|
191
|
+
return Object.fromEntries(
|
|
192
|
+
Object.entries(item).map(([key, entry]) => [redactor.redact(key), walk(entry)]),
|
|
193
|
+
);
|
|
194
|
+
}
|
|
195
|
+
return item;
|
|
196
|
+
};
|
|
197
|
+
return walk(value) as T;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** Overwrites, in place, every occurrence of each needle in `bytes` with `*`; true if any. */
|
|
201
|
+
function maskBytes(bytes: Uint8Array, needles: readonly Uint8Array[]): boolean {
|
|
202
|
+
let masked = false;
|
|
203
|
+
for (const needle of needles) {
|
|
204
|
+
if (needle.length === 0 || needle.length > bytes.length) continue;
|
|
205
|
+
const first = needle[0] as number;
|
|
206
|
+
for (let at = bytes.indexOf(first); at !== -1 && at <= bytes.length - needle.length; ) {
|
|
207
|
+
let match = true;
|
|
208
|
+
for (let k = 1; k < needle.length; k++) {
|
|
209
|
+
if (bytes[at + k] !== needle[k]) {
|
|
210
|
+
match = false;
|
|
211
|
+
break;
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
if (match) {
|
|
215
|
+
bytes.fill(0x2a, at, at + needle.length);
|
|
216
|
+
masked = true;
|
|
217
|
+
at = bytes.indexOf(first, at + needle.length);
|
|
218
|
+
} else at = bytes.indexOf(first, at + 1);
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
return masked;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* Redacts one batch of the server-function serializer's frames (INTERFACES §2.4) as values, not as
|
|
226
|
+
* text (Opus review 7): a string keeps its `$` escape, so a secret starting with `$` stays a
|
|
227
|
+
* string; a registered symbol's name is redacted; the bytes of an `ArrayBuffer`, a typed array or
|
|
228
|
+
* a file are searched for each protected value's UTF-8 bytes, which are overwritten with `*` in
|
|
229
|
+
* place, so every typed array keeps its length. Frames this function doesn't recognize are
|
|
230
|
+
* redacted as text.
|
|
231
|
+
*/
|
|
232
|
+
export function redactFrames<T>(
|
|
233
|
+
batch: T,
|
|
234
|
+
redactor: { redact(text: string): string; protectedBytes?(): Uint8Array[] },
|
|
235
|
+
): T {
|
|
236
|
+
if (!Array.isArray(batch)) return redactValue(batch, redactor);
|
|
237
|
+
// Which chunks hold bytes: the references to them are in this batch (the writer puts a value's
|
|
238
|
+
// chunks in the batch that refers to them).
|
|
239
|
+
const kinds = new Map<number, "A" | "T" | "B">();
|
|
240
|
+
const scan = (item: unknown): void => {
|
|
241
|
+
if (typeof item === "string") {
|
|
242
|
+
const match = /^\$([ATB])([0-9]+)$/.exec(item);
|
|
243
|
+
if (match) kinds.set(Number(match[2]), match[1] as "A" | "T" | "B");
|
|
244
|
+
} else if (Array.isArray(item)) item.forEach(scan);
|
|
245
|
+
else if (item !== null && typeof item === "object") Object.values(item).forEach(scan);
|
|
246
|
+
};
|
|
247
|
+
scan(batch);
|
|
248
|
+
const needles = redactor.protectedBytes?.() ?? [];
|
|
249
|
+
const maskBase64 = (text: unknown): unknown => {
|
|
250
|
+
if (typeof text !== "string" || needles.length === 0) return text;
|
|
251
|
+
let bytes: Uint8Array;
|
|
252
|
+
try {
|
|
253
|
+
bytes = fromBase64(text);
|
|
254
|
+
} catch {
|
|
255
|
+
return redactor.redact(text);
|
|
256
|
+
}
|
|
257
|
+
return maskBytes(bytes, needles) ? toBase64(bytes) : text;
|
|
258
|
+
};
|
|
259
|
+
const string = (text: string): string => {
|
|
260
|
+
if (text.startsWith("$$")) {
|
|
261
|
+
const plain = redactor.redact(text.slice(1));
|
|
262
|
+
return plain.startsWith("$") ? `$${plain}` : plain;
|
|
263
|
+
}
|
|
264
|
+
if (text.startsWith("$S")) return `$S${redactor.redact(text.slice(2))}`;
|
|
265
|
+
if (text.startsWith("$")) return text;
|
|
266
|
+
const plain = redactor.redact(text);
|
|
267
|
+
// A redaction can't make a plain string read as a reference.
|
|
268
|
+
return plain.startsWith("$") ? `$${plain}` : plain;
|
|
269
|
+
};
|
|
270
|
+
const value = (item: unknown): unknown => {
|
|
271
|
+
if (typeof item === "string") return string(item);
|
|
272
|
+
if (Array.isArray(item)) return item.map(value);
|
|
273
|
+
if (item !== null && typeof item === "object") {
|
|
274
|
+
const out: Record<string, unknown> = {};
|
|
275
|
+
for (const [key, entry] of Object.entries(item)) {
|
|
276
|
+
Object.defineProperty(out, redactor.redact(key), {
|
|
277
|
+
value: value(entry),
|
|
278
|
+
enumerable: true,
|
|
279
|
+
writable: true,
|
|
280
|
+
configurable: true,
|
|
281
|
+
});
|
|
282
|
+
}
|
|
283
|
+
return out;
|
|
284
|
+
}
|
|
285
|
+
return item;
|
|
286
|
+
};
|
|
287
|
+
return batch.map((frame: unknown) => {
|
|
288
|
+
if (frame === null || typeof frame !== "object") return frame;
|
|
289
|
+
const record = frame as Record<string, unknown>;
|
|
290
|
+
if (typeof record["c"] === "number") {
|
|
291
|
+
const kind = kinds.get(record["c"]);
|
|
292
|
+
const v = record["v"];
|
|
293
|
+
if (kind === "A") return { ...record, v: maskBase64(v) };
|
|
294
|
+
if (kind === "T" && Array.isArray(v)) return { ...record, v: [v[0], maskBase64(v[1])] };
|
|
295
|
+
if (kind === "B" && v !== null && typeof v === "object" && !Array.isArray(v)) {
|
|
296
|
+
const file = v as Record<string, unknown>;
|
|
297
|
+
return {
|
|
298
|
+
...record,
|
|
299
|
+
v: {
|
|
300
|
+
...file,
|
|
301
|
+
data: maskBase64(file["data"]),
|
|
302
|
+
...(typeof file["name"] === "string" ? { name: redactor.redact(file["name"]) } : {}),
|
|
303
|
+
},
|
|
304
|
+
};
|
|
305
|
+
}
|
|
306
|
+
return { ...record, v: value(v) };
|
|
307
|
+
}
|
|
308
|
+
// A promise or iterable frame: its value is encoded like a chunk's; an error is plain text.
|
|
309
|
+
return Object.fromEntries(
|
|
310
|
+
Object.entries(record).map(([key, entry]) => [
|
|
311
|
+
key,
|
|
312
|
+
key === "v" ? value(entry) : redactValue(entry, redactor),
|
|
313
|
+
]),
|
|
314
|
+
);
|
|
315
|
+
}) as T;
|
|
316
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The child side of supervisor messaging, for Node children the process manager starts with an
|
|
3
|
+
* IPC channel. It wires the JSON-RPC core to Node IPC and keeps the rule that a child never
|
|
4
|
+
* outlives its supervisor: when the channel disconnects (the supervisor exited or was killed), the
|
|
5
|
+
* child signals its own process group, so grandchildren go too, and exits (FAILURE_MODEL §2).
|
|
6
|
+
*
|
|
7
|
+
* ```ts
|
|
8
|
+
* const supervisor = connectToSupervisor({ onRequest: (method, params) => handle(method, params) });
|
|
9
|
+
* await supervisor.request("child/adopt", { pid: pty.pid }); // a program in its own session
|
|
10
|
+
* ```
|
|
11
|
+
*/
|
|
12
|
+
import { type JsonRpcParams, RpcPeer } from "@mostra/protocol";
|
|
13
|
+
|
|
14
|
+
/** Options for {@link connectToSupervisor}. */
|
|
15
|
+
export interface SupervisorConnectionOptions {
|
|
16
|
+
/** Answers the supervisor's requests. */
|
|
17
|
+
readonly onRequest?: (method: string, params: unknown) => unknown;
|
|
18
|
+
/** Receives the supervisor's notifications. */
|
|
19
|
+
readonly onNotification?: (method: string, params: unknown) => void;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** The child's end of the connection. */
|
|
23
|
+
export interface SupervisorConnection {
|
|
24
|
+
/** Sends a request to the supervisor, such as `child/adopt`. */
|
|
25
|
+
request(method: string, params?: JsonRpcParams): Promise<unknown>;
|
|
26
|
+
/** Sends a notification to the supervisor. */
|
|
27
|
+
notify(method: string, params?: JsonRpcParams): void;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Connects a Node child to its supervisor over the IPC channel.
|
|
32
|
+
*
|
|
33
|
+
* @throws Error when the process wasn't started with an IPC channel.
|
|
34
|
+
*/
|
|
35
|
+
export function connectToSupervisor(
|
|
36
|
+
options: SupervisorConnectionOptions = {},
|
|
37
|
+
): SupervisorConnection {
|
|
38
|
+
const send = process.send?.bind(process);
|
|
39
|
+
if (!send)
|
|
40
|
+
throw new Error("This process wasn't started by a Mostra supervisor (no IPC channel).");
|
|
41
|
+
const peer = new RpcPeer({
|
|
42
|
+
send: (message) => {
|
|
43
|
+
send(message);
|
|
44
|
+
},
|
|
45
|
+
...(options.onRequest ? { onRequest: options.onRequest } : {}),
|
|
46
|
+
...(options.onNotification ? { onNotification: options.onNotification } : {}),
|
|
47
|
+
});
|
|
48
|
+
process.on("message", (message) => peer.receive(message));
|
|
49
|
+
process.on("disconnect", () => {
|
|
50
|
+
peer.close();
|
|
51
|
+
exitWithGroup();
|
|
52
|
+
});
|
|
53
|
+
return {
|
|
54
|
+
request: (method, params) => peer.request(method, params),
|
|
55
|
+
notify: (method, params) => peer.notify(method, params),
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Signals this child's whole process group (it leads it) and exits. */
|
|
60
|
+
function exitWithGroup(): void {
|
|
61
|
+
try {
|
|
62
|
+
process.kill(-process.pid, "SIGTERM");
|
|
63
|
+
} catch {
|
|
64
|
+
// The group is already gone.
|
|
65
|
+
}
|
|
66
|
+
process.exit(0);
|
|
67
|
+
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The artifact environment (D95, DP-05): what a child that runs an artifact's own code, or code
|
|
3
|
+
* the artifact chose such as a package's lifecycle script, receives from the supervisor's
|
|
4
|
+
* environment. It is an allowlist, so the supervisor's own settings and a host's credentials
|
|
5
|
+
* (anything a spawning host put into Mostra's environment) never reach artifact code by accident.
|
|
6
|
+
* Install children use it from WP-04 on; workers (WP-08) start from it too.
|
|
7
|
+
*/
|
|
8
|
+
import { delimiter, dirname } from "node:path";
|
|
9
|
+
import type { Environment } from "../log.ts";
|
|
10
|
+
|
|
11
|
+
/** Variables an artifact's processes need to work like an ordinary shell's programs. */
|
|
12
|
+
const PASSED: ReadonlySet<string> = new Set([
|
|
13
|
+
"PATH",
|
|
14
|
+
"HOME",
|
|
15
|
+
"TMPDIR",
|
|
16
|
+
"LANG",
|
|
17
|
+
"LC_ALL",
|
|
18
|
+
"LC_CTYPE",
|
|
19
|
+
"TZ",
|
|
20
|
+
// Who the user is, and the toolchain a package's native build (node-gyp, prebuilds) uses.
|
|
21
|
+
"USER",
|
|
22
|
+
"LOGNAME",
|
|
23
|
+
"SHELL",
|
|
24
|
+
"TERM",
|
|
25
|
+
"XDG_CACHE_HOME",
|
|
26
|
+
"XDG_CONFIG_HOME",
|
|
27
|
+
"XDG_DATA_HOME",
|
|
28
|
+
"CC",
|
|
29
|
+
"CXX",
|
|
30
|
+
"MAKE",
|
|
31
|
+
"PYTHON",
|
|
32
|
+
"DEVELOPER_DIR",
|
|
33
|
+
"SDKROOT",
|
|
34
|
+
// Network access through the user's proxy and certificate authorities.
|
|
35
|
+
"HTTP_PROXY",
|
|
36
|
+
"HTTPS_PROXY",
|
|
37
|
+
"NO_PROXY",
|
|
38
|
+
"http_proxy",
|
|
39
|
+
"https_proxy",
|
|
40
|
+
"no_proxy",
|
|
41
|
+
"NODE_EXTRA_CA_CERTS",
|
|
42
|
+
"SSL_CERT_FILE",
|
|
43
|
+
"SSL_CERT_DIR",
|
|
44
|
+
]);
|
|
45
|
+
|
|
46
|
+
/** npm's own configuration channel: the user's registry, scopes and proxies for installs. */
|
|
47
|
+
const NPM_CONFIG = /^npm_config_/i;
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The artifact environment derived from the supervisor's `env`. Its `PATH` starts with the
|
|
51
|
+
* directory of the Node.js the runtime runs on (D142): a lifecycle script or server code that runs
|
|
52
|
+
* `node` gets the runtime bundle's private Node.js, on a machine with no other Node.js too.
|
|
53
|
+
*/
|
|
54
|
+
export function artifactEnvironment(env: Environment): Environment {
|
|
55
|
+
const result: Record<string, string> = {};
|
|
56
|
+
for (const [name, value] of Object.entries(env)) {
|
|
57
|
+
if (value === undefined) continue;
|
|
58
|
+
if (PASSED.has(name) || NPM_CONFIG.test(name)) result[name] = value;
|
|
59
|
+
}
|
|
60
|
+
const own = dirname(process.execPath);
|
|
61
|
+
const path = result["PATH"] ?? "/usr/bin:/bin";
|
|
62
|
+
result["PATH"] = path.split(delimiter)[0] === own ? path : `${own}${delimiter}${path}`;
|
|
63
|
+
return result;
|
|
64
|
+
}
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Process identity (DATA_MODEL §3 `child.start_time`, FAILURE_MODEL §2). A PID alone can be
|
|
3
|
+
* reused, so a process is identified by its PID plus an opaque start time: the boot it started in
|
|
4
|
+
* and when it started within that boot. Linux reads `/proc/<pid>/stat` (start ticks since boot)
|
|
5
|
+
* and the boot ID; macOS reads `ps -o lstart` (seconds) and `kern.boottime` (VERIFIED_FACTS,
|
|
6
|
+
* WP-02). Zombies count as gone: they have exited and only wait for their parent.
|
|
7
|
+
*
|
|
8
|
+
* Seconds are enough on macOS (issue #8): XNU hands out PIDs in order from the last one, up to
|
|
9
|
+
* 99,999, then from 100, skipping any PID still used as a process, process group or session
|
|
10
|
+
* (`forkproc` in `bsd/kern/kern_fork.c`). A PID comes back only after the whole range has been
|
|
11
|
+
* handed out, about 99,900 forks, which takes this machine about 100 s at its measured 1,000
|
|
12
|
+
* spawns a second, and never while its process group lives (VERIFIED_FACTS, WP-08).
|
|
13
|
+
*/
|
|
14
|
+
import { execFile } from "node:child_process";
|
|
15
|
+
import { readdir, readFile } from "node:fs/promises";
|
|
16
|
+
|
|
17
|
+
/** One running process as the operating system reports it. */
|
|
18
|
+
export interface ProcessInfo {
|
|
19
|
+
readonly pid: number;
|
|
20
|
+
/** Its process group. */
|
|
21
|
+
readonly pgid: number;
|
|
22
|
+
/** `<boot>/<start>`: opaque, but comparable with {@link startedNoEarlier} within one boot. */
|
|
23
|
+
readonly startTime: string;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Splits a start time into its boot and its position within the boot. */
|
|
27
|
+
function parts(startTime: string): { boot: string; at: number } | undefined {
|
|
28
|
+
const slash = startTime.lastIndexOf("/");
|
|
29
|
+
if (slash <= 0) return undefined;
|
|
30
|
+
const at = Number(startTime.slice(slash + 1));
|
|
31
|
+
return Number.isSafeInteger(at) ? { boot: startTime.slice(0, slash), at } : undefined;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Whether two start times belong to the same boot of the machine. */
|
|
35
|
+
export function sameBoot(a: string, b: string): boolean {
|
|
36
|
+
const left = parts(a);
|
|
37
|
+
const right = parts(b);
|
|
38
|
+
return left !== undefined && right !== undefined && left.boot === right.boot;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Whether `candidate` started in the same boot as `reference` and no earlier. On macOS the
|
|
43
|
+
* resolution is one second, so a process started in the same second counts as no earlier.
|
|
44
|
+
*/
|
|
45
|
+
export function startedNoEarlier(candidate: string, reference: string): boolean {
|
|
46
|
+
const c = parts(candidate);
|
|
47
|
+
const r = parts(reference);
|
|
48
|
+
return c !== undefined && r !== undefined && c.boot === r.boot && c.at >= r.at;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** Parses one `/proc/<pid>/stat` line. `comm` may contain spaces and parentheses. */
|
|
52
|
+
export function parseProcStat(line: string, boot: string): ProcessInfo | undefined {
|
|
53
|
+
const open = line.indexOf("(");
|
|
54
|
+
const close = line.lastIndexOf(")");
|
|
55
|
+
if (open < 0 || close < open) return undefined;
|
|
56
|
+
const pid = Number(line.slice(0, open).trim());
|
|
57
|
+
// Fields after `comm` start at field 3 (state); pgrp is field 5 and starttime field 22.
|
|
58
|
+
const rest = line
|
|
59
|
+
.slice(close + 1)
|
|
60
|
+
.trim()
|
|
61
|
+
.split(/\s+/);
|
|
62
|
+
// A zombie has exited; only its parent's wait is missing. It runs nothing and is skipped.
|
|
63
|
+
if (rest[0] === "Z") return undefined;
|
|
64
|
+
const pgid = Number(rest[2]);
|
|
65
|
+
const start = rest[19];
|
|
66
|
+
if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(pgid) || start === undefined) {
|
|
67
|
+
return undefined;
|
|
68
|
+
}
|
|
69
|
+
if (!/^\d+$/.test(start)) return undefined;
|
|
70
|
+
return { pid, pgid, startTime: `${boot}/${start}` };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Parses one line of `LC_ALL=C TZ=UTC ps -o pid=,pgid=,stat=,lstart=`, such as
|
|
77
|
+
* ` 214 99444 Ss Tue Oct 6 13:53:19 2026`. Zombies (`stat` starting with `Z`) are skipped.
|
|
78
|
+
*/
|
|
79
|
+
export function parsePsLine(line: string, boot: string): ProcessInfo | undefined {
|
|
80
|
+
const fields = line.trim().split(/\s+/);
|
|
81
|
+
if (fields.length < 8) return undefined;
|
|
82
|
+
const [pidText, pgidText, stat, , monthText, dayText, timeText, yearText] = fields;
|
|
83
|
+
if (stat?.startsWith("Z")) return undefined;
|
|
84
|
+
const pid = Number(pidText);
|
|
85
|
+
const pgid = Number(pgidText);
|
|
86
|
+
const month = MONTHS.indexOf(monthText ?? "");
|
|
87
|
+
const [hours, minutes, seconds] = (timeText ?? "").split(":").map(Number);
|
|
88
|
+
const millis = Date.UTC(
|
|
89
|
+
Number(yearText),
|
|
90
|
+
month,
|
|
91
|
+
Number(dayText),
|
|
92
|
+
hours ?? Number.NaN,
|
|
93
|
+
minutes ?? Number.NaN,
|
|
94
|
+
seconds ?? Number.NaN,
|
|
95
|
+
);
|
|
96
|
+
if (
|
|
97
|
+
!Number.isSafeInteger(pid) ||
|
|
98
|
+
!Number.isSafeInteger(pgid) ||
|
|
99
|
+
month < 0 ||
|
|
100
|
+
Number.isNaN(millis)
|
|
101
|
+
) {
|
|
102
|
+
return undefined;
|
|
103
|
+
}
|
|
104
|
+
return { pid, pgid, startTime: `${boot}/${millis / 1000}` };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function run(file: string, args: readonly string[]): Promise<{ code: number; stdout: string }> {
|
|
108
|
+
return new Promise((resolve, reject) => {
|
|
109
|
+
execFile(
|
|
110
|
+
file,
|
|
111
|
+
args,
|
|
112
|
+
{
|
|
113
|
+
env: { LC_ALL: "C", TZ: "UTC", PATH: "/usr/bin:/bin:/usr/sbin:/sbin" },
|
|
114
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
115
|
+
},
|
|
116
|
+
(error, stdout) => {
|
|
117
|
+
if (error && typeof error.code !== "number") {
|
|
118
|
+
reject(error);
|
|
119
|
+
return;
|
|
120
|
+
}
|
|
121
|
+
resolve({ code: typeof error?.code === "number" ? error.code : 0, stdout });
|
|
122
|
+
},
|
|
123
|
+
);
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
let cachedBoot: Promise<string> | undefined;
|
|
128
|
+
|
|
129
|
+
/** The identity of the current boot of this machine. */
|
|
130
|
+
export function bootId(): Promise<string> {
|
|
131
|
+
cachedBoot ??= (async () => {
|
|
132
|
+
if (process.platform === "linux") {
|
|
133
|
+
return (await readFile("/proc/sys/kernel/random/boot_id", "utf8")).trim();
|
|
134
|
+
}
|
|
135
|
+
const { stdout } = await run("/usr/sbin/sysctl", ["-n", "kern.boottime"]);
|
|
136
|
+
const match = /sec = (\d+), usec = (\d+)/.exec(stdout);
|
|
137
|
+
if (!match) throw new Error("Couldn't read kern.boottime.");
|
|
138
|
+
return `${match[1]}.${match[2]}`;
|
|
139
|
+
})();
|
|
140
|
+
return cachedBoot;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** Reads one process, or `undefined` when no process has that PID. */
|
|
144
|
+
export async function readProcess(pid: number): Promise<ProcessInfo | undefined> {
|
|
145
|
+
const boot = await bootId();
|
|
146
|
+
if (process.platform === "linux") {
|
|
147
|
+
try {
|
|
148
|
+
return parseProcStat(await readFile(`/proc/${pid}/stat`, "utf8"), boot);
|
|
149
|
+
} catch {
|
|
150
|
+
return undefined;
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
const { code, stdout } = await run("/bin/ps", [
|
|
154
|
+
"-o",
|
|
155
|
+
"pid=,pgid=,stat=,lstart=",
|
|
156
|
+
"-p",
|
|
157
|
+
String(pid),
|
|
158
|
+
]);
|
|
159
|
+
if (code !== 0) return undefined;
|
|
160
|
+
const [line] = stdout.split("\n").filter((text) => text.trim() !== "");
|
|
161
|
+
return line === undefined ? undefined : parsePsLine(line, boot);
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** Lists every process the user can see. */
|
|
165
|
+
export async function listProcesses(): Promise<ProcessInfo[]> {
|
|
166
|
+
const boot = await bootId();
|
|
167
|
+
if (process.platform === "linux") {
|
|
168
|
+
const entries = (await readdir("/proc")).filter((name) => /^\d+$/.test(name));
|
|
169
|
+
const infos = await Promise.all(
|
|
170
|
+
entries.map(async (name) => {
|
|
171
|
+
try {
|
|
172
|
+
return parseProcStat(await readFile(`/proc/${name}/stat`, "utf8"), boot);
|
|
173
|
+
} catch {
|
|
174
|
+
return undefined;
|
|
175
|
+
}
|
|
176
|
+
}),
|
|
177
|
+
);
|
|
178
|
+
return infos.filter((info): info is ProcessInfo => info !== undefined);
|
|
179
|
+
}
|
|
180
|
+
const { stdout } = await run("/bin/ps", ["-A", "-o", "pid=,pgid=,stat=,lstart="]);
|
|
181
|
+
return stdout
|
|
182
|
+
.split("\n")
|
|
183
|
+
.map((line) => parsePsLine(line, boot))
|
|
184
|
+
.filter((info): info is ProcessInfo => info !== undefined);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** Whether the process recorded as `pid` and `startTime` is still the one running. */
|
|
188
|
+
export async function isSameProcess(pid: number, startTime: string): Promise<boolean> {
|
|
189
|
+
const info = await readProcess(pid);
|
|
190
|
+
return info !== undefined && info.startTime === startTime;
|
|
191
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The process manager (RT-09): every child in its own process group, recorded with PID and start
|
|
3
|
+
* time, reaped after a supervisor crash, with typed JSON-RPC messages over Node IPC.
|
|
4
|
+
*/
|
|
5
|
+
export {
|
|
6
|
+
connectToSupervisor,
|
|
7
|
+
type SupervisorConnection,
|
|
8
|
+
type SupervisorConnectionOptions,
|
|
9
|
+
} from "./child.ts";
|
|
10
|
+
export { artifactEnvironment } from "./environment.ts";
|
|
11
|
+
export { isSameProcess, listProcesses, readProcess } from "./identity.ts";
|
|
12
|
+
export {
|
|
13
|
+
type ChildExit,
|
|
14
|
+
type ChildHandle,
|
|
15
|
+
openProcessManager,
|
|
16
|
+
type ProcessManager,
|
|
17
|
+
type ReapedChild,
|
|
18
|
+
type SpawnSpec,
|
|
19
|
+
} from "./manager.ts";
|