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

package/dist/transport/auto/transport.d.ts

@@ -0,0 +1,37 @@
+import type { Fetch } from '../http/index.js';
+import type { RequestOptions, Transport, TransportRequest, TransportResult } from '../index.js';
+import type { WebSocketConstructor } from '../websocket/index.js';
+import type { ClientWarning } from './warning.js';
+export interface AutoTransportOptions {
+    readonly endpoints: {
+        readonly http: string;
+        readonly websocket: string;
+    };
+    readonly codec?: 'json' | 'msgpack';
+    readonly fetch?: Fetch;
+    readonly websocket?: WebSocketConstructor;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+    readonly maximumRequestBytes?: number;
+    readonly maximumResponseBytes?: number;
+    readonly maximumBufferedBytes?: number;
+    readonly maximumActiveInvocations?: number;
+    readonly maximumBufferedStreamItems?: number;
+    readonly onWarning?: (warning: ClientWarning) => void;
+}
+/** Sticky WebSocket-first Transport with one delivery-aware HTTP fallback decision. */
+export declare class AutoTransport implements Transport {
+    private readonly websocket;
+    private readonly http;
+    private readonly decision;
+    private readonly timeoutMs;
+    private readonly onWarning;
+    private closed;
+    constructor(options: AutoTransportOptions);
+    dispatch(input: TransportRequest, options?: RequestOptions): Promise<TransportResult>;
+    private dispatchWithBudget;
+    close(): void;
+    private determine;
+    private tryWebsocket;
+    private requireOpen;
+}

package/dist/transport/auto/transport.js

@@ -0,0 +1,140 @@
+import { TransportError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
+import { HttpTransport } from '../http/index.js';
+import { positiveInteger } from '../index.js';
+import { WebSocketTransport } from '../websocket/index.js';
+import { AutoDecision } from './decision.js';
+import { InvocationBudget, mayFallback, warningTarget } from './fallback.js';
+import { emitWarning } from './warning.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Sticky WebSocket-first Transport with one delivery-aware HTTP fallback decision. */
+export class AutoTransport {
+    websocket;
+    http;
+    decision = new AutoDecision();
+    timeoutMs;
+    onWarning;
+    closed = false;
+    constructor(options) {
+        if (options === null || typeof options !== 'object') {
+            throw new TypeError('AutoTransport options must be an object.');
+        }
+        if (options.onWarning !== undefined && typeof options.onWarning !== 'function') {
+            throw new TypeError('AutoTransport onWarning must be a function.');
+        }
+        this.timeoutMs = positiveInteger(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 'timeoutMs');
+        this.onWarning = options.onWarning;
+        this.http = new HttpTransport({
+            url: options.endpoints.http,
+            ...(options.codec === undefined ? {} : { codec: options.codec }),
+            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+            ...(options.headers === undefined ? {} : { headers: options.headers }),
+            timeoutMs: this.timeoutMs,
+            ...(options.maximumRequestBytes === undefined
+                ? {}
+                : { maximumRequestBytes: options.maximumRequestBytes }),
+            ...(options.maximumResponseBytes === undefined
+                ? {}
+                : { maximumResponseBytes: options.maximumResponseBytes }),
+        });
+        this.websocket = new WebSocketTransport({
+            url: options.endpoints.websocket,
+            ...(options.codec === undefined ? {} : { codec: options.codec }),
+            ...(options.websocket === undefined ? {} : { websocket: options.websocket }),
+            timeoutMs: this.timeoutMs,
+            ...(options.maximumRequestBytes === undefined
+                ? {}
+                : { maximumRequestBytes: options.maximumRequestBytes }),
+            ...(options.maximumResponseBytes === undefined
+                ? {}
+                : { maximumResponseBytes: options.maximumResponseBytes }),
+            ...(options.maximumBufferedBytes === undefined
+                ? {}
+                : { maximumBufferedBytes: options.maximumBufferedBytes }),
+            ...(options.maximumActiveInvocations === undefined
+                ? {}
+                : { maximumActiveInvocations: options.maximumActiveInvocations }),
+            ...(options.maximumBufferedStreamItems === undefined
+                ? {}
+                : { maximumBufferedStreamItems: options.maximumBufferedStreamItems }),
+        });
+    }
+    async dispatch(input, options) {
+        this.requireOpen();
+        const budget = new InvocationBudget(options, this.timeoutMs);
+        return this.dispatchWithBudget(input, budget);
+    }
+    async dispatchWithBudget(input, budget) {
+        const ticket = this.decision.begin();
+        if (ticket.kind === 'selected') {
+            return ticket.selection === 'websocket'
+                ? this.tryWebsocket(input, budget, false)
+                : this.http.dispatch(input, budget.options());
+        }
+        if (ticket.kind === 'wait') {
+            const selection = await budget.wait(ticket.selection);
+            this.requireOpen();
+            if (!selection)
+                return this.dispatchWithBudget(input, budget);
+            return selection === 'websocket'
+                ? this.tryWebsocket(input, budget, false)
+                : this.http.dispatch(input, budget.options());
+        }
+        return this.determine(input, budget);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.decision.close();
+        this.websocket.close();
+    }
+    async determine(input, budget) {
+        return this.tryWebsocket(input, budget, true);
+    }
+    async tryWebsocket(input, budget, probing) {
+        try {
+            const result = await this.websocket.dispatch(input, budget.options());
+            if (probing)
+                this.decision.select('websocket');
+            return result;
+        }
+        catch (error) {
+            if (budget.cancelled) {
+                if (probing)
+                    this.decision.release();
+                throw error;
+            }
+            if (error instanceof TransportError &&
+                error.context.kind === 'invocation' &&
+                error.context.delivery === 'unknown') {
+                this.decision.demote();
+                throw error;
+            }
+            if (!mayFallback(error)) {
+                if (probing) {
+                    this.decision.select('websocket');
+                }
+                throw error;
+            }
+            const idempotency = budget.idempotency;
+            const warning = {
+                code: 'AUTO_TRANSPORT_DOWNGRADED',
+                target: warningTarget(input),
+                websocket: this.websocket.url,
+                http: this.http.url,
+                phase: error.phase,
+                delivery: 'not-sent',
+                idempotency,
+            };
+            emitWarning(Object.freeze(warning), this.onWarning);
+            this.decision.demote();
+            return this.http.dispatch(input, budget.options());
+        }
+    }
+    requireOpen() {
+        if (!this.closed)
+            return;
+        throw invocationFailure('AutoTransport is closed.', 'closed');
+    }
+}

package/dist/transport/auto/warning.d.ts

@@ -0,0 +1,13 @@
+import type { NodePath } from '@astrale-os/kernel-core/path';
+import type { TransportPhase } from '../../errors/index.js';
+export interface ClientWarning {
+    readonly code: 'AUTO_TRANSPORT_DOWNGRADED';
+    readonly target: NodePath;
+    readonly websocket: string;
+    readonly http: string;
+    readonly phase: TransportPhase;
+    readonly delivery: 'not-sent';
+    readonly idempotency: 'supplied' | 'absent';
+}
+export declare function formatClientWarning(warning: ClientWarning): string;
+export declare function emitWarning(warning: ClientWarning, observer: ((warning: ClientWarning) => void) | undefined): void;

package/dist/transport/auto/warning.js

@@ -0,0 +1,18 @@
+export function formatClientWarning(warning) {
+    return [
+        '[Astrale] WebSocket was unavailable before send; using HTTP for this client.',
+        `idempotency=${warning.idempotency}`,
+        `target=${JSON.stringify(warning.target)} websocket=${warning.websocket} http=${warning.http} phase=${warning.phase}`,
+    ].join(' ');
+}
+export function emitWarning(warning, observer) {
+    try {
+        if (observer)
+            observer(warning);
+        else
+            globalThis.console?.warn(formatClientWarning(warning));
+    }
+    catch {
+        // Warning observation cannot change invocation settlement.
+    }
+}

package/dist/transport/deadline.d.ts

@@ -0,0 +1,11 @@
+export interface ControlledSignal {
+    readonly signal: AbortSignal;
+    readonly timedOut: boolean;
+    cancel(reason?: unknown): void;
+    close(): void;
+}
+/** One caller signal plus one transport-owned lifetime deadline. */
+export declare function controlledSignal(parent: AbortSignal | undefined, timeoutMs: number): ControlledSignal;
+export declare function positiveInteger(input: number, label: string): number;
+export declare function requireLive(control: ControlledSignal): void;
+export declare function asError(value: unknown): Error;

package/dist/transport/deadline.js

@@ -0,0 +1,39 @@
+/** One caller signal plus one transport-owned lifetime deadline. */
+export function controlledSignal(parent, timeoutMs) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const abort = () => controller.abort(parent?.reason);
+    if (parent?.aborted)
+        abort();
+    else
+        parent?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort(new Error('request timeout'));
+    }, timeoutMs);
+    return {
+        signal: controller.signal,
+        get timedOut() {
+            return timedOut;
+        },
+        cancel: (reason) => controller.abort(reason),
+        close: () => {
+            clearTimeout(timer);
+            parent?.removeEventListener('abort', abort);
+        },
+    };
+}
+export function positiveInteger(input, label) {
+    if (!Number.isSafeInteger(input) || input < 1 || input > 2_147_483_647) {
+        throw new TypeError(`${label} must be a positive safe platform integer.`);
+    }
+    return input;
+}
+export function requireLive(control) {
+    if (!control.signal.aborted)
+        return;
+    throw control.signal.reason ?? new Error('request was cancelled.');
+}
+export function asError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}

package/dist/transport/failure.d.ts

@@ -0,0 +1,7 @@
+import { TransportError, type InvocationTransportErrorOptions } from '../errors/index.js';
+type InvocationFailureEvidence = Omit<InvocationTransportErrorOptions, 'delivery' | 'phase'> & {
+    readonly delivery?: InvocationTransportErrorOptions['delivery'];
+};
+/** Create invocation transport evidence with the common not-sent default. */
+export declare function invocationFailure(message: string, phase: InvocationTransportErrorOptions['phase'], evidence?: InvocationFailureEvidence): TransportError;
+export {};

package/dist/transport/failure.js

@@ -0,0 +1,9 @@
+import { TransportError } from '../errors/index.js';
+/** Create invocation transport evidence with the common not-sent default. */
+export function invocationFailure(message, phase, evidence = {}) {
+    return TransportError.invocation(message, {
+        ...evidence,
+        phase,
+        delivery: evidence.delivery ?? 'not-sent',
+    });
+}

package/dist/transport/http/index.d.ts

@@ -0,0 +1 @@
+export { HttpTransport, type Fetch, type HttpTransportOptions } from './transport.js';

package/dist/transport/http/index.js

@@ -0,0 +1 @@
+export { HttpTransport } from './transport.js';

package/dist/transport/http/response.d.ts

@@ -0,0 +1,8 @@
+import * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+export declare function codecForResponse(contentType: string | null): Promise<codecs.Codec | undefined>;
+export declare function readBoundedBody(response: Response, maximumBytes: number, signal: AbortSignal): Promise<Uint8Array>;
+export declare function requireId(expected: protocol.RequestId, received: protocol.RequestId): void;
+export declare function decodeProtocol<T>(label: string, decode: () => T): T;
+export declare function normalizeMediaType(input: string | null): string | undefined;
+export declare function binaryHeaders(input: Headers, names: readonly string[]): Readonly<Record<string, string>>;

package/dist/transport/http/response.js

@@ -0,0 +1,79 @@
+import * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import { ProtocolError, ResponseError } from '../../errors/index.js';
+import { asError } from '../index.js';
+export async function codecForResponse(contentType) {
+    const mediaType = normalizeMediaType(contentType);
+    const supported = mediaType === codecs.CONTENT_TYPE_MSGPACK
+        ? [codecs.json, await codecs.loadMsgpack()]
+        : [codecs.json];
+    return protocol.http.codecForContentType(contentType, supported);
+}
+export async function readBoundedBody(response, maximumBytes, signal) {
+    const declared = response.headers.get('content-length');
+    if (declared !== null && Number(declared) > maximumBytes) {
+        throw new ProtocolError(`response exceeds maximumResponseBytes (${maximumBytes}).`);
+    }
+    if (response.body === null)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            if (signal.aborted)
+                throw signal.reason;
+            const next = await reader.read();
+            if (next.done)
+                break;
+            total += next.value.byteLength;
+            if (total > maximumBytes) {
+                throw new ProtocolError(`response exceeds maximumResponseBytes (${maximumBytes}).`);
+            }
+            chunks.push(next.value);
+        }
+    }
+    catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        throw error;
+    }
+    const output = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+}
+export function requireId(expected, received) {
+    if (received !== expected) {
+        throw new ProtocolError(`response id ${JSON.stringify(received)} does not match request id ${JSON.stringify(expected)}.`);
+    }
+}
+export function decodeProtocol(label, decode) {
+    try {
+        return decode();
+    }
+    catch (error) {
+        if (error instanceof ResponseError || error instanceof ProtocolError)
+            throw error;
+        throw new ProtocolError(`server returned an invalid ${label}.`, { cause: asError(error) });
+    }
+}
+export function normalizeMediaType(input) {
+    if (input === null)
+        return undefined;
+    const value = input.split(';', 1)[0]?.trim().toLowerCase();
+    return value === '' ? undefined : value;
+}
+export function binaryHeaders(input, names) {
+    const output = {};
+    for (const name of names) {
+        const value = input.get(name);
+        if (value === null) {
+            throw new ProtocolError(`server omitted declared binary application header ${name}.`);
+        }
+        output[name] = value;
+    }
+    return Object.freeze(output);
+}

package/dist/transport/http/stream.d.ts

@@ -0,0 +1,26 @@
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import type { Stream } from '../../client/index.js';
+import { type ControlledSignal } from '../index.js';
+export declare class HttpStream implements Stream {
+    private readonly frames;
+    private readonly codec;
+    private readonly requestId;
+    private readonly control;
+    invocation: protocol.InvocationId;
+    private claimed;
+    private terminal;
+    private index;
+    private interruption;
+    private constructor();
+    static open(response: Response, codec: codecs.Codec, requestId: protocol.RequestId, maximumFrameBytes: number, control: ControlledSignal): Promise<HttpStream>;
+    [Symbol.asyncIterator](): AsyncIterator<Value>;
+    cancel(reason?: string): Promise<void>;
+    private next;
+    private readFrame;
+    private finish;
+    private interrupt;
+    private stop;
+    private abortFailure;
+}

package/dist/transport/http/stream.js

@@ -0,0 +1,214 @@
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import { ProtocolError, ResponseError, TransportError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
+import { asError } from '../index.js';
+import { decodeProtocol, requireId } from './response.js';
+export class HttpStream {
+    frames;
+    codec;
+    requestId;
+    control;
+    invocation;
+    claimed = false;
+    terminal = false;
+    index = 0;
+    interruption;
+    constructor(frames, codec, requestId, control) {
+        this.frames = frames;
+        this.codec = codec;
+        this.requestId = requestId;
+        this.control = control;
+        const abort = () => void this.interrupt(this.abortFailure(control.signal.reason));
+        if (control.signal.aborted)
+            abort();
+        else
+            control.signal.addEventListener('abort', abort, { once: true });
+    }
+    static async open(response, codec, requestId, maximumFrameBytes, control) {
+        if (response.body === null)
+            throw new ProtocolError('stream has no body.');
+        const stream = new HttpStream(new LengthPrefixedFrames(response.body.getReader(), maximumFrameBytes), codec, requestId, control);
+        const first = await stream.readFrame();
+        if (first === null || first.kind !== 'stream.start') {
+            await stream.stop('invalid stream start');
+            throw new ProtocolError('stream did not begin with stream.start.');
+        }
+        stream.invocation = first.invocation;
+        return stream;
+    }
+    [Symbol.asyncIterator]() {
+        if (this.claimed)
+            throw new TypeError('streams admit exactly one consumer.');
+        this.claimed = true;
+        return {
+            next: () => this.next(),
+            return: async () => {
+                await this.cancel('stream consumer stopped');
+                return { done: true, value: undefined };
+            },
+            throw: async (error) => {
+                await this.cancel('stream consumer failed');
+                throw error;
+            },
+        };
+    }
+    async cancel(reason = 'stream cancelled') {
+        await this.stop(reason);
+    }
+    async next() {
+        if (this.interruption !== undefined)
+            throw this.interruption;
+        if (this.terminal)
+            return { done: true, value: undefined };
+        try {
+            const frame = await this.readFrame();
+            if (frame === null) {
+                throw new ProtocolError('stream ended without a terminal frame.');
+            }
+            if (frame.kind === 'stream.item') {
+                if (frame.index !== this.index) {
+                    throw new ProtocolError(`stream item ${frame.index} does not match expected index ${this.index}.`);
+                }
+                this.index += 1;
+                return { done: false, value: frame.value };
+            }
+            if (frame.kind === 'stream.error') {
+                await this.finish();
+                throw new ResponseError(frame.error.code, frame.error.message, this.invocation, frame.error.data);
+            }
+            if (frame.kind !== 'stream.end') {
+                throw new ProtocolError(`Unexpected ${frame.kind} frame inside stream.`);
+            }
+            if (frame.count !== this.index) {
+                throw new ProtocolError(`stream ended with count ${frame.count}; ${this.index} items were received.`);
+            }
+            await this.finish();
+            return { done: true, value: undefined };
+        }
+        catch (error) {
+            const failure = this.interruption ?? retainInvocationId(error, this.invocation);
+            await this.stop(failure);
+            throw failure;
+        }
+    }
+    async readFrame() {
+        const payload = await this.frames.read();
+        if (this.interruption !== undefined)
+            throw this.interruption;
+        if (payload === null)
+            return null;
+        const frame = decodeProtocol('stream frame', () => protocol.decodeStreamFrame(this.codec.decode(payload)));
+        requireId(this.requestId, frame.requestId);
+        return frame;
+    }
+    async finish() {
+        if (this.terminal)
+            return;
+        await this.frames.requireEnd();
+        this.terminal = true;
+        this.control.close();
+    }
+    async interrupt(reason) {
+        if (this.terminal || this.interruption !== undefined)
+            return;
+        this.interruption = reason;
+        await this.frames.cancel(reason);
+        this.control.close();
+    }
+    async stop(reason) {
+        if (this.terminal)
+            return;
+        this.terminal = true;
+        this.control.cancel(reason);
+        await this.frames.cancel(reason);
+        this.control.close();
+    }
+    abortFailure(reason) {
+        if (this.control.timedOut) {
+            return invocationFailure('stream exceeded its invocation timeout.', 'timeout', {
+                cause: asError(reason),
+                delivery: 'unknown',
+                invocation: this.invocation,
+            });
+        }
+        return asError(reason ?? new Error('stream was cancelled.'));
+    }
+}
+function retainInvocationId(input, invocation) {
+    if (input instanceof ProtocolError && input.invocation === undefined) {
+        return new ProtocolError(input.message, { cause: input, invocation });
+    }
+    if (input instanceof TransportError &&
+        input.context.kind === 'invocation' &&
+        input.context.invocation === undefined) {
+        return invocationFailure(input.message, input.phase, {
+            cause: input,
+            delivery: input.context.delivery,
+            invocation,
+        });
+    }
+    return input;
+}
+class LengthPrefixedFrames {
+    reader;
+    maximumFrameBytes;
+    chunk = new Uint8Array();
+    offset = 0;
+    done = false;
+    constructor(reader, maximumFrameBytes) {
+        this.reader = reader;
+        this.maximumFrameBytes = maximumFrameBytes;
+    }
+    async read() {
+        const header = await this.take(4, true);
+        if (header === null)
+            return null;
+        const length = new DataView(header.buffer, header.byteOffset, header.byteLength).getUint32(0);
+        if (length > this.maximumFrameBytes) {
+            throw new ProtocolError(`stream frame exceeds maximumResponseBytes (${this.maximumFrameBytes}).`);
+        }
+        return (await this.take(length, false));
+    }
+    async requireEnd() {
+        const extra = await this.take(1, true);
+        if (extra !== null) {
+            throw new ProtocolError('stream contains data after its terminal frame.');
+        }
+    }
+    async cancel(reason) {
+        try {
+            await this.reader.cancel(reason);
+        }
+        catch {
+            // Cancellation is best-effort after the client has already chosen a terminal outcome.
+        }
+    }
+    async take(length, allowCleanEnd) {
+        const output = new Uint8Array(length);
+        let written = 0;
+        while (written < length) {
+            if (this.offset === this.chunk.byteLength) {
+                if (this.done) {
+                    if (allowCleanEnd && written === 0)
+                        return null;
+                    throw new ProtocolError('stream ended in the middle of a frame.');
+                }
+                const next = await this.reader.read();
+                if (next.done) {
+                    this.done = true;
+                    continue;
+                }
+                this.chunk = next.value;
+                this.offset = 0;
+                if (this.chunk.byteLength === 0)
+                    continue;
+            }
+            const available = this.chunk.byteLength - this.offset;
+            const count = Math.min(available, length - written);
+            output.set(this.chunk.subarray(this.offset, this.offset + count), written);
+            written += count;
+            this.offset += count;
+        }
+        return output;
+    }
+}

package/dist/transport/http/transport.d.ts

@@ -0,0 +1,32 @@
+import type { RequestOptions, Transport, TransportRequest, TransportResult } from '../index.js';
+/** Web Fetch capability used by the built-in HTTP transport. */
+export type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface HttpTransportOptions {
+    readonly url: string;
+    readonly codec?: 'json' | 'msgpack';
+    /** Inject this capability when the host does not provide global Fetch. */
+    readonly fetch?: Fetch;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+    /** Maximum bytes in one encoded request before Fetch handoff. */
+    readonly maximumRequestBytes?: number;
+    /** Maximum unary, binary, or individual stream-frame body size. */
+    readonly maximumResponseBytes?: number;
+}
+/** HTTP implementation of the universal invocation protocol. */
+export declare class HttpTransport implements Transport {
+    readonly url: string;
+    private readonly codecName;
+    private readonly fetchImpl;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly maximumRequestBytes;
+    private readonly maximumResponseBytes;
+    private nextId;
+    constructor(options: HttpTransportOptions);
+    dispatch(input: TransportRequest, options?: RequestOptions): Promise<TransportResult>;
+    private fetchResponse;
+    private decodeBinary;
+    private nextRequestId;
+    private requestCodec;
+}