@astrale-os/kernel-client 0.6.0-beta.2 → 0.6.0-beta.21

package/dist/transport/http/transport.js

@@ -1,6 +1,9 @@
-import { codecs, invocation as protocol } from '@astrale-os/kernel-protocol';
+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 { HttpByteStream } from './byte-stream.js';
 import { binaryHeaders, codecForResponse, decodeProtocol, normalizeMediaType, readBoundedBody, requireId, } from './response.js';
 import { HttpStream } from './stream.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -29,14 +32,14 @@ export class HttpTransport {
         this.maximumResponseBytes = positiveInteger(options.maximumResponseBytes ?? DEFAULT_MAXIMUM_RESPONSE_BYTES, 'maximumResponseBytes');
     }
     async dispatch(input, options = {}) {
-        const id = this.nextRequestId();
+        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,
-            id,
+            requestId,
             ...invocationInput,
             ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
         });
@@ -48,7 +51,7 @@ export class HttpTransport {
         try {
             requireLive(control);
             if (encodedByteLength(encoded) > this.maximumRequestBytes) {
-                throw new TransportError(`request exceeds maximumRequestBytes (${this.maximumRequestBytes}).`, { phase: 'send', delivery: 'not-sent' });
+                throw invocationFailure(`request exceeds maximumRequestBytes (${this.maximumRequestBytes}).`, 'send');
             }
             phase = 'send';
             delivery = 'unknown';
@@ -62,8 +65,9 @@ export class HttpTransport {
             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 binaryDelivery = response.headers.get(protocol.http.BINARY_DELIVERY_FIELD);
             const hasStreamSignal = streamFraming !== null;
-            const hasBinarySignal = binaryId !== null || binaryManifest !== null;
+            const hasBinarySignal = binaryId !== null || binaryManifest !== null || binaryDelivery !== null;
             if (hasStreamSignal && hasBinarySignal) {
                 throw new ProtocolError('server returned conflicting stream and binary response signals.');
             }
@@ -71,7 +75,13 @@ export class HttpTransport {
                 if (binaryId === null || binaryManifest === null) {
                     throw new ProtocolError('server returned an incomplete binary response signal.');
                 }
-                return await this.decodeBinary(response, id, binaryId, control);
+                if (binaryDelivery !== null && binaryDelivery !== protocol.http.STREAMING_BINARY_DELIVERY) {
+                    throw new ProtocolError('server returned an unsupported binary delivery signal.');
+                }
+                const binary = await this.decodeBinary(response, requestId, binaryId, binaryDelivery !== null, control);
+                if (!(binary.value.body instanceof Uint8Array))
+                    handedOff = true;
+                return binary;
             }
             const responseCodec = await codecForResponse(response.headers.get('content-type'));
             if (responseCodec === undefined) {
@@ -84,39 +94,43 @@ export class HttpTransport {
                 if (!response.ok) {
                     throw new ProtocolError('server returned a non-success stream response.');
                 }
-                const stream = await HttpStream.open(response, responseCodec, id, this.maximumResponseBytes, control);
+                const stream = await HttpStream.open(response, responseCodec, requestId, this.maximumResponseBytes, control);
                 requireLive(control);
                 handedOff = true;
-                return { kind: 'stream', stream };
+                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.id === null && 'error' in envelope) {
-                throw new ResponseError(envelope.error.code, envelope.error.message, envelope.error.data);
+            if (envelope.requestId === null && 'error' in envelope) {
+                throw new ResponseError(envelope.error.code, envelope.error.message, envelope.invocation, envelope.error.data);
             }
-            requireId(id, envelope.id);
+            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 });
+                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' });
+                return Object.freeze({ kind: 'miss', invocation: envelope.invocation });
             }
             if ('kind' in envelope && envelope.kind === 'redirect') {
-                const redirect = decodeProtocol('redirect response', () => protocol.decodeRedirect(envelope));
+                const response = decodeProtocol('redirect response', () => protocol.decodeRedirectResponse(envelope));
                 requireLive(control);
-                return redirectResult(redirect);
+                return redirectResult(response);
             }
             if ('error' in envelope) {
-                throw new ResponseError(envelope.error.code, envelope.error.message, envelope.error.data);
+                throw new ResponseError(envelope.error.code, envelope.error.message, envelope.invocation, envelope.error.data);
             }
             requireLive(control);
-            return { kind: 'value', value: envelope.result };
+            return { kind: 'value', value: envelope.result, invocation: envelope.invocation };
         }
         catch (error) {
             throw transportFailure(error, control, options.signal, timeoutMs, this.url, phase, delivery);
@@ -143,55 +157,69 @@ export class HttpTransport {
             signal: control.signal,
         });
     }
-    async decodeBinary(response, id, binaryId, control) {
-        if (!response.ok) {
-            throw new ProtocolError('server returned binary data with an error status.');
-        }
-        if (binaryId !== String(id)) {
-            throw new ProtocolError(`binary response id ${JSON.stringify(binaryId)} does not match request id ${id}.`);
+    async decodeBinary(response, requestId, binaryId, streaming, control) {
+        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)));
+        if (streaming) {
+            if (response.body === null)
+                throw new ProtocolError('streaming binary has no body.');
+            requireLive(control);
+            return {
+                kind: 'binary',
+                invocation,
+                value: {
+                    body: new HttpByteStream(response.body, this.maximumResponseBytes, control),
+                    mediaType,
+                    ...(response.status === 200 ? {} : { status: response.status }),
+                    ...(Object.keys(headers).length === 0 ? {} : { headers }),
+                },
+            };
+        }
+        const body = await readBoundedBody(response, this.maximumResponseBytes, control.signal);
+        requireLive(control);
         const binary = decodeProtocol('binary response', () => protocol.decodeBinaryResponse({
             kind: 'binary',
-            id,
+            requestId,
+            invocation,
             body,
             mediaType,
+            status: response.status,
             ...(Object.keys(headers).length === 0 ? {} : { headers }),
         }));
         requireLive(control);
         return {
             kind: 'binary',
+            invocation: binary.invocation,
             value: {
                 body: binary.body,
                 mediaType: binary.mediaType,
+                ...(binary.status === 200 ? {} : { status: binary.status }),
                 ...(binary.headers === undefined ? {} : { headers: binary.headers }),
             },
         };
     }
     nextRequestId() {
-        const id = this.nextId;
-        this.nextId = id === Number.MAX_SAFE_INTEGER ? 1 : id + 1;
-        return id;
+        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(redirect) {
+function redirectResult(response) {
     return Object.freeze({
         kind: 'redirect',
-        redirect: Object.freeze({
-            route: redirect.route,
-            ...(redirect.credential === undefined ? {} : { credential: redirect.credential }),
-            ...(redirect.trace === undefined ? {} : { trace: redirect.trace }),
-        }),
+        invocation: response.invocation,
+        redirect: response.redirect,
     });
 }
 function normalizeUrl(input) {
@@ -260,9 +288,8 @@ function transportFailure(input, control, parent, timeoutMs, url, phase, deliver
     if (input instanceof ResponseError || input instanceof ProtocolError)
         return input;
     if (control.timedOut) {
-        return new TransportError(`request timed out after ${timeoutMs}ms.`, {
+        return invocationFailure(`request timed out after ${timeoutMs}ms.`, 'timeout', {
             cause: asError(input),
-            phase: 'timeout',
             delivery,
         });
     }
@@ -270,9 +297,8 @@ function transportFailure(input, control, parent, timeoutMs, url, phase, deliver
         return asError(parent.reason ?? input);
     return input instanceof TransportError
         ? input
-        : new TransportError(`Failed to communicate with the server at ${url}.`, {
+        : invocationFailure(`Failed to communicate with the server at ${url}.`, phase, {
             cause: asError(input),
-            phase,
             delivery,
         });
 }
@@ -337,4 +363,3 @@ function hasControlCharacter(input) {
     }
     return false;
 }
-//# sourceMappingURL=transport.js.map

package/dist/transport/index.d.ts

@@ -1,3 +1,2 @@
 export type { RequestOptions, MissControl, StaleControl, Transport, TransportRequest, TransportResult, } from './transport.js';
 export { asError, controlledSignal, positiveInteger, requireLive, type ControlledSignal, } from './deadline.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/transport/index.js

@@ -1,2 +1 @@
 export { asError, controlledSignal, positiveInteger, requireLive, } from './deadline.js';
-//# sourceMappingURL=index.js.map

package/dist/transport/transport.d.ts

@@ -1,5 +1,5 @@
-import type { Result } from '@astrale-os/kernel-ports/functions';
 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;
@@ -19,9 +19,11 @@ export interface TransportRequest {
 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 {
@@ -30,4 +32,3 @@ export interface Transport {
     /** Optional owned-resource shutdown used by Client.close(). */
     readonly close?: () => void;
 }
-//# sourceMappingURL=transport.d.ts.map

package/dist/transport/transport.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=transport.js.map

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

@@ -1,4 +1,5 @@
-import { invocation as protocol, type codecs } from '@astrale-os/kernel-protocol';
+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';
@@ -29,10 +30,9 @@ export declare class WebSocketConnection implements ExchangeOwner {
     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, id: protocol.RequestId): void;
+    cancel(exchange: WebSocketExchange, requestId: protocol.RequestId): void;
     shutdown(reason?: Error, closeCode?: number, closeReason?: string): void;
     private onOpen;
     private onMessage;
     private onFailure;
 }
-//# sourceMappingURL=connection.d.ts.map

package/dist/transport/websocket/connection.js

@@ -1,5 +1,6 @@
-import { invocation as protocol } from '@astrale-os/kernel-protocol';
-import { ProtocolError, TransportError } from '../../errors/index.js';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import { ProtocolError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
 import { asError } from '../index.js';
 import { WebSocketExchange } from './exchange.js';
 const WS_CONNECTING = 0;
@@ -63,51 +64,45 @@ export class WebSocketConnection {
     dispatch(request, control, maximumBufferedItems) {
         if (!this.isOpen) {
             control.close();
-            return Promise.reject(new TransportError('WebSocket connection is not available.', {
-                phase: 'connect',
-                delivery: 'not-sent',
-            }));
+            return Promise.reject(invocationFailure('WebSocket connection is not available.', 'connect'));
         }
-        const key = requestKey(request.id);
+        const key = requestKey(request.requestId);
         if (this.active.has(key) || this.cancelled.has(key)) {
             control.close();
             return Promise.reject(new ProtocolError('WebSocket request ID is already in use.'));
         }
         if (this.active.size + this.cancelled.size >= this.maximumActiveInvocations) {
             control.close();
-            return Promise.reject(new TransportError(`WebSocket connection exceeds maximumActiveInvocations (${this.maximumActiveInvocations}).`, { phase: 'send', delivery: 'not-sent' }));
+            return Promise.reject(invocationFailure(`WebSocket connection exceeds maximumActiveInvocations (${this.maximumActiveInvocations}).`, 'send'));
         }
         const encoded = this.codec.encode(request);
         const encodedBytes = frameSize(encoded);
         if (encodedBytes > this.maximumRequestBytes) {
             control.close();
-            return Promise.reject(new TransportError(`WebSocket request exceeds maximumRequestBytes (${this.maximumRequestBytes}).`, { phase: 'send', delivery: 'not-sent' }));
+            return Promise.reject(invocationFailure(`WebSocket request exceeds maximumRequestBytes (${this.maximumRequestBytes}).`, 'send'));
         }
         if (this.socket.bufferedAmount + encodedBytes > this.maximumBufferedBytes) {
             control.close();
-            return Promise.reject(new TransportError(`WebSocket connection exceeds maximumBufferedBytes (${this.maximumBufferedBytes}).`, { phase: 'send', delivery: 'not-sent' }));
+            return Promise.reject(invocationFailure(`WebSocket connection exceeds maximumBufferedBytes (${this.maximumBufferedBytes}).`, 'send'));
         }
-        const exchange = new WebSocketExchange(this, request.id, control, maximumBufferedItems);
+        const exchange = new WebSocketExchange(this, request.requestId, control, maximumBufferedItems);
         this.active.set(key, exchange);
         return exchange.start((data) => this.socket.send(socketData(data)), encoded);
     }
     finish(exchange, reusable, closeCode = 1002) {
         removeExchange(this.active, exchange);
         if (!reusable) {
-            this.shutdown(new TransportError('WebSocket connection was closed after a binding failure.', {
-                phase: 'receive',
-                delivery: 'not-sent',
-            }), closeCode, closeReason(closeCode));
+            this.shutdown(invocationFailure('WebSocket connection was closed after a binding failure.', 'receive'), closeCode, closeReason(closeCode));
         }
     }
-    cancel(exchange, id) {
-        const key = requestKey(id);
+    cancel(exchange, requestId) {
+        const key = requestKey(requestId);
         if (this.active.get(key) !== exchange)
             return;
         this.active.delete(key);
         this.cancelled.add(key);
         try {
-            const encoded = this.codec.encode(protocol.decodeCancelRequest({ version: protocol.VERSION, kind: 'cancel', id }));
+            const encoded = this.codec.encode(protocol.decodeCancelRequest({ version: protocol.VERSION, kind: 'cancel', requestId }));
             const bytes = frameSize(encoded);
             if (bytes > this.maximumRequestBytes ||
                 this.socket.bufferedAmount + bytes > this.maximumBufferedBytes) {
@@ -116,17 +111,13 @@ export class WebSocketConnection {
             this.socket.send(socketData(encoded));
         }
         catch (error) {
-            this.shutdown(new TransportError('Failed to send WebSocket cancellation.', {
+            this.shutdown(invocationFailure('Failed to send WebSocket cancellation.', 'send', {
                 cause: asError(error),
-                phase: 'send',
                 delivery: 'unknown',
             }), error instanceof WebSocketBindingFailure ? error.closeCode : 1011, error instanceof WebSocketBindingFailure ? error.closeReason : 'Client send failed');
         }
     }
-    shutdown(reason = new TransportError('WebSocket connection was closed.', {
-        phase: 'closed',
-        delivery: 'not-sent',
-    }), closeCode = 1000, closeReason = 'Client closed') {
+    shutdown(reason = invocationFailure('WebSocket connection was closed.', 'closed'), closeCode = 1000, closeReason = 'Client closed') {
         if (this.closedState)
             return;
         this.closedState = true;
@@ -151,7 +142,7 @@ export class WebSocketConnection {
             return;
         const expected = protocol.websocket.subprotocolFor(this.codec);
         if (this.socket.protocol !== expected) {
-            this.shutdown(new TransportError(`server selected WebSocket subprotocol ${JSON.stringify(this.socket.protocol)}; expected ${JSON.stringify(expected)}.`, { phase: 'connect', delivery: 'not-sent' }), 1002, 'Subprotocol mismatch');
+            this.shutdown(invocationFailure(`server selected WebSocket subprotocol ${JSON.stringify(this.socket.protocol)}; expected ${JSON.stringify(expected)}.`, 'connect'), 1002, 'Subprotocol mismatch');
             return;
         }
         this.opened = true;
@@ -165,7 +156,7 @@ export class WebSocketConnection {
                 throw new WebSocketBindingFailure(`WebSocket frame exceeds maximumResponseBytes (${this.maximumResponseBytes}).`, 1009, 'Message too big');
             }
             const admitted = decodeFrame(this.codec, frame);
-            const key = requestKey(admitted.id);
+            const key = requestKey(admitted.requestId);
             const exchange = this.active.get(key);
             if (exchange !== undefined) {
                 exchange.receive(admitted);
@@ -186,10 +177,7 @@ export class WebSocketConnection {
     onFailure(message) {
         if (this.closedState)
             return;
-        this.shutdown(new TransportError(message, {
-            phase: this.opened ? 'receive' : 'connect',
-            delivery: 'not-sent',
-        }));
+        this.shutdown(invocationFailure(message, this.opened ? 'receive' : 'connect'));
     }
 }
 async function normalizeFrame(input) {
@@ -225,7 +213,7 @@ function decodeFrame(codec, input) {
         }
         const decoded = codec.decode(input);
         if (isKind(decoded, 'redirect'))
-            return protocol.decodeRedirect(decoded);
+            return protocol.decodeRedirectResponse(decoded);
         if (isKind(decoded, 'stale'))
             return protocol.decodeStale(decoded);
         if (isKind(decoded, 'miss'))
@@ -283,8 +271,8 @@ function isKind(input, kind) {
         !Array.isArray(input) &&
         input.kind === kind);
 }
-function requestKey(id) {
-    return id === null ? 'null:' : `${typeof id}:${String(id)}`;
+function requestKey(requestId) {
+    return requestId === null ? 'null:' : `${typeof requestId}:${String(requestId)}`;
 }
 function removeExchange(exchanges, exchange) {
     for (const [key, active] of exchanges) {
@@ -294,4 +282,3 @@ function removeExchange(exchanges, exchange) {
         return;
     }
 }
-//# sourceMappingURL=connection.js.map

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

@@ -1,17 +1,17 @@
 import type { Value } from '@astrale-os/kernel-dsl/value';
-import type { Stream } from '@astrale-os/kernel-ports/functions';
-import { type invocation as protocol } from '@astrale-os/kernel-protocol';
+import type * as protocol from '@astrale-os/kernel-protocol/invocation';
+import type { Stream } from '../../client/index.js';
 import type { ControlledSignal } from '../index.js';
 import type { TransportResult } from '../index.js';
 export interface ExchangeOwner {
     finish(exchange: WebSocketExchange, reusable: boolean, closeCode?: 1002 | 1008 | 1011): void;
-    cancel(exchange: WebSocketExchange, id: protocol.RequestId): void;
+    cancel(exchange: WebSocketExchange, requestId: protocol.RequestId): void;
 }
-export type WebSocketInbound = protocol.BinaryResponse | protocol.Redirect | protocol.Stale | protocol.Miss | protocol.Response | protocol.StreamFrame;
+export type WebSocketInbound = protocol.BinaryResponse | protocol.RedirectResponse | protocol.Stale | protocol.Miss | protocol.Response | protocol.StreamFrame;
 /** One correlated invocation within a multiplexed WebSocket connection. */
 export declare class WebSocketExchange implements Stream {
     private readonly owner;
-    private readonly id;
+    private readonly requestId;
     private readonly control;
     private readonly maximumBufferedItems;
     private readonly result;
@@ -25,7 +25,8 @@ export declare class WebSocketExchange implements Stream {
     private readonly waiters;
     private terminal;
     private sent;
-    constructor(owner: ExchangeOwner, id: protocol.RequestId, control: ControlledSignal, maximumBufferedItems: number);
+    private invocation?;
+    constructor(owner: ExchangeOwner, requestId: protocol.RequestId, control: ControlledSignal, maximumBufferedItems: number);
     start(send: (data: string | Uint8Array) => void, encoded: string | Uint8Array): Promise<TransportResult>;
     receive(input: WebSocketInbound): void;
     connectionFailed(error: Error): void;
@@ -43,4 +44,3 @@ export declare class WebSocketExchange implements Stream {
     private flushTerminal;
     private abortFailure;
 }
-//# sourceMappingURL=exchange.d.ts.map