From 459b321b5af101231c80fd68682d922f5fe319df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 12:12:23 +0100 Subject: [PATCH 01/14] refactor(transport): one owner for transfer phase budgets and the outgoing-request phase observer Move the transfer phase watchdog into host-kit/transport, add suspend() for demand-aware idle, and extract the node:http outgoing-phase observation that remote upload adopts. Co-Authored-By: Claude Sonnet 5.5 --- docs/agents/code-ownership.md | 1 + .../src/internal/transfer-phase.test.ts | 377 ++++++++++++++++++ .../host-kit/src/internal/transfer-phase.ts | 207 ++++++++++ packages/host-kit/src/transport.ts | 13 + .../__tests__/upload-stream-lifecycle.test.ts | 3 +- .../upload-stream-phase-budget.test.ts | 151 ------- packages/remote/src/upload-client.ts | 3 +- packages/remote/src/upload-stream.ts | 129 +----- 8 files changed, 622 insertions(+), 262 deletions(-) create mode 100644 packages/host-kit/src/internal/transfer-phase.test.ts create mode 100644 packages/host-kit/src/internal/transfer-phase.ts delete mode 100644 packages/remote/src/__tests__/upload-stream-phase-budget.test.ts diff --git a/docs/agents/code-ownership.md b/docs/agents/code-ownership.md index e9b65ea372..3bad123acc 100644 --- a/docs/agents/code-ownership.md +++ b/docs/agents/code-ownership.md @@ -22,6 +22,7 @@ For SDK entries `android-adb`, `artifacts`, `limrun`, `metro`, and `remote-confi For command-host readers, use `withSdkHost`. Keep provider callbacks on their supplied host. Request cancellation and progress belong in `@agent-device/host-kit/request`. +Outbound artifact-transfer phase budgets and the node:http phase observer belong in `@agent-device/host-kit/transport`. Per-call abort guards belong beside transports in `packages/daemon-client/src/daemon-client-transport.ts`. Contracts shared across layers belong in `packages/contracts/src`. Schema composition belongs in `packages/command-surface/src/schema`. diff --git a/packages/host-kit/src/internal/transfer-phase.test.ts b/packages/host-kit/src/internal/transfer-phase.test.ts new file mode 100644 index 0000000000..4ca08704b0 --- /dev/null +++ b/packages/host-kit/src/internal/transfer-phase.test.ts @@ -0,0 +1,377 @@ +// The phase budget one artifact-transfer attempt runs under (#4441). +// +// Three ceilings govern one attempt — connecting, moving body bytes, waiting for headers — and each +// has to end a stalled attempt on its own while none of them touches the aggregate budget the +// attempt was admitted under. Those are behaviour claims about a clock, so the clock here is +// controlled rather than waited out. The loopback proofs in `upload-stream-phases.test.ts` put the +// same watchdog in front of real sockets. + +import assert from 'node:assert/strict'; +import { EventEmitter } from 'node:events'; +import type { ClientRequest } from 'node:http'; +import { afterEach, test, vi } from 'vitest'; +import { AppError } from '@agent-device/kernel/errors'; +import { + createTransferPhaseWatchdog, + isTransferPhaseTimeoutError, + observeClientRequestPhases, + TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, + TRANSFER_CONNECT_TIMEOUT_MS, + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, +} from './transfer-phase.ts'; + +afterEach(() => { + vi.useRealTimers(); +}); + +test('the three transfer ceilings are the adopted policy values', () => { + assert.equal(TRANSFER_CONNECT_TIMEOUT_MS, 30_000); + assert.equal(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, 30_000); + assert.equal(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, 120_000); +}); + +test('a body phase restarts its ceiling on every byte that moves', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const watchdog = createTransferPhaseWatchdog(); + try { + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + // Three full ceilings' worth of wall clock, each broken by real progress: 300 seconds of a slow + // artifact is admitted work, and nothing here may end it. + for (const _ of [0, 1, 2]) { + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 20_000); + watchdog.touchBody(); + } + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS + 1); + assert.equal(watchdog.signal.aborted, true); + assertPhaseDetails( + watchdog.signal.reason, + 'response-body', + TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, + ); + } finally { + watchdog.dispose(); + } +}); + +test('a phase that carries no bytes is not extended by progress reported in another phase', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const watchdog = createTransferPhaseWatchdog(); + try { + watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 10_000); + // Bytes moving elsewhere — an unrelated header, a keepalive, a timer callback — are not the + // response-header wait making progress. + watchdog.touchBody(); + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + assertPhaseDetails( + watchdog.signal.reason, + 'response-headers', + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + ); + } finally { + watchdog.dispose(); + } +}); + +test('arming the next phase stops counting the previous one', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const watchdog = createTransferPhaseWatchdog(); + try { + watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS - 1_000); + watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + // 58 seconds of total attempt time: past the connect ceiling, which the completed hop may spend, + // and inside the header ceiling the attempt is actually waiting on. + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1_000); + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(1_000); + assertPhaseDetails( + watchdog.signal.reason, + 'response-headers', + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + ); + } finally { + watchdog.dispose(); + } +}); + +test('an enclosing deadline wins and is never extended by a phase timer', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const caller = new AbortController(); + const reason = new Error('preparation aggregate expired'); + setTimeout(() => caller.abort(reason), 5_000); + const watchdog = createTransferPhaseWatchdog(caller.signal); + try { + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(5_001); + // The caller's reason is the answer, not a phase's own evidence, so a consumer can still tell + // "the work this upload served is gone" from "this transfer stalled". + assert.equal(watchdog.signal.aborted, true); + assert.equal(watchdog.signal.reason, reason); + assert.equal(isTransferPhaseTimeoutError(watchdog.signal.reason), false); + } finally { + watchdog.dispose(); + } +}); + +test('a phase expiry is its own typed evidence and never caller cancellation', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const caller = new AbortController(); + const watchdog = createTransferPhaseWatchdog(caller.signal); + try { + watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); + assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); + // Distinctness the retry policy depends on: nobody canceled, so the caller's own signal stays + // live and an enclosing aggregate is free to reach a different outcome. + assert.equal(caller.signal.aborted, false); + } finally { + watchdog.dispose(); + } +}); + +test('a disposed watchdog stops watching', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const watchdog = createTransferPhaseWatchdog(); + watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); + watchdog.dispose(); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS * 3); + assert.equal(watchdog.signal.aborted, false); +}); + +test('a phase is never armed after the attempt is already over', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const watchdog = createTransferPhaseWatchdog(); + try { + watchdog.signal.throwIfAborted(); + const caller = new AbortController(); + caller.abort(new Error('gone')); + const late = createTransferPhaseWatchdog(caller.signal); + try { + late.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS * 2); + assert.equal(late.signal.reason.message, 'gone'); + } finally { + late.dispose(); + } + } finally { + watchdog.dispose(); + } +}); + +test('a suspended phase is not charged while nothing is owed, and the attempt stays live', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const caller = new AbortController(); + const watchdog = createTransferPhaseWatchdog(caller.signal); + try { + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); + watchdog.suspend(); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS * 5); + // Suspension is not settlement: nothing aborted, neither the attempt nor the caller's signal. + assert.equal(watchdog.signal.aborted, false); + assert.equal(caller.signal.aborted, false); + } finally { + watchdog.dispose(); + } +}); + +test('late progress does not rearm a suspended timer', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const watchdog = createTransferPhaseWatchdog(); + try { + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + watchdog.suspend(); + watchdog.touchBody(); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS * 3); + assert.equal(watchdog.signal.aborted, false); + } finally { + watchdog.dispose(); + } +}); + +test('arming resumes a suspended phase with a fresh full ceiling', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const watchdog = createTransferPhaseWatchdog(); + try { + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + watchdog.suspend(); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS * 2); + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); + assert.equal(watchdog.signal.aborted, false); + // Progress restarts the resumed phase again, so suspension left no residue. + watchdog.touchBody(); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(1); + assertPhaseDetails( + watchdog.signal.reason, + 'response-body', + TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, + ); + } finally { + watchdog.dispose(); + } +}); + +test('a caller cancellation still ends a suspended attempt with the caller reason', () => { + const caller = new AbortController(); + const watchdog = createTransferPhaseWatchdog(caller.signal); + try { + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + watchdog.suspend(); + const reason = new Error('caller left'); + caller.abort(reason); + assert.equal(watchdog.signal.aborted, true); + assert.equal(watchdog.signal.reason, reason); + } finally { + watchdog.dispose(); + } +}); + +test('suspending twice or before any phase is armed is harmless', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const watchdog = createTransferPhaseWatchdog(); + try { + watchdog.suspend(); + watchdog.suspend(); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS * 2); + assert.equal(watchdog.signal.aborted, false); + } finally { + watchdog.dispose(); + } +}); + +type FakeSocket = EventEmitter & { connecting: boolean; encrypted?: boolean }; + +function createObservedRequest(callerSignal?: AbortSignal) { + const req = new EventEmitter() as unknown as ClientRequest; + const watchdog = createTransferPhaseWatchdog(callerSignal); + watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); + const phases = observeClientRequestPhases(req, watchdog); + const emit = (event: string, ...args: unknown[]) => + (req as unknown as EventEmitter).emit(event, ...args); + const socket = (state: { connecting: boolean; encrypted?: boolean }): FakeSocket => + Object.assign(new EventEmitter(), state); + return { req, watchdog, phases, emit, socket }; +} + +test('a fresh socket keeps the connect ceiling until it connects, even after the body flushed', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const { watchdog, emit, socket } = createObservedRequest(); + try { + const fresh = socket({ connecting: true }); + emit('socket', fresh); + emit('finish'); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); + assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); + } finally { + watchdog.dispose(); + } +}); + +test('the header wait starts only after both the flush and the connection', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const { watchdog, emit, socket } = createObservedRequest(); + try { + const fresh = socket({ connecting: true }); + emit('socket', fresh); + emit('finish'); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS - 1_000); + fresh.emit('connect'); + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1); + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(1); + assertPhaseDetails( + watchdog.signal.reason, + 'response-headers', + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + ); + } finally { + watchdog.dispose(); + } +}); + +test('a TLS socket is established by secureConnect, not connect', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const { watchdog, emit, socket } = createObservedRequest(); + try { + const tls = socket({ connecting: true, encrypted: true }); + emit('socket', tls); + tls.emit('connect'); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); + assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); + } finally { + watchdog.dispose(); + } +}); + +test('a pooled socket is already connected and times the body write as inactivity', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const { watchdog, emit, socket } = createObservedRequest(); + try { + emit('socket', socket({ connecting: false })); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); + emit('drain'); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(1); + assertPhaseDetails( + watchdog.signal.reason, + 'request-body', + TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, + ); + } finally { + watchdog.dispose(); + } +}); + +test('once the response started, later request events do not overwrite its phase', async () => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + const { watchdog, phases, emit, socket } = createObservedRequest(); + try { + const fresh = socket({ connecting: true }); + emit('socket', fresh); + emit('response'); + assert.equal(phases.responseStarted, true); + fresh.emit('connect'); + emit('finish'); + emit('drain'); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS + 1); + assertPhaseDetails( + watchdog.signal.reason, + 'response-body', + TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, + ); + } finally { + watchdog.dispose(); + } +}); + +test('disposing the observer removes every listener it added', () => { + const { req, watchdog, phases, emit, socket } = createObservedRequest(); + try { + const fresh = socket({ connecting: true }); + emit('socket', fresh); + phases.dispose(); + const emitter = req as unknown as EventEmitter; + for (const event of ['socket', 'drain', 'finish', 'response']) { + assert.equal(emitter.listenerCount(event), 0, event); + } + assert.equal(fresh.listenerCount('connect'), 0); + } finally { + watchdog.dispose(); + } +}); + +function assertPhaseDetails(reason: unknown, phase: string, timeoutMs: number): void { + assert.ok(reason instanceof AppError, `phase expiry must be an AppError, got ${String(reason)}`); + assert.equal(isTransferPhaseTimeoutError(reason), true); + assert.deepEqual(reason.details, { + reason: 'transfer_phase_timeout', + transferPhase: phase, + timeoutMs, + }); +} diff --git a/packages/host-kit/src/internal/transfer-phase.ts b/packages/host-kit/src/internal/transfer-phase.ts new file mode 100644 index 0000000000..9453c967c4 --- /dev/null +++ b/packages/host-kit/src/internal/transfer-phase.ts @@ -0,0 +1,207 @@ +import type { ClientRequest } from 'node:http'; +import type { Socket } from 'node:net'; +import { AppError } from '@agent-device/kernel/errors'; + +/** + * Ceiling for establishing the connection one artifact-transfer attempt runs on. + * + * Kept beside its domain rather than on the socket: the same number governs every hop of an upload, + * every offset resume and a standalone artifact download, so "how long may one hop take to connect" + * has exactly one answer. + */ +export const TRANSFER_CONNECT_TIMEOUT_MS = 30_000; + +/** + * Ceiling for waiting on response headers once this side has written everything the server is + * waiting for. For an upload that is the moment its outgoing request body is fully flushed, never + * the moment the request was created; for a bodyless request it is connection establishment. + */ +export const TRANSFER_RESPONSE_HEADER_TIMEOUT_MS = 30_000; + +/** + * Ceiling for silence between body bytes in either direction. Bytes actually written or read reset + * it, so an artifact that keeps moving keeps its budget while a connection that stopped carrying + * bytes does not. Progress never touches the aggregate budget the attempt runs under. + */ +export const TRANSFER_BODY_INACTIVITY_TIMEOUT_MS = 120_000; + +export type TransferPhase = 'connect' | 'request-body' | 'response-headers' | 'response-body' | 'preflight' | 'finalize'; + +const BODY_PHASES: ReadonlySet = new Set(['request-body', 'response-body']); + +/** The `details.reason` every phase expiry carries, so no consumer has to match error text. */ +export const TRANSFER_PHASE_TIMEOUT_REASON = 'transfer_phase_timeout'; + +/** + * Watches the sequential phases of ONE transfer attempt. + * + * One attempt gets one watchdog: arming a later phase stops counting the earlier one, so the ceiling + * that applies is always the phase the transfer is actually in. Progress re-arms only the two body + * phases. Nothing here extends an enclosing aggregate budget — the caller's signal is combined in, + * never replaced, so the earliest deadline still wins and every attempt, redirect and resume keeps + * sharing the original aggregate. + */ +export type TransferPhaseWatchdog = { + /** The signal the attempt runs on: the caller's cancellation plus every phase deadline. */ + signal: AbortSignal; + /** Starts watching `phase` and resumes phase timing if it was suspended. The phase watched before stops counting. */ + arm(phase: TransferPhase, timeoutMs: number): void; + /** Records body bytes moving, so only the silence since the last byte counts against a body phase. */ + touchBody(): void; + /** + * Stops the armed phase's timer while this side owes the peer nothing, such as a consumer that has + * not asked for more bytes. The attempt stays live: the signal, the caller's cancellation and any + * enclosing aggregate are untouched, and late progress does not restart the timer. Only `arm` + * resumes phase timing. Unlike `dispose`, it does not mean the attempt is settled. + */ + suspend(): void; + /** Stops the armed timer. Call it once the attempt is settled. */ + dispose(): void; +}; + +export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): TransferPhaseWatchdog { + const phase = new AbortController(); + const signal = callerSignal ? AbortSignal.any([callerSignal, phase.signal]) : phase.signal; + let armed: { phase: TransferPhase; timeoutMs: number } | undefined; + let timer: ReturnType | undefined; + let suspended = false; + const rearm = () => { + if (timer !== undefined) clearTimeout(timer); + timer = undefined; + const current = armed; + if (!current || suspended) return; + timer = setTimeout(() => { + timer = undefined; + phase.abort(createTransferPhaseTimeoutError(current.phase, current.timeoutMs)); + }, current.timeoutMs); + timer.unref(); + }; + return { + signal, + arm(nextPhase, timeoutMs) { + if (signal.aborted) return; + armed = { phase: nextPhase, timeoutMs }; + suspended = false; + rearm(); + }, + touchBody() { + // Unrelated headers, keepalive traffic and timer callbacks are not body progress, and + // progress in one phase buys no time in another: only a body phase already armed re-arms. + if (!armed || !BODY_PHASES.has(armed.phase)) return; + rearm(); + }, + suspend() { + suspended = true; + rearm(); + }, + dispose() { + armed = undefined; + if (timer !== undefined) clearTimeout(timer); + timer = undefined; + }, + }; +} + +/** + * Typed evidence that a transfer phase, rather than the caller or the whole preparation aggregate, + * ended the attempt. The expired phase and its effective budget travel in `details`. + */ +export function createTransferPhaseTimeoutError(phase: TransferPhase, timeoutMs: number): AppError { + return new AppError('COMMAND_FAILED', `Artifact transfer ${phase} timed out`, { + reason: TRANSFER_PHASE_TIMEOUT_REASON, + transferPhase: phase, + timeoutMs, + }); +} + +/** Whether `error` is a transfer phase's own expiry, which no fallback or retry may restart. */ +export function isTransferPhaseTimeoutError(error: unknown): boolean { + return error instanceof AppError && error.details?.reason === TRANSFER_PHASE_TIMEOUT_REASON; +} + +/** What `observeClientRequestPhases` reports and owns for one outgoing request. */ +export type ClientRequestPhases = { + /** Whether the response has started. Request-side events no longer move the phase after this. */ + readonly responseStarted: boolean; + /** Removes every listener the observer added. Call it once the exchange is settled. */ + dispose(): void; +}; + +/** + * Drives `watchdog` through the phases of ONE outgoing `node:http` request. + * + * The caller arms `connect` before issuing the request. From the events that follow, this owner + * decides the phase the exchange is in: + * - A fresh socket is not a connection until `connect`, or `secureConnect` for TLS. A pooled socket + * already is. Until then the connect ceiling keeps counting, even when the whole body already sits + * in the write buffer, because buffered bytes are not transport progress. + * - A connected exchange that is still writing is in `request-body`. `drain` is the progress that + * restarts its inactivity budget, since it reports bytes the socket actually accepted. + * - The header wait starts only after BOTH the request `finish` and the connection. + * - Once the response starts, the exchange is in `response-body` and no later request event can + * overwrite it. The caller reports response bytes with `touchBody`. + * + * Attach it in the tick that creates the request. It waits on nothing: every listener it adds is + * removed by `dispose`. + */ +export function observeClientRequestPhases( + req: ClientRequest, + watchdog: TransferPhaseWatchdog, +): ClientRequestPhases { + let established = false; + let flushed = false; + let responseStarted = false; + let socket: Socket | undefined; + let connectEvent: 'connect' | 'secureConnect' | undefined; + const advance = () => { + if (responseStarted || watchdog.signal.aborted || !established) return; + if (flushed) { + watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + } else { + watchdog.arm('request-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + } + }; + const onConnected = () => { + established = true; + advance(); + }; + const onSocket = (next: Socket) => { + if (!next.connecting) { + established = true; + advance(); + return; + } + socket = next; + const secured = (next as { encrypted?: boolean }).encrypted === true; + connectEvent = secured ? 'secureConnect' : 'connect'; + next.once(connectEvent, onConnected); + }; + const onDrain = () => { + if (!responseStarted) watchdog.touchBody(); + }; + const onFinish = () => { + flushed = true; + advance(); + }; + const onResponse = () => { + responseStarted = true; + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + }; + req.on('socket', onSocket); + req.on('drain', onDrain); + req.on('finish', onFinish); + // The request's own response callback is registered first, so the phase has to move before it runs. + req.prependListener('response', onResponse); + return { + get responseStarted() { + return responseStarted; + }, + dispose() { + req.off('socket', onSocket); + req.off('drain', onDrain); + req.off('finish', onFinish); + req.off('response', onResponse); + if (socket && connectEvent) socket.off(connectEvent, onConnected); + }, + }; +} diff --git a/packages/host-kit/src/transport.ts b/packages/host-kit/src/transport.ts index 6b55289d46..23c9daaf19 100644 --- a/packages/host-kit/src/transport.ts +++ b/packages/host-kit/src/transport.ts @@ -7,3 +7,16 @@ export { timingSafeStringEqual, type NodeHttpRequester, } from './internal/transport.ts'; +export { + createTransferPhaseTimeoutError, + createTransferPhaseWatchdog, + isTransferPhaseTimeoutError, + observeClientRequestPhases, + TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, + TRANSFER_CONNECT_TIMEOUT_MS, + TRANSFER_PHASE_TIMEOUT_REASON, + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + type ClientRequestPhases, + type TransferPhase, + type TransferPhaseWatchdog, +} from './internal/transfer-phase.ts'; diff --git a/packages/remote/src/__tests__/upload-stream-lifecycle.test.ts b/packages/remote/src/__tests__/upload-stream-lifecycle.test.ts index ed1cd9a47a..c7a01db9dd 100644 --- a/packages/remote/src/__tests__/upload-stream-lifecycle.test.ts +++ b/packages/remote/src/__tests__/upload-stream-lifecycle.test.ts @@ -1,5 +1,6 @@ import { afterEach, assert, test, vi } from 'vitest'; -import { isRetryableUploadStreamError, isTransferPhaseTimeoutError } from '../upload-stream.ts'; +import { isTransferPhaseTimeoutError } from '@agent-device/host-kit/transport'; +import { isRetryableUploadStreamError } from '../upload-stream.ts'; import { LEGACY_UPLOAD_REQUEST, TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, diff --git a/packages/remote/src/__tests__/upload-stream-phase-budget.test.ts b/packages/remote/src/__tests__/upload-stream-phase-budget.test.ts deleted file mode 100644 index 788c7e3ce5..0000000000 --- a/packages/remote/src/__tests__/upload-stream-phase-budget.test.ts +++ /dev/null @@ -1,151 +0,0 @@ -import assert from 'node:assert/strict'; -import { afterEach, test, vi } from 'vitest'; -import { AppError } from '@agent-device/kernel/errors'; -import { - createTransferPhaseWatchdog, - isTransferPhaseTimeoutError, - TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, - TRANSFER_CONNECT_TIMEOUT_MS, - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, -} from '../upload-stream.ts'; - -afterEach(() => { - vi.useRealTimers(); -}); - -test('the three transfer ceilings are the adopted policy values', () => { - assert.equal(TRANSFER_CONNECT_TIMEOUT_MS, 30_000); - assert.equal(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, 30_000); - assert.equal(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, 120_000); -}); - -test('a body phase restarts its ceiling on every byte that moves', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - for (const _ of [0, 1, 2]) { - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 20_000); - watchdog.touchBody(); - } - assert.equal(watchdog.signal.aborted, false); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS + 1); - assert.equal(watchdog.signal.aborted, true); - assertPhaseDetails( - watchdog.signal.reason, - 'response-body', - TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); - } -}); - -test('a phase that carries no bytes is not extended by progress reported in another phase', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 10_000); - watchdog.touchBody(); - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - assertPhaseDetails( - watchdog.signal.reason, - 'response-headers', - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); - } -}); - -test('arming the next phase stops counting the previous one', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS - 1_000); - watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1_000); - assert.equal(watchdog.signal.aborted, false); - await vi.advanceTimersByTimeAsync(1_000); - assertPhaseDetails( - watchdog.signal.reason, - 'response-headers', - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); - } -}); - -test('an enclosing deadline wins and is never extended by a phase timer', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const caller = new AbortController(); - const reason = new Error('preparation aggregate expired'); - setTimeout(() => caller.abort(reason), 5_000); - const watchdog = createTransferPhaseWatchdog(caller.signal); - try { - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(5_001); - assert.equal(watchdog.signal.aborted, true); - assert.equal(watchdog.signal.reason, reason); - assert.equal(isTransferPhaseTimeoutError(watchdog.signal.reason), false); - } finally { - watchdog.dispose(); - } -}); - -test('a phase expiry is its own typed evidence and never caller cancellation', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const caller = new AbortController(); - const watchdog = createTransferPhaseWatchdog(caller.signal); - try { - watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); - assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); - assert.equal(caller.signal.aborted, false); - } finally { - watchdog.dispose(); - } -}); - -test('a disposed watchdog stops watching', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); - watchdog.dispose(); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS * 3); - assert.equal(watchdog.signal.aborted, false); -}); - -test('a phase is never armed after the attempt is already over', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.signal.throwIfAborted(); - const caller = new AbortController(); - caller.abort(new Error('gone')); - const late = createTransferPhaseWatchdog(caller.signal); - try { - late.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - assert.equal(vi.getTimerCount(), 0); - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS * 2); - assert.equal(late.signal.reason.message, 'gone'); - } finally { - late.dispose(); - } - } finally { - watchdog.dispose(); - } -}); - -function assertPhaseDetails(reason: unknown, phase: string, timeoutMs: number): void { - assert.ok(reason instanceof AppError, `phase expiry must be an AppError, got ${String(reason)}`); - assert.equal(isTransferPhaseTimeoutError(reason), true); - assert.deepEqual(reason.details, { - reason: 'transfer_phase_timeout', - transferPhase: phase, - timeoutMs, - }); -} diff --git a/packages/remote/src/upload-client.ts b/packages/remote/src/upload-client.ts index 62291f5fe1..2a90de0e60 100644 --- a/packages/remote/src/upload-client.ts +++ b/packages/remote/src/upload-client.ts @@ -7,13 +7,12 @@ import { } from '@agent-device/contracts/daemon-http'; import { prepareUploadArtifact, type PreparedUploadArtifact } from './upload-client-artifact.ts'; import { - createTransferPhaseWatchdog, isRetryableUploadStreamError, - isTransferPhaseTimeoutError, streamFileToHttpRequest, withUploadPreparationDeadline, } from './upload-stream.ts'; import type { UploadProgressSink } from './upload-progress.ts'; +import { createTransferPhaseWatchdog, isTransferPhaseTimeoutError } from '@agent-device/host-kit/transport'; /** Ceiling for the small JSON `preflight` and `finalize` calls that bracket an upload. */ const UPLOAD_CONTROL_PLANE_TIMEOUT_MS = 30_000; diff --git a/packages/remote/src/upload-stream.ts b/packages/remote/src/upload-stream.ts index 8b112650ac..e52f5a5f89 100644 --- a/packages/remote/src/upload-stream.ts +++ b/packages/remote/src/upload-stream.ts @@ -5,9 +5,12 @@ import { pipeline } from 'node:stream/promises'; import { addAbortSignal } from 'node:stream'; import { AppError } from '@agent-device/kernel/errors'; import { + createTransferPhaseWatchdog, loadNodeHttpRequester, + observeClientRequestPhases, observeCompletedRequestWrites, readNodeHttpResponseBody, + TRANSFER_CONNECT_TIMEOUT_MS, } from '@agent-device/host-kit/transport'; import { createUploadProgressTransform, @@ -15,81 +18,6 @@ import { type UploadProgressStage, } from './upload-progress.ts'; -export const TRANSFER_CONNECT_TIMEOUT_MS = 30_000; - -/** Header wait starts after connection and outgoing flush, never while the body progresses. */ -export const TRANSFER_RESPONSE_HEADER_TIMEOUT_MS = 30_000; - -export const TRANSFER_BODY_INACTIVITY_TIMEOUT_MS = 120_000; - -export type TransferPhase = - | 'connect' - | 'request-body' - | 'response-headers' - | 'response-body' - | 'preflight' - | 'finalize'; - -const BODY_PHASES: ReadonlySet = new Set(['request-body', 'response-body']); - -const TRANSFER_PHASE_TIMEOUT_REASON = 'transfer_phase_timeout'; - -/** One sequential phase under the earliest caller/aggregate deadline; progress resets body phases only. */ -export type TransferPhaseWatchdog = { - signal: AbortSignal; - arm(phase: TransferPhase, timeoutMs: number): void; - touchBody(): void; - /** Stops the armed timer. Call it once the attempt is settled. */ - dispose(): void; -}; - -export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): TransferPhaseWatchdog { - const phase = new AbortController(); - const signal = callerSignal ? AbortSignal.any([callerSignal, phase.signal]) : phase.signal; - let armed: { phase: TransferPhase; timeoutMs: number } | undefined; - let timer: ReturnType | undefined; - const rearm = () => { - if (timer !== undefined) clearTimeout(timer); - const current = armed; - if (!current) return; - timer = setTimeout(() => { - timer = undefined; - phase.abort(createTransferPhaseTimeoutError(current.phase, current.timeoutMs)); - }, current.timeoutMs); - timer.unref(); - }; - return { - signal, - arm(nextPhase, timeoutMs) { - if (signal.aborted) return; - armed = { phase: nextPhase, timeoutMs }; - rearm(); - }, - touchBody() { - if (!armed || !BODY_PHASES.has(armed.phase)) return; - rearm(); - }, - dispose() { - armed = undefined; - if (timer !== undefined) clearTimeout(timer); - timer = undefined; - }, - }; -} - -function createTransferPhaseTimeoutError(phase: TransferPhase, timeoutMs: number): AppError { - return new AppError('COMMAND_FAILED', `Artifact transfer ${phase} timed out`, { - reason: TRANSFER_PHASE_TIMEOUT_REASON, - transferPhase: phase, - timeoutMs, - }); -} - -/** Whether `error` is a transfer phase's own expiry, which no fallback or retry may restart. */ -export function isTransferPhaseTimeoutError(error: unknown): boolean { - return error instanceof AppError && error.details?.reason === TRANSFER_PHASE_TIMEOUT_REASON; -} - const UPLOAD_PREPARATION_TIMEOUT_MS = 600_000; export async function withUploadPreparationDeadline( @@ -144,7 +72,10 @@ export async function streamFileToHttpRequest(options: { errorMessage: string; errorHint?: string; retryable?: boolean; - /** Every attempt and hop shares the enclosing aggregate/caller signal. */ + /** + * The preparation aggregate `uploadArtifact` opened, combined with its caller's cancellation. Every + * attempt, redirect and resume runs under it; none of them opens a deadline of its own. + */ signal: AbortSignal; progress?: UploadStreamProgressOptions; }): Promise { @@ -177,37 +108,30 @@ async function streamFileToHttpRequestAttempt(options: { const headers = buildUploadRequestHeaders(options.headers, options.startOffset, payloadSize); emitUploadAttemptStarted(options.progress, options.startOffset, payloadSize); + // A redirect or a resume is a new attempt with fresh phase timers under the same `options.signal`. const watchdog = createTransferPhaseWatchdog(options.signal); watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); + // The owned pipeline (file → progress → request). Every exit joins it, so no owned byte overlaps + // the outcome or the next hop. let upload: Promise | undefined; let uploadSettled = false; - let responseReceived = false; return await new Promise((resolve, reject) => { let outgoingEnded = false; - let transportEstablished = false; - let bodyFlushed = false; const settle = (result: UploadStreamResponse) => { + phases.dispose(); stopObservingWrites(); watchdog.dispose(); resolve(result); }; const fail = (error: unknown) => { + phases.dispose(); stopObservingWrites(); watchdog.dispose(); // The queued pipeline has to settle before the join in `finally`. req.destroy(); reject(error); }; - const advanceOutgoingPhase = () => { - if (responseReceived || watchdog.signal.aborted) return; - if (!transportEstablished) return; - if (bodyFlushed) { - watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - } else { - watchdog.arm('request-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - } - }; const req = transport.request( { protocol: options.url.protocol, @@ -221,8 +145,6 @@ async function streamFileToHttpRequestAttempt(options: { signal: watchdog.signal, }, (res) => { - responseReceived = true; - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); addAbortSignal(watchdog.signal, res); void handleUploadResponse(res) .then((result) => settle(result)) @@ -232,28 +154,15 @@ async function streamFileToHttpRequestAttempt(options: { }, ); - req.on('socket', (socket) => { - if (socket.connecting) { - const secured = (socket as { encrypted?: boolean }).encrypted === true; - socket.once(secured ? 'secureConnect' : 'connect', () => { - transportEstablished = true; - advanceOutgoingPhase(); - }); - } else { - transportEstablished = true; - advanceOutgoingPhase(); - } - }); - req.on('finish', () => { - bodyFlushed = true; - advanceOutgoingPhase(); - }); + const phases = observeClientRequestPhases(req, watchdog); const stopObservingWrites = observeCompletedRequestWrites(req, watchdog.signal, () => watchdog.touchBody(), ); req.on('error', (err) => { - if (responseReceived) return; + if (phases.responseStarted) return; + // A cancellation or an expired phase is this client's own outcome, never a transport failure + // that a retry or a legacy fallback could fix. if (watchdog.signal.aborted) { fail(watchdog.signal.reason); return; @@ -285,12 +194,13 @@ async function streamFileToHttpRequestAttempt(options: { })().catch((err: unknown) => { // After a response, only this attempt's own teardown ends the pipeline, and the server's // verdict stays the outcome: a 413 read completely is a 413, not a transport break. - if (responseReceived) return; + if (phases.responseStarted) return; req.destroy(); if (watchdog.signal.aborted) { fail(watchdog.signal.reason); return; } + // A transport break reports through `error`, so this is the artifact read failing. const error = err instanceof Error ? err : new Error(String(err)); fail(new AppError('COMMAND_FAILED', 'Failed to read local artifact', {}, error)); }); @@ -309,8 +219,11 @@ async function streamFileToHttpRequestAttempt(options: { }; async function handleUploadResponse(res: IncomingMessage): Promise { + // Read the accepted answer to its end, then end and join the outgoing work before this attempt + // resolves or the next hop starts. const body = await readNodeHttpResponseBody(res, () => watchdog.touchBody()); await endOutgoingWork(); + phases.dispose(); stopObservingWrites(); watchdog.dispose(); From 0e493d50bbc40eda20176d5fc5ae4f51b917d27b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 15:44:14 +0100 Subject: [PATCH 02/14] refactor(transport): keep transfer phase budgets in host-kit's transport internals internal/transfer-phase.ts was a new module that every client, daemon, proxy and remote entry evaluated eagerly through the transport barrel. The phase watchdog, its typed expiry classifier and the outgoing-request phase observer now live in internal/transport.ts, which those closures already evaluate. The barrel exports only what production consumers import: createTransferPhaseWatchdog, isTransferPhaseTimeoutError, observeClientRequestPhases and TRANSFER_CONNECT_TIMEOUT_MS. The remote loopback tests pin the response-header and body-inactivity policy values as literals in their shared fixtures; the host-kit tests import the owner module directly and are renamed for it (transport-phases.test.ts). Co-Authored-By: Claude Opus 5.5 --- .../host-kit/src/internal/transfer-phase.ts | 207 ------------------ ...phase.test.ts => transport-phases.test.ts} | 8 +- packages/host-kit/src/internal/transport.ts | 205 +++++++++++++++++ packages/host-kit/src/transport.ts | 17 +- 4 files changed, 211 insertions(+), 226 deletions(-) delete mode 100644 packages/host-kit/src/internal/transfer-phase.ts rename packages/host-kit/src/internal/{transfer-phase.test.ts => transport-phases.test.ts} (98%) diff --git a/packages/host-kit/src/internal/transfer-phase.ts b/packages/host-kit/src/internal/transfer-phase.ts deleted file mode 100644 index 9453c967c4..0000000000 --- a/packages/host-kit/src/internal/transfer-phase.ts +++ /dev/null @@ -1,207 +0,0 @@ -import type { ClientRequest } from 'node:http'; -import type { Socket } from 'node:net'; -import { AppError } from '@agent-device/kernel/errors'; - -/** - * Ceiling for establishing the connection one artifact-transfer attempt runs on. - * - * Kept beside its domain rather than on the socket: the same number governs every hop of an upload, - * every offset resume and a standalone artifact download, so "how long may one hop take to connect" - * has exactly one answer. - */ -export const TRANSFER_CONNECT_TIMEOUT_MS = 30_000; - -/** - * Ceiling for waiting on response headers once this side has written everything the server is - * waiting for. For an upload that is the moment its outgoing request body is fully flushed, never - * the moment the request was created; for a bodyless request it is connection establishment. - */ -export const TRANSFER_RESPONSE_HEADER_TIMEOUT_MS = 30_000; - -/** - * Ceiling for silence between body bytes in either direction. Bytes actually written or read reset - * it, so an artifact that keeps moving keeps its budget while a connection that stopped carrying - * bytes does not. Progress never touches the aggregate budget the attempt runs under. - */ -export const TRANSFER_BODY_INACTIVITY_TIMEOUT_MS = 120_000; - -export type TransferPhase = 'connect' | 'request-body' | 'response-headers' | 'response-body' | 'preflight' | 'finalize'; - -const BODY_PHASES: ReadonlySet = new Set(['request-body', 'response-body']); - -/** The `details.reason` every phase expiry carries, so no consumer has to match error text. */ -export const TRANSFER_PHASE_TIMEOUT_REASON = 'transfer_phase_timeout'; - -/** - * Watches the sequential phases of ONE transfer attempt. - * - * One attempt gets one watchdog: arming a later phase stops counting the earlier one, so the ceiling - * that applies is always the phase the transfer is actually in. Progress re-arms only the two body - * phases. Nothing here extends an enclosing aggregate budget — the caller's signal is combined in, - * never replaced, so the earliest deadline still wins and every attempt, redirect and resume keeps - * sharing the original aggregate. - */ -export type TransferPhaseWatchdog = { - /** The signal the attempt runs on: the caller's cancellation plus every phase deadline. */ - signal: AbortSignal; - /** Starts watching `phase` and resumes phase timing if it was suspended. The phase watched before stops counting. */ - arm(phase: TransferPhase, timeoutMs: number): void; - /** Records body bytes moving, so only the silence since the last byte counts against a body phase. */ - touchBody(): void; - /** - * Stops the armed phase's timer while this side owes the peer nothing, such as a consumer that has - * not asked for more bytes. The attempt stays live: the signal, the caller's cancellation and any - * enclosing aggregate are untouched, and late progress does not restart the timer. Only `arm` - * resumes phase timing. Unlike `dispose`, it does not mean the attempt is settled. - */ - suspend(): void; - /** Stops the armed timer. Call it once the attempt is settled. */ - dispose(): void; -}; - -export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): TransferPhaseWatchdog { - const phase = new AbortController(); - const signal = callerSignal ? AbortSignal.any([callerSignal, phase.signal]) : phase.signal; - let armed: { phase: TransferPhase; timeoutMs: number } | undefined; - let timer: ReturnType | undefined; - let suspended = false; - const rearm = () => { - if (timer !== undefined) clearTimeout(timer); - timer = undefined; - const current = armed; - if (!current || suspended) return; - timer = setTimeout(() => { - timer = undefined; - phase.abort(createTransferPhaseTimeoutError(current.phase, current.timeoutMs)); - }, current.timeoutMs); - timer.unref(); - }; - return { - signal, - arm(nextPhase, timeoutMs) { - if (signal.aborted) return; - armed = { phase: nextPhase, timeoutMs }; - suspended = false; - rearm(); - }, - touchBody() { - // Unrelated headers, keepalive traffic and timer callbacks are not body progress, and - // progress in one phase buys no time in another: only a body phase already armed re-arms. - if (!armed || !BODY_PHASES.has(armed.phase)) return; - rearm(); - }, - suspend() { - suspended = true; - rearm(); - }, - dispose() { - armed = undefined; - if (timer !== undefined) clearTimeout(timer); - timer = undefined; - }, - }; -} - -/** - * Typed evidence that a transfer phase, rather than the caller or the whole preparation aggregate, - * ended the attempt. The expired phase and its effective budget travel in `details`. - */ -export function createTransferPhaseTimeoutError(phase: TransferPhase, timeoutMs: number): AppError { - return new AppError('COMMAND_FAILED', `Artifact transfer ${phase} timed out`, { - reason: TRANSFER_PHASE_TIMEOUT_REASON, - transferPhase: phase, - timeoutMs, - }); -} - -/** Whether `error` is a transfer phase's own expiry, which no fallback or retry may restart. */ -export function isTransferPhaseTimeoutError(error: unknown): boolean { - return error instanceof AppError && error.details?.reason === TRANSFER_PHASE_TIMEOUT_REASON; -} - -/** What `observeClientRequestPhases` reports and owns for one outgoing request. */ -export type ClientRequestPhases = { - /** Whether the response has started. Request-side events no longer move the phase after this. */ - readonly responseStarted: boolean; - /** Removes every listener the observer added. Call it once the exchange is settled. */ - dispose(): void; -}; - -/** - * Drives `watchdog` through the phases of ONE outgoing `node:http` request. - * - * The caller arms `connect` before issuing the request. From the events that follow, this owner - * decides the phase the exchange is in: - * - A fresh socket is not a connection until `connect`, or `secureConnect` for TLS. A pooled socket - * already is. Until then the connect ceiling keeps counting, even when the whole body already sits - * in the write buffer, because buffered bytes are not transport progress. - * - A connected exchange that is still writing is in `request-body`. `drain` is the progress that - * restarts its inactivity budget, since it reports bytes the socket actually accepted. - * - The header wait starts only after BOTH the request `finish` and the connection. - * - Once the response starts, the exchange is in `response-body` and no later request event can - * overwrite it. The caller reports response bytes with `touchBody`. - * - * Attach it in the tick that creates the request. It waits on nothing: every listener it adds is - * removed by `dispose`. - */ -export function observeClientRequestPhases( - req: ClientRequest, - watchdog: TransferPhaseWatchdog, -): ClientRequestPhases { - let established = false; - let flushed = false; - let responseStarted = false; - let socket: Socket | undefined; - let connectEvent: 'connect' | 'secureConnect' | undefined; - const advance = () => { - if (responseStarted || watchdog.signal.aborted || !established) return; - if (flushed) { - watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - } else { - watchdog.arm('request-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - } - }; - const onConnected = () => { - established = true; - advance(); - }; - const onSocket = (next: Socket) => { - if (!next.connecting) { - established = true; - advance(); - return; - } - socket = next; - const secured = (next as { encrypted?: boolean }).encrypted === true; - connectEvent = secured ? 'secureConnect' : 'connect'; - next.once(connectEvent, onConnected); - }; - const onDrain = () => { - if (!responseStarted) watchdog.touchBody(); - }; - const onFinish = () => { - flushed = true; - advance(); - }; - const onResponse = () => { - responseStarted = true; - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - }; - req.on('socket', onSocket); - req.on('drain', onDrain); - req.on('finish', onFinish); - // The request's own response callback is registered first, so the phase has to move before it runs. - req.prependListener('response', onResponse); - return { - get responseStarted() { - return responseStarted; - }, - dispose() { - req.off('socket', onSocket); - req.off('drain', onDrain); - req.off('finish', onFinish); - req.off('response', onResponse); - if (socket && connectEvent) socket.off(connectEvent, onConnected); - }, - }; -} diff --git a/packages/host-kit/src/internal/transfer-phase.test.ts b/packages/host-kit/src/internal/transport-phases.test.ts similarity index 98% rename from packages/host-kit/src/internal/transfer-phase.test.ts rename to packages/host-kit/src/internal/transport-phases.test.ts index 4ca08704b0..f9d14c95d1 100644 --- a/packages/host-kit/src/internal/transfer-phase.test.ts +++ b/packages/host-kit/src/internal/transport-phases.test.ts @@ -18,7 +18,7 @@ import { TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, TRANSFER_CONNECT_TIMEOUT_MS, TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, -} from './transfer-phase.ts'; +} from './transport.ts'; afterEach(() => { vi.useRealTimers(); @@ -318,11 +318,7 @@ test('a pooled socket is already connected and times the body write as inactivit await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); assert.equal(watchdog.signal.aborted, false); await vi.advanceTimersByTimeAsync(1); - assertPhaseDetails( - watchdog.signal.reason, - 'request-body', - TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, - ); + assertPhaseDetails(watchdog.signal.reason, 'request-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); } finally { watchdog.dispose(); } diff --git a/packages/host-kit/src/internal/transport.ts b/packages/host-kit/src/internal/transport.ts index 8e4a1351b1..8b0a96d40d 100644 --- a/packages/host-kit/src/internal/transport.ts +++ b/packages/host-kit/src/internal/transport.ts @@ -1,6 +1,7 @@ import crypto from 'node:crypto'; import { types } from 'node:util'; import type { ClientRequest, IncomingMessage } from 'node:http'; +import type { Socket } from 'node:net'; import { AppError } from '@agent-device/kernel/errors'; export function consumeTextLines( @@ -137,3 +138,207 @@ export function observeCompletedRequestWrites( else Reflect.deleteProperty(req, 'write'); }; } + +/** + * Ceiling for establishing the connection one artifact-transfer attempt runs on. + * + * Kept beside its domain rather than on the socket: the same number governs every hop of an upload, + * every offset resume and a standalone artifact download, so "how long may one hop take to connect" + * has exactly one answer. + */ +export const TRANSFER_CONNECT_TIMEOUT_MS = 30_000; + +/** + * Ceiling for waiting on response headers once this side has written everything the server is + * waiting for. For an upload that is the moment its outgoing request body is fully flushed, never + * the moment the request was created; for a bodyless request it is connection establishment. + */ +export const TRANSFER_RESPONSE_HEADER_TIMEOUT_MS = 30_000; + +/** + * Ceiling for silence between body bytes in either direction. Bytes actually written or read reset + * it, so an artifact that keeps moving keeps its budget while a connection that stopped carrying + * bytes does not. Progress never touches the aggregate budget the attempt runs under. + */ +export const TRANSFER_BODY_INACTIVITY_TIMEOUT_MS = 120_000; + +export type TransferPhase = 'connect' | 'request-body' | 'response-headers' | 'response-body' | 'preflight' | 'finalize'; + +const BODY_PHASES: ReadonlySet = new Set(['request-body', 'response-body']); + +/** The `details.reason` every phase expiry carries, so no consumer has to match error text. */ +const TRANSFER_PHASE_TIMEOUT_REASON = 'transfer_phase_timeout'; + +/** + * Watches the sequential phases of ONE transfer attempt. + * + * One attempt gets one watchdog: arming a later phase stops counting the earlier one, so the ceiling + * that applies is always the phase the transfer is actually in. Progress re-arms only the two body + * phases. Nothing here extends an enclosing aggregate budget — the caller's signal is combined in, + * never replaced, so the earliest deadline still wins and every attempt, redirect and resume keeps + * sharing the original aggregate. + */ +export type TransferPhaseWatchdog = { + /** The signal the attempt runs on: the caller's cancellation plus every phase deadline. */ + signal: AbortSignal; + /** Starts watching `phase` and resumes phase timing if it was suspended. The phase watched before stops counting. */ + arm(phase: TransferPhase, timeoutMs: number): void; + /** Records body bytes moving, so only the silence since the last byte counts against a body phase. */ + touchBody(): void; + /** + * Stops the armed phase's timer while this side owes the peer nothing, such as a consumer that has + * not asked for more bytes. The attempt stays live: the signal, the caller's cancellation and any + * enclosing aggregate are untouched, and late progress does not restart the timer. Only `arm` + * resumes phase timing. Unlike `dispose`, it does not mean the attempt is settled. + */ + suspend(): void; + /** Stops the armed timer. Call it once the attempt is settled. */ + dispose(): void; +}; + +export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): TransferPhaseWatchdog { + const phase = new AbortController(); + const signal = callerSignal ? AbortSignal.any([callerSignal, phase.signal]) : phase.signal; + let armed: { phase: TransferPhase; timeoutMs: number } | undefined; + let timer: ReturnType | undefined; + let suspended = false; + const rearm = () => { + if (timer !== undefined) clearTimeout(timer); + timer = undefined; + const current = armed; + if (!current || suspended) return; + timer = setTimeout(() => { + timer = undefined; + phase.abort(createTransferPhaseTimeoutError(current.phase, current.timeoutMs)); + }, current.timeoutMs); + timer.unref(); + }; + return { + signal, + arm(nextPhase, timeoutMs) { + if (signal.aborted) return; + armed = { phase: nextPhase, timeoutMs }; + suspended = false; + rearm(); + }, + touchBody() { + // Unrelated headers, keepalive traffic and timer callbacks are not body progress, and + // progress in one phase buys no time in another: only a body phase already armed re-arms. + if (!armed || !BODY_PHASES.has(armed.phase)) return; + rearm(); + }, + suspend() { + suspended = true; + rearm(); + }, + dispose() { + armed = undefined; + if (timer !== undefined) clearTimeout(timer); + timer = undefined; + }, + }; +} + +/** + * Typed evidence that a transfer phase, rather than the caller or the whole preparation aggregate, + * ended the attempt. The expired phase and its effective budget travel in `details`. + */ +function createTransferPhaseTimeoutError(phase: TransferPhase, timeoutMs: number): AppError { + return new AppError('COMMAND_FAILED', `Artifact transfer ${phase} timed out`, { + reason: TRANSFER_PHASE_TIMEOUT_REASON, + transferPhase: phase, + timeoutMs, + }); +} + +/** Whether `error` is a transfer phase's own expiry, which no fallback or retry may restart. */ +export function isTransferPhaseTimeoutError(error: unknown): boolean { + return error instanceof AppError && error.details?.reason === TRANSFER_PHASE_TIMEOUT_REASON; +} + +/** What `observeClientRequestPhases` reports and owns for one outgoing request. */ +export type ClientRequestPhases = { + /** Whether the response has started. Request-side events no longer move the phase after this. */ + readonly responseStarted: boolean; + /** Removes every listener the observer added. Call it once the exchange is settled. */ + dispose(): void; +}; + +/** + * Drives `watchdog` through the phases of ONE outgoing `node:http` request. + * + * The caller arms `connect` before issuing the request. From the events that follow, this owner + * decides the phase the exchange is in: + * - A fresh socket is not a connection until `connect`, or `secureConnect` for TLS. A pooled socket + * already is. Until then the connect ceiling keeps counting, even when the whole body already sits + * in the write buffer, because buffered bytes are not transport progress. + * - A connected exchange that is still writing is in `request-body`. `drain` is the progress that + * restarts its inactivity budget, since it reports bytes the socket actually accepted. + * - The header wait starts only after BOTH the request `finish` and the connection. + * - Once the response starts, the exchange is in `response-body` and no later request event can + * overwrite it. The caller reports response bytes with `touchBody`. + * + * Attach it in the tick that creates the request. It waits on nothing: every listener it adds is + * removed by `dispose`. + */ +export function observeClientRequestPhases( + req: ClientRequest, + watchdog: TransferPhaseWatchdog, +): ClientRequestPhases { + let established = false; + let flushed = false; + let responseStarted = false; + let socket: Socket | undefined; + let connectEvent: 'connect' | 'secureConnect' | undefined; + const advance = () => { + if (responseStarted || watchdog.signal.aborted || !established) return; + if (flushed) { + watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + } else { + watchdog.arm('request-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + } + }; + const onConnected = () => { + established = true; + advance(); + }; + const onSocket = (next: Socket) => { + if (!next.connecting) { + established = true; + advance(); + return; + } + socket = next; + const secured = (next as { encrypted?: boolean }).encrypted === true; + connectEvent = secured ? 'secureConnect' : 'connect'; + next.once(connectEvent, onConnected); + }; + const onDrain = () => { + if (!responseStarted) watchdog.touchBody(); + }; + const onFinish = () => { + flushed = true; + advance(); + }; + const onResponse = () => { + responseStarted = true; + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + }; + req.on('socket', onSocket); + req.on('drain', onDrain); + req.on('finish', onFinish); + // The request's own response callback is registered first, so the phase has to move before it runs. + req.prependListener('response', onResponse); + return { + get responseStarted() { + return responseStarted; + }, + dispose() { + req.off('socket', onSocket); + req.off('drain', onDrain); + req.off('finish', onFinish); + req.off('response', onResponse); + if (socket && connectEvent) socket.off(connectEvent, onConnected); + }, + }; +} diff --git a/packages/host-kit/src/transport.ts b/packages/host-kit/src/transport.ts index 23c9daaf19..16202f2ff3 100644 --- a/packages/host-kit/src/transport.ts +++ b/packages/host-kit/src/transport.ts @@ -1,22 +1,13 @@ export { consumeTextLines, + createTransferPhaseWatchdog, + isTransferPhaseTimeoutError, loadNodeHttpRequester, + observeClientRequestPhases, observeCompletedRequestWrites, readNodeHttpRequestBody, readNodeHttpResponseBody, timingSafeStringEqual, + TRANSFER_CONNECT_TIMEOUT_MS, type NodeHttpRequester, } from './internal/transport.ts'; -export { - createTransferPhaseTimeoutError, - createTransferPhaseWatchdog, - isTransferPhaseTimeoutError, - observeClientRequestPhases, - TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, - TRANSFER_CONNECT_TIMEOUT_MS, - TRANSFER_PHASE_TIMEOUT_REASON, - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - type ClientRequestPhases, - type TransferPhase, - type TransferPhaseWatchdog, -} from './internal/transfer-phase.ts'; From b9b226f9ecde474a89885cea9dbb512117ec6307 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 15:44:14 +0100 Subject: [PATCH 03/14] chore(gates): acknowledge the host-kit phase observer in the upload attempt wire digest Moving the outgoing-request phase observation into host-kit/transport and retiring it per attempt changed streamFileToHttpRequestAttempt's digest without a ledger update. The digest is the one wire-compat.test.ts prints for the current source; requests on the wire are unchanged. Co-Authored-By: Claude Opus 5.5 --- test/wire-compat/ledger.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 98ffb5dd36..c2f84ff9b2 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -496,8 +496,8 @@ }, { "declaration": "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt", - "digest": "sha256:1a4b994c3ac2cf89e01e9c56526a5c9a0356fb8de425a248d062bd1cd67686b8", - "rationale": "#4441 keeps each attempt under its sequential phase watchdog and corrects its transport lifecycle: the connect ceiling now ends at actual socket or TLS-handshake establishment, body progress counts only transport writes, and an early response reads the accepted answer to its end, then destroys and joins the owned file/request pipeline and retires this attempt's phase watchdog before resolving or starting the redirect/resume attempt, so a completed hop's timers never reach the next hop. Bytes on the wire are unchanged: same route, method, headers, body framing, resume-offset handling and redirect limit. Only this client's own sequencing and deadlines moved, so a protocol-2 peer parses exactly what it parsed before. Request-body progress is now each non-empty request write that completes without an error, which Node reports once the bytes reach the local kernel, instead of drain, which fires only after a write returned false. The write wrapper passes every argument and the backpressure result through, so the bytes and framing on the wire do not change. That completed-write observer is host-kit's transport owner, which also stops reporting after the response starts, the signal aborts or the request is destroyed; no request changes. The response-header ceiling starts at connected request finish, without waiting for or rearming after source-file close. This changes local deadline timing only; URL, method, credentials, body, redirects, resume headers and response framing are unchanged." + "digest": "sha256:3447b4c74b58d84c2cc785572ea14374ae80df24902e666fd642a537c41af33e", + "rationale": "#4441 keeps each attempt under its sequential phase watchdog and corrects its transport lifecycle: the connect ceiling now ends at actual socket or TLS-handshake establishment, body progress counts only transport writes, and an early response reads the accepted answer to its end, then destroys and joins the owned file/request pipeline and retires this attempt's phase watchdog before resolving or starting the redirect/resume attempt, so a completed hop's timers never reach the next hop. The outgoing-request phase observation now comes from @agent-device/host-kit/transport's observeClientRequestPhases, which listens to the same socket, TLS-handshake and finish events and is removed when the attempt settles. Bytes on the wire are unchanged: same route, method, headers, body framing, resume-offset handling and redirect limit. Only this client's own sequencing and deadlines moved, so a protocol-2 peer parses exactly what it parsed before. Request-body progress is now each non-empty request write that completes without an error, which Node reports once the bytes reach the local kernel, instead of drain, which fires only after a write returned false. The write wrapper passes every argument and the backpressure result through, so the bytes and framing on the wire do not change. That completed-write observer is host-kit's transport owner, which also stops reporting after the response starts, the signal aborts or the request is destroyed; no request changes." }, { "declaration": "packages/remote/src/daemon-artifacts.ts#resolveMaterializedArtifactPath", From 731c3d6dc358a336e34a25829a9f19d4d85f3c38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 15:46:41 +0100 Subject: [PATCH 04/14] docs(agents): drop the transfer-phase ownership line that overflows the agent-docs budget docs/agents was 40081 bytes against the 40000-byte guidance budget. The one module that owns transfer phase budgets and its host-kit/transport export already state that ownership. Co-Authored-By: Claude Opus 5.5 --- docs/agents/code-ownership.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/agents/code-ownership.md b/docs/agents/code-ownership.md index 3bad123acc..e9b65ea372 100644 --- a/docs/agents/code-ownership.md +++ b/docs/agents/code-ownership.md @@ -22,7 +22,6 @@ For SDK entries `android-adb`, `artifacts`, `limrun`, `metro`, and `remote-confi For command-host readers, use `withSdkHost`. Keep provider callbacks on their supplied host. Request cancellation and progress belong in `@agent-device/host-kit/request`. -Outbound artifact-transfer phase budgets and the node:http phase observer belong in `@agent-device/host-kit/transport`. Per-call abort guards belong beside transports in `packages/daemon-client/src/daemon-client-transport.ts`. Contracts shared across layers belong in `packages/contracts/src`. Schema composition belongs in `packages/command-surface/src/schema`. From a889020206fe4df1b9b69b8aa9d084d581011394 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 17:04:42 +0100 Subject: [PATCH 05/14] refactor(transport): keep phase surface limited to current consumers --- .../src/internal/transport-phases.test.ts | 85 +------------------ packages/host-kit/src/internal/transport.ts | 25 +----- 2 files changed, 4 insertions(+), 106 deletions(-) diff --git a/packages/host-kit/src/internal/transport-phases.test.ts b/packages/host-kit/src/internal/transport-phases.test.ts index f9d14c95d1..dbdb72c07c 100644 --- a/packages/host-kit/src/internal/transport-phases.test.ts +++ b/packages/host-kit/src/internal/transport-phases.test.ts @@ -150,6 +150,7 @@ test('a phase is never armed after the attempt is already over', async () => { const late = createTransferPhaseWatchdog(caller.signal); try { late.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + assert.equal(vi.getTimerCount(), 0); await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS * 2); assert.equal(late.signal.reason.message, 'gone'); } finally { @@ -160,90 +161,6 @@ test('a phase is never armed after the attempt is already over', async () => { } }); -test('a suspended phase is not charged while nothing is owed, and the attempt stays live', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const caller = new AbortController(); - const watchdog = createTransferPhaseWatchdog(caller.signal); - try { - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); - watchdog.suspend(); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS * 5); - // Suspension is not settlement: nothing aborted, neither the attempt nor the caller's signal. - assert.equal(watchdog.signal.aborted, false); - assert.equal(caller.signal.aborted, false); - } finally { - watchdog.dispose(); - } -}); - -test('late progress does not rearm a suspended timer', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - watchdog.suspend(); - watchdog.touchBody(); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS * 3); - assert.equal(watchdog.signal.aborted, false); - } finally { - watchdog.dispose(); - } -}); - -test('arming resumes a suspended phase with a fresh full ceiling', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - watchdog.suspend(); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS * 2); - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); - assert.equal(watchdog.signal.aborted, false); - // Progress restarts the resumed phase again, so suspension left no residue. - watchdog.touchBody(); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); - assert.equal(watchdog.signal.aborted, false); - await vi.advanceTimersByTimeAsync(1); - assertPhaseDetails( - watchdog.signal.reason, - 'response-body', - TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); - } -}); - -test('a caller cancellation still ends a suspended attempt with the caller reason', () => { - const caller = new AbortController(); - const watchdog = createTransferPhaseWatchdog(caller.signal); - try { - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - watchdog.suspend(); - const reason = new Error('caller left'); - caller.abort(reason); - assert.equal(watchdog.signal.aborted, true); - assert.equal(watchdog.signal.reason, reason); - } finally { - watchdog.dispose(); - } -}); - -test('suspending twice or before any phase is armed is harmless', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.suspend(); - watchdog.suspend(); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS * 2); - assert.equal(watchdog.signal.aborted, false); - } finally { - watchdog.dispose(); - } -}); - type FakeSocket = EventEmitter & { connecting: boolean; encrypted?: boolean }; function createObservedRequest(callerSignal?: AbortSignal) { diff --git a/packages/host-kit/src/internal/transport.ts b/packages/host-kit/src/internal/transport.ts index 8b0a96d40d..3c1951fccb 100644 --- a/packages/host-kit/src/internal/transport.ts +++ b/packages/host-kit/src/internal/transport.ts @@ -139,13 +139,7 @@ export function observeCompletedRequestWrites( }; } -/** - * Ceiling for establishing the connection one artifact-transfer attempt runs on. - * - * Kept beside its domain rather than on the socket: the same number governs every hop of an upload, - * every offset resume and a standalone artifact download, so "how long may one hop take to connect" - * has exactly one answer. - */ +/** Ceiling for establishing the connection for each upload hop or offset resume. */ export const TRANSFER_CONNECT_TIMEOUT_MS = 30_000; /** @@ -181,17 +175,10 @@ const TRANSFER_PHASE_TIMEOUT_REASON = 'transfer_phase_timeout'; export type TransferPhaseWatchdog = { /** The signal the attempt runs on: the caller's cancellation plus every phase deadline. */ signal: AbortSignal; - /** Starts watching `phase` and resumes phase timing if it was suspended. The phase watched before stops counting. */ + /** Starts watching `phase`. The phase watched before stops counting. */ arm(phase: TransferPhase, timeoutMs: number): void; /** Records body bytes moving, so only the silence since the last byte counts against a body phase. */ touchBody(): void; - /** - * Stops the armed phase's timer while this side owes the peer nothing, such as a consumer that has - * not asked for more bytes. The attempt stays live: the signal, the caller's cancellation and any - * enclosing aggregate are untouched, and late progress does not restart the timer. Only `arm` - * resumes phase timing. Unlike `dispose`, it does not mean the attempt is settled. - */ - suspend(): void; /** Stops the armed timer. Call it once the attempt is settled. */ dispose(): void; }; @@ -201,12 +188,11 @@ export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): Transfe const signal = callerSignal ? AbortSignal.any([callerSignal, phase.signal]) : phase.signal; let armed: { phase: TransferPhase; timeoutMs: number } | undefined; let timer: ReturnType | undefined; - let suspended = false; const rearm = () => { if (timer !== undefined) clearTimeout(timer); timer = undefined; const current = armed; - if (!current || suspended) return; + if (!current) return; timer = setTimeout(() => { timer = undefined; phase.abort(createTransferPhaseTimeoutError(current.phase, current.timeoutMs)); @@ -218,7 +204,6 @@ export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): Transfe arm(nextPhase, timeoutMs) { if (signal.aborted) return; armed = { phase: nextPhase, timeoutMs }; - suspended = false; rearm(); }, touchBody() { @@ -227,10 +212,6 @@ export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): Transfe if (!armed || !BODY_PHASES.has(armed.phase)) return; rearm(); }, - suspend() { - suspended = true; - rearm(); - }, dispose() { armed = undefined; if (timer !== undefined) clearTimeout(timer); From d7d1be7c2f287fe51670a857cc50c97014bd8ecd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 18:37:07 +0100 Subject: [PATCH 06/14] fix(transport): compose the host-kit write owner beside the phase owner The outgoing-request phase observer stops treating drain as body progress and owns only the connection, flush and response phases. The upload attempt composes it with host-kit's observeCompletedRequestWrites once per request and disposes both at every settlement. Generic write cases live with the write owner; the phase suite keeps the composition cases. Co-Authored-By: Claude Opus 5.5 --- .../src/internal/transport-phases.test.ts | 68 ++++++++++++------- packages/host-kit/src/internal/transport.ts | 14 ++-- 2 files changed, 49 insertions(+), 33 deletions(-) diff --git a/packages/host-kit/src/internal/transport-phases.test.ts b/packages/host-kit/src/internal/transport-phases.test.ts index dbdb72c07c..8a61d4656c 100644 --- a/packages/host-kit/src/internal/transport-phases.test.ts +++ b/packages/host-kit/src/internal/transport-phases.test.ts @@ -1,10 +1,5 @@ -// The phase budget one artifact-transfer attempt runs under (#4441). -// -// Three ceilings govern one attempt — connecting, moving body bytes, waiting for headers — and each -// has to end a stalled attempt on its own while none of them touches the aggregate budget the -// attempt was admitted under. Those are behaviour claims about a clock, so the clock here is -// controlled rather than waited out. The loopback proofs in `upload-stream-phases.test.ts` put the -// same watchdog in front of real sockets. +// The phase budget of one artifact-transfer attempt (#4441), on a controlled clock. Each ceiling ends a +// stalled attempt on its own, and none of them touches the aggregate the attempt was admitted under. import assert from 'node:assert/strict'; import { EventEmitter } from 'node:events'; @@ -15,6 +10,7 @@ import { createTransferPhaseWatchdog, isTransferPhaseTimeoutError, observeClientRequestPhases, + observeCompletedRequestWrites, TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, TRANSFER_CONNECT_TIMEOUT_MS, TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, @@ -163,16 +159,35 @@ test('a phase is never armed after the attempt is already over', async () => { type FakeSocket = EventEmitter & { connecting: boolean; encrypted?: boolean }; -function createObservedRequest(callerSignal?: AbortSignal) { - const req = new EventEmitter() as unknown as ClientRequest; - const watchdog = createTransferPhaseWatchdog(callerSignal); +/** A request whose writes the test completes by hand, as Node does once a chunk reaches the kernel. */ +class FakeRequest extends EventEmitter { + destroyed = false; + readonly callbacks: unknown[] = []; + write(...args: unknown[]): boolean { + this.callbacks.push(args.find((arg) => typeof arg === 'function')); + return true; + } + complete(index: number): void { + const callback = this.callbacks[index]; + assert.ok(typeof callback === 'function', `write ${index} has no callback`); + callback(null); + } +} + +/** One request observed as the upload attempt observes it: the phase owner beside the write owner. */ +function createObservedRequest() { + const fake = new FakeRequest(); + const watchdog = createTransferPhaseWatchdog(); watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); + const req = fake as unknown as ClientRequest; const phases = observeClientRequestPhases(req, watchdog); - const emit = (event: string, ...args: unknown[]) => - (req as unknown as EventEmitter).emit(event, ...args); + const stopObservingWrites = observeCompletedRequestWrites(req, watchdog.signal, () => + watchdog.touchBody(), + ); + const emit = (event: string, ...args: unknown[]) => fake.emit(event, ...args); const socket = (state: { connecting: boolean; encrypted?: boolean }): FakeSocket => Object.assign(new EventEmitter(), state); - return { req, watchdog, phases, emit, socket }; + return { fake, req, watchdog, phases, stopObservingWrites, emit, socket }; } test('a fresh socket keeps the connect ceiling until it connects, even after the body flushed', async () => { @@ -227,11 +242,12 @@ test('a TLS socket is established by secureConnect, not connect', async () => { test('a pooled socket is already connected and times the body write as inactivity', async () => { vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const { watchdog, emit, socket } = createObservedRequest(); + const { fake, req, watchdog, emit, socket } = createObservedRequest(); try { emit('socket', socket({ connecting: false })); + req.write(Buffer.from('body')); await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); - emit('drain'); + fake.complete(0); await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); assert.equal(watchdog.signal.aborted, false); await vi.advanceTimersByTimeAsync(1); @@ -243,16 +259,19 @@ test('a pooled socket is already connected and times the body write as inactivit test('once the response started, later request events do not overwrite its phase', async () => { vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const { watchdog, phases, emit, socket } = createObservedRequest(); + const { fake, req, watchdog, phases, emit, socket } = createObservedRequest(); try { const fresh = socket({ connecting: true }); emit('socket', fresh); + req.write(Buffer.from('body')); emit('response'); assert.equal(phases.responseStarted, true); fresh.emit('connect'); emit('finish'); - emit('drain'); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS + 1); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); + // A request write that completes now says nothing about the response body. + fake.complete(0); + await vi.advanceTimersByTimeAsync(1_001); assertPhaseDetails( watchdog.signal.reason, 'response-body', @@ -263,17 +282,18 @@ test('once the response started, later request events do not overwrite its phase } }); -test('disposing the observer removes every listener it added', () => { - const { req, watchdog, phases, emit, socket } = createObservedRequest(); +test('disposing the phase observer removes only its own listeners', () => { + const { fake, watchdog, phases, stopObservingWrites, emit, socket } = createObservedRequest(); try { const fresh = socket({ connecting: true }); emit('socket', fresh); phases.dispose(); - const emitter = req as unknown as EventEmitter; - for (const event of ['socket', 'drain', 'finish', 'response']) { - assert.equal(emitter.listenerCount(event), 0, event); - } + assert.equal(fake.listenerCount('socket'), 0); + assert.equal(fake.listenerCount('finish'), 0); assert.equal(fresh.listenerCount('connect'), 0); + assert.equal(fake.listenerCount('response'), 1, "the write owner's listener is its own"); + stopObservingWrites(); + assert.equal(fake.listenerCount('response'), 0); } finally { watchdog.dispose(); } diff --git a/packages/host-kit/src/internal/transport.ts b/packages/host-kit/src/internal/transport.ts index 3c1951fccb..5ff95751a3 100644 --- a/packages/host-kit/src/internal/transport.ts +++ b/packages/host-kit/src/internal/transport.ts @@ -253,14 +253,15 @@ export type ClientRequestPhases = { * - A fresh socket is not a connection until `connect`, or `secureConnect` for TLS. A pooled socket * already is. Until then the connect ceiling keeps counting, even when the whole body already sits * in the write buffer, because buffered bytes are not transport progress. - * - A connected exchange that is still writing is in `request-body`. `drain` is the progress that - * restarts its inactivity budget, since it reports bytes the socket actually accepted. + * - A connected exchange that is still writing is in `request-body`. Only the body progress the + * caller reports with `touchBody`, such as `observeCompletedRequestWrites` completions, restarts + * its inactivity budget. * - The header wait starts only after BOTH the request `finish` and the connection. * - Once the response starts, the exchange is in `response-body` and no later request event can * overwrite it. The caller reports response bytes with `touchBody`. * - * Attach it in the tick that creates the request. It waits on nothing: every listener it adds is - * removed by `dispose`. + * Attach it in the tick that creates the request. It waits on nothing: `dispose` removes every + * listener it adds. */ export function observeClientRequestPhases( req: ClientRequest, @@ -294,9 +295,6 @@ export function observeClientRequestPhases( connectEvent = secured ? 'secureConnect' : 'connect'; next.once(connectEvent, onConnected); }; - const onDrain = () => { - if (!responseStarted) watchdog.touchBody(); - }; const onFinish = () => { flushed = true; advance(); @@ -306,7 +304,6 @@ export function observeClientRequestPhases( watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); }; req.on('socket', onSocket); - req.on('drain', onDrain); req.on('finish', onFinish); // The request's own response callback is registered first, so the phase has to move before it runs. req.prependListener('response', onResponse); @@ -316,7 +313,6 @@ export function observeClientRequestPhases( }, dispose() { req.off('socket', onSocket); - req.off('drain', onDrain); req.off('finish', onFinish); req.off('response', onResponse); if (socket && connectEvent) socket.off(connectEvent, onConnected); From 717fceb0d526a9b69693af56490530285a4af6ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 18:37:44 +0100 Subject: [PATCH 07/14] chore(gates): acknowledge the composed write and phase owners in the upload attempt digest Co-Authored-By: Claude Opus 5.5 --- test/wire-compat/ledger.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index c2f84ff9b2..51e3ad8c16 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -182,7 +182,7 @@ "packages/remote/src/upload-stream.ts#parseNonNegativeIntegerHeader": "sha256:5cbe9c6994459d673d988a51407e65556e28175b187ce0a9d27cbb6331962834", "packages/remote/src/upload-stream.ts#parseUploadResumeOffset": "sha256:297184ea22a6dc1cda9aee17034122ae0ea2f43d0355647f6fcf02f3f4b5ca0e", "packages/remote/src/upload-stream.ts#streamFileToHttpRequest": "sha256:c2b5e1369c8b1c9420036e23163d21e43fa2ac8b889c6a8f028cc6095055a16f", - "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt": "sha256:1a4b994c3ac2cf89e01e9c56526a5c9a0356fb8de425a248d062bd1cd67686b8", + "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt": "sha256:1d3dfa85e45dafd39bd69ab8bb597d851e95d2f4c99b70f2cee65c7f4c688a7c", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_INSTANCE_HEADER": "sha256:d2bb3f4846470188a0fc1724271da0f0bcbdf2337bd6bf331508142cadcb65d8", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_UPSTREAM_INSTANCE_HEADER": "sha256:4564c2ce437d30d7a823e3326f4375c0750ba8d42bec22b4d02e8eb7f7db2973", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_INSTANCE_MISMATCH_HEADER": "sha256:a197edaf7f9fa94a6aab269856aa852da3204cc586f5fd23198689eb11908b61", @@ -496,8 +496,8 @@ }, { "declaration": "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt", - "digest": "sha256:3447b4c74b58d84c2cc785572ea14374ae80df24902e666fd642a537c41af33e", - "rationale": "#4441 keeps each attempt under its sequential phase watchdog and corrects its transport lifecycle: the connect ceiling now ends at actual socket or TLS-handshake establishment, body progress counts only transport writes, and an early response reads the accepted answer to its end, then destroys and joins the owned file/request pipeline and retires this attempt's phase watchdog before resolving or starting the redirect/resume attempt, so a completed hop's timers never reach the next hop. The outgoing-request phase observation now comes from @agent-device/host-kit/transport's observeClientRequestPhases, which listens to the same socket, TLS-handshake and finish events and is removed when the attempt settles. Bytes on the wire are unchanged: same route, method, headers, body framing, resume-offset handling and redirect limit. Only this client's own sequencing and deadlines moved, so a protocol-2 peer parses exactly what it parsed before. Request-body progress is now each non-empty request write that completes without an error, which Node reports once the bytes reach the local kernel, instead of drain, which fires only after a write returned false. The write wrapper passes every argument and the backpressure result through, so the bytes and framing on the wire do not change. That completed-write observer is host-kit's transport owner, which also stops reporting after the response starts, the signal aborts or the request is destroyed; no request changes." + "digest": "sha256:1d3dfa85e45dafd39bd69ab8bb597d851e95d2f4c99b70f2cee65c7f4c688a7c", + "rationale": "#4441 keeps each attempt under its sequential phase watchdog and corrects its transport lifecycle: the connect ceiling now ends at actual socket or TLS-handshake establishment, body progress counts only transport writes, and an early response reads the accepted answer to its end, then destroys and joins the owned file/request pipeline and retires this attempt's phase watchdog before resolving or starting the redirect/resume attempt, so a completed hop's timers never reach the next hop. The outgoing-request phase observation now comes from @agent-device/host-kit/transport's observeClientRequestPhases, which listens to the same socket, TLS-handshake and finish events and is removed when the attempt settles. Bytes on the wire are unchanged: same route, method, headers, body framing, resume-offset handling and redirect limit. Only this client's own sequencing and deadlines moved, so a protocol-2 peer parses exactly what it parsed before. Request-body progress is now each non-empty request write that completes without an error, which Node reports once the bytes reach the local kernel, instead of drain, which fires only after a write returned false. The write wrapper passes every argument and the backpressure result through, so the bytes and framing on the wire do not change. That completed-write observer is host-kit's transport owner, which also stops reporting after the response starts, the signal aborts or the request is destroyed; no request changes. The attempt composes that write owner with the phase observer once per request and disposes both when it settles." }, { "declaration": "packages/remote/src/daemon-artifacts.ts#resolveMaterializedArtifactPath", From b8a74f6c0c88bba37c8b65488936078795b3cda0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 18:42:06 +0100 Subject: [PATCH 08/14] test(transport): dispose phase-suite watchdogs with their test The phase suite installs its controlled clock once per test and disposes every watchdog when its test finishes; the phase and watchdog docs say what the code does without repeating it. Co-Authored-By: Claude Opus 5.5 --- .../src/internal/transport-phases.test.ts | 318 +++++++----------- packages/host-kit/src/internal/transport.ts | 28 +- 2 files changed, 138 insertions(+), 208 deletions(-) diff --git a/packages/host-kit/src/internal/transport-phases.test.ts b/packages/host-kit/src/internal/transport-phases.test.ts index 8a61d4656c..e066a8919b 100644 --- a/packages/host-kit/src/internal/transport-phases.test.ts +++ b/packages/host-kit/src/internal/transport-phases.test.ts @@ -4,7 +4,7 @@ import assert from 'node:assert/strict'; import { EventEmitter } from 'node:events'; import type { ClientRequest } from 'node:http'; -import { afterEach, test, vi } from 'vitest'; +import { afterEach, beforeEach, onTestFinished, test, vi } from 'vitest'; import { AppError } from '@agent-device/kernel/errors'; import { createTransferPhaseWatchdog, @@ -14,12 +14,24 @@ import { TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, TRANSFER_CONNECT_TIMEOUT_MS, TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + type TransferPhaseWatchdog, } from './transport.ts'; +beforeEach(() => { + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); +}); + afterEach(() => { vi.useRealTimers(); }); +/** A watchdog disposed when its test finishes. */ +function watchPhases(callerSignal?: AbortSignal): TransferPhaseWatchdog { + const watchdog = createTransferPhaseWatchdog(callerSignal); + onTestFinished(() => watchdog.dispose()); + return watchdog; +} + test('the three transfer ceilings are the adopted policy values', () => { assert.equal(TRANSFER_CONNECT_TIMEOUT_MS, 30_000); assert.equal(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, 30_000); @@ -27,109 +39,79 @@ test('the three transfer ceilings are the adopted policy values', () => { }); test('a body phase restarts its ceiling on every byte that moves', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - // Three full ceilings' worth of wall clock, each broken by real progress: 300 seconds of a slow - // artifact is admitted work, and nothing here may end it. - for (const _ of [0, 1, 2]) { - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 20_000); - watchdog.touchBody(); - } - assert.equal(watchdog.signal.aborted, false); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS + 1); - assert.equal(watchdog.signal.aborted, true); - assertPhaseDetails( - watchdog.signal.reason, - 'response-body', - TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); + const watchdog = watchPhases(); + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + // Three full ceilings' worth of wall clock, each broken by real progress: 300 seconds of a slow + // artifact is admitted work, and nothing here may end it. + for (const _ of [0, 1, 2]) { + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 20_000); + watchdog.touchBody(); } + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS + 1); + assert.equal(watchdog.signal.aborted, true); + assertPhaseDetails(watchdog.signal.reason, 'response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); }); test('a phase that carries no bytes is not extended by progress reported in another phase', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 10_000); - // Bytes moving elsewhere — an unrelated header, a keepalive, a timer callback — are not the - // response-header wait making progress. - watchdog.touchBody(); - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - assertPhaseDetails( - watchdog.signal.reason, - 'response-headers', - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); - } + const watchdog = watchPhases(); + watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 10_000); + // Bytes moving elsewhere — an unrelated header, a keepalive, a timer callback — are not the + // response-header wait making progress. + watchdog.touchBody(); + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + assertPhaseDetails( + watchdog.signal.reason, + 'response-headers', + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + ); }); test('arming the next phase stops counting the previous one', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS - 1_000); - watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - // 58 seconds of total attempt time: past the connect ceiling, which the completed hop may spend, - // and inside the header ceiling the attempt is actually waiting on. - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1_000); - assert.equal(watchdog.signal.aborted, false); - await vi.advanceTimersByTimeAsync(1_000); - assertPhaseDetails( - watchdog.signal.reason, - 'response-headers', - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); - } + const watchdog = watchPhases(); + watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS - 1_000); + watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + // 58 seconds of total attempt time: past the connect ceiling, which the completed hop may spend, + // and inside the header ceiling the attempt is actually waiting on. + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1_000); + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(1_000); + assertPhaseDetails( + watchdog.signal.reason, + 'response-headers', + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + ); }); test('an enclosing deadline wins and is never extended by a phase timer', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); const caller = new AbortController(); const reason = new Error('preparation aggregate expired'); setTimeout(() => caller.abort(reason), 5_000); - const watchdog = createTransferPhaseWatchdog(caller.signal); - try { - watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(5_001); - // The caller's reason is the answer, not a phase's own evidence, so a consumer can still tell - // "the work this upload served is gone" from "this transfer stalled". - assert.equal(watchdog.signal.aborted, true); - assert.equal(watchdog.signal.reason, reason); - assert.equal(isTransferPhaseTimeoutError(watchdog.signal.reason), false); - } finally { - watchdog.dispose(); - } + const watchdog = watchPhases(caller.signal); + watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(5_001); + // The caller's reason is the answer, not a phase's own evidence, so a consumer can still tell + // "the work this upload served is gone" from "this transfer stalled". + assert.equal(watchdog.signal.aborted, true); + assert.equal(watchdog.signal.reason, reason); + assert.equal(isTransferPhaseTimeoutError(watchdog.signal.reason), false); }); test('a phase expiry is its own typed evidence and never caller cancellation', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); const caller = new AbortController(); - const watchdog = createTransferPhaseWatchdog(caller.signal); - try { - watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); - assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); - // Distinctness the retry policy depends on: nobody canceled, so the caller's own signal stays - // live and an enclosing aggregate is free to reach a different outcome. - assert.equal(caller.signal.aborted, false); - } finally { - watchdog.dispose(); - } + const watchdog = watchPhases(caller.signal); + watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); + assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); + // Distinctness the retry policy depends on: nobody canceled, so the caller's own signal stays + // live and an enclosing aggregate is free to reach a different outcome. + assert.equal(caller.signal.aborted, false); }); test('a disposed watchdog stops watching', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); + const watchdog = watchPhases(); watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); watchdog.dispose(); await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS * 3); @@ -137,24 +119,15 @@ test('a disposed watchdog stops watching', async () => { }); test('a phase is never armed after the attempt is already over', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); - const watchdog = createTransferPhaseWatchdog(); - try { - watchdog.signal.throwIfAborted(); - const caller = new AbortController(); - caller.abort(new Error('gone')); - const late = createTransferPhaseWatchdog(caller.signal); - try { - late.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - assert.equal(vi.getTimerCount(), 0); - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS * 2); - assert.equal(late.signal.reason.message, 'gone'); - } finally { - late.dispose(); - } - } finally { - watchdog.dispose(); - } + const watchdog = watchPhases(); + watchdog.signal.throwIfAborted(); + const caller = new AbortController(); + caller.abort(new Error('gone')); + const late = watchPhases(caller.signal); + late.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); + assert.equal(vi.getTimerCount(), 0); + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS * 2); + assert.equal(late.signal.reason.message, 'gone'); }); type FakeSocket = EventEmitter & { connecting: boolean; encrypted?: boolean }; @@ -177,7 +150,7 @@ class FakeRequest extends EventEmitter { /** One request observed as the upload attempt observes it: the phase owner beside the write owner. */ function createObservedRequest() { const fake = new FakeRequest(); - const watchdog = createTransferPhaseWatchdog(); + const watchdog = watchPhases(); watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); const req = fake as unknown as ClientRequest; const phases = observeClientRequestPhases(req, watchdog); @@ -191,112 +164,79 @@ function createObservedRequest() { } test('a fresh socket keeps the connect ceiling until it connects, even after the body flushed', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); const { watchdog, emit, socket } = createObservedRequest(); - try { - const fresh = socket({ connecting: true }); - emit('socket', fresh); - emit('finish'); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); - assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); - } finally { - watchdog.dispose(); - } + const fresh = socket({ connecting: true }); + emit('socket', fresh); + emit('finish'); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); + assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); }); test('the header wait starts only after both the flush and the connection', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); const { watchdog, emit, socket } = createObservedRequest(); - try { - const fresh = socket({ connecting: true }); - emit('socket', fresh); - emit('finish'); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS - 1_000); - fresh.emit('connect'); - await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1); - assert.equal(watchdog.signal.aborted, false); - await vi.advanceTimersByTimeAsync(1); - assertPhaseDetails( - watchdog.signal.reason, - 'response-headers', - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); - } + const fresh = socket({ connecting: true }); + emit('socket', fresh); + emit('finish'); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS - 1_000); + fresh.emit('connect'); + await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1); + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(1); + assertPhaseDetails( + watchdog.signal.reason, + 'response-headers', + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + ); }); test('a TLS socket is established by secureConnect, not connect', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); const { watchdog, emit, socket } = createObservedRequest(); - try { - const tls = socket({ connecting: true, encrypted: true }); - emit('socket', tls); - tls.emit('connect'); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); - assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); - } finally { - watchdog.dispose(); - } + const tls = socket({ connecting: true, encrypted: true }); + emit('socket', tls); + tls.emit('connect'); + await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); + assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); }); test('a pooled socket is already connected and times the body write as inactivity', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); const { fake, req, watchdog, emit, socket } = createObservedRequest(); - try { - emit('socket', socket({ connecting: false })); - req.write(Buffer.from('body')); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); - fake.complete(0); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); - assert.equal(watchdog.signal.aborted, false); - await vi.advanceTimersByTimeAsync(1); - assertPhaseDetails(watchdog.signal.reason, 'request-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - } finally { - watchdog.dispose(); - } + emit('socket', socket({ connecting: false })); + req.write(Buffer.from('body')); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); + fake.complete(0); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); + assert.equal(watchdog.signal.aborted, false); + await vi.advanceTimersByTimeAsync(1); + assertPhaseDetails(watchdog.signal.reason, 'request-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); }); test('once the response started, later request events do not overwrite its phase', async () => { - vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); const { fake, req, watchdog, phases, emit, socket } = createObservedRequest(); - try { - const fresh = socket({ connecting: true }); - emit('socket', fresh); - req.write(Buffer.from('body')); - emit('response'); - assert.equal(phases.responseStarted, true); - fresh.emit('connect'); - emit('finish'); - await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); - // A request write that completes now says nothing about the response body. - fake.complete(0); - await vi.advanceTimersByTimeAsync(1_001); - assertPhaseDetails( - watchdog.signal.reason, - 'response-body', - TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, - ); - } finally { - watchdog.dispose(); - } + const fresh = socket({ connecting: true }); + emit('socket', fresh); + req.write(Buffer.from('body')); + emit('response'); + assert.equal(phases.responseStarted, true); + fresh.emit('connect'); + emit('finish'); + await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); + // A request write that completes now says nothing about the response body. + fake.complete(0); + await vi.advanceTimersByTimeAsync(1_001); + assertPhaseDetails(watchdog.signal.reason, 'response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); }); test('disposing the phase observer removes only its own listeners', () => { - const { fake, watchdog, phases, stopObservingWrites, emit, socket } = createObservedRequest(); - try { - const fresh = socket({ connecting: true }); - emit('socket', fresh); - phases.dispose(); - assert.equal(fake.listenerCount('socket'), 0); - assert.equal(fake.listenerCount('finish'), 0); - assert.equal(fresh.listenerCount('connect'), 0); - assert.equal(fake.listenerCount('response'), 1, "the write owner's listener is its own"); - stopObservingWrites(); - assert.equal(fake.listenerCount('response'), 0); - } finally { - watchdog.dispose(); - } + const { fake, phases, stopObservingWrites, emit, socket } = createObservedRequest(); + const fresh = socket({ connecting: true }); + emit('socket', fresh); + phases.dispose(); + assert.equal(fake.listenerCount('socket'), 0); + assert.equal(fake.listenerCount('finish'), 0); + assert.equal(fresh.listenerCount('connect'), 0); + assert.equal(fake.listenerCount('response'), 1, "the write owner's listener is its own"); + stopObservingWrites(); + assert.equal(fake.listenerCount('response'), 0); }); function assertPhaseDetails(reason: unknown, phase: string, timeoutMs: number): void { diff --git a/packages/host-kit/src/internal/transport.ts b/packages/host-kit/src/internal/transport.ts index 5ff95751a3..282ac25349 100644 --- a/packages/host-kit/src/internal/transport.ts +++ b/packages/host-kit/src/internal/transport.ts @@ -143,16 +143,14 @@ export function observeCompletedRequestWrites( export const TRANSFER_CONNECT_TIMEOUT_MS = 30_000; /** - * Ceiling for waiting on response headers once this side has written everything the server is - * waiting for. For an upload that is the moment its outgoing request body is fully flushed, never - * the moment the request was created; for a bodyless request it is connection establishment. + * Ceiling for response headers once this side's body is fully flushed, never from the moment the + * request was created; for a bodyless request, from connection establishment. */ export const TRANSFER_RESPONSE_HEADER_TIMEOUT_MS = 30_000; /** - * Ceiling for silence between body bytes in either direction. Bytes actually written or read reset - * it, so an artifact that keeps moving keeps its budget while a connection that stopped carrying - * bytes does not. Progress never touches the aggregate budget the attempt runs under. + * Ceiling for silence between body bytes in either direction. Moving bytes reset it; they never + * touch the aggregate budget the attempt runs under. */ export const TRANSFER_BODY_INACTIVITY_TIMEOUT_MS = 120_000; @@ -164,13 +162,9 @@ const BODY_PHASES: ReadonlySet = new Set(['request-body', 'respon const TRANSFER_PHASE_TIMEOUT_REASON = 'transfer_phase_timeout'; /** - * Watches the sequential phases of ONE transfer attempt. - * - * One attempt gets one watchdog: arming a later phase stops counting the earlier one, so the ceiling - * that applies is always the phase the transfer is actually in. Progress re-arms only the two body - * phases. Nothing here extends an enclosing aggregate budget — the caller's signal is combined in, - * never replaced, so the earliest deadline still wins and every attempt, redirect and resume keeps - * sharing the original aggregate. + * Watches the sequential phases of ONE transfer attempt: arming a later phase stops counting the + * earlier one, and progress re-arms only a body phase. The caller's signal is combined in, never + * replaced, so an enclosing aggregate deadline still wins and is never extended. */ export type TransferPhaseWatchdog = { /** The signal the attempt runs on: the caller's cancellation plus every phase deadline. */ @@ -207,8 +201,7 @@ export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): Transfe rearm(); }, touchBody() { - // Unrelated headers, keepalive traffic and timer callbacks are not body progress, and - // progress in one phase buys no time in another: only a body phase already armed re-arms. + // Progress in one phase buys no time in another. if (!armed || !BODY_PHASES.has(armed.phase)) return; rearm(); }, @@ -220,10 +213,7 @@ export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): Transfe }; } -/** - * Typed evidence that a transfer phase, rather than the caller or the whole preparation aggregate, - * ended the attempt. The expired phase and its effective budget travel in `details`. - */ +/** Typed evidence that a phase, not the caller or the aggregate, ended the attempt. */ function createTransferPhaseTimeoutError(phase: TransferPhase, timeoutMs: number): AppError { return new AppError('COMMAND_FAILED', `Artifact transfer ${phase} timed out`, { reason: TRANSFER_PHASE_TIMEOUT_REASON, From e3a4793c608ed83de588a236d35714b4091d9968 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 20:15:58 +0100 Subject: [PATCH 09/14] refactor(transport): keep control deadlines in the shared phase owner --- .../src/internal/transport-phases.test.ts | 54 ++++----------- packages/host-kit/src/internal/transport.ts | 65 +++++-------------- packages/remote/src/upload-client.ts | 5 +- packages/remote/src/upload-stream.ts | 14 +--- 4 files changed, 31 insertions(+), 107 deletions(-) diff --git a/packages/host-kit/src/internal/transport-phases.test.ts b/packages/host-kit/src/internal/transport-phases.test.ts index e066a8919b..68865afe46 100644 --- a/packages/host-kit/src/internal/transport-phases.test.ts +++ b/packages/host-kit/src/internal/transport-phases.test.ts @@ -1,6 +1,3 @@ -// The phase budget of one artifact-transfer attempt (#4441), on a controlled clock. Each ceiling ends a -// stalled attempt on its own, and none of them touches the aggregate the attempt was admitted under. - import assert from 'node:assert/strict'; import { EventEmitter } from 'node:events'; import type { ClientRequest } from 'node:http'; @@ -14,7 +11,6 @@ import { TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, TRANSFER_CONNECT_TIMEOUT_MS, TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - type TransferPhaseWatchdog, } from './transport.ts'; beforeEach(() => { @@ -25,8 +21,7 @@ afterEach(() => { vi.useRealTimers(); }); -/** A watchdog disposed when its test finishes. */ -function watchPhases(callerSignal?: AbortSignal): TransferPhaseWatchdog { +function watchPhases(callerSignal?: AbortSignal) { const watchdog = createTransferPhaseWatchdog(callerSignal); onTestFinished(() => watchdog.dispose()); return watchdog; @@ -41,8 +36,6 @@ test('the three transfer ceilings are the adopted policy values', () => { test('a body phase restarts its ceiling on every byte that moves', async () => { const watchdog = watchPhases(); watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); - // Three full ceilings' worth of wall clock, each broken by real progress: 300 seconds of a slow - // artifact is admitted work, and nothing here may end it. for (const _ of [0, 1, 2]) { await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 20_000); watchdog.touchBody(); @@ -50,22 +43,16 @@ test('a body phase restarts its ceiling on every byte that moves', async () => { assert.equal(watchdog.signal.aborted, false); await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS + 1); assert.equal(watchdog.signal.aborted, true); - assertPhaseDetails(watchdog.signal.reason, 'response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + assertPhaseDetails(watchdog.signal.reason, 'response-body', 120_000); }); test('a phase that carries no bytes is not extended by progress reported in another phase', async () => { const watchdog = watchPhases(); watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 10_000); - // Bytes moving elsewhere — an unrelated header, a keepalive, a timer callback — are not the - // response-header wait making progress. watchdog.touchBody(); await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - assertPhaseDetails( - watchdog.signal.reason, - 'response-headers', - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - ); + assertPhaseDetails(watchdog.signal.reason, 'response-headers', 30_000); }); test('arming the next phase stops counting the previous one', async () => { @@ -73,16 +60,10 @@ test('arming the next phase stops counting the previous one', async () => { watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS - 1_000); watchdog.arm('response-headers', TRANSFER_RESPONSE_HEADER_TIMEOUT_MS); - // 58 seconds of total attempt time: past the connect ceiling, which the completed hop may spend, - // and inside the header ceiling the attempt is actually waiting on. await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1_000); assert.equal(watchdog.signal.aborted, false); await vi.advanceTimersByTimeAsync(1_000); - assertPhaseDetails( - watchdog.signal.reason, - 'response-headers', - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - ); + assertPhaseDetails(watchdog.signal.reason, 'response-headers', 30_000); }); test('an enclosing deadline wins and is never extended by a phase timer', async () => { @@ -92,8 +73,6 @@ test('an enclosing deadline wins and is never extended by a phase timer', async const watchdog = watchPhases(caller.signal); watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); await vi.advanceTimersByTimeAsync(5_001); - // The caller's reason is the answer, not a phase's own evidence, so a consumer can still tell - // "the work this upload served is gone" from "this transfer stalled". assert.equal(watchdog.signal.aborted, true); assert.equal(watchdog.signal.reason, reason); assert.equal(isTransferPhaseTimeoutError(watchdog.signal.reason), false); @@ -104,9 +83,7 @@ test('a phase expiry is its own typed evidence and never caller cancellation', a const watchdog = watchPhases(caller.signal); watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); - assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); - // Distinctness the retry policy depends on: nobody canceled, so the caller's own signal stays - // live and an enclosing aggregate is free to reach a different outcome. + assertPhaseDetails(watchdog.signal.reason, 'connect', 30_000); assert.equal(caller.signal.aborted, false); }); @@ -130,9 +107,6 @@ test('a phase is never armed after the attempt is already over', async () => { assert.equal(late.signal.reason.message, 'gone'); }); -type FakeSocket = EventEmitter & { connecting: boolean; encrypted?: boolean }; - -/** A request whose writes the test completes by hand, as Node does once a chunk reaches the kernel. */ class FakeRequest extends EventEmitter { destroyed = false; readonly callbacks: unknown[] = []; @@ -147,7 +121,6 @@ class FakeRequest extends EventEmitter { } } -/** One request observed as the upload attempt observes it: the phase owner beside the write owner. */ function createObservedRequest() { const fake = new FakeRequest(); const watchdog = watchPhases(); @@ -158,7 +131,7 @@ function createObservedRequest() { watchdog.touchBody(), ); const emit = (event: string, ...args: unknown[]) => fake.emit(event, ...args); - const socket = (state: { connecting: boolean; encrypted?: boolean }): FakeSocket => + const socket = (state: { connecting: boolean; encrypted?: boolean }) => Object.assign(new EventEmitter(), state); return { fake, req, watchdog, phases, stopObservingWrites, emit, socket }; } @@ -169,7 +142,7 @@ test('a fresh socket keeps the connect ceiling until it connects, even after the emit('socket', fresh); emit('finish'); await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); - assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); + assertPhaseDetails(watchdog.signal.reason, 'connect', 30_000); }); test('the header wait starts only after both the flush and the connection', async () => { @@ -182,11 +155,7 @@ test('the header wait starts only after both the flush and the connection', asyn await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS - 1); assert.equal(watchdog.signal.aborted, false); await vi.advanceTimersByTimeAsync(1); - assertPhaseDetails( - watchdog.signal.reason, - 'response-headers', - TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, - ); + assertPhaseDetails(watchdog.signal.reason, 'response-headers', 30_000); }); test('a TLS socket is established by secureConnect, not connect', async () => { @@ -195,7 +164,7 @@ test('a TLS socket is established by secureConnect, not connect', async () => { emit('socket', tls); tls.emit('connect'); await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); - assertPhaseDetails(watchdog.signal.reason, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); + assertPhaseDetails(watchdog.signal.reason, 'connect', 30_000); }); test('a pooled socket is already connected and times the body write as inactivity', async () => { @@ -207,7 +176,7 @@ test('a pooled socket is already connected and times the body write as inactivit await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1); assert.equal(watchdog.signal.aborted, false); await vi.advanceTimersByTimeAsync(1); - assertPhaseDetails(watchdog.signal.reason, 'request-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + assertPhaseDetails(watchdog.signal.reason, 'request-body', 120_000); }); test('once the response started, later request events do not overwrite its phase', async () => { @@ -220,10 +189,9 @@ test('once the response started, later request events do not overwrite its phase fresh.emit('connect'); emit('finish'); await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS - 1_000); - // A request write that completes now says nothing about the response body. fake.complete(0); await vi.advanceTimersByTimeAsync(1_001); - assertPhaseDetails(watchdog.signal.reason, 'response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + assertPhaseDetails(watchdog.signal.reason, 'response-body', 120_000); }); test('disposing the phase observer removes only its own listeners', () => { diff --git a/packages/host-kit/src/internal/transport.ts b/packages/host-kit/src/internal/transport.ts index 282ac25349..9ec5aec7e4 100644 --- a/packages/host-kit/src/internal/transport.ts +++ b/packages/host-kit/src/internal/transport.ts @@ -90,13 +90,9 @@ export function timingSafeStringEqual(a: string, b: string): boolean { } /** - * Reports each non-empty `req.write` chunk that Node completes without an error: its bytes reached - * the local kernel, not the peer. A queued write, `drain`, and a completion after the response - * started, after `signal` aborted, after a destroy or after disposal are not reported. - * - * Attach it in the tick that creates the request, before anything writes to it. The wrapper keeps - * the arguments, `this`, the backpressure result and one call of the caller's callback with its - * error. Disposing removes its listener and restores `write` only while this wrapper is installed. + * Reports successful nonempty write completions as local-kernel acceptance, never peer receipt. + * Attach at construction. Late response/abort/destroy/dispose completions do not count. + * Disposal restores this wrapper only; caller arguments, callback and backpressure are preserved. */ export function observeCompletedRequestWrites( req: ClientRequest, @@ -139,41 +135,30 @@ export function observeCompletedRequestWrites( }; } -/** Ceiling for establishing the connection for each upload hop or offset resume. */ export const TRANSFER_CONNECT_TIMEOUT_MS = 30_000; -/** - * Ceiling for response headers once this side's body is fully flushed, never from the moment the - * request was created; for a bodyless request, from connection establishment. - */ +/** Header wait begins after connection and outgoing flush. */ export const TRANSFER_RESPONSE_HEADER_TIMEOUT_MS = 30_000; -/** - * Ceiling for silence between body bytes in either direction. Moving bytes reset it; they never - * touch the aggregate budget the attempt runs under. - */ export const TRANSFER_BODY_INACTIVITY_TIMEOUT_MS = 120_000; -export type TransferPhase = 'connect' | 'request-body' | 'response-headers' | 'response-body' | 'preflight' | 'finalize'; +export type TransferPhase = + | 'connect' + | 'request-body' + | 'response-headers' + | 'response-body' + | 'preflight' + | 'finalize'; const BODY_PHASES: ReadonlySet = new Set(['request-body', 'response-body']); -/** The `details.reason` every phase expiry carries, so no consumer has to match error text. */ const TRANSFER_PHASE_TIMEOUT_REASON = 'transfer_phase_timeout'; -/** - * Watches the sequential phases of ONE transfer attempt: arming a later phase stops counting the - * earlier one, and progress re-arms only a body phase. The caller's signal is combined in, never - * replaced, so an enclosing aggregate deadline still wins and is never extended. - */ +/** Sequential phases under the earliest caller/aggregate deadline; only body progress rearms. */ export type TransferPhaseWatchdog = { - /** The signal the attempt runs on: the caller's cancellation plus every phase deadline. */ signal: AbortSignal; - /** Starts watching `phase`. The phase watched before stops counting. */ arm(phase: TransferPhase, timeoutMs: number): void; - /** Records body bytes moving, so only the silence since the last byte counts against a body phase. */ touchBody(): void; - /** Stops the armed timer. Call it once the attempt is settled. */ dispose(): void; }; @@ -201,7 +186,6 @@ export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): Transfe rearm(); }, touchBody() { - // Progress in one phase buys no time in another. if (!armed || !BODY_PHASES.has(armed.phase)) return; rearm(); }, @@ -213,7 +197,6 @@ export function createTransferPhaseWatchdog(callerSignal?: AbortSignal): Transfe }; } -/** Typed evidence that a phase, not the caller or the aggregate, ended the attempt. */ function createTransferPhaseTimeoutError(phase: TransferPhase, timeoutMs: number): AppError { return new AppError('COMMAND_FAILED', `Artifact transfer ${phase} timed out`, { reason: TRANSFER_PHASE_TIMEOUT_REASON, @@ -222,36 +205,19 @@ function createTransferPhaseTimeoutError(phase: TransferPhase, timeoutMs: number }); } -/** Whether `error` is a transfer phase's own expiry, which no fallback or retry may restart. */ export function isTransferPhaseTimeoutError(error: unknown): boolean { return error instanceof AppError && error.details?.reason === TRANSFER_PHASE_TIMEOUT_REASON; } -/** What `observeClientRequestPhases` reports and owns for one outgoing request. */ export type ClientRequestPhases = { - /** Whether the response has started. Request-side events no longer move the phase after this. */ readonly responseStarted: boolean; - /** Removes every listener the observer added. Call it once the exchange is settled. */ dispose(): void; }; /** - * Drives `watchdog` through the phases of ONE outgoing `node:http` request. - * - * The caller arms `connect` before issuing the request. From the events that follow, this owner - * decides the phase the exchange is in: - * - A fresh socket is not a connection until `connect`, or `secureConnect` for TLS. A pooled socket - * already is. Until then the connect ceiling keeps counting, even when the whole body already sits - * in the write buffer, because buffered bytes are not transport progress. - * - A connected exchange that is still writing is in `request-body`. Only the body progress the - * caller reports with `touchBody`, such as `observeCompletedRequestWrites` completions, restarts - * its inactivity budget. - * - The header wait starts only after BOTH the request `finish` and the connection. - * - Once the response starts, the exchange is in `response-body` and no later request event can - * overwrite it. The caller reports response bytes with `touchBody`. - * - * Attach it in the tick that creates the request. It waits on nothing: `dispose` removes every - * listener it adds. + * Attach at construction after arming connect. Headers need connection and request finish. + * TLS needs secureConnect; pooled sockets are connected. Buffered bytes are not progress. + * The caller reports body bytes; response start retires request events. Dispose at settlement. */ export function observeClientRequestPhases( req: ClientRequest, @@ -295,7 +261,6 @@ export function observeClientRequestPhases( }; req.on('socket', onSocket); req.on('finish', onFinish); - // The request's own response callback is registered first, so the phase has to move before it runs. req.prependListener('response', onResponse); return { get responseStarted() { diff --git a/packages/remote/src/upload-client.ts b/packages/remote/src/upload-client.ts index 2a90de0e60..b390acbbf4 100644 --- a/packages/remote/src/upload-client.ts +++ b/packages/remote/src/upload-client.ts @@ -12,7 +12,10 @@ import { withUploadPreparationDeadline, } from './upload-stream.ts'; import type { UploadProgressSink } from './upload-progress.ts'; -import { createTransferPhaseWatchdog, isTransferPhaseTimeoutError } from '@agent-device/host-kit/transport'; +import { + createTransferPhaseWatchdog, + isTransferPhaseTimeoutError, +} from '@agent-device/host-kit/transport'; /** Ceiling for the small JSON `preflight` and `finalize` calls that bracket an upload. */ const UPLOAD_CONTROL_PLANE_TIMEOUT_MS = 30_000; diff --git a/packages/remote/src/upload-stream.ts b/packages/remote/src/upload-stream.ts index e52f5a5f89..c4dc7c741d 100644 --- a/packages/remote/src/upload-stream.ts +++ b/packages/remote/src/upload-stream.ts @@ -72,10 +72,7 @@ export async function streamFileToHttpRequest(options: { errorMessage: string; errorHint?: string; retryable?: boolean; - /** - * The preparation aggregate `uploadArtifact` opened, combined with its caller's cancellation. Every - * attempt, redirect and resume runs under it; none of them opens a deadline of its own. - */ + /** All hops share the enclosing aggregate/caller signal. */ signal: AbortSignal; progress?: UploadStreamProgressOptions; }): Promise { @@ -108,12 +105,9 @@ async function streamFileToHttpRequestAttempt(options: { const headers = buildUploadRequestHeaders(options.headers, options.startOffset, payloadSize); emitUploadAttemptStarted(options.progress, options.startOffset, payloadSize); - // A redirect or a resume is a new attempt with fresh phase timers under the same `options.signal`. const watchdog = createTransferPhaseWatchdog(options.signal); watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS); - // The owned pipeline (file → progress → request). Every exit joins it, so no owned byte overlaps - // the outcome or the next hop. let upload: Promise | undefined; let uploadSettled = false; return await new Promise((resolve, reject) => { @@ -128,7 +122,6 @@ async function streamFileToHttpRequestAttempt(options: { phases.dispose(); stopObservingWrites(); watchdog.dispose(); - // The queued pipeline has to settle before the join in `finally`. req.destroy(); reject(error); }; @@ -161,8 +154,6 @@ async function streamFileToHttpRequestAttempt(options: { req.on('error', (err) => { if (phases.responseStarted) return; - // A cancellation or an expired phase is this client's own outcome, never a transport failure - // that a retry or a legacy fallback could fix. if (watchdog.signal.aborted) { fail(watchdog.signal.reason); return; @@ -200,7 +191,6 @@ async function streamFileToHttpRequestAttempt(options: { fail(watchdog.signal.reason); return; } - // A transport break reports through `error`, so this is the artifact read failing. const error = err instanceof Error ? err : new Error(String(err)); fail(new AppError('COMMAND_FAILED', 'Failed to read local artifact', {}, error)); }); @@ -219,8 +209,6 @@ async function streamFileToHttpRequestAttempt(options: { }; async function handleUploadResponse(res: IncomingMessage): Promise { - // Read the accepted answer to its end, then end and join the outgoing work before this attempt - // resolves or the next hop starts. const body = await readNodeHttpResponseBody(res, () => watchdog.touchBody()); await endOutgoingWork(); phases.dispose(); From 0230de42a242adfb7904854de9722b2465a01e85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 20:36:42 +0100 Subject: [PATCH 10/14] docs(transport): retain the response phase ordering constraint --- packages/host-kit/src/internal/transport.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/host-kit/src/internal/transport.ts b/packages/host-kit/src/internal/transport.ts index 9ec5aec7e4..dab18d4d34 100644 --- a/packages/host-kit/src/internal/transport.ts +++ b/packages/host-kit/src/internal/transport.ts @@ -125,6 +125,7 @@ export function observeCompletedRequestWrites( return Reflect.apply(write, this, args); }; req.write = observedWrite; + // Move the phase before the request's response callback runs. req.prependListener('response', onResponse); return () => { observing = false; From 3c3674a2217799f4f4f9e9d258de17947769c60a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 22:21:43 +0100 Subject: [PATCH 11/14] refactor(remote): consolidate upload failure and join ownership --- packages/host-kit/src/internal/transport.ts | 2 +- packages/remote/src/upload-stream.ts | 43 ++++----------------- 2 files changed, 9 insertions(+), 36 deletions(-) diff --git a/packages/host-kit/src/internal/transport.ts b/packages/host-kit/src/internal/transport.ts index dab18d4d34..d698985b1e 100644 --- a/packages/host-kit/src/internal/transport.ts +++ b/packages/host-kit/src/internal/transport.ts @@ -125,7 +125,7 @@ export function observeCompletedRequestWrites( return Reflect.apply(write, this, args); }; req.write = observedWrite; - // Move the phase before the request's response callback runs. + // Stop counting writes before the request's response callback runs. req.prependListener('response', onResponse); return () => { observing = false; diff --git a/packages/remote/src/upload-stream.ts b/packages/remote/src/upload-stream.ts index c4dc7c741d..e660215067 100644 --- a/packages/remote/src/upload-stream.ts +++ b/packages/remote/src/upload-stream.ts @@ -111,19 +111,12 @@ async function streamFileToHttpRequestAttempt(options: { let upload: Promise | undefined; let uploadSettled = false; return await new Promise((resolve, reject) => { - let outgoingEnded = false; - const settle = (result: UploadStreamResponse) => { - phases.dispose(); - stopObservingWrites(); - watchdog.dispose(); - resolve(result); - }; const fail = (error: unknown) => { phases.dispose(); stopObservingWrites(); watchdog.dispose(); req.destroy(); - reject(error); + reject(watchdog.signal.aborted ? watchdog.signal.reason : error); }; const req = transport.request( { @@ -139,11 +132,7 @@ async function streamFileToHttpRequestAttempt(options: { }, (res) => { addAbortSignal(watchdog.signal, res); - void handleUploadResponse(res) - .then((result) => settle(result)) - .catch((error: unknown) => - fail(watchdog.signal.aborted ? watchdog.signal.reason : error), - ); + void handleUploadResponse(res).then(resolve).catch(fail); }, ); @@ -154,10 +143,6 @@ async function streamFileToHttpRequestAttempt(options: { req.on('error', (err) => { if (phases.responseStarted) return; - if (watchdog.signal.aborted) { - fail(watchdog.signal.reason); - return; - } fail( new AppError( 'COMMAND_FAILED', @@ -186,31 +171,19 @@ async function streamFileToHttpRequestAttempt(options: { // After a response, only this attempt's own teardown ends the pipeline, and the server's // verdict stays the outcome: a 413 read completely is a 413, not a transport break. if (phases.responseStarted) return; - req.destroy(); - if (watchdog.signal.aborted) { - fail(watchdog.signal.reason); - return; - } const error = err instanceof Error ? err : new Error(String(err)); fail(new AppError('COMMAND_FAILED', 'Failed to read local artifact', {}, error)); }); - const endOutgoingWork = (): Promise => { - if (!outgoingEnded) { - outgoingEnded = true; - // The response is consumed, so a destroy cannot cut it short; it settles a pipeline blocked - // on a peer that stopped reading. A flushed pipeline keeps its pooled socket. - if (!uploadSettled) req.destroy(); - } - return upload!.then( + async function handleUploadResponse(res: IncomingMessage): Promise { + const body = await readNodeHttpResponseBody(res, () => watchdog.touchBody()); + // The response is consumed, so a destroy cannot cut it short; it settles a pipeline blocked + // on a peer that stopped reading. A flushed pipeline keeps its pooled socket. + if (!uploadSettled) req.destroy(); + await upload!.then( () => undefined, () => undefined, ); - }; - - async function handleUploadResponse(res: IncomingMessage): Promise { - const body = await readNodeHttpResponseBody(res, () => watchdog.touchBody()); - await endOutgoingWork(); phases.dispose(); stopObservingWrites(); watchdog.dispose(); From 48b8a9858448cb9ade0de53fa36efb0b2a3082a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 22:21:43 +0100 Subject: [PATCH 12/14] chore(gates): acknowledge consolidated upload outcome ownership --- test/wire-compat/ledger.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 51e3ad8c16..1a0c8af75b 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -182,7 +182,7 @@ "packages/remote/src/upload-stream.ts#parseNonNegativeIntegerHeader": "sha256:5cbe9c6994459d673d988a51407e65556e28175b187ce0a9d27cbb6331962834", "packages/remote/src/upload-stream.ts#parseUploadResumeOffset": "sha256:297184ea22a6dc1cda9aee17034122ae0ea2f43d0355647f6fcf02f3f4b5ca0e", "packages/remote/src/upload-stream.ts#streamFileToHttpRequest": "sha256:c2b5e1369c8b1c9420036e23163d21e43fa2ac8b889c6a8f028cc6095055a16f", - "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt": "sha256:1d3dfa85e45dafd39bd69ab8bb597d851e95d2f4c99b70f2cee65c7f4c688a7c", + "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt": "sha256:6ca0ad50c06f9a81d8ba3ad15503e2394a56cb46c3d18cbff1d40a2b3171fa2f", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_INSTANCE_HEADER": "sha256:d2bb3f4846470188a0fc1724271da0f0bcbdf2337bd6bf331508142cadcb65d8", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_UPSTREAM_INSTANCE_HEADER": "sha256:4564c2ce437d30d7a823e3326f4375c0750ba8d42bec22b4d02e8eb7f7db2973", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_INSTANCE_MISMATCH_HEADER": "sha256:a197edaf7f9fa94a6aab269856aa852da3204cc586f5fd23198689eb11908b61", @@ -496,8 +496,8 @@ }, { "declaration": "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt", - "digest": "sha256:1d3dfa85e45dafd39bd69ab8bb597d851e95d2f4c99b70f2cee65c7f4c688a7c", - "rationale": "#4441 keeps each attempt under its sequential phase watchdog and corrects its transport lifecycle: the connect ceiling now ends at actual socket or TLS-handshake establishment, body progress counts only transport writes, and an early response reads the accepted answer to its end, then destroys and joins the owned file/request pipeline and retires this attempt's phase watchdog before resolving or starting the redirect/resume attempt, so a completed hop's timers never reach the next hop. The outgoing-request phase observation now comes from @agent-device/host-kit/transport's observeClientRequestPhases, which listens to the same socket, TLS-handshake and finish events and is removed when the attempt settles. Bytes on the wire are unchanged: same route, method, headers, body framing, resume-offset handling and redirect limit. Only this client's own sequencing and deadlines moved, so a protocol-2 peer parses exactly what it parsed before. Request-body progress is now each non-empty request write that completes without an error, which Node reports once the bytes reach the local kernel, instead of drain, which fires only after a write returned false. The write wrapper passes every argument and the backpressure result through, so the bytes and framing on the wire do not change. That completed-write observer is host-kit's transport owner, which also stops reporting after the response starts, the signal aborts or the request is destroyed; no request changes. The attempt composes that write owner with the phase observer once per request and disposes both when it settles." + "digest": "sha256:6ca0ad50c06f9a81d8ba3ad15503e2394a56cb46c3d18cbff1d40a2b3171fa2f", + "rationale": "#4441 keeps each attempt under its sequential phase watchdog and corrects its transport lifecycle: the connect ceiling now ends at actual socket or TLS-handshake establishment, body progress counts only transport writes, and an early response reads the accepted answer to its end, then destroys and joins the owned file/request pipeline and retires this attempt's phase watchdog before resolving or starting the redirect/resume attempt, so a completed hop's timers never reach the next hop. The outgoing-request phase observation now comes from @agent-device/host-kit/transport's observeClientRequestPhases, which listens to the same socket, TLS-handshake and finish events and is removed when the attempt settles. Bytes on the wire are unchanged: same route, method, headers, body framing, resume-offset handling and redirect limit. Only this client's own sequencing and deadlines moved, so a protocol-2 peer parses exactly what it parsed before. Request-body progress is now each non-empty request write that completes without an error, which Node reports once the bytes reach the local kernel, instead of drain, which fires only after a write returned false. The write wrapper passes every argument and the backpressure result through, so the bytes and framing on the wire do not change. That completed-write observer is host-kit's transport owner, which also stops reporting after the response starts, the signal aborts or the request is destroyed; no request changes. The attempt composes that write owner with the phase observer once per request and disposes both when it settles. Duplicate success disposal and abort-reason mapping are consolidated without changing precedence. The sole response-path pipeline join remains before outcome or next hop; URL, method, authentication, payloads and framing remain unchanged." }, { "declaration": "packages/remote/src/daemon-artifacts.ts#resolveMaterializedArtifactPath", From e5fa7a2831bfb008214af512226f35fe8982103d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 22:28:44 +0100 Subject: [PATCH 13/14] refactor(remote): omit the redundant successful join callback --- packages/remote/src/upload-stream.ts | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/packages/remote/src/upload-stream.ts b/packages/remote/src/upload-stream.ts index e660215067..ce9e439515 100644 --- a/packages/remote/src/upload-stream.ts +++ b/packages/remote/src/upload-stream.ts @@ -180,10 +180,7 @@ async function streamFileToHttpRequestAttempt(options: { // The response is consumed, so a destroy cannot cut it short; it settles a pipeline blocked // on a peer that stopped reading. A flushed pipeline keeps its pooled socket. if (!uploadSettled) req.destroy(); - await upload!.then( - () => undefined, - () => undefined, - ); + await upload!.catch(() => undefined); phases.dispose(); stopObservingWrites(); watchdog.dispose(); From 024cb04a4d38de644148233ae79108191a28507d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 22:28:44 +0100 Subject: [PATCH 14/14] chore(gates): pin the final upload join digest --- test/wire-compat/ledger.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 1a0c8af75b..6abd0a754c 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -182,7 +182,7 @@ "packages/remote/src/upload-stream.ts#parseNonNegativeIntegerHeader": "sha256:5cbe9c6994459d673d988a51407e65556e28175b187ce0a9d27cbb6331962834", "packages/remote/src/upload-stream.ts#parseUploadResumeOffset": "sha256:297184ea22a6dc1cda9aee17034122ae0ea2f43d0355647f6fcf02f3f4b5ca0e", "packages/remote/src/upload-stream.ts#streamFileToHttpRequest": "sha256:c2b5e1369c8b1c9420036e23163d21e43fa2ac8b889c6a8f028cc6095055a16f", - "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt": "sha256:6ca0ad50c06f9a81d8ba3ad15503e2394a56cb46c3d18cbff1d40a2b3171fa2f", + "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt": "sha256:23ba867eb3ec61b3d95a094715d974951eae1c9e3ebd4b1cb335ed71ec113259", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_INSTANCE_HEADER": "sha256:d2bb3f4846470188a0fc1724271da0f0bcbdf2337bd6bf331508142cadcb65d8", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_UPSTREAM_INSTANCE_HEADER": "sha256:4564c2ce437d30d7a823e3326f4375c0750ba8d42bec22b4d02e8eb7f7db2973", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_INSTANCE_MISMATCH_HEADER": "sha256:a197edaf7f9fa94a6aab269856aa852da3204cc586f5fd23198689eb11908b61", @@ -496,7 +496,7 @@ }, { "declaration": "packages/remote/src/upload-stream.ts#streamFileToHttpRequestAttempt", - "digest": "sha256:6ca0ad50c06f9a81d8ba3ad15503e2394a56cb46c3d18cbff1d40a2b3171fa2f", + "digest": "sha256:23ba867eb3ec61b3d95a094715d974951eae1c9e3ebd4b1cb335ed71ec113259", "rationale": "#4441 keeps each attempt under its sequential phase watchdog and corrects its transport lifecycle: the connect ceiling now ends at actual socket or TLS-handshake establishment, body progress counts only transport writes, and an early response reads the accepted answer to its end, then destroys and joins the owned file/request pipeline and retires this attempt's phase watchdog before resolving or starting the redirect/resume attempt, so a completed hop's timers never reach the next hop. The outgoing-request phase observation now comes from @agent-device/host-kit/transport's observeClientRequestPhases, which listens to the same socket, TLS-handshake and finish events and is removed when the attempt settles. Bytes on the wire are unchanged: same route, method, headers, body framing, resume-offset handling and redirect limit. Only this client's own sequencing and deadlines moved, so a protocol-2 peer parses exactly what it parsed before. Request-body progress is now each non-empty request write that completes without an error, which Node reports once the bytes reach the local kernel, instead of drain, which fires only after a write returned false. The write wrapper passes every argument and the backpressure result through, so the bytes and framing on the wire do not change. That completed-write observer is host-kit's transport owner, which also stops reporting after the response starts, the signal aborts or the request is destroyed; no request changes. The attempt composes that write owner with the phase observer once per request and disposes both when it settles. Duplicate success disposal and abort-reason mapping are consolidated without changing precedence. The sole response-path pipeline join remains before outcome or next hop; URL, method, authentication, payloads and framing remain unchanged." }, {