@namzu/sandbox 16.0.0 → 17.0.0

package/dist/backends/firecracker/transport.js

@@ -58,6 +58,21 @@ import tls from 'node:tls';
 import { OperationDeadline, OperationDeadlineExpired } from '../readiness.js';
 import { REMOTE_EXECUTION_PROTOCOL_VERSION, RemoteCancellationUnknownError, RemoteExecutionController, RemoteProtocolError, } from '../remote-execution-controller.js';
 import { ExecResultAccumulator, MIN_STREAM_HEARTBEAT_MS, READ_FILE_STREAM_FEATURE, STREAM_HEARTBEAT_MAX_ECHO_FACTOR, STREAM_HEARTBEAT_MISS_LIMIT, WRITE_FILE_PARTS_FEATURE, parseExecLine, } from './protocol.js';
+/** The reportable view of a ledger — see {@link FirecrackerTransportTiming}. */
+function timingOf(ledger) {
+    return {
+        dialMs: ledger.dialMs,
+        reserveMs: ledger.reserveMs,
+        executeMs: ledger.executeMs,
+        drainMs: ledger.executeSettledAt > 0 ? Date.now() - ledger.executeSettledAt : 0,
+        // Spread conditionally, not set to a sentinel: "this phase was never
+        // reached" and "this phase took no measurable time" are different
+        // statements, and only an absent field says the first.
+        ...(ledger.firstFrameMs !== undefined ? { firstFrameMs: ledger.firstFrameMs } : {}),
+        ...(ledger.terminatorMs !== undefined ? { terminatorMs: ledger.terminatorMs } : {}),
+        ...(ledger.peerCloseMs !== undefined ? { peerCloseMs: ledger.peerCloseMs } : {}),
+    };
+}
 const DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_CONNECT_RETRY_BUDGET_MS = 30_000;
 const DEFAULT_CONNECT_RETRY_INTERVAL_MS = 100;
@@ -68,6 +83,37 @@ const DEFAULT_EXECUTION_TIMEOUT_MS = 5 * 60_000;
 // bounded TERM -> KILL confirmation window so a quiet but correctly
 // terminating command can still deliver its terminal frame and output tail.
 const EXECUTION_TRANSPORT_GRACE_MS = 10_000;
+/**
+ * How long a reply that has already TERMINATED waits for the peer's own close
+ * before this transport gives up on it. Three callers, all of them read-reply
+ * loops that resolve on that close: {@link VsockAgentTransport.request} (one
+ * control or file reply), {@link VsockAgentTransport.executeRaw} (an exec's
+ * zero-length terminator frame) and `streamFramedRequest` (a
+ * `read-file-stream`'s end frame).
+ *
+ * **A reject-only guard, and deliberately not a budget to spend.** It can
+ * only turn a socket whose peer never closes into a named failure
+ * (`exec peer did not close after terminator`, or the `stream`/`control`
+ * wordings); it can never resolve a call, because every resolution path in
+ * this file requires the peer's `close` event. Raising it therefore buys no
+ * slow success — it delays a diagnosis — and lowering it fails a peer that
+ * was merely slow to close. It is not a wait any caller is expected to pay:
+ * a call that resolves has paid a real close, and how long the peer took to
+ * deliver it is reported as
+ * {@link FirecrackerTransportTiming.peerCloseMs}.
+ *
+ * **The contract this states for a host-owned relay.** After writing the
+ * terminator frame the agent calls `socket.end()` — a half-close — and this
+ * transport resolves the call on the resulting `close`. A relay between the
+ * guest and this process that forwards the payload but holds the FIN (its
+ * own idle timer, a full-duplex buffering policy, a proxy that waits for the
+ * guest process to exit) transfers that wait onto every call: under this
+ * bound it is reported as `peerCloseMs`, and at or past it the call REJECTS
+ * by name, with no `peerCloseMs` in the report — the number a host would
+ * otherwise be reading is one this transport chose, and it does not supply
+ * it. A relay that forwards the FIN promptly costs the guest's RTT and
+ * nothing else.
+ */
 const POST_RESPONSE_CLOSE_TIMEOUT_MS = 1_000;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /**
@@ -344,7 +390,7 @@ export class VsockAgentTransport {
      */
     guestFeatureList;
     permanentDialFailure;
-    executionController;
+    onExecTiming;
     constructor(handle, options = {}) {
         this.handle = handle;
         this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
@@ -363,24 +409,65 @@ export class VsockAgentTransport {
             this.writeFilePartBytes = Math.max(1, Math.floor(options.writeFilePartBytes));
         }
         this.permanentDialFailure = options.permanentDialFailure;
-        const adapter = {
+        this.onExecTiming = options.onExecTiming;
+    }
+    /**
+     * The reserve-before-admission triple this transport hands the shared
+     * {@link RemoteExecutionController}, with `ledger` — when a timing hook
+     * asked for one — accumulating the phases it wraps.
+     *
+     * A FACTORY rather than a constructor-built field, because the ledger is
+     * per call: this transport holds no cross-call connection state (it dials
+     * fresh every time), so building an adapter per `exec()` is free and
+     * makes concurrent `exec()` calls correctly independent — each gets its
+     * own accumulator, with no shared mutable field for two in-flight calls
+     * to race on. Same arrangement, and the same reason, as the kubernetes
+     * tier's `KubernetesAgentTransport.exec`.
+     */
+    executionAdapter(ledger) {
+        return {
             label: 'framed microVM agent',
-            reserve: async (signal) => await this.reserveExecution(signal),
-            cancel: async (executionId, signal) => await this.cancelExecution(executionId, signal),
-            execute: async (executionId, command, argv, opts, signal, context) => await this.executeRaw({
-                ...(executionId ? { executionId } : {}),
-                command,
-                args: argv ?? [],
-                ...(opts?.cwd !== undefined ? { cwd: opts.cwd } : {}),
-                ...(opts?.env !== undefined ? { env: opts.env } : {}),
-                ...(opts?.timeout !== undefined ? { timeoutMs: opts.timeout } : {}),
-                ...(context?.stdin !== undefined ? { stdin: context.stdin } : {}),
-                ...(context?.maxOutputBytes !== undefined
-                    ? { maxOutputBytes: context.maxOutputBytes }
-                    : {}),
-            }, opts, signal),
+            reserve: async (signal) => {
+                if (ledger === undefined)
+                    return await this.reserveExecution(signal);
+                const startedAt = Date.now();
+                try {
+                    return await this.reserveExecution(signal, ledger);
+                }
+                finally {
+                    ledger.reserveMs += Date.now() - startedAt;
+                }
+            },
+            cancel: async (executionId, signal) => await this.cancelExecution(executionId, signal, ledger),
+            execute: async (executionId, command, argv, opts, signal, context) => {
+                const body = {
+                    ...(executionId ? { executionId } : {}),
+                    command,
+                    args: argv ?? [],
+                    ...(opts?.cwd !== undefined ? { cwd: opts.cwd } : {}),
+                    ...(opts?.env !== undefined ? { env: opts.env } : {}),
+                    ...(opts?.timeout !== undefined ? { timeoutMs: opts.timeout } : {}),
+                    ...(context?.stdin !== undefined ? { stdin: context.stdin } : {}),
+                    ...(context?.maxOutputBytes !== undefined
+                        ? { maxOutputBytes: context.maxOutputBytes }
+                        : {}),
+                };
+                if (ledger === undefined)
+                    return await this.executeRaw(body, opts, signal);
+                const startedAt = Date.now();
+                try {
+                    return await this.executeRaw(body, opts, signal, ledger);
+                }
+                finally {
+                    ledger.executeMs += Date.now() - startedAt;
+                    // Stamped in the `finally` so it is set on the failure path
+                    // too: a drain interval is only worth reporting when the
+                    // round trip settled, and "settled" includes "settled by
+                    // rejecting".
+                    ledger.executeSettledAt = Date.now();
+                }
+            },
         };
-        this.executionController = new RemoteExecutionController(adapter);
     }
     /**
      * Dial the agent with the resume-survival retry budget. Resolves a
@@ -390,7 +477,7 @@ export class VsockAgentTransport {
      * {@link VsockTransportOptions.permanentDialFailure} says this particular
      * failure is not one waiting will cure.
      */
-    async dial(signal) {
+    async dial(signal, ledger) {
         const deadline = Date.now() + this.connectRetryBudgetMs;
         const dialStartedAt = Date.now();
         let lastErr;
@@ -403,7 +490,14 @@ export class VsockAgentTransport {
                 // is precisely the case a watcher needs to hear about.
                 this.onDialAttempt?.();
                 const socket = await this.connectOnce(signal);
-                this.onDial?.(Date.now() - dialStartedAt);
+                const durationMs = Date.now() - dialStartedAt;
+                this.onDial?.(durationMs);
+                // The same interval the hook above reports, folded into the
+                // call's own ledger: a caller asking where an exec's wall time
+                // went wants it as one number per call, and this dial belongs
+                // to that call.
+                if (ledger !== undefined)
+                    ledger.dialMs += durationMs;
                 return socket;
             }
             catch (err) {
@@ -675,10 +769,21 @@ export class VsockAgentTransport {
      * is torn down rather than wedging the caller.
      */
     async request(req, signal) {
+        return await this.requestFramed(req, signal);
+    }
+    /**
+     * {@link request}, with the one thing the public signature has no place
+     * for: the exec call's timing ledger, so the reserve round trip that
+     * reaches the guest through this method is counted against the call that
+     * paid for its dial. Private rather than a third parameter, because a
+     * public method whose extra argument exists only for internal
+     * instrumentation is a parameter a caller can only misuse.
+     */
+    async requestFramed(req, signal, ledger) {
         const envelope = this.withCredential(req);
         const payload = JSON.stringify(envelope);
         this.assertPreauthBudget(payload);
-        const socket = await this.dial(signal);
+        const socket = await this.dial(signal, ledger);
         return await new Promise((resolve, reject) => {
             const reader = new FrameReader();
             let settled = false;
@@ -757,12 +862,21 @@ export class VsockAgentTransport {
      * {@link SandboxExecResult} via the shared {@link ExecResultAccumulator}.
      * The agent terminates the stream with a zero-length frame.
      */
-    async executeRaw(body, opts, signal) {
+    async executeRaw(body, opts, signal, ledger) {
         const envelope = this.withCredential({ op: 'execute', body });
         const payload = JSON.stringify(envelope);
         this.assertPreauthBudget(payload);
-        const socket = await this.dial(signal);
+        const socket = await this.dial(signal, ledger);
         const start = Date.now();
+        // The instant the request goes on the wire. The three execute
+        // sub-phases of {@link FirecrackerTransportTiming} are measured from
+        // here, so they answer "how long after the guest was asked" rather
+        // than "how long after this call began" — the dial that precedes it
+        // is already counted in `dialMs` and inside `executeMs`.
+        let writtenAt = 0;
+        // Stamped once, when the terminator frame is parsed, so `peerCloseMs`
+        // measures the peer's close and not the whole round trip.
+        let terminatorAt = 0;
         return await new Promise((resolve, reject) => {
             const reader = new FrameReader();
             const acc = new ExecResultAccumulator(start, opts?.onOutput);
@@ -804,6 +918,12 @@ export class VsockAgentTransport {
                     finish(err instanceof Error ? err : new Error(String(err)));
                     return;
                 }
+                // Recorded before the terminator check below and before any
+                // parsing: the first frame ARRIVED, which stays true even if
+                // this call goes on to reject over the frame's contents.
+                if (ledger !== undefined && ledger.firstFrameMs === undefined && frames.length > 0) {
+                    ledger.firstFrameMs = Date.now() - writtenAt;
+                }
                 for (const payload of frames) {
                     if (terminated) {
                         finish(new Error('vsock transport: exec stream emitted data after its terminator'));
@@ -828,6 +948,14 @@ export class VsockAgentTransport {
                     }
                 }
                 if (terminated) {
+                    // The terminator WAS read, so it is reported even if this
+                    // call is about to reject over what followed it: the
+                    // question these numbers answer is where the time went,
+                    // not whether the call ended well.
+                    if (ledger !== undefined && ledger.terminatorMs === undefined) {
+                        terminatorAt = Date.now();
+                        ledger.terminatorMs = terminatorAt - writtenAt;
+                    }
                     if (reader.bufferedBytes > 0) {
                         finish(new Error('vsock transport: exec stream has trailing partial data'));
                         return;
@@ -839,8 +967,25 @@ export class VsockAgentTransport {
             });
             socket.once('error', (err) => finish(err));
             socket.once('close', () => {
-                if (terminated && terminalResult)
+                // A close that arrives with this call ALREADY settled is one
+                // this transport caused itself: `finish` is the only writer of
+                // `settled` and its next statement is `socket.destroy()`, so
+                // the guard timer, the observation timer and the caller's abort
+                // each destroy the socket and then react to the `close` that
+                // destroy emits. Crediting the peer for it would report
+                // {@link POST_RESPONSE_CLOSE_TIMEOUT_MS} — a constant this
+                // transport chose — as a duration the peer took, in exactly the
+                // case a host is reading the field to diagnose. The same rule
+                // `readFileFrames` applies in the same position: an end this
+                // side already reached is not news.
+                if (settled)
+                    return;
+                if (terminated && terminalResult) {
+                    if (ledger !== undefined && terminatorAt > 0) {
+                        ledger.peerCloseMs = Date.now() - terminatorAt;
+                    }
                     finish(null, terminalResult);
+                }
                 else
                     finish(new Error('vsock transport: socket closed before exec stream terminator'));
             });
@@ -849,6 +994,7 @@ export class VsockAgentTransport {
                 return;
             }
             signal?.addEventListener('abort', abort, { once: true });
+            writtenAt = Date.now();
             socket.write(frame(payload));
         });
     }
@@ -862,7 +1008,7 @@ export class VsockAgentTransport {
         if (body.executionId !== undefined) {
             throw new RemoteProtocolError('VsockAgentTransport.execute does not accept caller-owned execution ids');
         }
-        return await this.executionController.exec(body.command, body.args ? [...body.args] : undefined, {
+        return await this.runExec(body.command, body.args ? [...body.args] : undefined, {
             ...opts,
             ...(body.cwd !== undefined ? { cwd: body.cwd } : {}),
             ...(body.env !== undefined ? { env: body.env } : {}),
@@ -874,7 +1020,55 @@ export class VsockAgentTransport {
         });
     }
     async exec(command, argv, opts) {
-        return await this.executionController.exec(command, argv, opts);
+        return await this.runExec(command, argv, opts);
+    }
+    /**
+     * One command through a call-scoped adapter + controller, reporting the
+     * call's phases to {@link VsockTransportOptions.onExecTiming} when a host
+     * asked for them.
+     *
+     * The ledger is created HERE and nowhere else — because it is per call,
+     * not per transport, so two concurrent `exec()` calls each get their own
+     * accumulator. Constructing a controller per call costs an allocation and
+     * nothing else: the controller's only per-instance state is its readonly
+     * configuration, so a fresh one behaves exactly like a shared one, and
+     * this transport dials fresh per request either way.
+     *
+     * The hook fires in a `finally`, on the failure paths as well as the
+     * happy one: an exec that rejected after its reserve round trip is
+     * precisely the call whose phase breakdown a host needs. Measuring into a
+     * ledger that nobody reads is what "no hook, no cost" means here — with
+     * no hook there is no ledger, and the `undefined` checks in `dial` and
+     * `executeRaw` skip the clock reads entirely.
+     */
+    async runExec(command, argv, opts, context) {
+        const hook = this.onExecTiming;
+        if (hook === undefined) {
+            return await new RemoteExecutionController(this.executionAdapter()).exec(command, argv, opts, context);
+        }
+        const ledger = {
+            dialMs: 0,
+            reserveMs: 0,
+            executeMs: 0,
+            executeSettledAt: 0,
+        };
+        try {
+            return await new RemoteExecutionController(this.executionAdapter(ledger)).exec(command, argv, opts, context);
+        }
+        finally {
+            // Caught, not propagated: this hook is an OBSERVER, and a listener
+            // that throws must not turn a command that ran into a caller's
+            // exception — the rule {@link VsockTransportOptions.onGuestReply}
+            // already states for this transport's other observers. A `finally`
+            // that let it through would replace the call's own error with the
+            // listener's, which is the worst version of that failure.
+            try {
+                hook(timingOf(ledger));
+            }
+            catch {
+                // The listener's problem, and only the listener's.
+            }
+        }
     }
     /**
      * The raw `/execute` primitive with NO admission/reservation
@@ -892,8 +1086,8 @@ export class VsockAgentTransport {
     async executeStreamed(body, opts, signal) {
         return await this.executeRaw(body, opts, signal);
     }
-    async reserveExecution(signal) {
-        const response = await this.request({ op: 'reserve-execution' }, signal);
+    async reserveExecution(signal, ledger) {
+        const response = await this.requestFramed({ op: 'reserve-execution' }, signal, ledger);
         if (response.ok === false &&
             typeof response.error === 'string' &&
             response.error.startsWith('unknown_op:')) {
@@ -904,8 +1098,8 @@ export class VsockAgentTransport {
         }
         return response;
     }
-    async cancelExecution(executionId, signal) {
-        return await this.request({ op: 'cancel-execution', body: { executionId } }, signal);
+    async cancelExecution(executionId, signal, ledger) {
+        return await this.requestFramed({ op: 'cancel-execution', body: { executionId } }, signal, ledger);
     }
     /** Readiness probe. A healthy guest must also speak the exact host protocol. */
     async healthz(signal) {