// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. // See LICENSE in the project root for license information. import type { Readable } from 'node:stream'; import { DAEMON_INPUT_LIFECYCLE_PROTOCOL_MINOR, DAEMON_INVOCATION_KIND_PROTOCOL_MINOR, DAEMON_KEEPALIVE_PROTOCOL_MINOR, DAEMON_LIFECYCLE_PROTOCOL_MINOR, DAEMON_PROTOCOL_VERSION, DAEMON_REQUEST_LIFECYCLE_PROTOCOL_MINOR, DAEMON_REQUEST_STARTED_PROTOCOL_MINOR, DAEMON_WORKSPACE_RESTART_PROTOCOL_MINOR, DaemonFrameType, DaemonProtocolError, decodeDaemonControlMessage, decodeDaemonEventFrame, decodeDaemonLogChunk, encodeDaemonControlMessage, encodeDaemonStdinChunk, type DaemonControlMessage, type DaemonRestartReason, type IDaemonClientCaps, type IDaemonCommandResult, type IDaemonContinuingOperations, type IDaemonEventEnvelope, type IDaemonFrame, type IDaemonNativeLockHolder, type IDaemonPongMessage, type IDaemonProtocolVersion, type IDaemonRequestEnvelope, type IDaemonRequestRejectedMessage, type IDaemonShutdownAckMessage } from '@rushstack/rush-daemon-protocol'; import { connectDaemonAsync, type DaemonFrameConnection } from '@rushstack/rush-daemon-transport'; import { DAEMON_DISCONNECTED_MESSAGE, DaemonClientError } from './DaemonClientError'; import { adaptDaemonRequestToPeer } from './DaemonRequestEnvironment'; const MAX_STDIN_CHUNK_BYTES: number = 64 * 1024; const DEFAULT_PING_AFTER_MS: number = 10_000; const DEFAULT_UNRESPONSIVE_AFTER_MS: number = 30_000; /** The liveness check looks at least this often, so that it reports a silent daemon at most this late. */ const MAX_LIVENESS_CHECK_INTERVAL_MS: number = 1000; /** Options for a fresh connection; readiness includes both hello and ping. @beta */ export interface IDaemonClientConnectOptions { readonly socketPath: string; readonly capabilities?: IDaemonClientCaps; readonly expectedDaemonVersion?: string; /** Deadline for connection and handshake, in milliseconds. Defaults to 5000. */ readonly timeoutMs?: number; /** * Asks the daemon to leave its warm set out of the reply that proves the connection ready, which * {@link DaemonClient.status} returns. The warm set names every retained, protected and watched project, so a * client that doesn't report it should set this. Older daemons send it anyway. Defaults to false. The pings of * the liveness check always ask to leave it out; see {@link IDaemonClientLivenessOptions}. */ readonly omitWarmSetStatus?: boolean; } /** * What a request that waits for a daemon restart waits for, as its queue position reports it. Older daemons omit * these fields. * * @beta */ export interface IDaemonRestartWaitDetails { /** * How many of the requests that the queue position counts run a rushx script. Without a restart reason, the * request waits for that many running rushx scripts to exit before it runs, because it restarts the daemon once * it ends (a native `install` or `update`), which would end them. */ readonly scriptCount?: number; /** The request, a rushx script, waits for another request's restart rather than its own. */ readonly restartsForAnotherRequest?: boolean; } /** One request's backpressured destinations. Callback order is wire order. @beta */ export interface IDaemonClientExecuteOptions { readonly request: IDaemonRequestEnvelope; readonly onStdoutAsync?: (bytes: Uint8Array, operationId: string) => Promise; readonly onStderrAsync?: (bytes: Uint8Array, operationId: string) => Promise; readonly onEventAsync?: (event: IDaemonEventEnvelope) => Promise; /** * Called with the request's one-based queue position whenever it changes, or when the daemon reports it again * because what the request waits for changed. `restartReason` is set while the request waits for a daemon restart * for that reason, and `restartWait` then says more about the wait. Without one, `restartWait.scriptCount` is set * while the request waits for rushx scripts to exit, since it restarts the daemon once it ends. */ readonly onQueuePositionAsync?: ( position: number, restartReason?: DaemonRestartReason, restartWait?: IDaemonRestartWaitDetails, /** * Set while the request waits for a Rush process that the daemon does not run to release the repository's lock, * with what the daemon knows about that process. */ nativeLockHolder?: IDaemonNativeLockHolder, /** * Set while the request waits only for the operations that an earlier failed command left running after its * early result, with their count and up to three of their names, in name order. */ continuingOperations?: IDaemonContinuingOperations ) => Promise; /** * Called once, when the daemon first admits the request's input. For a rushx script, that is when the script * starts. Only daemons that negotiate the input lifecycle admit input. */ readonly onInputAdmittedAsync?: () => Promise; readonly abortSignal?: AbortSignal; /** Protocol 0.7 input waits for stdinReady credits; older peers use the legacy raw-mode/terminal policy. */ readonly stdin?: Readable; /** Requires negotiated stdin admission and EOF; older peers fall back before requestStart or input consumption. */ readonly requiresStdinEnd?: boolean; readonly setRawMode?: (enabled: boolean) => void; readonly initialRawMode?: boolean; /** Treat a raw Ctrl+C byte as request cancellation. Defaults to false, preserving arbitrary input bytes. */ readonly cancelOnCtrlC?: boolean; /** Time allowed to finish cancellation. Defaults to 5000 milliseconds. */ readonly cancellationTimeoutMs?: number; /** * Called once, synchronously, when the client asks the daemon to cancel the request: after `abortSignal` aborts, * or on a raw Ctrl+C with `cancelOnCtrlC`. The daemon then has `timeoutMs` to deliver its final result; after * that, the client disconnects without it. Not called for a request that was never sent. */ readonly onCancelRequested?: (timeoutMs: number) => void; /** * Checks that the daemon still responds while the request runs. Daemons older than protocol 0.13 are not * checked. The check stops when the client asks the daemon to cancel the request. */ readonly liveness?: IDaemonClientLivenessOptions; } /** * How long a daemon has sent nothing to a request's connection. * * @beta */ export interface IDaemonSilence { /** The daemon's process ID, when it reported one. */ readonly pid: number | undefined; /** How long the daemon has sent nothing, in milliseconds. */ readonly silentForMs: number; } /** * A check that the daemon still responds while a request runs. Once the daemon has sent nothing for `pingAfterMs`, * the client pings it, with one ping at a time, and asks it to leave the warm set out of the reply. Only time in * which the client could read what the daemon sent counts: not time spent in the client's own callbacks, and not * time in which the client's event loop stalled, for example while its process was stopped. * * @beta */ export interface IDaemonClientLivenessOptions { /** Defaults to 10000 milliseconds. */ readonly pingAfterMs?: number; /** Defaults to 30000 milliseconds. */ readonly unresponsiveAfterMs?: number; /** Called once the daemon has sent nothing, not even the reply to a ping, for `unresponsiveAfterMs`. */ readonly onUnresponsive: (silence: IDaemonSilence) => void; /** Called when the daemon sends something after `onUnresponsive`, with how long it had sent nothing. */ readonly onResponsive?: (silence: IDaemonSilence) => void; } /** A running liveness check; see {@link IDaemonClientLivenessOptions}. */ interface ILivenessCheck { readonly options: IDaemonClientLivenessOptions; readonly pingAfterMs: number; readonly unresponsiveAfterMs: number; readonly intervalMs: number; /** When the check last ran, as a `performance.now()` value. */ lastCheckAtMs: number; } /** Only explicit, pre-execution rejections permit in-process fallback. @beta */ export type DaemonClientOutcome = | { readonly kind: 'result'; readonly result: IDaemonCommandResult } | { readonly kind: 'fallback'; readonly reason: | 'unsupported' | 'controllingTerminalRequired' | 'stdinEndUnsupported' | 'restartRetriesExhausted'; readonly message?: string; } | { readonly kind: 'rejected'; readonly rejection: IDaemonRequestRejectedMessage['payload'] }; interface IDeferred { readonly promise: Promise; readonly resolve: (value: T) => void; readonly reject: (error: Error) => void; } function deferred(): IDeferred { let resolveDeferred!: (value: T) => void; let rejectDeferred!: (error: Error) => void; const promise: Promise = new Promise((resolve, reject) => { resolveDeferred = resolve; rejectDeferred = reject; }); return { promise, resolve: resolveDeferred, reject: rejectDeferred }; } /** * A single-invocation client. Always closes after execution; request IDs are never recycled. * @remarks No command parsing, process-global environment changes, or terminal rendering occurs here. * @beta */ export class DaemonClient { readonly #connection: DaemonFrameConnection; readonly #ready: IDeferred = deferred(); readonly #connectOptions: IDaemonClientConnectOptions; #peerProtocolVersion: IDaemonProtocolVersion | undefined; #used: boolean = false; #result: IDeferred | undefined; #shutdown: IDeferred | undefined; #shutdownAcknowledged: boolean = false; #shutdownAck: IDaemonShutdownAckMessage['payload'] = {}; #execution: IDaemonClientExecuteOptions | undefined; #finished: boolean = false; #inputStarted: boolean = false; #inputAdmitted: boolean = false; #observedExecution: boolean = false; #inputEnded: boolean = false; #supportsInputLifecycle: boolean = false; #supportsRequestStarted: boolean = false; #queued: boolean = false; #requestStarted: boolean = false; /** Whether the connection closed before the client read everything that the daemon sent. */ #closedBeforeReadingAll: boolean = false; #inputAcknowledgement: IDeferred | undefined; #inputTail: Promise = Promise.resolve(); #rawModeChanged: boolean = false; #sendTail: Promise = Promise.resolve(); #cancelTimer: ReturnType | undefined; #cancelSent: boolean = false; #wasInputPaused: boolean = true; #daemonPid: number | undefined; /** When the client last received a frame, or finished handling one, as a `performance.now()` value. */ #lastHeardAtMs: number = 0; #frameInFlight: boolean = false; /** The handling of the last frame that the transport handed over. */ #frameHandled: Promise = Promise.resolve(); #livenessTimer: ReturnType | undefined; #pingPending: boolean = false; #silenceReported: boolean = false; private constructor(connection: DaemonFrameConnection, options: IDaemonClientConnectOptions) { this.#connection = connection; this.#connectOptions = options; connection.onFrame((frame) => (this.#frameHandled = this.#receiveFrameAsync(frame))); connection.onClosed((error) => { if (this.#shutdown && this.#shutdownAcknowledged && !error) { this.#shutdown.resolve(undefined); return; } const lost: Error = error ?? new DaemonClientError( 'disconnected', this.#shutdown ? 'Daemon disconnected before acknowledging shutdown.' : DAEMON_DISCONNECTED_MESSAGE ); // A frame that the close discarded may have said that the request left the queue. this.#closedBeforeReadingAll = !connection.closedAfterReadingAll; if (!this.queuedWithoutStarting) { this.#fail(lost); return; } // A frame that arrived before the close may still say that the request left the queue. void this.#settleReceivedFramesAsync().then(() => this.#fail(lost)); }); } public static async connectAsync(options: IDaemonClientConnectOptions): Promise { const timeoutMs: number = options.timeoutMs ?? 5000; validateTimeout(timeoutMs); const started: number = Date.now(); const connection: DaemonFrameConnection = await connectDaemonAsync(options.socketPath, { connectTimeoutMs: timeoutMs }); const client: DaemonClient = new DaemonClient(connection, options); const timer: ReturnType = setTimeout( () => { connection.abort( new DaemonClientError( 'timeout', `Daemon at ${options.socketPath} did not complete hello/ping readiness within ${timeoutMs}ms.` ) ); }, Math.max(1, timeoutMs - (Date.now() - started)) ); try { // Observe readiness before a send failure can reject it. await Promise.all([ client.#ready.promise, client.#sendControlAsync({ kind: 'hello', payload: { protocolVersion: DAEMON_PROTOCOL_VERSION } }) ]); return client; } catch (error) { await client.closeAsync(); throw error; } finally { clearTimeout(timer); } } /** * The reply that proved this connection ready. It has no `workspace.warmSet` when the connection set * {@link IDaemonClientConnectOptions.omitWarmSetStatus} and the daemon supports it. */ public get status(): Promise { return this.#ready.promise; } /** The common protocol version established by hello. */ public get protocolVersion(): IDaemonProtocolVersion { return this.#peerProtocolVersion!; } /** * Whether the request waited in the daemon's queue and is known not to have started: the daemon reported a queue * position and says when it starts a request (protocol 0.14), but has not said so, no output, event, terminal * control or stdin admission arrived, and the client did not ask it to cancel. If the daemon exits then, the * request has not run. Once the connection has closed, this is also false unless the client read everything * that the daemon sent (see `DaemonFrameConnection.closedAfterReadingAll`), because a frame that the close * discarded may have said that the request started. */ public get queuedWithoutStarting(): boolean { return ( this.#supportsRequestStarted && this.#queued && !this.#requestStarted && !this.#observedExecution && !this.#inputAdmitted && !this.#inputStarted && !this.#rawModeChanged && !this.#cancelSent && !this.#closedBeforeReadingAll ); } /** * Requests shutdown on a fresh connection and waits for acknowledgement followed by EOF. * @remarks This confirms acceptance and connection closure, not successful workspace cleanup. * Requires protocol 0.6. The timeout defaults to 15000 milliseconds. * @returns The acknowledgement, including the number of running requests the shutdown aborts when the * daemon reports it. */ public async shutdownAsync(timeoutMs: number = 15000): Promise { if (this.#used) throw new Error('Create a fresh DaemonClient for shutdown.'); this.#used = true; let timer: ReturnType | undefined; try { validateTimeout(timeoutMs); if (this.protocolVersion.minor < DAEMON_LIFECYCLE_PROTOCOL_MINOR) { throw new DaemonClientError('versionMismatch', 'Daemon shutdown requires protocol 0.6 or newer.'); } this.#shutdown = deferred(); timer = setTimeout(() => { this.#connection.abort( new DaemonClientError( 'timeout', 'Timed out waiting for shutdown acknowledgement and EOF; no PID was signaled.' ) ); }, timeoutMs); await Promise.all([this.#shutdown.promise, this.#sendControlAsync({ kind: 'shutdown', payload: {} })]); return this.#shutdownAck; } finally { clearTimeout(timer); await this.closeAsync(); } } /** Executes once, relays the result after output drains, and restores terminal state on every exit. */ public async executeAsync(options: IDaemonClientExecuteOptions): Promise { if (this.#used) throw new Error('Create a fresh DaemonClient for each invocation.'); this.#used = true; this.#execution = options; const cancel = (): void => this.#cancel(); options.abortSignal?.addEventListener('abort', cancel, { once: true }); try { validateTimeout(options.cancellationTimeoutMs ?? 5000); validateTimeout(options.liveness?.pingAfterMs ?? DEFAULT_PING_AFTER_MS); validateTimeout(options.liveness?.unresponsiveAfterMs ?? DEFAULT_UNRESPONSIVE_AFTER_MS); if (options.stdin?.readableEncoding) { throw new Error('Daemon stdin must supply raw bytes; do not use setEncoding().'); } if (options.requiresStdinEnd && (!options.stdin || !options.request.terminal.acceptsStdin)) { throw new Error('requiresStdinEnd requires a stdin source and an input-capable request.'); } if (options.abortSignal?.aborted) { return { kind: 'result', result: { requestId: options.request.requestId, exitCode: 130, outcome: 'aborted', aborted: true } }; } if (options.requiresStdinEnd && !this.#supportsInputLifecycle) { return { kind: 'fallback', reason: 'stdinEndUnsupported', message: 'The daemon does not support stdin admission and EOF; no request was sent.' }; } if ( options.request.invocationKind === 'rushx' && this.protocolVersion.minor < DAEMON_INVOCATION_KIND_PROTOCOL_MINOR ) { return { kind: 'fallback', reason: 'unsupported', message: 'The daemon does not support explicit Rushx invocations; no request was sent.' }; } if ( options.request.invocationKind !== 'rushx' && options.request.commandOrigin === 'built-in' && ['install', 'update'].includes(options.request.commandName) && this.protocolVersion.minor < DAEMON_WORKSPACE_RESTART_PROTOCOL_MINOR ) { return { kind: 'fallback', reason: 'unsupported', message: 'The daemon does not support native mutation handoff; no request was sent.' }; } this.#result = deferred(); this.#startLivenessCheck(options.liveness); await Promise.all([ this.#sendControlAsync({ kind: 'requestStart', payload: adaptDaemonRequestToPeer(options.request, this.protocolVersion, process.platform) }), this.#result.promise ]); return await this.#result.promise; } finally { this.#finished = true; this.#stopLivenessCheck(); clearTimeout(this.#cancelTimer); options.abortSignal?.removeEventListener('abort', cancel); this.#stopInput(); try { if (this.#rawModeChanged) options.setRawMode?.(options.initialRawMode ?? false); } finally { await this.closeAsync(); } } } public async closeAsync(): Promise { await this.#connection.closeAsync(); } #cancel(): void { if (this.#cancelSent || this.#finished || !this.#execution) return; this.#cancelSent = true; this.#stopLivenessCheck(); this.#stopInput(); const timeoutMs: number = this.#execution.cancellationTimeoutMs ?? 5000; this.#cancelTimer = setTimeout(() => { this.#connection.abort( new DaemonClientError( 'timeout', 'Daemon did not finish cancellation; disconnected without retrying the command.' ) ); }, timeoutMs); void this.#sendControlAsync({ kind: 'requestCancel', payload: { requestId: this.#execution.request.requestId } }).catch((error: Error) => this.#fail(error)); this.#execution.onCancelRequested?.(timeoutMs); } /** Handles a frame; while it does, the client reads nothing more, so the daemon's silence is not measured. */ async #receiveFrameAsync(frame: IDaemonFrame): Promise { const nowMs: number = performance.now(); if (this.#silenceReported) { this.#silenceReported = false; this.#execution?.liveness?.onResponsive?.({ pid: this.#daemonPid, silentForMs: nowMs - this.#lastHeardAtMs }); } this.#frameInFlight = true; try { await this.#onFrameAsync(frame); } finally { this.#frameInFlight = false; this.#lastHeardAtMs = performance.now(); } } /** * Waits until the client has handled the frames that it received before its connection closed, or until one of * them shows that the request left the queue. The transport hands decoded frames over without waiting for I/O, so * once no frame is in flight after a turn of the event loop, none is left. */ async #settleReceivedFramesAsync(): Promise { while (this.queuedWithoutStarting) { if (this.#frameInFlight) { await this.#frameHandled.catch(() => undefined); } else { await new Promise((resolve) => setImmediate(resolve)); if (!this.#frameInFlight) return; } } } #startLivenessCheck(options: IDaemonClientLivenessOptions | undefined): void { if (!options || this.protocolVersion.minor < DAEMON_KEEPALIVE_PROTOCOL_MINOR) return; const pingAfterMs: number = options.pingAfterMs ?? DEFAULT_PING_AFTER_MS; const unresponsiveAfterMs: number = options.unresponsiveAfterMs ?? DEFAULT_UNRESPONSIVE_AFTER_MS; const check: ILivenessCheck = { options, pingAfterMs, unresponsiveAfterMs, intervalMs: Math.min(MAX_LIVENESS_CHECK_INTERVAL_MS, pingAfterMs, unresponsiveAfterMs), lastCheckAtMs: performance.now() }; this.#lastHeardAtMs = check.lastCheckAtMs; this.#livenessTimer = setInterval(() => this.#checkLiveness(check), check.intervalMs); this.#livenessTimer.unref?.(); } #checkLiveness(check: ILivenessCheck): void { const nowMs: number = performance.now(); // A check that runs this late means that the client's own event loop stalled, for example while the process // was stopped. Frames that the daemon sent meanwhile may still wait to be read, so that is not its silence. const stalledMs: number = nowMs - check.lastCheckAtMs - check.intervalMs; check.lastCheckAtMs = nowMs; if (stalledMs > check.intervalMs) { this.#lastHeardAtMs = Math.min(nowMs, this.#lastHeardAtMs + stalledMs); } if (this.#finished || this.#frameInFlight) return; const silentForMs: number = nowMs - this.#lastHeardAtMs; if (silentForMs >= check.pingAfterMs && !this.#pingPending) { this.#pingPending = true; // A send that fails closes the connection, which fails the request. Only the pong's arrival counts, so the // daemon need not read or send its warm set. this.#sendControlAsync({ kind: 'ping', payload: { omitWarmSet: true } }).catch(() => undefined); } if (silentForMs >= check.unresponsiveAfterMs && !this.#silenceReported) { this.#silenceReported = true; check.options.onUnresponsive({ pid: this.#daemonPid, silentForMs }); } } /** Once stopped, the check reports nothing more, not even that the daemon responds again. */ #stopLivenessCheck(): void { clearInterval(this.#livenessTimer); this.#livenessTimer = undefined; this.#silenceReported = false; } async #onFrameAsync(frame: IDaemonFrame): Promise { if (frame.kind === DaemonFrameType.controlJson) { await this.#onControlAsync(decodeDaemonControlMessage(frame.payload)); return; } const execution: IDaemonClientExecuteOptions = this.#requireExecution(); this.#observedExecution = true; if (frame.kind === DaemonFrameType.event) { await execution.onEventAsync?.(decodeDaemonEventFrame(frame.payload)); } else if (frame.kind === DaemonFrameType.logStdout || frame.kind === DaemonFrameType.logStderr) { const { chunk, operationId } = decodeDaemonLogChunk(frame.payload); const sink: IDaemonClientExecuteOptions['onStdoutAsync'] = frame.kind === DaemonFrameType.logStdout ? execution.onStdoutAsync : execution.onStderrAsync; if (!sink) throw new Error('A daemon output stream has no destination.'); await sink(chunk, operationId); } else { throw new DaemonProtocolError('malformedControlMessage', 'Unexpected input frame from daemon.'); } } async #onControlAsync(message: DaemonControlMessage): Promise { if (message.kind === 'error') throw new DaemonProtocolError(message.payload.code, message.payload.message); if (!this.#peerProtocolVersion) { if (message.kind !== 'helloAck') throw new Error('Expected daemon helloAck.'); const version: IDaemonProtocolVersion = message.payload.protocolVersion; if ( version.major !== DAEMON_PROTOCOL_VERSION.major || version.minor < DAEMON_REQUEST_LIFECYCLE_PROTOCOL_MINOR ) { throw new DaemonClientError( 'versionMismatch', 'Daemon does not support the required request lifecycle protocol; restart it with a matching version.' ); } this.#peerProtocolVersion = Object.freeze({ major: version.major, minor: Math.min(version.minor, DAEMON_PROTOCOL_VERSION.minor) }); this.#supportsInputLifecycle = this.#peerProtocolVersion.minor >= DAEMON_INPUT_LIFECYCLE_PROTOCOL_MINOR && this.#connectOptions.capabilities?.supportsInputLifecycle !== false; this.#supportsRequestStarted = this.#peerProtocolVersion.minor >= DAEMON_REQUEST_STARTED_PROTOCOL_MINOR; await this.#sendControlAsync({ kind: 'subscribe', payload: { ...this.#connectOptions.capabilities, isTTY: this.#connectOptions.capabilities?.isTTY ?? false, supportsInteractiveIO: true, supportsInputLifecycle: this.#supportsInputLifecycle, supportsRequestAdmission: true, supportsRequestLifecycle: true, supportsRequestStarted: this.#supportsRequestStarted } }); await this.#sendControlAsync({ kind: 'ping', payload: this.#connectOptions.omitWarmSetStatus ? { omitWarmSet: true } : {} }); return; } if (message.kind === 'pong' && !this.#used) { const expected: string | undefined = this.#connectOptions.expectedDaemonVersion; if (expected !== undefined && message.payload.daemonVersion !== expected) { throw new DaemonClientError( 'versionMismatch', `Expected daemon ${expected}, received ${message.payload.daemonVersion ?? 'unknown'}. Stop the old daemon before retrying; no PID was killed.` ); } this.#daemonPid = message.payload.pid; this.#ready.resolve(message.payload); return; } // The reply to the liveness check's ping, which can also arrive after the result. if (message.kind === 'pong' && this.#pingPending) { this.#pingPending = false; return; } if (message.kind === 'shutdownAck') { if (!this.#shutdown || this.#shutdownAcknowledged) { throw new DaemonProtocolError('malformedControlMessage', 'Unexpected shutdown acknowledgement.'); } this.#shutdownAcknowledged = true; this.#shutdownAck = message.payload; return; } const execution: IDaemonClientExecuteOptions = this.#requireExecution(); if (!('requestId' in message.payload) || message.payload.requestId !== execution.request.requestId) { throw new DaemonProtocolError( 'malformedControlMessage', 'Daemon control does not belong to the active request.' ); } switch (message.kind) { case 'requestResult': this.#complete({ kind: 'result', result: message.payload }); return; case 'requestRejected': this.#complete( message.payload.code === 'unsupported' ? { kind: 'fallback', reason: 'unsupported', message: message.payload.message } : { kind: 'rejected', rejection: message.payload } ); return; case 'terminalPolicy': if (message.payload.decision === 'requiresInProcess') { this.#complete({ kind: 'fallback', reason: 'controllingTerminalRequired' }); } else { if (!this.#supportsInputLifecycle) this.#startInput(); } return; case 'setRawMode': if (!execution.setRawMode) throw new Error('Daemon requested raw mode from a client without terminal control.'); execution.setRawMode(message.payload.enabled); this.#rawModeChanged = true; await this.#sendControlAsync({ kind: 'rawModeChanged', payload: message.payload }); if (!this.#supportsInputLifecycle) { if (message.payload.enabled) this.#startInput(); else this.#stopInput(); } return; case 'stdinReady': if (!this.#supportsInputLifecycle) { throw new DaemonProtocolError('malformedControlMessage', 'Unexpected stdin admission.'); } if (!this.#inputAdmitted) { this.#inputAdmitted = true; this.#startInput(); await execution.onInputAdmittedAsync?.(); } else if (this.#inputAcknowledgement) { const acknowledgement: IDeferred = this.#inputAcknowledgement; this.#inputAcknowledgement = undefined; acknowledgement.resolve(undefined); } else { throw new DaemonProtocolError('malformedControlMessage', 'Unexpected stdin write acknowledgement.'); } return; case 'requestStarted': if (!this.#supportsRequestStarted) { throw new DaemonProtocolError('malformedControlMessage', 'Unexpected request start notice.'); } this.#requestStarted = true; return; case 'queuePosition': { this.#queued = true; const { position, restartReason, scriptCount, restartsForAnotherRequest, nativeLockHolder, continuingOperations } = message.payload; await execution.onQueuePositionAsync?.( position, restartReason, { scriptCount, restartsForAnotherRequest }, nativeLockHolder, continuingOperations ); return; } default: throw new DaemonProtocolError( 'malformedControlMessage', `Unexpected daemon control: ${message.kind}.` ); } } #requireExecution(): IDaemonClientExecuteOptions { if (!this.#execution || this.#finished) throw new Error('Daemon sent request output outside an active request.'); return this.#execution; } #complete(outcome: DaemonClientOutcome): void { const restart: boolean = outcome.kind === 'result' && outcome.result.retryAfterRestart === true; if (restart && this.protocolVersion.minor < DAEMON_WORKSPACE_RESTART_PROTOCOL_MINOR) { throw new DaemonProtocolError('malformedControlMessage', 'Unexpected pre-execution restart outcome.'); } if ( (outcome.kind === 'fallback' || restart) && (this.#observedExecution || this.#inputAdmitted || this.#inputStarted || this.#rawModeChanged) ) { throw new DaemonProtocolError( 'malformedControlMessage', 'Daemon requested fallback or restart after output, terminal control, or stdin admission; the command was not retried.' ); } if (restart && this.#cancelSent) { outcome = { kind: 'result', result: { requestId: this.#execution!.request.requestId, outcome: 'aborted', exitCode: 130, aborted: true } }; } this.#finished = true; this.#stopInput(); this.#inputAcknowledgement?.resolve(undefined); this.#inputAcknowledgement = undefined; this.#result!.resolve(outcome); } #fail(error: Error): void { this.#inputAcknowledgement?.reject(error); this.#inputAcknowledgement = undefined; this.#ready.reject(error); this.#result?.reject(error); this.#shutdown?.reject(error); } async #sendControlAsync(message: DaemonControlMessage): Promise { return this.#sendFrameAsync({ kind: DaemonFrameType.controlJson, payload: encodeDaemonControlMessage(message) }); } #sendFrameAsync(frame: IDaemonFrame): Promise { this.#sendTail = this.#sendTail.then(() => this.#connection.sendFrameAsync(frame)); return this.#sendTail; } readonly #onInput = (chunk: Buffer): void => { const execution: IDaemonClientExecuteOptions = this.#requireExecution(); if (execution.cancelOnCtrlC && chunk.includes(3)) { this.#cancel(); return; } execution.stdin!.pause(); this.#inputTail = this.#sendInputAsync(chunk); void this.#inputTail .then(() => { if (this.#inputStarted && !this.#finished) execution.stdin!.resume(); }) .catch((error: Error) => this.#connection.abort(error)); }; async #sendInputAsync(chunk: Uint8Array): Promise { for (let offset: number = 0; offset < chunk.byteLength; offset += MAX_STDIN_CHUNK_BYTES) { if (this.#finished || this.#cancelSent) return; const acknowledgement: IDeferred | undefined = this.#supportsInputLifecycle ? deferred() : undefined; this.#inputAcknowledgement = acknowledgement; await Promise.all([ this.#sendFrameAsync({ kind: DaemonFrameType.stdin, payload: encodeDaemonStdinChunk({ requestId: this.#execution!.request.requestId, chunk: chunk.subarray(offset, offset + MAX_STDIN_CHUNK_BYTES) }) }), acknowledgement?.promise ]); } } readonly #onInputError = (error: Error): void => this.#connection.abort(error); readonly #onInputEnd = (): void => { if (!this.#inputStarted || this.#inputEnded || this.#finished) return; this.#inputEnded = true; this.#stopInput(); void this.#inputTail .then(async () => { if (this.#finished || this.#cancelSent) return; await this.#sendControlAsync({ kind: 'stdinEnd', payload: { requestId: this.#execution!.request.requestId } }); }) .catch((error: Error) => this.#connection.abort(error)); }; #startInput(): void { const execution: IDaemonClientExecuteOptions = this.#requireExecution(); if ( this.#inputStarted || this.#inputEnded || !execution.stdin || !execution.request.terminal.acceptsStdin ) return; if (execution.stdin.destroyed && !execution.stdin.readableEnded) { throw new Error('Daemon stdin closed before admission without reaching EOF.'); } this.#wasInputPaused = execution.stdin.isPaused(); this.#inputStarted = true; execution.stdin.on('data', this.#onInput); execution.stdin.on('error', this.#onInputError); if (this.#supportsInputLifecycle) { execution.stdin.once('end', this.#onInputEnd); if (execution.stdin.readableEnded) { this.#onInputEnd(); return; } } execution.stdin.resume(); } #stopInput(): void { if (!this.#inputStarted) return; this.#inputStarted = false; const stdin: Readable = this.#execution!.stdin!; stdin.pause(); stdin.removeListener('data', this.#onInput); stdin.removeListener('error', this.#onInputError); stdin.removeListener('end', this.#onInputEnd); if (!this.#wasInputPaused && stdin.listenerCount('data') > 0) stdin.resume(); } } function validateTimeout(timeoutMs: number): void { if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 0x7fffffff) { throw new RangeError('Client timeout must be an integer between 1 and 2147483647 milliseconds.'); } }