@boxrouter/sdk 0.0.0-stage → 0.12.190

package/dist/telemetry.js

@@ -0,0 +1,438 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestTrace = void 0;
+exports.isTimeoutError = isTimeoutError;
+exports.setRequestPhaseObserver = setRequestPhaseObserver;
+exports.tracedRequest = tracedRequest;
+const api_1 = require("@opentelemetry/api");
+const telemetry_gen_1 = require("./telemetry.gen");
+const api_error_1 = require("./api-error");
+function isTimeoutError(error) {
+    return error instanceof DOMException && error.name === 'TimeoutError';
+}
+const RESPONSE_HEADERS_DURATION = 'boxrouter.client.response_headers.duration_ms';
+const RESPONSE_PROCESSING_DURATION = 'boxrouter.client.response_processing.duration_ms';
+const REQUEST_PREPARATION_DURATION = 'boxrouter.client.request_preparation.duration_ms';
+let requestPhaseObserver;
+/** Opt in to bounded, payload-free request phase observations. */
+function setRequestPhaseObserver(observer) {
+    requestPhaseObserver = observer;
+}
+function monotonicMilliseconds() {
+    try {
+        const performance = globalThis.performance;
+        const now = performance?.now;
+        if (typeof now !== 'function')
+            return undefined;
+        const value = now.call(performance);
+        return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function elapsedMilliseconds(start, end) {
+    if (start === undefined || end === undefined || end < start)
+        return undefined;
+    const elapsed = end - start;
+    return Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : undefined;
+}
+function nonRecordingParentSpan(parent) {
+    let spanContext = api_1.INVALID_SPAN_CONTEXT;
+    try {
+        spanContext = api_1.trace.getSpan(parent)?.spanContext() ?? api_1.INVALID_SPAN_CONTEXT;
+    }
+    catch { /* Optional observation. */ }
+    return api_1.trace.wrapSpanContext(spanContext);
+}
+/** The application owns providers, sampling, propagation and export. */
+class RequestTrace {
+    span;
+    context;
+    streaming = false;
+    timingEnabled = false;
+    requestPreparationStarted;
+    requestPreparationDuration;
+    requestPreparationMeasured = false;
+    responseHeadersDuration;
+    responseProcessingStarted;
+    responseProcessingDuration;
+    responseProcessingMeasured = false;
+    phaseObserver;
+    streamLifetimeStarted;
+    requestPreparationOutcomeSent = false;
+    responseProcessingOutcomeSent = false;
+    responseHeadersOutcomeSent = false;
+    responseHeadersSpanWritten = false;
+    responseStatus;
+    responseWasHttpError = false;
+    constructor(method, path, parent) {
+        let parentContext = parent;
+        if (parentContext === undefined) {
+            try {
+                parentContext = api_1.context.active();
+            }
+            catch {
+                parentContext = api_1.ROOT_CONTEXT;
+            }
+        }
+        this.context = parentContext;
+        this.phaseObserver = requestPhaseObserver;
+        const operation = telemetry_gen_1.operationNames.get(`${method} ${path}`);
+        try {
+            this.span = api_1.trace.getTracer('boxrouter.client').startSpan(operation ? `boxrouter.${operation}` : 'boxrouter.request', { kind: api_1.SpanKind.CLIENT }, parentContext);
+        }
+        catch {
+            this.span = nonRecordingParentSpan(parentContext);
+            this.phaseObserver = undefined;
+            return;
+        }
+        try {
+            this.context = api_1.trace.setSpan(parentContext, this.span);
+        }
+        catch { /* Preserve parent propagation. */ }
+        let recording = false;
+        try {
+            recording = this.span.isRecording();
+        }
+        catch { /* Optional timing observation. */ }
+        this.timingEnabled = recording || this.phaseObserver !== undefined;
+        if (this.timingEnabled)
+            this.requestPreparationStarted = monotonicMilliseconds();
+    }
+    inject(headers) {
+        try {
+            const carrier = {};
+            api_1.propagation.inject(this.context, carrier);
+            // A globally configured baggage propagator must not export application data.
+            if (carrier.traceparent)
+                headers.set('traceparent', carrier.traceparent);
+        }
+        catch { /* Optional propagation must not block the request. */ }
+    }
+    async fetchResponse(fetchCallback) {
+        if (!this.timingEnabled && !this.phaseObserver)
+            return fetchCallback();
+        const started = monotonicMilliseconds();
+        this.requestPreparationMeasured = true;
+        this.requestPreparationDuration = elapsedMilliseconds(this.requestPreparationStarted, started);
+        try {
+            const response = await fetchCallback();
+            const returned = monotonicMilliseconds();
+            this.responseHeadersDuration = elapsedMilliseconds(started, returned);
+            if (returned !== undefined && (started === undefined || returned >= started)) {
+                this.responseProcessingStarted = returned;
+            }
+            this.setTiming(REQUEST_PREPARATION_DURATION, this.requestPreparationDuration);
+            if (this.phaseObserver)
+                this.finishRequestPreparationOutcome('success');
+            return response;
+        }
+        catch (error) {
+            this.responseHeadersDuration = elapsedMilliseconds(started, monotonicMilliseconds());
+            this.setTiming(REQUEST_PREPARATION_DURATION, this.requestPreparationDuration);
+            let outcome = 'unknown';
+            try {
+                outcome = this.responseOutcome(error);
+            }
+            catch { /* Preserve the fetch failure. */ }
+            if (this.phaseObserver) {
+                try {
+                    this.finishRequestPreparationOutcome('success');
+                }
+                catch { /* Preserve the fetch failure. */ }
+            }
+            try {
+                this.finishResponseHeadersOutcome(outcome);
+            }
+            catch { /* Preserve the fetch failure. */ }
+            throw error;
+        }
+    }
+    finishBufferedResponse() {
+        if (!this.timingEnabled)
+            return;
+        if (!this.requestPreparationMeasured) {
+            const finished = monotonicMilliseconds();
+            this.requestPreparationMeasured = true;
+            this.requestPreparationDuration = elapsedMilliseconds(this.requestPreparationStarted, finished);
+            this.setTiming(REQUEST_PREPARATION_DURATION, this.requestPreparationDuration);
+        }
+        if (this.phaseObserver)
+            this.finishRequestPreparationOutcome('success');
+        let recording = false;
+        try {
+            recording = this.span.isRecording();
+        }
+        catch { /* Optional timing observation. */ }
+        if (!recording)
+            return;
+        this.recordResponseHeadersSpan();
+        this.setTiming(RESPONSE_PROCESSING_DURATION, this.responseProcessingDuration);
+    }
+    recordResponseHeadersSpan() {
+        if (this.responseHeadersSpanWritten)
+            return;
+        let recording = false;
+        try {
+            recording = this.span.isRecording();
+        }
+        catch { /* Optional timing observation. */ }
+        if (!recording)
+            return;
+        this.responseHeadersSpanWritten = true;
+        this.setTiming(RESPONSE_HEADERS_DURATION, this.responseHeadersDuration);
+    }
+    finishRequestPreparationOutcome(outcome) {
+        if (!this.phaseObserver || this.requestPreparationOutcomeSent)
+            return;
+        if (!this.requestPreparationMeasured) {
+            const finished = monotonicMilliseconds();
+            this.requestPreparationMeasured = true;
+            this.requestPreparationDuration = elapsedMilliseconds(this.requestPreparationStarted, finished);
+            this.setTiming(REQUEST_PREPARATION_DURATION, this.requestPreparationDuration);
+        }
+        this.requestPreparationOutcomeSent = true;
+        const durationMs = this.requestPreparationDuration;
+        if (durationMs === undefined)
+            return;
+        try {
+            this.phaseObserver({ phase: 'request_preparation', outcome, durationMs });
+        }
+        catch { /* Preserve request result. */ }
+    }
+    finishResponseHeadersOutcome(outcome) {
+        this.recordResponseHeadersSpan();
+        if (!this.phaseObserver || this.responseHeadersOutcomeSent)
+            return;
+        this.responseHeadersOutcomeSent = true;
+        const durationMs = this.responseHeadersDuration;
+        if (durationMs === undefined)
+            return;
+        try {
+            this.phaseObserver({ phase: 'response_headers', outcome, durationMs });
+        }
+        catch { /* Preserve request result. */ }
+    }
+    finishResponseOutcome(outcome) {
+        this.finishResponseProcessing();
+        if (!this.phaseObserver || this.responseProcessingOutcomeSent)
+            return;
+        this.responseProcessingOutcomeSent = true;
+        const durationMs = this.responseProcessingDuration;
+        if (durationMs !== undefined) {
+            try {
+                this.phaseObserver({ phase: 'response_processing', outcome, durationMs });
+            }
+            catch { /* Preserve request result. */ }
+        }
+    }
+    startStreamLifetime() {
+        if (!this.phaseObserver)
+            return;
+        this.streamLifetimeStarted = monotonicMilliseconds();
+    }
+    finishStreamLifetime(outcome) {
+        if (!this.phaseObserver || this.streamLifetimeStarted === undefined)
+            return;
+        const durationMs = elapsedMilliseconds(this.streamLifetimeStarted, monotonicMilliseconds());
+        this.streamLifetimeStarted = undefined;
+        if (durationMs === undefined)
+            return;
+        try {
+            this.phaseObserver({ phase: 'stream_lifetime', outcome, durationMs });
+        }
+        catch { /* Preserve stream result. */ }
+    }
+    finishResponseProcessing() {
+        if ((!this.timingEnabled && !this.phaseObserver) || this.responseProcessingStarted === undefined || this.responseProcessingMeasured)
+            return;
+        this.responseProcessingMeasured = true;
+        this.responseProcessingDuration = elapsedMilliseconds(this.responseProcessingStarted, monotonicMilliseconds());
+    }
+    finishObserverOutcome(outcome) {
+        if (!this.phaseObserver)
+            return;
+        this.finishResponseOutcome(outcome);
+    }
+    finishFailureOutcomes(error) {
+        if (!this.phaseObserver)
+            return;
+        let outcome;
+        try {
+            outcome = this.responseOutcome(error);
+        }
+        catch {
+            return;
+        }
+        try {
+            this.finishRequestPreparationOutcome(outcome);
+        }
+        catch { /* Preserve the caller's original failure. */ }
+        try {
+            this.finishObserverOutcome(outcome);
+        }
+        catch { /* Preserve the caller's original failure. */ }
+    }
+    response(response) {
+        this.responseStatus = response.status;
+        this.responseWasHttpError = !response.ok;
+        try {
+            this.span.setAttribute('http.response.status_code', response.status);
+        }
+        catch { /* Optional observation. */ }
+        try {
+            const requestId = response.headers.get('x-request-id') ?? '';
+            if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(requestId)) {
+                this.span.setAttribute('boxrouter.request.id', requestId);
+            }
+        }
+        catch { /* Optional observation. */ }
+        try {
+            if (!response.ok)
+                this.span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+        }
+        catch { /* Optional observation. */ }
+        try {
+            this.finishResponseHeadersOutcome(response.ok ? 'success' : 'http_error');
+        }
+        catch { /* Preserve the response. */ }
+        // Start body decoding only after response attributes and status have been recorded.
+        if (this.responseProcessingStarted !== undefined)
+            this.responseProcessingStarted = monotonicMilliseconds();
+    }
+    error(error) {
+        // Generated response handling may report errors before control returns to tracedRequest.
+        this.finishResponseProcessing();
+        let classified = error;
+        try {
+            if (classified instanceof api_error_1.RequestError) {
+                const cause = classified.cause;
+                if (cause !== undefined)
+                    classified = cause;
+            }
+        }
+        catch { /* Keep the fixed classifier safe when error properties are hostile. */ }
+        // Error.name/message and thrown response bodies can contain arbitrary payloads.
+        let type = 'unknown';
+        try {
+            type = classified?.code === 'parse_error' ? 'parse_error'
+                : isTimeoutError(classified) ? 'TimeoutError'
+                    : classified instanceof DOMException && classified.name === 'AbortError' ? 'AbortError'
+                        : classified instanceof TypeError ? 'TypeError'
+                            : classified instanceof SyntaxError ? 'SyntaxError' : classified instanceof Error ? 'Error' : 'unknown';
+        }
+        catch { /* Retain the fixed unknown classification. */ }
+        try {
+            this.span.setAttribute('error.type', type);
+        }
+        catch { /* Optional observation. */ }
+        try {
+            this.span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+        }
+        catch { /* Optional observation. */ }
+    }
+    responseOutcome(error) {
+        if (this.responseWasHttpError)
+            return 'http_error';
+        if (error instanceof api_error_1.APIError)
+            return 'parse_error';
+        try {
+            if (error?.code === 'parse_error')
+                return 'parse_error';
+        }
+        catch { /* Keep the fixed classifier safe when error properties are hostile. */ }
+        if (this.streamLifetimeStarted !== undefined)
+            return 'stream_error';
+        if (error instanceof api_error_1.RequestError) {
+            if (error.cause instanceof DOMException && error.cause.name === 'AbortError')
+                return 'cancelled';
+            if (error.response && !error.response.ok)
+                return 'http_error';
+            if (error.response)
+                return 'parse_error';
+            if (error.cause instanceof TypeError)
+                return 'network_error';
+            return 'network_error';
+        }
+        if (error instanceof DOMException && error.name === 'AbortError')
+            return 'cancelled';
+        if (error instanceof SyntaxError)
+            return 'parse_error';
+        if (error instanceof TypeError)
+            return 'network_error';
+        return 'unknown';
+    }
+    successfulResponseOutcome() {
+        return this.responseStatus !== undefined && this.responseStatus >= 400 ? 'http_error' : 'success';
+    }
+    setTiming(name, value) {
+        if (value === undefined)
+            return;
+        try {
+            this.span.setAttribute(name, value);
+        }
+        catch { /* Optional timing observation. */ }
+    }
+}
+exports.RequestTrace = RequestTrace;
+function tracedRequest(method, path, run) {
+    const telemetry = new RequestTrace(method, path);
+    let operation;
+    const finish = () => {
+        if (telemetry.streaming)
+            return;
+        try {
+            telemetry.finishBufferedResponse();
+        }
+        catch { /* Preserve the caller's result and failure. */ }
+        try {
+            telemetry.span.end();
+        }
+        catch { /* Optional observation. */ }
+    };
+    const runOnce = () => {
+        if (operation)
+            return operation;
+        let result;
+        try {
+            result = Promise.resolve(run(telemetry));
+        }
+        catch (error) {
+            result = Promise.reject(error);
+        }
+        operation = result.then(value => {
+            if (!telemetry.streaming) {
+                try {
+                    telemetry.finishResponseProcessing();
+                    telemetry.finishObserverOutcome(telemetry.successfulResponseOutcome());
+                }
+                catch { /* Preserve the caller's result. */ }
+            }
+            finish();
+            return value;
+        }, error => {
+            try {
+                telemetry.finishFailureOutcomes(error);
+            }
+            catch { /* Preserve the caller's original failure. */ }
+            try {
+                telemetry.error(error);
+            }
+            catch { /* Preserve the caller's original failure. */ }
+            finish();
+            throw error;
+        });
+        return operation;
+    };
+    let scoped;
+    try {
+        scoped = api_1.context.with(telemetry.context, runOnce);
+    }
+    catch { /* Run once outside failed observation. */ }
+    try {
+        void Promise.resolve(scoped).catch(() => undefined);
+    }
+    catch { /* Ignore optional context completion. */ }
+    return operation ?? runOnce();
+}

package/dist/terminal.d.ts

@@ -0,0 +1,61 @@
+import type { BoxRouterApi } from './sdk.gen';
+import type { SandboxTerminal, SandboxTerminalErrorEvent, SandboxTerminalExitEvent, SandboxTerminalOutputEvent } from './types.gen';
+import { type MutationOptions, type RequestOptions } from './sandboxes';
+/** Terminal output: the exact bytes the program wrote, decoded from the wire's base64. */
+export interface TerminalOutputEvent extends Omit<SandboxTerminalOutputEvent, 'data_base64'> {
+    data: Uint8Array;
+}
+export type TerminalEvent = TerminalOutputEvent | SandboxTerminalExitEvent | SandboxTerminalErrorEvent;
+export interface TerminalOptions extends MutationOptions {
+    rows?: number;
+    cols?: number;
+    timeoutSeconds?: number;
+    terminalId?: string;
+}
+export interface TerminalEvents {
+    stream: AsyncGenerator<TerminalEvent>;
+    /** Close this HTTP observer only; the shell keeps running. */
+    close(): void;
+}
+export interface TerminalOutputOptions extends RequestOptions {
+    /** Resume after this cursor; omitted resumes after the last event consumed by this handle. */
+    lastEventId?: string;
+}
+export declare class TerminalError extends Error {
+    readonly event: SandboxTerminalErrorEvent;
+    readonly code: string;
+    readonly outcome: SandboxTerminalErrorEvent['error']['outcome'];
+    readonly retry: SandboxTerminalErrorEvent['error']['retry'];
+    constructor(event: SandboxTerminalErrorEvent);
+}
+type RegisterObserver = (close: () => void) => () => void;
+export declare function closeObservers(observers: Iterable<() => void>): void;
+export declare function combineCleanupErrors(errors: unknown[], message: string): unknown;
+/**
+ * One PTY shell on any provider. Closing this handle detaches local observers only; the shell runs
+ * until it exits, is killed or reaches its timeout. Attach again with its id.
+ */
+export declare class Terminal {
+    #private;
+    readonly state: SandboxTerminal;
+    constructor(api: BoxRouterApi, state: SandboxTerminal, registerObserver?: RegisterObserver);
+    get id(): string;
+    get sandboxId(): string;
+    get lastEventId(): string | null;
+    get exitCode(): number | null;
+    /** Detach this handle's HTTP observers only; the remote shell keeps running. */
+    close(): void;
+    /** Raw typed events; an early end throws. */
+    events(options?: TerminalOutputOptions): Promise<TerminalEvents>;
+    /** Yield exact output chunks, then stop at exit; errors and incomplete streams raise. */
+    output(options?: TerminalOutputOptions): AsyncGenerator<Uint8Array>;
+    /** Await writes sequentially. Never replay an uncertain write. */
+    write(data: Uint8Array, options?: MutationOptions): Promise<void>;
+    /** Change the window size; the foreground program receives SIGWINCH. */
+    resize(rows: number, cols: number, options?: MutationOptions): Promise<void>;
+    /** End the shell; its exit event follows on the stream. */
+    kill(options?: MutationOptions): Promise<void>;
+}
+/** Open a PTY shell by sandbox ID, or attach to terminalId; observer ownership stays local. */
+export declare function openTerminal(api: BoxRouterApi, sandboxId: string, options?: TerminalOptions, registerObserver?: RegisterObserver): Promise<Terminal>;
+export {};