Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
218 changes: 218 additions & 0 deletions packages/host-kit/src/internal/transport-phases.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,218 @@
import assert from 'node:assert/strict';
import { EventEmitter } from 'node:events';
import type { ClientRequest } from 'node:http';
import { afterEach, beforeEach, onTestFinished, test, vi } from 'vitest';
import { AppError } from '@agent-device/kernel/errors';
import {
createTransferPhaseWatchdog,
isTransferPhaseTimeoutError,
observeClientRequestPhases,
observeCompletedRequestWrites,
TRANSFER_BODY_INACTIVITY_TIMEOUT_MS,
TRANSFER_CONNECT_TIMEOUT_MS,
TRANSFER_RESPONSE_HEADER_TIMEOUT_MS,
} from './transport.ts';

beforeEach(() => {
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
});

afterEach(() => {
vi.useRealTimers();
});

function watchPhases(callerSignal?: AbortSignal) {
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);
assert.equal(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, 120_000);
});

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);
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', 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);
watchdog.touchBody();
await vi.advanceTimersByTimeAsync(TRANSFER_RESPONSE_HEADER_TIMEOUT_MS);
assertPhaseDetails(watchdog.signal.reason, 'response-headers', 30_000);
});

test('arming the next phase stops counting the previous one', async () => {
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);
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', 30_000);
});

test('an enclosing deadline wins and is never extended by a phase timer', async () => {
const caller = new AbortController();
const reason = new Error('preparation aggregate expired');
setTimeout(() => caller.abort(reason), 5_000);
const watchdog = watchPhases(caller.signal);
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);
});

test('a phase expiry is its own typed evidence and never caller cancellation', async () => {
const caller = new AbortController();
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', 30_000);
assert.equal(caller.signal.aborted, false);
});

test('a disposed watchdog stops watching', async () => {
const watchdog = watchPhases();
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 () => {
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');
});

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);
}
}

function createObservedRequest() {
const fake = new FakeRequest();
const watchdog = watchPhases();
watchdog.arm('connect', TRANSFER_CONNECT_TIMEOUT_MS);
const req = fake as unknown as ClientRequest;
const phases = observeClientRequestPhases(req, watchdog);
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 }) =>
Object.assign(new EventEmitter(), state);
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 () => {
const { watchdog, emit, socket } = createObservedRequest();
const fresh = socket({ connecting: true });
emit('socket', fresh);
emit('finish');
await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1);
assertPhaseDetails(watchdog.signal.reason, 'connect', 30_000);
});

test('the header wait starts only after both the flush and the connection', async () => {
const { watchdog, emit, socket } = createObservedRequest();
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', 30_000);
});

test('a TLS socket is established by secureConnect, not connect', async () => {
const { watchdog, emit, socket } = createObservedRequest();
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', 30_000);
});

test('a pooled socket is already connected and times the body write as inactivity', async () => {
const { fake, req, watchdog, emit, socket } = createObservedRequest();
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', 120_000);
});

test('once the response started, later request events do not overwrite its phase', async () => {
const { fake, req, watchdog, phases, emit, socket } = createObservedRequest();
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);
fake.complete(0);
await vi.advanceTimersByTimeAsync(1_001);
assertPhaseDetails(watchdog.signal.reason, 'response-body', 120_000);
});

test('disposing the phase observer removes only its own listeners', () => {
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 {
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,
});
}
152 changes: 145 additions & 7 deletions packages/host-kit/src/internal/transport.ts
Original file line number Diff line number Diff line change
@@ -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(
Expand Down Expand Up @@ -89,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,
Expand Down Expand Up @@ -128,6 +125,7 @@ export function observeCompletedRequestWrites(
return Reflect.apply(write, this, args);
};
req.write = observedWrite;
// Stop counting writes before the request's response callback runs.
req.prependListener('response', onResponse);
return () => {
observing = false;
Expand All @@ -137,3 +135,143 @@ export function observeCompletedRequestWrites(
else Reflect.deleteProperty(req, 'write');
};
}

export const TRANSFER_CONNECT_TIMEOUT_MS = 30_000;

/** Header wait begins after connection and outgoing flush. */
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<TransferPhase> = new Set(['request-body', 'response-body']);

const TRANSFER_PHASE_TIMEOUT_REASON = 'transfer_phase_timeout';

/** Sequential phases under the earliest caller/aggregate deadline; only body progress rearms. */
export type TransferPhaseWatchdog = {
signal: AbortSignal;
arm(phase: TransferPhase, timeoutMs: number): void;
touchBody(): void;
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<typeof setTimeout> | undefined;
const rearm = () => {
if (timer !== undefined) clearTimeout(timer);
timer = undefined;
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,
});
}

export function isTransferPhaseTimeoutError(error: unknown): boolean {
return error instanceof AppError && error.details?.reason === TRANSFER_PHASE_TIMEOUT_REASON;
}

export type ClientRequestPhases = {
readonly responseStarted: boolean;
dispose(): void;
};

/**
* 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,
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 onFinish = () => {
flushed = true;
advance();
};
const onResponse = () => {
responseStarted = true;
watchdog.arm('response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS);
};
req.on('socket', onSocket);
req.on('finish', onFinish);
req.prependListener('response', onResponse);
return {
get responseStarted() {
return responseStarted;
},
dispose() {
req.off('socket', onSocket);
req.off('finish', onFinish);
req.off('response', onResponse);
if (socket && connectEvent) socket.off(connectEvent, onConnected);
},
};
}
Comment thread
thymikee marked this conversation as resolved.
Resolved
Loading
Loading