@muse-code/sdk 1.4.2 → 1.4.4
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/dist/src/connection/connection.d.ts +21 -0
- package/dist/src/connection/connection.js +38 -5
- package/dist/src/connection/spawn.d.ts +28 -1
- package/dist/src/connection/spawn.js +42 -8
- package/dist/src/facade/client.d.ts +9 -0
- package/dist/src/facade/client.js +87 -14
- package/dist/src/facade/gap-fill.js +14 -1
- package/dist/src/facade/host-start.d.ts +62 -0
- package/dist/src/facade/host-start.js +81 -0
- package/dist/src/facade/session.js +1 -0
- package/dist/src/facade/turn-submit.js +3 -0
- package/dist/src/fingerprint.d.ts +1 -1
- package/dist/src/fingerprint.js +1 -1
- package/dist/src/fold/session-fold.d.ts +14 -4
- package/dist/src/fold/session-fold.js +22 -1
- package/dist/src/index.d.ts +2 -0
- package/dist/src/index.js +5 -0
- package/dist/src/msp.d.ts +505 -48
- package/package.json +1 -1
|
@@ -42,6 +42,19 @@ export interface DuplexTransport {
|
|
|
42
42
|
* public `child.close()` — gets the same step 0 (PR #22819 round 4).
|
|
43
43
|
*/
|
|
44
44
|
export declare const submissionTail: unique symbol;
|
|
45
|
+
/**
|
|
46
|
+
* Module-private friend seam, like {@link submissionTail}: a request whose
|
|
47
|
+
* promise also yields the exact response frame it settled on, so a caller
|
|
48
|
+
* that refuses a successful result (the handshake's schema-fingerprint
|
|
49
|
+
* check) can put the whole refused frame on `ProtocolError.line`, the same
|
|
50
|
+
* value every other refusal carries (#50588 review).
|
|
51
|
+
*/
|
|
52
|
+
export declare const requestWithFrame: unique symbol;
|
|
53
|
+
/** What {@link requestWithFrame} resolves with: the result and its wire line. */
|
|
54
|
+
export interface FramedResult {
|
|
55
|
+
readonly result: Record<string, unknown>;
|
|
56
|
+
readonly line: string;
|
|
57
|
+
}
|
|
45
58
|
/**
|
|
46
59
|
* Tuning knobs for a `Connection`. Every option is optional: the defaults
|
|
47
60
|
* suit a spawned host, so most applications never pass this at all.
|
|
@@ -81,6 +94,12 @@ export declare class MspError extends Error {
|
|
|
81
94
|
}
|
|
82
95
|
/** A local framing/correlation violation, never a server-authored MSP error. */
|
|
83
96
|
export declare class ProtocolError extends Error {
|
|
97
|
+
/**
|
|
98
|
+
* The inbound frame (wire line) the violation was detected on, when there
|
|
99
|
+
* is one — the whole line, e.g. the response a pending request refused;
|
|
100
|
+
* an oversized frame is cut to the frame limit. Absent for local state
|
|
101
|
+
* errors (closed connection, EOF) that no frame caused.
|
|
102
|
+
*/
|
|
84
103
|
readonly line: string | undefined;
|
|
85
104
|
constructor(message: string, line?: string);
|
|
86
105
|
}
|
|
@@ -104,6 +123,8 @@ export declare class Connection {
|
|
|
104
123
|
/** See {@link submissionTail}. */
|
|
105
124
|
[submissionTail](): Promise<void>;
|
|
106
125
|
request(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
126
|
+
/** See {@link requestWithFrame}. */
|
|
127
|
+
[requestWithFrame](method: string, params?: Record<string, unknown>): Promise<FramedResult>;
|
|
107
128
|
/**
|
|
108
129
|
* Take one id from THIS connection's single `commandId` minter (INV-013).
|
|
109
130
|
*
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
* stdout's encoding before implementing this interface — is one
|
|
9
9
|
* well-behaved transport, not the general guarantee.
|
|
10
10
|
*/
|
|
11
|
+
import { createHash } from "node:crypto";
|
|
11
12
|
const DEFAULT_FRAME_LIMIT_BYTES = 10_485_760;
|
|
12
13
|
/**
|
|
13
14
|
* Module-private friend seam (never on the package barrel, like spawn.ts's
|
|
@@ -16,6 +17,14 @@ const DEFAULT_FRAME_LIMIT_BYTES = 10_485_760;
|
|
|
16
17
|
* public `child.close()` — gets the same step 0 (PR #22819 round 4).
|
|
17
18
|
*/
|
|
18
19
|
export const submissionTail = Symbol("Connection.submissionTail");
|
|
20
|
+
/**
|
|
21
|
+
* Module-private friend seam, like {@link submissionTail}: a request whose
|
|
22
|
+
* promise also yields the exact response frame it settled on, so a caller
|
|
23
|
+
* that refuses a successful result (the handshake's schema-fingerprint
|
|
24
|
+
* check) can put the whole refused frame on `ProtocolError.line`, the same
|
|
25
|
+
* value every other refusal carries (#50588 review).
|
|
26
|
+
*/
|
|
27
|
+
export const requestWithFrame = Symbol("Connection.requestWithFrame");
|
|
19
28
|
/** The one typed error family consumers branch on (INV-012). */
|
|
20
29
|
export class MspError extends Error {
|
|
21
30
|
code;
|
|
@@ -33,6 +42,12 @@ export class MspError extends Error {
|
|
|
33
42
|
}
|
|
34
43
|
/** A local framing/correlation violation, never a server-authored MSP error. */
|
|
35
44
|
export class ProtocolError extends Error {
|
|
45
|
+
/**
|
|
46
|
+
* The inbound frame (wire line) the violation was detected on, when there
|
|
47
|
+
* is one — the whole line, e.g. the response a pending request refused;
|
|
48
|
+
* an oversized frame is cut to the frame limit. Absent for local state
|
|
49
|
+
* errors (closed connection, EOF) that no frame caused.
|
|
50
|
+
*/
|
|
36
51
|
line;
|
|
37
52
|
constructor(message, line) {
|
|
38
53
|
super(message);
|
|
@@ -77,6 +92,13 @@ function canonical(value) {
|
|
|
77
92
|
}
|
|
78
93
|
return JSON.stringify(value);
|
|
79
94
|
}
|
|
95
|
+
// FR-45137-1: the dedup guards compare fingerprints, so a remembered command
|
|
96
|
+
// costs 64 hex chars no matter how large its payload (or ack) was. The hash
|
|
97
|
+
// guards a correctness check, so it is SHA-256, not a faster non-crypto hash
|
|
98
|
+
// whose collision would silently accept a different payload.
|
|
99
|
+
function fingerprint(canonicalForm) {
|
|
100
|
+
return createHash("sha256").update(canonicalForm, "utf8").digest("hex");
|
|
101
|
+
}
|
|
80
102
|
/** Create the SDK-owned UUIDv7 command-id source for a connection/client. */
|
|
81
103
|
export function createUuidV7Mint() {
|
|
82
104
|
let lastMs = -1;
|
|
@@ -177,6 +199,13 @@ export class Connection {
|
|
|
177
199
|
return this.#submitTail;
|
|
178
200
|
}
|
|
179
201
|
request(method, params) {
|
|
202
|
+
return this.#request(method, params).then((framed) => framed.result);
|
|
203
|
+
}
|
|
204
|
+
/** See {@link requestWithFrame}. */
|
|
205
|
+
[requestWithFrame](method, params) {
|
|
206
|
+
return this.#request(method, params);
|
|
207
|
+
}
|
|
208
|
+
#request(method, params) {
|
|
180
209
|
if (this.#finished)
|
|
181
210
|
return Promise.reject(new ProtocolError("connection is closed"));
|
|
182
211
|
const id = this.#mintRequestId();
|
|
@@ -193,7 +222,10 @@ export class Connection {
|
|
|
193
222
|
...(params === undefined ? {} : { params }),
|
|
194
223
|
};
|
|
195
224
|
return new Promise((resolve, reject) => {
|
|
196
|
-
this.#pending.set(requestKey(id), {
|
|
225
|
+
this.#pending.set(requestKey(id), {
|
|
226
|
+
resolve: (result, line) => resolve({ result, line }),
|
|
227
|
+
reject,
|
|
228
|
+
});
|
|
197
229
|
void this.#write(request).catch((error) => {
|
|
198
230
|
this.#pending.delete(requestKey(id));
|
|
199
231
|
reject(error);
|
|
@@ -241,7 +273,7 @@ export class Connection {
|
|
|
241
273
|
async command(method, params, options) {
|
|
242
274
|
const commandId = options?.commandId ?? this.#mintCommandId();
|
|
243
275
|
const commandParams = { ...params, commandId };
|
|
244
|
-
const signature = canonical({ method, params: commandParams });
|
|
276
|
+
const signature = fingerprint(canonical({ method, params: commandParams }));
|
|
245
277
|
const memory = this.#commands.get(commandId);
|
|
246
278
|
if (memory !== undefined && memory.signature !== signature) {
|
|
247
279
|
throw new ProtocolError(`commandId ${commandId} was reused with a different payload`);
|
|
@@ -261,10 +293,11 @@ export class Connection {
|
|
|
261
293
|
if (ack["commandId"] !== undefined && ack["commandId"] !== commandId) {
|
|
262
294
|
throw new ProtocolError(`${method} ack commandId ${String(ack["commandId"])} did not echo ${commandId}`);
|
|
263
295
|
}
|
|
264
|
-
|
|
296
|
+
const ackFingerprint = fingerprint(canonical(ack));
|
|
297
|
+
if (remembered.ack !== undefined && remembered.ack !== ackFingerprint) {
|
|
265
298
|
throw new ProtocolError(`${method} replay for commandId ${commandId} did not return a value-identical ack`);
|
|
266
299
|
}
|
|
267
|
-
remembered.ack =
|
|
300
|
+
remembered.ack = ackFingerprint;
|
|
268
301
|
return ack;
|
|
269
302
|
}
|
|
270
303
|
catch (error) {
|
|
@@ -475,7 +508,7 @@ export class Connection {
|
|
|
475
508
|
pending.reject(new ProtocolError("response result must be an object", line));
|
|
476
509
|
return;
|
|
477
510
|
}
|
|
478
|
-
pending.resolve(result);
|
|
511
|
+
pending.resolve(result, line);
|
|
479
512
|
return;
|
|
480
513
|
}
|
|
481
514
|
const error = frame["error"];
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
/** Node stdio binding and type-state handshake for the MSP connection. */
|
|
2
|
-
import
|
|
2
|
+
import { spawn } from "node:child_process";
|
|
3
|
+
import type { ChildProcessWithoutNullStreams, SpawnOptionsWithoutStdio } from "node:child_process";
|
|
3
4
|
import type { InitializeParams, InitializeResult } from "../msp.js";
|
|
4
5
|
import { Connection } from "./connection.js";
|
|
5
6
|
import type { ConnectionOptions, DuplexTransport, NotificationHandler, ProtocolErrorHandler, ServerRequestHandler } from "./connection.js";
|
|
@@ -73,9 +74,22 @@ export interface MuseServeChildOptions {
|
|
|
73
74
|
* `0..2147483647`; anything else throws `RangeError` at spawn.
|
|
74
75
|
*/
|
|
75
76
|
readonly shutdownTimeoutMs?: number;
|
|
77
|
+
/**
|
|
78
|
+
* Deterministic-test seam; production always uses `child_process.spawn`.
|
|
79
|
+
* A stub here observes the exact options the call site passes, so a
|
|
80
|
+
* `windowsHide` override at the call site fails the pin (FR-45141-1).
|
|
81
|
+
*/
|
|
82
|
+
readonly spawnFn?: typeof spawn;
|
|
76
83
|
}
|
|
77
84
|
declare const ownedTransport: unique symbol;
|
|
78
85
|
declare const adoptFlushSource: unique symbol;
|
|
86
|
+
/**
|
|
87
|
+
* Module friend seam: did `initialize` get a usable answer before the
|
|
88
|
+
* handshake failed? Exported from this MODULE only (never the package
|
|
89
|
+
* barrel) so the facade can word a host lost AFTER answering truthfully
|
|
90
|
+
* (#49912) without a new public member on `MspHandshake`.
|
|
91
|
+
*/
|
|
92
|
+
export declare const initializeAnswered: unique symbol;
|
|
79
93
|
/**
|
|
80
94
|
* Shutdown deadline contract: `expired` resolves and never rejects; after
|
|
81
95
|
* `clear()` it may remain pending forever.
|
|
@@ -122,6 +136,17 @@ export declare class ChildStdioTransport implements DuplexTransport {
|
|
|
122
136
|
[adoptFlushSource](source: () => Promise<void>): void;
|
|
123
137
|
close(flushed?: Promise<void>): Promise<void>;
|
|
124
138
|
}
|
|
139
|
+
/**
|
|
140
|
+
* The exact options `MuseServeChild.spawn` hands to `child_process.spawn`,
|
|
141
|
+
* factored out so the spawn-options pin can assert on them without spawning.
|
|
142
|
+
* Exported from this MODULE only (never the package barrel) — the same
|
|
143
|
+
* module-only-test-seam precedent as `isBenignCloseRace`.
|
|
144
|
+
*/
|
|
145
|
+
export declare function buildSpawnOptions(options: {
|
|
146
|
+
readonly cwd?: string;
|
|
147
|
+
readonly env?: NodeJS.ProcessEnv;
|
|
148
|
+
readonly detached: boolean;
|
|
149
|
+
}): SpawnOptionsWithoutStdio;
|
|
125
150
|
/** One owned MSP host process with SS2.11 diagnostics and total exit mapping. */
|
|
126
151
|
export declare class MuseServeChild {
|
|
127
152
|
#private;
|
|
@@ -143,6 +168,8 @@ export declare class MspHandshake {
|
|
|
143
168
|
onNotification(handler: NotificationHandler): void;
|
|
144
169
|
onProtocolError(handler: ProtocolErrorHandler): void;
|
|
145
170
|
close(): Promise<ProcessExit>;
|
|
171
|
+
/** See {@link initializeAnswered}. */
|
|
172
|
+
[initializeAnswered](): boolean;
|
|
146
173
|
initialize(params: InitializeParams): Promise<SpawnedMspConnection>;
|
|
147
174
|
}
|
|
148
175
|
/** A fully initialized connection plus its owned process boundary. */
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/** Node stdio binding and type-state handshake for the MSP connection. */
|
|
2
2
|
import { spawn } from "node:child_process";
|
|
3
|
-
import { Connection, ProtocolError, submissionTail, } from "./connection.js";
|
|
3
|
+
import { Connection, ProtocolError, requestWithFrame, submissionTail, } from "./connection.js";
|
|
4
4
|
import { checkServedFingerprint } from "../fingerprint.js";
|
|
5
5
|
const DEFAULT_STDERR_MAX_BYTES = 8 * 1024;
|
|
6
6
|
const DEFAULT_STDERR_MAX_LINES = 100;
|
|
@@ -16,6 +16,13 @@ const SIGTERM_GRACE_MS = 2_000;
|
|
|
16
16
|
const MAX_SHUTDOWN_TIMEOUT_MS = 2_147_483_647;
|
|
17
17
|
const ownedTransport = Symbol("MuseServeChild.transport");
|
|
18
18
|
const adoptFlushSource = Symbol("ChildStdioTransport.adoptFlushSource");
|
|
19
|
+
/**
|
|
20
|
+
* Module friend seam: did `initialize` get a usable answer before the
|
|
21
|
+
* handshake failed? Exported from this MODULE only (never the package
|
|
22
|
+
* barrel) so the facade can word a host lost AFTER answering truthfully
|
|
23
|
+
* (#49912) without a new public member on `MspHandshake`.
|
|
24
|
+
*/
|
|
25
|
+
export const initializeAnswered = Symbol("MspHandshake.initializeAnswered");
|
|
19
26
|
function makeShutdownDeadline(budgetMs) {
|
|
20
27
|
let timer;
|
|
21
28
|
const expired = new Promise((resolve) => {
|
|
@@ -332,6 +339,23 @@ export class ChildStdioTransport {
|
|
|
332
339
|
yield String(chunk);
|
|
333
340
|
}
|
|
334
341
|
}
|
|
342
|
+
/**
|
|
343
|
+
* The exact options `MuseServeChild.spawn` hands to `child_process.spawn`,
|
|
344
|
+
* factored out so the spawn-options pin can assert on them without spawning.
|
|
345
|
+
* Exported from this MODULE only (never the package barrel) — the same
|
|
346
|
+
* module-only-test-seam precedent as `isBenignCloseRace`.
|
|
347
|
+
*/
|
|
348
|
+
export function buildSpawnOptions(options) {
|
|
349
|
+
return {
|
|
350
|
+
...(options.cwd === undefined ? {} : { cwd: options.cwd }),
|
|
351
|
+
...(options.env === undefined ? {} : { env: options.env }),
|
|
352
|
+
detached: options.detached,
|
|
353
|
+
// FR-45141-1: `muse serve` is never meant to be seen. Without this, a
|
|
354
|
+
// Windows host with no console of its own pops a console window for the
|
|
355
|
+
// life of the connection; the flag is a no-op on other platforms.
|
|
356
|
+
windowsHide: true,
|
|
357
|
+
};
|
|
358
|
+
}
|
|
335
359
|
/** One owned MSP host process with SS2.11 diagnostics and total exit mapping. */
|
|
336
360
|
export class MuseServeChild {
|
|
337
361
|
#tail = new StderrTail();
|
|
@@ -360,12 +384,13 @@ export class MuseServeChild {
|
|
|
360
384
|
// PID is a POSIX primitive, and pretending otherwise would fake
|
|
361
385
|
// subtree containment there.
|
|
362
386
|
const ownsProcessGroup = process.platform !== "win32";
|
|
363
|
-
const spawnOptions = {
|
|
364
|
-
|
|
365
|
-
|
|
387
|
+
const spawnOptions = buildSpawnOptions({
|
|
388
|
+
cwd: options.cwd,
|
|
389
|
+
env: options.env,
|
|
366
390
|
detached: ownsProcessGroup,
|
|
367
|
-
};
|
|
368
|
-
|
|
391
|
+
});
|
|
392
|
+
const spawnChild = options.spawnFn ?? spawn;
|
|
393
|
+
return new MuseServeChild(spawnChild(options.museBin, [...(options.args ?? [])], spawnOptions), options.onStderr, options.shutdownTimeoutMs, ownsProcessGroup);
|
|
369
394
|
}
|
|
370
395
|
get stderrTail() {
|
|
371
396
|
return this.#tail.lines();
|
|
@@ -385,6 +410,7 @@ export class MspHandshake {
|
|
|
385
410
|
child;
|
|
386
411
|
#transport;
|
|
387
412
|
#started = false;
|
|
413
|
+
#answered = false;
|
|
388
414
|
constructor(options) {
|
|
389
415
|
this.child = MuseServeChild.spawn({
|
|
390
416
|
museBin: options.command,
|
|
@@ -420,14 +446,22 @@ export class MspHandshake {
|
|
|
420
446
|
await this.#connection.close();
|
|
421
447
|
return await this.#transport.exited;
|
|
422
448
|
}
|
|
449
|
+
/** See {@link initializeAnswered}. */
|
|
450
|
+
[initializeAnswered]() {
|
|
451
|
+
return this.#answered;
|
|
452
|
+
}
|
|
423
453
|
async initialize(params) {
|
|
424
454
|
if (this.#started)
|
|
425
455
|
throw new ProtocolError("initialize may be sent only once per connection");
|
|
426
456
|
this.#started = true;
|
|
427
|
-
const raw = await this.#connection
|
|
457
|
+
const { result: raw, line } = await this.#connection[requestWithFrame]("initialize", params);
|
|
458
|
+
this.#answered = true;
|
|
428
459
|
const result = raw;
|
|
429
460
|
if (typeof result.schema?.fingerprint !== "string") {
|
|
430
|
-
|
|
461
|
+
// The whole refused frame rides on the error, as on every other
|
|
462
|
+
// refusal: a host that answered with an unusable result was not lost,
|
|
463
|
+
// and the facade tells the two apart by it (#49912, #50588 review).
|
|
464
|
+
throw new ProtocolError("initialize result has no schema fingerprint", line);
|
|
431
465
|
}
|
|
432
466
|
const fingerprintWarning = checkServedFingerprint(result.schema.fingerprint);
|
|
433
467
|
this.#connection.notify("initialized");
|
|
@@ -106,6 +106,15 @@ export declare class MuseClient {
|
|
|
106
106
|
* reason this factory exists beside the bare constructor: SS2.13.1 makes the
|
|
107
107
|
* absent/unrecognized distinction load-bearing, and a caller re-deriving it
|
|
108
108
|
* by hand is a caller that can get it wrong.
|
|
109
|
+
*
|
|
110
|
+
* Rejects with {@link MuseHostStartError} when the host is lost before the
|
|
111
|
+
* handshake completes (the binary could not be spawned, or the process
|
|
112
|
+
* ended first — exit code or signal plus the bounded stderr tail;
|
|
113
|
+
* `answeredInitialize` says whether it died after a usable answer). A host
|
|
114
|
+
* that answers with a reply the SDK refuses keeps its own error: an
|
|
115
|
+
* `MspError` for an SS1.6 refusal, or a `ProtocolError` (with the whole
|
|
116
|
+
* refused frame on `line`) for a reply the SDK cannot use, such as one with
|
|
117
|
+
* no schema fingerprint.
|
|
109
118
|
*/
|
|
110
119
|
static spawn(options: MuseClientSpawnOptions): Promise<MuseClient>;
|
|
111
120
|
/**
|
|
@@ -35,10 +35,12 @@
|
|
|
35
35
|
* chain close that gap — add a member upstream and the BUILD fails here until
|
|
36
36
|
* it is forwarded (or explicitly allow-listed as unforwardable).
|
|
37
37
|
*/
|
|
38
|
-
import { spawnMspConnection } from "../connection/spawn.js";
|
|
38
|
+
import { initializeAnswered, spawnMspConnection } from "../connection/spawn.js";
|
|
39
39
|
import { MuseSessionDiscardedError } from "../errors.js";
|
|
40
40
|
import { DiscardedSessions } from "./discarded.js";
|
|
41
41
|
import { isAbnormalHostDeath, readSessionDurability } from "./host-death.js";
|
|
42
|
+
import { MspError, ProtocolError } from "../connection/connection.js";
|
|
43
|
+
import { hostStartFailure } from "./host-start.js";
|
|
42
44
|
import { Session } from "./session.js";
|
|
43
45
|
/**
|
|
44
46
|
* Every `StartParams` member `startSession` forwards. `config` is temporarily
|
|
@@ -72,6 +74,15 @@ export class MuseClient {
|
|
|
72
74
|
#discarded;
|
|
73
75
|
/** Sessions this client opened, so one death notification reaches them all. */
|
|
74
76
|
#sessions = new Set();
|
|
77
|
+
/**
|
|
78
|
+
* Frames naming a session this client has not registered YET, held only
|
|
79
|
+
* while a `session/start`/`session/resume` is in flight (#49790): the host
|
|
80
|
+
* flushes the resume replay BEFORE the result, and the promise awaiting that
|
|
81
|
+
* result resumes only after the whole chunk has been routed. `#route` holds,
|
|
82
|
+
* `#openSession` drains, `#open` clears when the last open settles.
|
|
83
|
+
*/
|
|
84
|
+
#held = new Map();
|
|
85
|
+
#opening = 0;
|
|
75
86
|
/** The spawned host, when `spawn` built this client. */
|
|
76
87
|
#child;
|
|
77
88
|
#initializeResult;
|
|
@@ -113,16 +124,29 @@ export class MuseClient {
|
|
|
113
124
|
* session: `Session.apply` already tolerates unknown methods, but only the
|
|
114
125
|
* frames that name a `sessionId` have an owner to route to. A frame naming
|
|
115
126
|
* an UNKNOWN session is dropped for the same reason — routing it anywhere
|
|
116
|
-
* would trip the foreign-frame throw on a session it does not belong to
|
|
127
|
+
* would trip the foreign-frame throw on a session it does not belong to —
|
|
128
|
+
* UNLESS an open is in flight, when it may be that open's own session named
|
|
129
|
+
* by the server before the awaiting promise has run (#49790): then it is
|
|
130
|
+
* held for `#openSession` to fold, or for `#open` to clear.
|
|
117
131
|
*/
|
|
118
132
|
#route(notification) {
|
|
119
133
|
const named = notification.params?.sessionId;
|
|
120
134
|
if (typeof named !== "string")
|
|
121
135
|
return;
|
|
136
|
+
let delivered = false;
|
|
122
137
|
for (const session of this.#sessions) {
|
|
123
|
-
if (session.sessionId === named)
|
|
138
|
+
if (session.sessionId === named) {
|
|
124
139
|
session.apply(notification);
|
|
140
|
+
delivered = true;
|
|
141
|
+
}
|
|
125
142
|
}
|
|
143
|
+
if (delivered || this.#opening === 0)
|
|
144
|
+
return;
|
|
145
|
+
const held = this.#held.get(named);
|
|
146
|
+
if (held === undefined)
|
|
147
|
+
this.#held.set(named, [notification]);
|
|
148
|
+
else
|
|
149
|
+
held.push(notification);
|
|
126
150
|
}
|
|
127
151
|
/**
|
|
128
152
|
* Spawn an owned host, run the SS1.4 handshake, and hand back a client whose
|
|
@@ -132,6 +156,15 @@ export class MuseClient {
|
|
|
132
156
|
* reason this factory exists beside the bare constructor: SS2.13.1 makes the
|
|
133
157
|
* absent/unrecognized distinction load-bearing, and a caller re-deriving it
|
|
134
158
|
* by hand is a caller that can get it wrong.
|
|
159
|
+
*
|
|
160
|
+
* Rejects with {@link MuseHostStartError} when the host is lost before the
|
|
161
|
+
* handshake completes (the binary could not be spawned, or the process
|
|
162
|
+
* ended first — exit code or signal plus the bounded stderr tail;
|
|
163
|
+
* `answeredInitialize` says whether it died after a usable answer). A host
|
|
164
|
+
* that answers with a reply the SDK refuses keeps its own error: an
|
|
165
|
+
* `MspError` for an SS1.6 refusal, or a `ProtocolError` (with the whole
|
|
166
|
+
* refused frame on `line`) for a reply the SDK cannot use, such as one with
|
|
167
|
+
* no schema fingerprint.
|
|
135
168
|
*/
|
|
136
169
|
static async spawn(options) {
|
|
137
170
|
const handshake = spawnMspConnection({
|
|
@@ -154,7 +187,23 @@ export class MuseClient {
|
|
|
154
187
|
catch (error) {
|
|
155
188
|
// A failed handshake must not leak the process it already spawned.
|
|
156
189
|
await handshake.close().catch(() => undefined);
|
|
157
|
-
|
|
190
|
+
// A host that ANSWERED `initialize` is not a lost host, however it ends
|
|
191
|
+
// once we close it: its answer is the actionable error. "Answered" is
|
|
192
|
+
// evidence that a response frame came back — an SS1.6 `MspError`, or a
|
|
193
|
+
// `ProtocolError` carrying the frame the SDK refused (a malformed or
|
|
194
|
+
// version-skewed reply) — never the error's class alone (#49912).
|
|
195
|
+
// Decided before the exit is read, so our own close ladder can never
|
|
196
|
+
// dress an answer up as a death.
|
|
197
|
+
const answered = error instanceof MspError || (error instanceof ProtocolError && error.line !== undefined);
|
|
198
|
+
if (answered)
|
|
199
|
+
throw error;
|
|
200
|
+
// No refused frame: the host was lost — before answering, or after a
|
|
201
|
+
// usable answer while we sent `initialized` (the error then says so).
|
|
202
|
+
// close() ended at its observed exit (or its spawn failure), so the
|
|
203
|
+
// evidence is settled: the typed error carries the spawn error or the
|
|
204
|
+
// SS2.11 row plus the stderr tail instead of the transport's first
|
|
205
|
+
// symptom (#49791, #49912).
|
|
206
|
+
throw await hostStartFailure(handshake.child, error, handshake[initializeAnswered]());
|
|
158
207
|
}
|
|
159
208
|
return new MuseClient(spawned.connection, {
|
|
160
209
|
durability: readSessionDurability(spawned.initializeResult),
|
|
@@ -203,15 +252,13 @@ export class MuseClient {
|
|
|
203
252
|
params.workspaceRoots = options.workspaceRoots;
|
|
204
253
|
if (options.modelId != null)
|
|
205
254
|
params.modelId = options.modelId;
|
|
206
|
-
const raw = await this.#connection.command("session/start", params);
|
|
207
|
-
const result = raw;
|
|
208
255
|
// Keyed by the id the SERVER named, never the one the caller asked for:
|
|
209
256
|
// `sessionId` is a REQUEST on start, and a session keyed by a hopeful id
|
|
210
257
|
// would reject every one of its own events as foreign.
|
|
211
|
-
return this.#
|
|
212
|
-
result,
|
|
258
|
+
return this.#open("session/start", params, (raw) => ({
|
|
259
|
+
result: raw,
|
|
213
260
|
verb: "session/start",
|
|
214
|
-
});
|
|
261
|
+
}));
|
|
215
262
|
}
|
|
216
263
|
/**
|
|
217
264
|
* Load an existing session and subscribe this connection to its view
|
|
@@ -231,12 +278,10 @@ export class MuseClient {
|
|
|
231
278
|
params.excludeItems = options.excludeItems;
|
|
232
279
|
if (options.history != null)
|
|
233
280
|
params.history = options.history;
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
return this.#openSession(result.session.sessionId, {
|
|
237
|
-
result,
|
|
281
|
+
return this.#open("session/resume", params, (raw) => ({
|
|
282
|
+
result: raw,
|
|
238
283
|
verb: "session/resume",
|
|
239
|
-
});
|
|
284
|
+
}));
|
|
240
285
|
}
|
|
241
286
|
/**
|
|
242
287
|
* Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
|
|
@@ -265,6 +310,25 @@ export class MuseClient {
|
|
|
265
310
|
}
|
|
266
311
|
await this.#connection.close();
|
|
267
312
|
}
|
|
313
|
+
/**
|
|
314
|
+
* The window `#route` holds unknown-session frames for: from the request to
|
|
315
|
+
* the Session's registration. Counted, not flagged, so two concurrent opens
|
|
316
|
+
* keep it open until the LAST settles; cleared on settle so a frame that
|
|
317
|
+
* named no session this client opened is held no longer than the open it
|
|
318
|
+
* rode in with (#49790).
|
|
319
|
+
*/
|
|
320
|
+
async #open(verb, params, opening) {
|
|
321
|
+
this.#opening += 1;
|
|
322
|
+
try {
|
|
323
|
+
const opened = opening(await this.#connection.command(verb, params));
|
|
324
|
+
return this.#openSession(opened.result.session.sessionId, opened);
|
|
325
|
+
}
|
|
326
|
+
finally {
|
|
327
|
+
this.#opening -= 1;
|
|
328
|
+
if (this.#opening === 0)
|
|
329
|
+
this.#held.clear();
|
|
330
|
+
}
|
|
331
|
+
}
|
|
268
332
|
#openSession(sessionId, opening) {
|
|
269
333
|
const session = new Session({
|
|
270
334
|
connection: this.#connection,
|
|
@@ -274,6 +338,15 @@ export class MuseClient {
|
|
|
274
338
|
sessionId,
|
|
275
339
|
});
|
|
276
340
|
this.#sessions.add(session);
|
|
341
|
+
// The frames that named this session while its verb was in flight fold
|
|
342
|
+
// NOW, in arrival order — synchronously, so nothing the pump routes next
|
|
343
|
+
// can overtake them.
|
|
344
|
+
const held = this.#held.get(sessionId);
|
|
345
|
+
if (held !== undefined) {
|
|
346
|
+
this.#held.delete(sessionId);
|
|
347
|
+
for (const frame of held)
|
|
348
|
+
session.apply(frame);
|
|
349
|
+
}
|
|
277
350
|
return session;
|
|
278
351
|
}
|
|
279
352
|
#assertReattachAllowed(sessionId) {
|
|
@@ -208,9 +208,13 @@ export class GapFiller {
|
|
|
208
208
|
return;
|
|
209
209
|
const result = await this.#page(connection, this.#cursor);
|
|
210
210
|
let reached = false;
|
|
211
|
+
// The last cursor this page served, skipped events included — where a
|
|
212
|
+
// walk toward an extended target resumes after an end-of-view page.
|
|
213
|
+
let lastServed;
|
|
211
214
|
for (const event of result.events) {
|
|
212
215
|
this.#requireOwnSession(event, after, target);
|
|
213
216
|
const cursor = event.params.viewCursor;
|
|
217
|
+
lastServed = cursor;
|
|
214
218
|
// An EARLIER fill already served — and applied — this durable event.
|
|
215
219
|
// A later walk may legally page through the same range, and re-applying
|
|
216
220
|
// it here is the same double fold the discard exists to prevent (PR
|
|
@@ -243,8 +247,17 @@ export class GapFiller {
|
|
|
243
247
|
// The server's own end of the view. `next` names a LIVE cursor and
|
|
244
248
|
// `view/page` serves durable-sourced events only (tdd SS4.7.3), so a
|
|
245
249
|
// hole whose tail was ephemeral ends here and never at `target`.
|
|
246
|
-
|
|
250
|
+
//
|
|
251
|
+
// The cursor still advances to the last event served (#50252, the Rust
|
|
252
|
+
// SDK's INV-002 rule from #49869): if a `view/gap` extended the target
|
|
253
|
+
// while this page was in flight, `#walk` comes back here toward the new
|
|
254
|
+
// one, and re-asking from where this walk started would re-serve — and
|
|
255
|
+
// fold a second time — every event this page just delivered.
|
|
256
|
+
if (result.nextCursor === null) {
|
|
257
|
+
if (lastServed !== undefined)
|
|
258
|
+
this.#cursor = lastServed;
|
|
247
259
|
return;
|
|
260
|
+
}
|
|
248
261
|
// PROGRESS is the only bound on this walk, and it has to be, because a
|
|
249
262
|
// legitimate fill is unbounded in length: an attempt cap would silently
|
|
250
263
|
// truncate one. A page that carries no event, repeats the cursor it was
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The typed failure of `MuseClient.spawn` when the host is lost before the
|
|
3
|
+
* SS1.4 handshake completes (#49791).
|
|
4
|
+
*
|
|
5
|
+
* Without it the rejection is whatever the transport saw first — `write
|
|
6
|
+
* EPIPE` on the first frame, or `connection reached EOF` — while the evidence
|
|
7
|
+
* that explains it (Node's spawn error, or the SS2.11 exit row with its
|
|
8
|
+
* bounded stderr tail) sits unread on the child the facade already owns.
|
|
9
|
+
* Spec 14990 Scenario 4 attaches that evidence to every process-exit error;
|
|
10
|
+
* this module is the handshake-failure arm of that rule.
|
|
11
|
+
*/
|
|
12
|
+
import type { ExitClassification, MuseServeChild } from "../connection/spawn.js";
|
|
13
|
+
/**
|
|
14
|
+
* How the host was lost. Two arms because the repair differs: `spawnFailed`
|
|
15
|
+
* means no process ever ran (`error` is Node's own spawn error — `code`
|
|
16
|
+
* `ENOENT`, `EACCES`, … — so fix the path or its permissions); `hostExited`
|
|
17
|
+
* means a process ran and ended before the handshake completed, and `exit` is
|
|
18
|
+
* its SS2.11 row — any row, the clean one included: a host that wrote its
|
|
19
|
+
* complaint to stderr and exited 0 before its first frame is still a lost
|
|
20
|
+
* host, and the row says only how it ended. `answeredInitialize` says whether
|
|
21
|
+
* it got as far as a usable `initialize` answer before dying (then the loss
|
|
22
|
+
* came while the SDK was completing the handshake, not at startup).
|
|
23
|
+
*/
|
|
24
|
+
export type HostStartFailure = {
|
|
25
|
+
readonly kind: "spawnFailed";
|
|
26
|
+
readonly error: NodeJS.ErrnoException;
|
|
27
|
+
} | {
|
|
28
|
+
readonly kind: "hostExited";
|
|
29
|
+
readonly exit: ExitClassification;
|
|
30
|
+
readonly answeredInitialize: boolean;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* `MuseClient.spawn` lost its host before the handshake completed.
|
|
34
|
+
*
|
|
35
|
+
* Typed rather than a bare `Error` because the two arms of `failure` name
|
|
36
|
+
* STATES an embedder branches on (retry after fixing the path, versus act on
|
|
37
|
+
* an SS2.11 retry posture). The transport error that first surfaced the loss
|
|
38
|
+
* rides as `cause`, so nothing the old rejection carried is dropped.
|
|
39
|
+
*/
|
|
40
|
+
export declare class MuseHostStartError extends Error {
|
|
41
|
+
readonly failure: HostStartFailure;
|
|
42
|
+
/**
|
|
43
|
+
* The SDK's bounded stderr tail when the host was lost, one accessor
|
|
44
|
+
* regardless of arm: empty when no process ran, and the only place the
|
|
45
|
+
* evidence lives when the row is `cleanShutdown` (SS2.11 keeps no tail on
|
|
46
|
+
* the clean row; a logger wants the lines either way).
|
|
47
|
+
*/
|
|
48
|
+
readonly stderrTail: readonly string[];
|
|
49
|
+
constructor(failure: HostStartFailure, stderrTail: readonly string[], cause: unknown);
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Read a lost host's evidence into the typed error. "Lost" is decided by
|
|
53
|
+
* whether the host ANSWERED — whether a response frame came back — never by
|
|
54
|
+
* how it ended: the caller keeps an answer's own error (`MspError`, or a
|
|
55
|
+
* `ProtocolError` carrying the refused frame) and routes only frameless
|
|
56
|
+
* failures here, where the row says how the unanswering host ended.
|
|
57
|
+
*
|
|
58
|
+
* Call only after the handshake's `close()` has settled: the close ladder
|
|
59
|
+
* ends at the child's observed exit (or at its spawn failure), so
|
|
60
|
+
* `child.exit` is already settled here and this never waits on a live host.
|
|
61
|
+
*/
|
|
62
|
+
export declare function hostStartFailure(child: MuseServeChild, cause: unknown, answeredInitialize: boolean): Promise<MuseHostStartError>;
|