@orkestrel/process 0.0.9 → 0.0.11
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 +18 -23
- package/dist/src/core/index.cjs +33 -17
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +171 -148
- package/dist/src/core/index.d.ts +171 -148
- package/dist/src/core/index.js +33 -17
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +157 -97
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +316 -93
- package/dist/src/server/index.d.ts +316 -93
- package/dist/src/server/index.js +157 -98
- package/dist/src/server/index.js.map +1 -1
- package/package.json +11 -12
package/dist/src/server/index.js
CHANGED
|
@@ -8,6 +8,42 @@ import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_DRAIN, PROCESS_EVIDENCE,
|
|
|
8
8
|
import { createInterface } from "node:readline";
|
|
9
9
|
import { Emitter } from "@orkestrel/emitter";
|
|
10
10
|
import { StringDecoder } from "node:string_decoder";
|
|
11
|
+
//#region src/server/cloners.ts
|
|
12
|
+
/**
|
|
13
|
+
* Takes one owned frozen snapshot of a caller's command.
|
|
14
|
+
*
|
|
15
|
+
* @remarks
|
|
16
|
+
* Every public entry point snapshots before it validates, so the object validated is the object
|
|
17
|
+
* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
|
|
18
|
+
* command whose `file` changes between reads would otherwise validate one executable and spawn
|
|
19
|
+
* another. The argument vector and the environment record are copied and frozen, so a caller
|
|
20
|
+
* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
|
|
21
|
+
* becoming an explicit `undefined`.
|
|
22
|
+
*
|
|
23
|
+
* @param command - The caller's command, whose properties may be getters
|
|
24
|
+
* @returns A frozen command carrying the values read at this instant
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* ```ts
|
|
28
|
+
* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
function snapshotCommand(command) {
|
|
32
|
+
const file = command.file;
|
|
33
|
+
const argumentsList = Object.freeze([...command.arguments]);
|
|
34
|
+
const sourceEnvironment = command.environment;
|
|
35
|
+
const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
|
|
36
|
+
const input = command.input;
|
|
37
|
+
const isolated = command.isolated;
|
|
38
|
+
return Object.freeze({
|
|
39
|
+
file,
|
|
40
|
+
arguments: argumentsList,
|
|
41
|
+
...environment === void 0 ? {} : { environment },
|
|
42
|
+
...input === void 0 ? {} : { input },
|
|
43
|
+
...isolated === void 0 ? {} : { isolated }
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
//#endregion
|
|
11
47
|
//#region src/server/helpers.ts
|
|
12
48
|
/**
|
|
13
49
|
* Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
|
|
@@ -106,40 +142,6 @@ function captureChunk(chunk, room) {
|
|
|
106
142
|
return Buffer.from(chunk.subarray(0, room));
|
|
107
143
|
}
|
|
108
144
|
/**
|
|
109
|
-
* Takes one owned frozen snapshot of a caller's command.
|
|
110
|
-
*
|
|
111
|
-
* @remarks
|
|
112
|
-
* Every public entry point snapshots before it validates, so the object validated is the object
|
|
113
|
-
* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
|
|
114
|
-
* command whose `file` changes between reads would otherwise validate one executable and spawn
|
|
115
|
-
* another. The argument vector and the environment record are copied and frozen, so a caller
|
|
116
|
-
* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
|
|
117
|
-
* becoming an explicit `undefined`.
|
|
118
|
-
*
|
|
119
|
-
* @param command - The caller's command, whose properties may be getters
|
|
120
|
-
* @returns A frozen command carrying the values read at this instant
|
|
121
|
-
*
|
|
122
|
-
* @example
|
|
123
|
-
* ```ts
|
|
124
|
-
* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
|
|
125
|
-
* ```
|
|
126
|
-
*/
|
|
127
|
-
function snapshotCommand(command) {
|
|
128
|
-
const file = command.file;
|
|
129
|
-
const argumentsList = Object.freeze([...command.arguments]);
|
|
130
|
-
const sourceEnvironment = command.environment;
|
|
131
|
-
const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
|
|
132
|
-
const input = command.input;
|
|
133
|
-
const isolated = command.isolated;
|
|
134
|
-
return Object.freeze({
|
|
135
|
-
file,
|
|
136
|
-
arguments: argumentsList,
|
|
137
|
-
...environment === void 0 ? {} : { environment },
|
|
138
|
-
...input === void 0 ? {} : { input },
|
|
139
|
-
...isolated === void 0 ? {} : { isolated }
|
|
140
|
-
});
|
|
141
|
-
}
|
|
142
|
-
/**
|
|
143
145
|
* Renders one command into its diagnostic command line.
|
|
144
146
|
*
|
|
145
147
|
* @param command - The executable and its argument vector
|
|
@@ -256,7 +258,7 @@ function mergeEnvironment(isolated, base, override) {
|
|
|
256
258
|
* command. An unreadable or malformed path reports `false` rather than throwing.
|
|
257
259
|
*
|
|
258
260
|
* @param target - The absolute or relative path to inspect
|
|
259
|
-
* @returns True
|
|
261
|
+
* @returns True if the path resolves to a regular file; false otherwise
|
|
260
262
|
*
|
|
261
263
|
* @example
|
|
262
264
|
* ```ts
|
|
@@ -304,7 +306,8 @@ function buildExecutableCandidates(file, workspace, environment, platform) {
|
|
|
304
306
|
return Object.freeze(targets);
|
|
305
307
|
}
|
|
306
308
|
/**
|
|
307
|
-
* Resolves a command file to the executable path the host would launch
|
|
309
|
+
* Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX
|
|
310
|
+
* host, which performs its own lookup.
|
|
308
311
|
*
|
|
309
312
|
* @param file - The command executable name or path
|
|
310
313
|
* @param options - The directory searched first and the child's effective environment
|
|
@@ -529,7 +532,7 @@ function validateWorkspace(workspace) {
|
|
|
529
532
|
* initiated against a pid the host may have reused.
|
|
530
533
|
*
|
|
531
534
|
* @param child - The child boundary
|
|
532
|
-
* @returns True
|
|
535
|
+
* @returns True if the process has exited; false otherwise
|
|
533
536
|
*
|
|
534
537
|
* @example
|
|
535
538
|
* ```ts
|
|
@@ -585,7 +588,7 @@ function killProcess(child, signal) {
|
|
|
585
588
|
*
|
|
586
589
|
* @param pid - The root process id of the tree to end
|
|
587
590
|
* @param timeout - The milliseconds the utility is given before it is killed
|
|
588
|
-
* @returns True
|
|
591
|
+
* @returns True if the utility reported success; false otherwise (it failed, was unavailable, or was cut off)
|
|
589
592
|
*
|
|
590
593
|
* @example
|
|
591
594
|
* ```ts
|
|
@@ -636,7 +639,7 @@ function waitForExit(child, timeout) {
|
|
|
636
639
|
*
|
|
637
640
|
* @param child - The child boundary
|
|
638
641
|
* @param timeout - The milliseconds to wait before giving up
|
|
639
|
-
* @returns True
|
|
642
|
+
* @returns True if the host close arrived inside the deadline; false otherwise
|
|
640
643
|
*
|
|
641
644
|
* @example
|
|
642
645
|
* ```ts
|
|
@@ -671,7 +674,7 @@ function waitForClose(child, timeout) {
|
|
|
671
674
|
* @param child - The child boundary
|
|
672
675
|
* @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
|
|
673
676
|
* @param confirm - The milliseconds the native exit is awaited after the final kill
|
|
674
|
-
* @returns True
|
|
677
|
+
* @returns True if the native exit was observed; false otherwise (`confirm` elapsed without it)
|
|
675
678
|
*
|
|
676
679
|
* @example
|
|
677
680
|
* ```ts
|
|
@@ -1029,7 +1032,7 @@ function detach(command, options) {
|
|
|
1029
1032
|
child.unref();
|
|
1030
1033
|
}
|
|
1031
1034
|
//#endregion
|
|
1032
|
-
//#region src/server/Supervisor.ts
|
|
1035
|
+
//#region src/server/processes/Supervisor.ts
|
|
1033
1036
|
/**
|
|
1034
1037
|
* Supervises one child process and reports each lifecycle moment to the face composing it.
|
|
1035
1038
|
*
|
|
@@ -1058,6 +1061,25 @@ function detach(command, options) {
|
|
|
1058
1061
|
* termination completes. `relieve` is optional because a face that never pauses the child's output
|
|
1059
1062
|
* holds no backpressure to release, and a face with nothing to do there would otherwise declare an
|
|
1060
1063
|
* empty method to say so.
|
|
1064
|
+
*
|
|
1065
|
+
* @example
|
|
1066
|
+
* ```ts
|
|
1067
|
+
* import { Supervisor } from '@orkestrel/process/server'
|
|
1068
|
+
*
|
|
1069
|
+
* const engine = new Supervisor(
|
|
1070
|
+
* { command: { file: 'node', arguments: ['--version'] }, workspace: process.cwd() },
|
|
1071
|
+
* {
|
|
1072
|
+
* chunk: () => undefined,
|
|
1073
|
+
* fault: () => undefined,
|
|
1074
|
+
* close: () => undefined,
|
|
1075
|
+
* terminal: () => undefined,
|
|
1076
|
+
* teardown: () => undefined,
|
|
1077
|
+
* },
|
|
1078
|
+
* )
|
|
1079
|
+
* const exit = await engine.exit
|
|
1080
|
+
* exit.code // 0
|
|
1081
|
+
* await engine.destroy()
|
|
1082
|
+
* ```
|
|
1061
1083
|
*/
|
|
1062
1084
|
var Supervisor = class {
|
|
1063
1085
|
#chunk;
|
|
@@ -1087,7 +1109,7 @@ var Supervisor = class {
|
|
|
1087
1109
|
#termination;
|
|
1088
1110
|
#destruction;
|
|
1089
1111
|
/**
|
|
1090
|
-
*
|
|
1112
|
+
* Spawns one child process and begins standard-error capture.
|
|
1091
1113
|
*
|
|
1092
1114
|
* @remarks
|
|
1093
1115
|
* The face's callbacks are captured before anything is read or spawned, so the first moment the
|
|
@@ -1164,36 +1186,36 @@ var Supervisor = class {
|
|
|
1164
1186
|
if (signal.aborted) this.stop();
|
|
1165
1187
|
}
|
|
1166
1188
|
}
|
|
1167
|
-
/**
|
|
1189
|
+
/** Holds the child's standard-output stream, for the composing face to attach its own consumer to. */
|
|
1168
1190
|
get stdout() {
|
|
1169
1191
|
return this.#child.stdout;
|
|
1170
1192
|
}
|
|
1171
|
-
/**
|
|
1193
|
+
/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
|
|
1172
1194
|
get pid() {
|
|
1173
1195
|
return this.#child.pid;
|
|
1174
1196
|
}
|
|
1175
|
-
/**
|
|
1197
|
+
/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
|
|
1176
1198
|
get code() {
|
|
1177
1199
|
return this.#child.exitCode;
|
|
1178
1200
|
}
|
|
1179
|
-
/**
|
|
1201
|
+
/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
|
|
1180
1202
|
get signal() {
|
|
1181
1203
|
return this.#child.signalCode;
|
|
1182
1204
|
}
|
|
1183
|
-
/**
|
|
1205
|
+
/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
|
|
1184
1206
|
get evidence() {
|
|
1185
1207
|
return this.#tail.toString("utf8");
|
|
1186
1208
|
}
|
|
1187
|
-
/**
|
|
1209
|
+
/** Reports whether the terminal moment arrived and `exit` settled. */
|
|
1188
1210
|
get settled() {
|
|
1189
1211
|
return this.#settled;
|
|
1190
1212
|
}
|
|
1191
|
-
/**
|
|
1213
|
+
/** Reports whether termination began, including after the terminal moment. */
|
|
1192
1214
|
get stopping() {
|
|
1193
1215
|
return this.#stopping;
|
|
1194
1216
|
}
|
|
1195
1217
|
/**
|
|
1196
|
-
*
|
|
1218
|
+
* Settles at the child's own ending, awaited without the terminal moment's drain window.
|
|
1197
1219
|
*
|
|
1198
1220
|
* @remarks
|
|
1199
1221
|
* Never rejects, and resolves no value: `code` and `signal` carry the terminal facts as soon as
|
|
@@ -1203,7 +1225,7 @@ var Supervisor = class {
|
|
|
1203
1225
|
get ending() {
|
|
1204
1226
|
return this.#ending.promise;
|
|
1205
1227
|
}
|
|
1206
|
-
/**
|
|
1228
|
+
/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
|
|
1207
1229
|
get exit() {
|
|
1208
1230
|
return this.#exit.promise;
|
|
1209
1231
|
}
|
|
@@ -1220,7 +1242,30 @@ var Supervisor = class {
|
|
|
1220
1242
|
* discard.
|
|
1221
1243
|
*
|
|
1222
1244
|
* @param bytes - The payload to write, already framed by the caller
|
|
1223
|
-
* @returns True
|
|
1245
|
+
* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
|
|
1246
|
+
*
|
|
1247
|
+
* @example
|
|
1248
|
+
* ```ts
|
|
1249
|
+
* import { Supervisor } from '@orkestrel/process/server'
|
|
1250
|
+
*
|
|
1251
|
+
* const engine = new Supervisor(
|
|
1252
|
+
* {
|
|
1253
|
+
* command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
|
|
1254
|
+
* workspace: process.cwd(),
|
|
1255
|
+
* writable: true,
|
|
1256
|
+
* },
|
|
1257
|
+
* {
|
|
1258
|
+
* chunk: () => undefined,
|
|
1259
|
+
* fault: () => undefined,
|
|
1260
|
+
* close: () => undefined,
|
|
1261
|
+
* terminal: () => undefined,
|
|
1262
|
+
* teardown: () => undefined,
|
|
1263
|
+
* },
|
|
1264
|
+
* )
|
|
1265
|
+
* const accepted = await engine.deliver(new TextEncoder().encode('ping\n'))
|
|
1266
|
+
* accepted // true
|
|
1267
|
+
* await engine.destroy()
|
|
1268
|
+
* ```
|
|
1224
1269
|
*/
|
|
1225
1270
|
deliver(bytes) {
|
|
1226
1271
|
const stdin = this.#child.stdin;
|
|
@@ -1271,7 +1316,7 @@ var Supervisor = class {
|
|
|
1271
1316
|
* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
|
|
1272
1317
|
* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
|
|
1273
1318
|
*
|
|
1274
|
-
* @returns True
|
|
1319
|
+
* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
|
|
1275
1320
|
*/
|
|
1276
1321
|
stop() {
|
|
1277
1322
|
if (this.#termination !== void 0) return this.#termination;
|
|
@@ -1399,9 +1444,10 @@ var Supervisor = class {
|
|
|
1399
1444
|
}
|
|
1400
1445
|
};
|
|
1401
1446
|
//#endregion
|
|
1402
|
-
//#region src/server/Process.ts
|
|
1447
|
+
//#region src/server/processes/Process.ts
|
|
1403
1448
|
/**
|
|
1404
|
-
* Supervises one child
|
|
1449
|
+
* Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
|
|
1450
|
+
* every observation channel aligned at termination.
|
|
1405
1451
|
*
|
|
1406
1452
|
* @remarks
|
|
1407
1453
|
* The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
|
|
@@ -1446,7 +1492,7 @@ var Process = class {
|
|
|
1446
1492
|
#truncated = false;
|
|
1447
1493
|
#ended = false;
|
|
1448
1494
|
/**
|
|
1449
|
-
*
|
|
1495
|
+
* Spawns one child process and begins stream capture.
|
|
1450
1496
|
*
|
|
1451
1497
|
* @param options - Command, workspace, termination, capture, stdin, and observation settings
|
|
1452
1498
|
* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
|
|
@@ -1501,48 +1547,48 @@ var Process = class {
|
|
|
1501
1547
|
this.#reader.on("line", this.#push.bind(this));
|
|
1502
1548
|
this.#reader.once("close", this.#finish.bind(this));
|
|
1503
1549
|
}
|
|
1504
|
-
/**
|
|
1550
|
+
/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
|
|
1505
1551
|
get pid() {
|
|
1506
1552
|
return this.#engine.pid;
|
|
1507
1553
|
}
|
|
1508
|
-
/**
|
|
1554
|
+
/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
|
|
1509
1555
|
get code() {
|
|
1510
1556
|
return this.#engine.code;
|
|
1511
1557
|
}
|
|
1512
|
-
/**
|
|
1558
|
+
/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
|
|
1513
1559
|
get signal() {
|
|
1514
1560
|
return this.#engine.signal;
|
|
1515
1561
|
}
|
|
1516
|
-
/**
|
|
1562
|
+
/** Holds the typed lifecycle observation surface. */
|
|
1517
1563
|
get emitter() {
|
|
1518
1564
|
return this.#emitter;
|
|
1519
1565
|
}
|
|
1520
|
-
/**
|
|
1566
|
+
/** Yields the captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
|
|
1521
1567
|
get lines() {
|
|
1522
1568
|
return this.#lines;
|
|
1523
1569
|
}
|
|
1524
|
-
/**
|
|
1570
|
+
/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
|
|
1525
1571
|
get evidence() {
|
|
1526
1572
|
return this.#engine.evidence;
|
|
1527
1573
|
}
|
|
1528
|
-
/**
|
|
1574
|
+
/** Reports whether the `lines` stream omitted output after a retention bound was reached. */
|
|
1529
1575
|
get truncated() {
|
|
1530
1576
|
return this.#truncated;
|
|
1531
1577
|
}
|
|
1532
|
-
/**
|
|
1578
|
+
/** Reports whether the terminal moment arrived and `exit` settled. */
|
|
1533
1579
|
get settled() {
|
|
1534
1580
|
return this.#engine.settled;
|
|
1535
1581
|
}
|
|
1536
|
-
/**
|
|
1582
|
+
/** Reports whether termination began, including after the terminal moment. */
|
|
1537
1583
|
get stopping() {
|
|
1538
1584
|
return this.#engine.stopping;
|
|
1539
1585
|
}
|
|
1540
|
-
/**
|
|
1586
|
+
/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
|
|
1541
1587
|
get exit() {
|
|
1542
1588
|
return this.#engine.exit;
|
|
1543
1589
|
}
|
|
1544
1590
|
/**
|
|
1545
|
-
*
|
|
1591
|
+
* Writes one line to the open standard-input channel.
|
|
1546
1592
|
*
|
|
1547
1593
|
* @remarks
|
|
1548
1594
|
* Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
|
|
@@ -1556,7 +1602,7 @@ var Process = class {
|
|
|
1556
1602
|
* for bytes the package is about to discard.
|
|
1557
1603
|
*
|
|
1558
1604
|
* @param text - The line text without its trailing newline
|
|
1559
|
-
* @returns True
|
|
1605
|
+
* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
|
|
1560
1606
|
*/
|
|
1561
1607
|
send(text) {
|
|
1562
1608
|
return this.#engine.deliver(Buffer.from(`${text}\n`, "utf8"));
|
|
@@ -1570,7 +1616,7 @@ var Process = class {
|
|
|
1570
1616
|
* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
|
|
1571
1617
|
* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
|
|
1572
1618
|
*
|
|
1573
|
-
* @returns True
|
|
1619
|
+
* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
|
|
1574
1620
|
*/
|
|
1575
1621
|
stop() {
|
|
1576
1622
|
return this.#engine.stop();
|
|
@@ -1688,9 +1734,10 @@ var Process = class {
|
|
|
1688
1734
|
}
|
|
1689
1735
|
};
|
|
1690
1736
|
//#endregion
|
|
1691
|
-
//#region src/server/ProcessManager.ts
|
|
1737
|
+
//#region src/server/processes/ProcessManager.ts
|
|
1692
1738
|
/**
|
|
1693
|
-
*
|
|
1739
|
+
* Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
|
|
1740
|
+
* every live child on teardown.
|
|
1694
1741
|
*
|
|
1695
1742
|
* @remarks
|
|
1696
1743
|
* A child launched under an id joins the registry and emits `launch`; when it settles it removes
|
|
@@ -1726,7 +1773,7 @@ var ProcessManager = class {
|
|
|
1726
1773
|
#destroying = false;
|
|
1727
1774
|
#ending;
|
|
1728
1775
|
/**
|
|
1729
|
-
*
|
|
1776
|
+
* Constructs a process registry.
|
|
1730
1777
|
*
|
|
1731
1778
|
* @param options - Initial fleet-level observation hooks and listener-error handling
|
|
1732
1779
|
*/
|
|
@@ -1738,16 +1785,16 @@ var ProcessManager = class {
|
|
|
1738
1785
|
...error === void 0 ? {} : { error }
|
|
1739
1786
|
});
|
|
1740
1787
|
}
|
|
1741
|
-
/**
|
|
1788
|
+
/** Holds the typed fleet-level observation surface. */
|
|
1742
1789
|
get emitter() {
|
|
1743
1790
|
return this.#emitter;
|
|
1744
1791
|
}
|
|
1745
|
-
/**
|
|
1792
|
+
/** Counts the live children. */
|
|
1746
1793
|
get count() {
|
|
1747
1794
|
return this.#children.size;
|
|
1748
1795
|
}
|
|
1749
1796
|
/**
|
|
1750
|
-
*
|
|
1797
|
+
* Returns the live child under `id`, or `undefined` when none is.
|
|
1751
1798
|
*
|
|
1752
1799
|
* @param id - The registry key
|
|
1753
1800
|
* @returns The child, or `undefined`
|
|
@@ -1756,7 +1803,7 @@ var ProcessManager = class {
|
|
|
1756
1803
|
return this.#children.get(id);
|
|
1757
1804
|
}
|
|
1758
1805
|
/**
|
|
1759
|
-
*
|
|
1806
|
+
* Returns a snapshot of every live child.
|
|
1760
1807
|
*
|
|
1761
1808
|
* @returns The live children in launch order
|
|
1762
1809
|
*/
|
|
@@ -1764,7 +1811,7 @@ var ProcessManager = class {
|
|
|
1764
1811
|
return [...this.#children.values()];
|
|
1765
1812
|
}
|
|
1766
1813
|
/**
|
|
1767
|
-
*
|
|
1814
|
+
* Spawns and registers one child under `id`.
|
|
1768
1815
|
*
|
|
1769
1816
|
* @remarks
|
|
1770
1817
|
* {@link Process} reads every option before it spawns, so a caller's own option getter runs while
|
|
@@ -1802,7 +1849,7 @@ var ProcessManager = class {
|
|
|
1802
1849
|
return this.#stopMany(target);
|
|
1803
1850
|
}
|
|
1804
1851
|
/**
|
|
1805
|
-
*
|
|
1852
|
+
* Stops every child, then destroys the registry emitter last.
|
|
1806
1853
|
*
|
|
1807
1854
|
* @remarks
|
|
1808
1855
|
* Always resolves, and refuses a later `launch` with a {@link createProtocolError}. Each child is
|
|
@@ -1855,7 +1902,7 @@ var ProcessManager = class {
|
|
|
1855
1902
|
}
|
|
1856
1903
|
};
|
|
1857
1904
|
//#endregion
|
|
1858
|
-
//#region src/server/Session.ts
|
|
1905
|
+
//#region src/server/processes/Session.ts
|
|
1859
1906
|
/**
|
|
1860
1907
|
* Supervises one child and publishes its standard output as raw bytes.
|
|
1861
1908
|
*
|
|
@@ -1892,7 +1939,7 @@ var Session = class {
|
|
|
1892
1939
|
#engine;
|
|
1893
1940
|
#output;
|
|
1894
1941
|
/**
|
|
1895
|
-
*
|
|
1942
|
+
* Spawns one child process and begins byte capture.
|
|
1896
1943
|
*
|
|
1897
1944
|
* @param options - Command, workspace, termination, evidence, stdin, and observation settings
|
|
1898
1945
|
* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
|
|
@@ -1930,39 +1977,39 @@ var Session = class {
|
|
|
1930
1977
|
});
|
|
1931
1978
|
this.#engine.stdout.on("data", this.#output);
|
|
1932
1979
|
}
|
|
1933
|
-
/**
|
|
1980
|
+
/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
|
|
1934
1981
|
get pid() {
|
|
1935
1982
|
return this.#engine.pid;
|
|
1936
1983
|
}
|
|
1937
|
-
/**
|
|
1984
|
+
/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
|
|
1938
1985
|
get code() {
|
|
1939
1986
|
return this.#engine.code;
|
|
1940
1987
|
}
|
|
1941
|
-
/**
|
|
1988
|
+
/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
|
|
1942
1989
|
get signal() {
|
|
1943
1990
|
return this.#engine.signal;
|
|
1944
1991
|
}
|
|
1945
|
-
/**
|
|
1992
|
+
/** Holds the typed lifecycle observation surface. */
|
|
1946
1993
|
get emitter() {
|
|
1947
1994
|
return this.#emitter;
|
|
1948
1995
|
}
|
|
1949
|
-
/**
|
|
1996
|
+
/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
|
|
1950
1997
|
get evidence() {
|
|
1951
1998
|
return this.#engine.evidence;
|
|
1952
1999
|
}
|
|
1953
|
-
/**
|
|
2000
|
+
/** Reports whether the terminal moment arrived and `exit` settled. */
|
|
1954
2001
|
get settled() {
|
|
1955
2002
|
return this.#engine.settled;
|
|
1956
2003
|
}
|
|
1957
|
-
/**
|
|
2004
|
+
/** Reports whether termination began, including after the terminal moment. `end` never turns it true. */
|
|
1958
2005
|
get stopping() {
|
|
1959
2006
|
return this.#engine.stopping;
|
|
1960
2007
|
}
|
|
1961
|
-
/**
|
|
2008
|
+
/** Settles at the child's own ending, awaited without the terminal moment's drain window. */
|
|
1962
2009
|
get ending() {
|
|
1963
2010
|
return this.#engine.ending;
|
|
1964
2011
|
}
|
|
1965
|
-
/**
|
|
2012
|
+
/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
|
|
1966
2013
|
get exit() {
|
|
1967
2014
|
return this.#engine.exit;
|
|
1968
2015
|
}
|
|
@@ -1976,7 +2023,7 @@ var Session = class {
|
|
|
1976
2023
|
* returned promise settles.
|
|
1977
2024
|
*
|
|
1978
2025
|
* @param bytes - The payload to write, already framed by the caller
|
|
1979
|
-
* @returns True
|
|
2026
|
+
* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
|
|
1980
2027
|
*/
|
|
1981
2028
|
write(bytes) {
|
|
1982
2029
|
return this.#engine.deliver(bytes);
|
|
@@ -2000,7 +2047,7 @@ var Session = class {
|
|
|
2000
2047
|
* @remarks
|
|
2001
2048
|
* Never rejects, and every call shares one termination bounded by `grace` and `drain`.
|
|
2002
2049
|
*
|
|
2003
|
-
* @returns True
|
|
2050
|
+
* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
|
|
2004
2051
|
*/
|
|
2005
2052
|
stop() {
|
|
2006
2053
|
return this.#engine.stop();
|
|
@@ -2036,27 +2083,37 @@ var Session = class {
|
|
|
2036
2083
|
//#endregion
|
|
2037
2084
|
//#region src/server/factories.ts
|
|
2038
2085
|
/**
|
|
2039
|
-
* Creates one supervised child process
|
|
2086
|
+
* Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
|
|
2087
|
+
* holds the published contract rather than the `Process` class.
|
|
2040
2088
|
*
|
|
2041
2089
|
* @param options - Command, workspace, termination, evidence, stdin, and observation settings
|
|
2042
2090
|
* @returns The launched {@link ProcessInterface}
|
|
2043
2091
|
*
|
|
2044
|
-
* @example
|
|
2092
|
+
* @example Supervise a child and read its lines
|
|
2045
2093
|
* ```ts
|
|
2046
2094
|
* import { createProcess } from '@orkestrel/process/server'
|
|
2047
2095
|
*
|
|
2048
2096
|
* const child = createProcess({
|
|
2049
|
-
* command: { file: 'node', arguments: ['
|
|
2097
|
+
* command: { file: 'node', arguments: ['-e', 'console.log("ready"); console.log("done")'] },
|
|
2050
2098
|
* workspace: process.cwd(),
|
|
2051
|
-
* grace:
|
|
2099
|
+
* grace: 5_000, // POSIX only: the window between SIGTERM and SIGKILL
|
|
2052
2100
|
* })
|
|
2101
|
+
*
|
|
2102
|
+
* const lines: string[] = []
|
|
2103
|
+
* for await (const line of child.lines) lines.push(line)
|
|
2104
|
+
* lines // ['ready', 'done']
|
|
2105
|
+
*
|
|
2106
|
+
* const exit = await child.exit
|
|
2107
|
+
* exit.code // 0
|
|
2108
|
+
* await child.destroy()
|
|
2053
2109
|
* ```
|
|
2054
2110
|
*/
|
|
2055
2111
|
function createProcess(options) {
|
|
2056
2112
|
return new Process(options);
|
|
2057
2113
|
}
|
|
2058
2114
|
/**
|
|
2059
|
-
* Creates one raw byte session over a supervised child process
|
|
2115
|
+
* Creates one raw byte session over a supervised child process and returns it as a
|
|
2116
|
+
* {@link SessionInterface}, so a caller holds the published contract rather than the `Session` class.
|
|
2060
2117
|
*
|
|
2061
2118
|
* @param options - Command, workspace, termination, evidence, stdin, and observation settings
|
|
2062
2119
|
* @returns The launched {@link SessionInterface}
|
|
@@ -2076,7 +2133,9 @@ function createSession(options) {
|
|
|
2076
2133
|
return new Session(options);
|
|
2077
2134
|
}
|
|
2078
2135
|
/**
|
|
2079
|
-
* Creates one keyed registry of supervised child processes
|
|
2136
|
+
* Creates one empty keyed registry of supervised child processes and returns it as a
|
|
2137
|
+
* {@link ProcessManagerInterface}, so a caller holds the published contract rather than the
|
|
2138
|
+
* `ProcessManager` class.
|
|
2080
2139
|
*
|
|
2081
2140
|
* @param options - Initial fleet-level observation hooks and listener-error handling
|
|
2082
2141
|
* @returns The {@link ProcessManagerInterface} registry
|
|
@@ -2092,6 +2151,6 @@ function createProcessManager(options) {
|
|
|
2092
2151
|
return new ProcessManager(options);
|
|
2093
2152
|
}
|
|
2094
2153
|
//#endregion
|
|
2095
|
-
export { Process, ProcessManager, Session, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, captureChunk, createProcess, createProcessManager, createSession, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
|
|
2154
|
+
export { Process, ProcessManager, Session, Supervisor, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, captureChunk, createProcess, createProcessManager, createSession, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
|
|
2096
2155
|
|
|
2097
2156
|
//# sourceMappingURL=index.js.map
|