@astrale-os/kernel-client 0.5.1 → 0.6.0-beta.10

package/dist/transport/http/transport.js

@@ -0,0 +1,343 @@
+import * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import { ProtocolError, ResponseError, TransportError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
+import { asError, controlledSignal, positiveInteger, requireLive, } from '../index.js';
+import { binaryHeaders, codecForResponse, decodeProtocol, normalizeMediaType, readBoundedBody, requireId, } from './response.js';
+import { HttpStream } from './stream.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAXIMUM_REQUEST_BYTES = 16 * 1024 * 1024;
+const DEFAULT_MAXIMUM_RESPONSE_BYTES = 16 * 1024 * 1024;
+/** HTTP implementation of the universal invocation protocol. */
+export class HttpTransport {
+    url;
+    codecName;
+    fetchImpl;
+    headers;
+    timeoutMs;
+    maximumRequestBytes;
+    maximumResponseBytes;
+    nextId = 1;
+    constructor(options) {
+        if (options === null || typeof options !== 'object') {
+            throw new TypeError('HttpTransport options must be an object.');
+        }
+        this.url = normalizeUrl(options.url);
+        this.codecName = admitCodecName(options.codec);
+        this.fetchImpl = admitFetch(options.fetch);
+        this.headers = admitHeaders(options.headers ?? {});
+        this.timeoutMs = positiveInteger(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 'timeoutMs');
+        this.maximumRequestBytes = positiveInteger(options.maximumRequestBytes ?? DEFAULT_MAXIMUM_REQUEST_BYTES, 'maximumRequestBytes');
+        this.maximumResponseBytes = positiveInteger(options.maximumResponseBytes ?? DEFAULT_MAXIMUM_RESPONSE_BYTES, 'maximumResponseBytes');
+    }
+    async dispatch(input, options = {}) {
+        const requestId = this.nextRequestId();
+        const timeoutMs = positiveInteger(options.timeoutMs ?? this.timeoutMs, 'timeoutMs');
+        const codec = await this.requestCodec();
+        const { trace: traceInput, ...invocationInput } = input;
+        const trace = traceInput === undefined ? undefined : protocol.admitTrace(traceInput);
+        const request = protocol.decodeRequest({
+            version: protocol.VERSION,
+            requestId,
+            ...invocationInput,
+            ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
+        });
+        const encoded = codec.encode(request);
+        const control = controlledSignal(options.signal, timeoutMs);
+        let handedOff = false;
+        let phase = 'connect';
+        let delivery = 'not-sent';
+        try {
+            requireLive(control);
+            if (encodedByteLength(encoded) > this.maximumRequestBytes) {
+                throw invocationFailure(`request exceeds maximumRequestBytes (${this.maximumRequestBytes}).`, 'send');
+            }
+            phase = 'send';
+            delivery = 'unknown';
+            const response = await this.fetchResponse(codec, encoded, trace, control);
+            phase = 'receive';
+            requireLive(control);
+            if (response.status >= 300 && response.status < 400) {
+                throw new ProtocolError('server returned a network redirect.');
+            }
+            requireNoStore(response);
+            const streamFraming = response.headers.get(protocol.http.STREAM_FRAMING_FIELD);
+            const binaryId = response.headers.get(protocol.http.REQUEST_ID_FIELD);
+            const binaryManifest = response.headers.get(protocol.http.BINARY_HEADERS_FIELD);
+            const hasStreamSignal = streamFraming !== null;
+            const hasBinarySignal = binaryId !== null || binaryManifest !== null;
+            if (hasStreamSignal && hasBinarySignal) {
+                throw new ProtocolError('server returned conflicting stream and binary response signals.');
+            }
+            if (hasBinarySignal) {
+                if (binaryId === null || binaryManifest === null) {
+                    throw new ProtocolError('server returned an incomplete binary response signal.');
+                }
+                return await this.decodeBinary(response, requestId, binaryId, control);
+            }
+            const responseCodec = await codecForResponse(response.headers.get('content-type'));
+            if (responseCodec === undefined) {
+                throw new ProtocolError(`server returned unsupported Content-Type ${JSON.stringify(response.headers.get('content-type'))}.`);
+            }
+            if (hasStreamSignal) {
+                if (streamFraming !== protocol.http.LENGTH_PREFIX_V1) {
+                    throw new ProtocolError(`server returned unsupported stream framing ${JSON.stringify(streamFraming)}.`);
+                }
+                if (!response.ok) {
+                    throw new ProtocolError('server returned a non-success stream response.');
+                }
+                const stream = await HttpStream.open(response, responseCodec, requestId, this.maximumResponseBytes, control);
+                requireLive(control);
+                handedOff = true;
+                return { kind: 'stream', stream, invocation: stream.invocation };
+            }
+            const body = await readBoundedBody(response, this.maximumResponseBytes, control.signal);
+            requireLive(control);
+            const decoded = decodeProtocol('response body', () => responseCodec.decode(body));
+            const envelope = decodeProtocol('response envelope', () => protocol.decodeResponse(decoded));
+            if (envelope.requestId === null && 'error' in envelope) {
+                throw new ResponseError(envelope.error.code, envelope.error.message, envelope.invocation, envelope.error.data);
+            }
+            requireId(requestId, envelope.requestId);
+            if ('kind' in envelope && envelope.kind === 'stale') {
+                const stale = decodeProtocol('stale response', () => protocol.decodeStale(envelope));
+                requireLive(control);
+                return Object.freeze({
+                    kind: 'stale',
+                    current: stale.current,
+                    invocation: stale.invocation,
+                });
+            }
+            if ('kind' in envelope && envelope.kind === 'miss') {
+                decodeProtocol('miss response', () => protocol.decodeMiss(envelope));
+                requireLive(control);
+                return Object.freeze({ kind: 'miss', invocation: envelope.invocation });
+            }
+            if ('kind' in envelope && envelope.kind === 'redirect') {
+                const response = decodeProtocol('redirect response', () => protocol.decodeRedirectResponse(envelope));
+                requireLive(control);
+                return redirectResult(response);
+            }
+            if ('error' in envelope) {
+                throw new ResponseError(envelope.error.code, envelope.error.message, envelope.invocation, envelope.error.data);
+            }
+            requireLive(control);
+            return { kind: 'value', value: envelope.result, invocation: envelope.invocation };
+        }
+        catch (error) {
+            throw transportFailure(error, control, options.signal, timeoutMs, this.url, phase, delivery);
+        }
+        finally {
+            if (!handedOff)
+                control.close();
+        }
+    }
+    async fetchResponse(codec, encoded, trace, control) {
+        return this.fetchImpl(this.url, {
+            method: 'POST',
+            redirect: 'error',
+            credentials: 'omit',
+            cache: 'no-store',
+            referrerPolicy: 'no-referrer',
+            headers: {
+                ...this.headers,
+                ...protocol.http.encodeTraceHeaders(trace),
+                'content-type': codec.contentType,
+                accept: codec.contentType,
+            },
+            body: toBody(encoded),
+            signal: control.signal,
+        });
+    }
+    async decodeBinary(response, requestId, binaryId, control) {
+        if (!response.ok) {
+            throw new ProtocolError('server returned binary data with an error status.');
+        }
+        if (binaryId !== String(requestId)) {
+            throw new ProtocolError(`binary response requestId ${JSON.stringify(binaryId)} does not match request requestId ${requestId}.`);
+        }
+        const mediaType = normalizeMediaType(response.headers.get('content-type'));
+        if (mediaType === undefined) {
+            throw new ProtocolError('binary response has no media type.');
+        }
+        const body = await readBoundedBody(response, this.maximumResponseBytes, control.signal);
+        requireLive(control);
+        const headerNames = decodeProtocol('binary application-header manifest', () => protocol.http.decodeBinaryHeaderNames(response.headers.get(protocol.http.BINARY_HEADERS_FIELD)));
+        const headers = binaryHeaders(response.headers, headerNames);
+        const invocation = decodeProtocol('binary InvocationId field', () => protocol.http.decodeInvocationId(response.headers.get(protocol.http.INVOCATION_FIELD)));
+        const binary = decodeProtocol('binary response', () => protocol.decodeBinaryResponse({
+            kind: 'binary',
+            requestId,
+            invocation,
+            body,
+            mediaType,
+            ...(Object.keys(headers).length === 0 ? {} : { headers }),
+        }));
+        requireLive(control);
+        return {
+            kind: 'binary',
+            invocation: binary.invocation,
+            value: {
+                body: binary.body,
+                mediaType: binary.mediaType,
+                ...(binary.headers === undefined ? {} : { headers: binary.headers }),
+            },
+        };
+    }
+    nextRequestId() {
+        const requestId = this.nextId;
+        this.nextId = requestId === Number.MAX_SAFE_INTEGER ? 1 : requestId + 1;
+        return requestId;
+    }
+    requestCodec() {
+        return this.codecName === 'msgpack' ? codecs.loadMsgpack() : Promise.resolve(codecs.json);
+    }
+}
+function redirectResult(response) {
+    return Object.freeze({
+        kind: 'redirect',
+        invocation: response.invocation,
+        redirect: response.redirect,
+    });
+}
+function normalizeUrl(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('server URL must be a string.');
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch (error) {
+        throw new TypeError(`Invalid server URL ${JSON.stringify(input)}.`, { cause: asError(error) });
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new TypeError('server URL must use http or https.');
+    }
+    if (parsed.username !== '' || parsed.password !== '' || parsed.hash !== '') {
+        throw new TypeError('server URL cannot contain credentials or a fragment.');
+    }
+    return parsed.toString();
+}
+function admitHeaders(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('HTTP headers must be an object.');
+    }
+    const output = {};
+    for (const [name, value] of Object.entries(input)) {
+        if (!HEADER_NAME.test(name)) {
+            throw new TypeError(`HTTP header name ${JSON.stringify(name)} is invalid.`);
+        }
+        const normalized = name.toLowerCase();
+        if (Object.hasOwn(output, normalized)) {
+            throw new TypeError(`HTTP header ${JSON.stringify(name)} occurs more than once.`);
+        }
+        if (isReservedRequestHeader(normalized)) {
+            throw new TypeError(`HTTP header ${JSON.stringify(name)} is owned by transport.`);
+        }
+        if (typeof value !== 'string') {
+            throw new TypeError(`HTTP header ${JSON.stringify(name)} must be a string.`);
+        }
+        if (hasControlCharacter(value)) {
+            throw new TypeError(`HTTP header ${JSON.stringify(name)} contains a control character.`);
+        }
+        output[normalized] = value;
+    }
+    return Object.freeze(output);
+}
+function toBody(input) {
+    if (typeof input === 'string')
+        return input;
+    const copy = new Uint8Array(input);
+    return copy.buffer;
+}
+function encodedByteLength(input) {
+    return typeof input === 'string' ? new TextEncoder().encode(input).byteLength : input.byteLength;
+}
+function requireNoStore(response) {
+    const directives = response.headers
+        .get('cache-control')
+        ?.split(',')
+        .map((directive) => directive.trim().toLowerCase()) ?? [];
+    if (!directives.includes('no-store')) {
+        throw new ProtocolError('server response is missing Cache-Control: no-store.');
+    }
+}
+function transportFailure(input, control, parent, timeoutMs, url, phase, delivery) {
+    if (input instanceof ResponseError || input instanceof ProtocolError)
+        return input;
+    if (control.timedOut) {
+        return invocationFailure(`request timed out after ${timeoutMs}ms.`, 'timeout', {
+            cause: asError(input),
+            delivery,
+        });
+    }
+    if (parent?.aborted)
+        return asError(parent.reason ?? input);
+    return input instanceof TransportError
+        ? input
+        : invocationFailure(`Failed to communicate with the server at ${url}.`, phase, {
+            cause: asError(input),
+            delivery,
+        });
+}
+function admitCodecName(input) {
+    if (input === undefined || input === 'json')
+        return 'json';
+    if (input === 'msgpack')
+        return input;
+    throw new TypeError('codec must be "json" or "msgpack".');
+}
+function admitFetch(input) {
+    const implementation = input ?? globalThis.fetch;
+    if (typeof implementation !== 'function') {
+        throw new TypeError('HttpTransport requires a Fetch implementation.');
+    }
+    return input === undefined ? implementation.bind(globalThis) : implementation;
+}
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const RESERVED_REQUEST_HEADERS = new Set([
+    'accept',
+    'accept-encoding',
+    'authorization',
+    'cache-control',
+    'connection',
+    'content-length',
+    'content-type',
+    'cookie',
+    'expect',
+    'forwarded',
+    'host',
+    'keep-alive',
+    'origin',
+    'pragma',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'referer',
+    'referrer-policy',
+    'set-cookie',
+    'te',
+    protocol.http.TRACEPARENT_FIELD,
+    protocol.http.TRACESTATE_FIELD,
+    protocol.http.BAGGAGE_FIELD,
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    'via',
+]);
+function isReservedRequestHeader(name) {
+    return (RESERVED_REQUEST_HEADERS.has(name) ||
+        name.startsWith('access-control-') ||
+        name.startsWith('content-') ||
+        name.startsWith('proxy-') ||
+        name.startsWith('sec-websocket-') ||
+        name.startsWith('x-astrale-') ||
+        name.startsWith('x-forwarded-'));
+}
+function hasControlCharacter(input) {
+    for (let index = 0; index < input.length; index += 1) {
+        const code = input.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}

package/dist/transport/index.d.ts

@@ -1,8 +1,2 @@
-export type { BatchEntry, Transport, TransportRequest } from './contract.js';
-export { HttpEnvelopeTransport, type HttpEnvelopeTransportConfig } from './http-envelope.js';
-export { WsEnvelopeTransport, type WsEnvelopeTransportConfig } from './ws-envelope.js';
-export { HttpRoutedTransport, type HttpRoutedTransportConfig, type RoutedTransportRequest, } from './http-routed.js';
-export type { BinaryResponse } from './binary.js';
-export { safeFetch } from './fetch.js';
-export { nextRequestId } from './request-id.js';
-//# sourceMappingURL=index.d.ts.map
+export type { RequestOptions, MissControl, StaleControl, Transport, TransportRequest, TransportResult, } from './transport.js';
+export { asError, controlledSignal, positiveInteger, requireLive, type ControlledSignal, } from './deadline.js';

package/dist/transport/index.js

@@ -1,6 +1 @@
-export { HttpEnvelopeTransport } from './http-envelope.js';
-export { WsEnvelopeTransport } from './ws-envelope.js';
-export { HttpRoutedTransport, } from './http-routed.js';
-export { safeFetch } from './fetch.js';
-export { nextRequestId } from './request-id.js';
-//# sourceMappingURL=index.js.map
+export { asError, controlledSignal, positiveInteger, requireLive, } from './deadline.js';

package/dist/transport/transport.d.ts

@@ -0,0 +1,34 @@
+import type { invocation as protocol } from '@astrale-os/kernel-protocol';
+import type { Result } from '../client/result.js';
+export interface RequestOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly idempotencyKey?: protocol.IdempotencyKey;
+}
+export interface TransportRequest {
+    readonly call: protocol.Call;
+    /** Internally supplied per-attempt correlation syntax; never a RequestOptions field. */
+    readonly trace?: protocol.Trace;
+    readonly credential?: string;
+    readonly delegate?: protocol.Delegate;
+    readonly routing?: protocol.Routing;
+    /** Source-Kernel Schema Registration precondition; omitted after routing. */
+    readonly schema?: protocol.SchemaTarget;
+}
+/** Correlated reserved control decoded independently from application results and errors. */
+export interface StaleControl {
+    readonly kind: 'stale';
+    readonly current: protocol.Stale['current'];
+    readonly invocation: protocol.InvocationId;
+}
+export interface MissControl {
+    readonly kind: 'miss';
+    readonly invocation: protocol.InvocationId;
+}
+export type TransportResult = Result | StaleControl | MissControl;
+export interface Transport {
+    /** Primary embedding-environment adapter for a complete invocation boundary. */
+    dispatch(input: TransportRequest, options?: RequestOptions): Promise<TransportResult>;
+    /** Optional owned-resource shutdown used by Client.close(). */
+    readonly close?: () => void;
+}

package/dist/transport/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/transport/websocket/connection.d.ts

@@ -0,0 +1,38 @@
+import type * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import type { ControlledSignal } from '../index.js';
+import type { TransportResult } from '../index.js';
+import type { ExchangeOwner } from './exchange.js';
+import type { WebSocketConstructor } from './transport.js';
+import { WebSocketExchange } from './exchange.js';
+export interface ConnectionOwner {
+    closed(connection: WebSocketConnection): void;
+}
+export declare class WebSocketConnection implements ExchangeOwner {
+    private readonly owner;
+    private readonly codec;
+    private readonly maximumRequestBytes;
+    private readonly maximumResponseBytes;
+    private readonly maximumBufferedBytes;
+    private readonly maximumActiveInvocations;
+    private readonly socket;
+    private readonly ready;
+    private resolveReady;
+    private rejectReady;
+    private opened;
+    private closedState;
+    private readonly active;
+    private readonly cancelled;
+    private incoming;
+    constructor(owner: ConnectionOwner, WebSocketConstructor: WebSocketConstructor, url: string, codec: codecs.Codec, maximumRequestBytes: number, maximumResponseBytes: number, maximumBufferedBytes: number, maximumActiveInvocations: number);
+    get isOpen(): boolean;
+    get isAvailable(): boolean;
+    connect(control: ControlledSignal): Promise<void>;
+    dispatch(request: protocol.Request, control: ControlledSignal, maximumBufferedItems: number): Promise<TransportResult>;
+    finish(exchange: WebSocketExchange, reusable: boolean, closeCode?: 1002 | 1008 | 1011): void;
+    cancel(exchange: WebSocketExchange, requestId: protocol.RequestId): void;
+    shutdown(reason?: Error, closeCode?: number, closeReason?: string): void;
+    private onOpen;
+    private onMessage;
+    private onFailure;
+}