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

package/dist/client/client.js

@@ -1,393 +1,92 @@
-import { KERNEL_ERROR_CODES, substituteTemplate } from '@astrale-os/kernel-api';
-import { ConnectionError, InvalidTransportError, KernelError, WebOSError, withDetails, } from '../errors/errors.js';
-import { SchemaRegistry } from '../schema/registry.js';
-import { createSchemaClient } from '../schema/typed-client.js';
-import { HttpEnvelopeTransport, HttpRoutedTransport, WsEnvelopeTransport, } from '../transport/index.js';
-import { DEFAULT_REQUEST_TIMEOUT_MS } from '../wire/meta.js';
-import { createBoundClientView } from './bound.js';
-import { freezeResult } from './freeze.js';
-/**
- * KernelClient — one URL, one kernel. Discriminated `Send*Result`s,
- * no auto-follow, no cross-host pool, no transport fallback. Identity
- * is opaque — the client forwards credentials onto the wire and never
- * inspects, compares, or rotates them.
- *
- * Four facets:
- *  - Lean primitives: `send` / `sendStream` / `sendBinary` / `signal` /
- *    `batch` — surface transport outcomes as-is, no orchestration.
- *  - Identity views: `as(credential)` returns a `BoundClientView` that
- *    curries the credential into every call. A value, not a class.
- *  - Schema proxy: `withSchema(schema)` returns a schema-typed proxy
- *    that throws `UNHANDLED_REDIRECT` on redirect (use `send` for
- *    redirect-aware calls).
- *  - Lifecycle: `disconnect()` releases held resources (open WS).
- */
-export class KernelClient {
-    url;
-    defaultTimeout;
-    defaultTransport;
-    defaultProtocol;
-    hooks;
-    codec;
-    schema;
-    httpEnvelope;
-    httpRouted;
-    wsFactory;
-    logger;
-    ws = null;
-    wsState = 'unknown';
-    constructor(config) {
-        this.url = config.url.replace(/\/$/, '');
-        this.defaultTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
-        this.defaultTransport = config.defaultTransport ?? 'http';
-        this.defaultProtocol = config.defaultProtocol ?? 'envelope';
-        this.hooks = config.hooks ?? {};
-        this.codec = config.codec ?? 'json';
-        this.logger = config.logger ?? console;
-        // Schema: either an existing registry (shared across clients) or an
-        // array we load into a fresh registry. `SchemaRegistry.is` is a duck
-        // check — `instanceof` fails across package duplicates / realms.
-        if (SchemaRegistry.is(config.schema)) {
-            this.schema = config.schema;
-        }
-        else {
-            this.schema = new SchemaRegistry();
-            if (Array.isArray(config.schema) && config.schema.length > 0) {
-                this.schema.load(config.schema);
-            }
+import { ClientError } from '../errors/index.js';
+import { HttpTransport } from '../transport/http/index.js';
+import { authenticated, resolveCredential } from './credential.js';
+import { admitRequest, invocation } from './request.js';
+import { requireBinary, requireStream, requireValue } from './result.js';
+import { admittedMissError, admittedStaleRouteError } from './routing-control.js';
+const controlledDispatch = new WeakMap();
+/** Package-private redirect continuation path; intentionally absent from the public Client facade. */
+export function dispatchTrace(client, credential, call, options, trace) {
+    const dispatch = controlledDispatch.get(client);
+    if (dispatch === undefined)
+        throw new TypeError('Trace dispatch requires an owned Client.');
+    return dispatch(credential, call, options, trace);
+}
+/** Pure client for the universal remote Function invocation boundary. */
+export class Client {
+    transport;
+    lifecycle = new AbortController();
+    closed = false;
+    constructor(options) {
+        if (options === null || typeof options !== 'object') {
+            throw new TypeError('Client options must be an object.');
         }
-        this.httpEnvelope = new HttpEnvelopeTransport({
-            url: this.url,
-            codec: this.codec,
-            requestTimeout: this.defaultTimeout,
-            retry: config.retry,
-            fetch: config.fetch,
-        });
-        this.httpRouted = new HttpRoutedTransport({
-            requestTimeout: this.defaultTimeout,
-            fetch: config.fetch,
-        });
-        this.wsFactory = () => new WsEnvelopeTransport({
-            url: this.url,
-            codec: this.codec,
-            requestTimeout: this.defaultTimeout,
-        });
+        this.transport = Object.hasOwn(options, 'transport')
+            ? admitTransport(options.transport)
+            : new HttpTransport(options);
+        controlledDispatch.set(this, (credential, call, requestOptions, trace) => this.dispatchWith(credential, call, requestOptions, trace));
     }
-    // ─── Transport primitives ─────────────────────────────────────────────────
-    async send(method, params, credential, opts) {
-        return this.dispatchUnary('call', method, params, credential, opts);
+    dispatch(call, options) {
+        return this.dispatchWith(undefined, call, options);
     }
-    async sendStream(method, params, credential, opts) {
-        return this.dispatchUnary('stream', method, params, credential, opts);
+    call(call, options) {
+        return requireValue(this.dispatch(call, options));
     }
-    async sendBinary(method, params, credential, opts) {
-        return this.dispatchUnary('binary', method, params, credential, opts);
+    stream(call, options) {
+        return requireStream(this.dispatch(call, options));
     }
-    signal(method, params, credential, opts) {
-        const schemaEntry = this.lookupSchema(method, opts);
-        const { transport, transportReq } = this.selectTransport('signal', method, params, credential, opts, schemaEntry);
-        const beforeCtx = this.beforeCtx(method, params, credential, transport.name, transportReq, opts);
-        void this.runHooks('onBeforeSend', beforeCtx);
-        transport.signal(transportReq);
-        void this.runHooks('onAfterSignal', { ...beforeCtx, dispatchedAt: Date.now() });
-    }
-    async batch(requests, credential, opts) {
-        if (requests.length === 0)
-            return [];
-        // Batch uses the envelope transport — the only path with a
-        // multi-request wire shape. Snapshot each entry's schema once so an
-        // external registry mutating mid-dispatch doesn't retarget half the
-        // batch. Mixing routed-only methods in is a policy error — flag it
-        // before any wire work starts.
-        const snapshot = requests.map((r) => ({
-            method: r.method,
-            params: r.params,
-            schema: this.lookupSchema(r.method, opts),
-        }));
-        for (const entry of snapshot) {
-            if (isRoutedOnly(entry.schema)) {
-                throw new InvalidTransportError(`Method "${entry.method}" has a route binding; batch only supports envelope calls`);
-            }
-        }
-        const transportRequests = snapshot.map((entry) => this.buildEnvelopeRequest(entry.method, entry.params, credential, opts, entry.schema));
-        const entries = await this.httpEnvelope.batch(transportRequests);
-        return entries;
+    binary(call, options) {
+        return requireBinary(this.dispatch(call, options));
     }
-    // ─── Identity & schema views ──────────────────────────────────────────────
     as(credential) {
-        return createBoundClientView(this, credential);
-    }
-    /**
-     * Return a schema-typed proxy. `defaultCredential` — used by
-     * `BoundClientView.withSchema` — supplies a credential when the
-     * per-call `ProxyCallOptions.credential` is absent. Unbound callers
-     * that provide neither send a no-auth request; the server decides
-     * whether that's valid (per §9.0.1 the client treats credentials as
-     * opaque and never pre-judges them).
-     */
-    withSchema(schema, defaultCredential) {
-        return createSchemaClient(async (method, params, credential, opts) => {
-            const effective = (credential ?? defaultCredential?.() ?? '');
-            const result = await this.send(method, params, effective, opts);
-            if (result.kind === 'redirect') {
-                // Proxy is value-path only by contract (§9.4). Callers wanting
-                // redirect awareness use `client.send` directly.
-                const err = new KernelError(`Unhandled redirect: "${method}" resolved to ${result.redirection.url}. ` +
-                    `Use client.send() to handle redirects explicitly.`, KERNEL_ERROR_CODES.INTERNAL_ERROR, 'UNHANDLED_REDIRECT');
-                withDetails(err, {
-                    method: String(method),
-                    params,
-                    url: this.url,
-                    transport: result.meta.transport,
-                    correlationId: opts?.correlationId,
-                    meta: result.meta,
-                    redirection: result.redirection,
-                });
-                throw err;
-            }
-            return result.value;
-        }, schema);
-    }
-    describe(method) {
-        return this.schema.get(method);
-    }
-    // ─── Connection lifecycle ─────────────────────────────────────────────────
-    /**
-     * Release any held resources (open WebSocket). Idempotent. The client
-     * stays reusable — a subsequent `send(...)` lazily re-opens a fresh
-     * WebSocket if the default or per-call transport selects `'ws'`. Resets
-     * the `'auto'` probe state so the next call re-probes.
-     */
-    disconnect() {
-        this.ws?.disconnect();
-        this.ws = null;
-        this.httpEnvelope.disconnect();
-        this.httpRouted.disconnect();
-        this.wsState = 'unknown';
-    }
-    // ─── Internals ────────────────────────────────────────────────────────────
-    lookupSchema(method, opts) {
-        return this.schema.resolve(method, opts?.class) ?? this.schema.get(method);
-    }
-    /**
-     * Resolve the transport instance + request shape for this call.
-     * `canFallback` signals to `dispatchUnary` that a WS `ConnectionError`
-     * on this attempt should retry on HTTP (auto-mode probe only).
-     */
-    selectTransport(kind, method, params, credential, opts, schemaEntry) {
-        const requested = opts?.transport ?? this.defaultTransport;
-        const protocol = opts?.protocol ?? this.defaultProtocol;
-        const binding = schemaEntry?.binding;
-        const route = binding?.route;
-        const remoteUrl = opts?.url ?? binding?.remoteUrl;
-        const preferRoute = protocol === 'auto' && !!route;
-        if (preferRoute) {
-            if (!remoteUrl) {
-                // Binding without remoteUrl is a schema misconfig — caller can
-                // still rescue by passing opts.url, but both missing is broken.
-                throw new InvalidTransportError(`Method "${method}" declares a route binding but has no remoteUrl; ` +
-                    `register a schema with binding.remoteUrl or pass opts.url`);
-            }
-            return {
-                transport: this.httpRouted,
-                transportReq: this.buildRoutedRequest(method, params, credential, opts, route, remoteUrl),
-                canFallback: false,
-            };
-        }
-        const resolved = this.resolveEnvelopePipe(requested, kind);
-        return {
-            transport: resolved === 'ws' ? this.envelopeWs() : this.httpEnvelope,
-            transportReq: this.buildEnvelopeRequest(method, params, credential, opts, schemaEntry),
-            canFallback: requested === 'auto' && resolved === 'ws' && this.wsState === 'unknown',
-        };
-    }
-    /**
-     * Resolve `CallTransport` to a concrete envelope pipe. Binary is always
-     * HTTP (server-side WS binary unimplemented). In `'auto'+unknown`, signal
-     * stays on HTTP — fire-and-forget can't communicate fallback.
-     */
-    resolveEnvelopePipe(requested, kind) {
-        if (kind === 'binary')
-            return 'http';
-        if (requested === 'http')
-            return 'http';
-        if (requested === 'ws')
-            return 'ws';
-        if (this.wsState === 'unavailable')
-            return 'http';
-        if (this.wsState === 'proven')
-            return 'ws';
-        return kind === 'signal' ? 'http' : 'ws';
-    }
-    envelopeWs() {
-        if (!this.ws)
-            this.ws = this.wsFactory();
-        return this.ws;
-    }
-    buildEnvelopeRequest(method, params, credential, opts, schemaEntry) {
-        const binding = schemaEntry?.binding;
-        const remoteUrl = opts?.url ?? binding?.remoteUrl;
-        const url = remoteUrl && params && typeof params === 'object'
-            ? substituteTemplate(remoteUrl, params)
-            : remoteUrl;
-        return {
-            method,
-            params,
-            credential,
-            timeout: opts?.timeout ?? this.defaultTimeout,
-            signal: opts?.signal,
-            correlationId: opts?.correlationId,
-            url,
-            ...(opts?.self !== undefined && { self: opts.self }),
-        };
-    }
-    buildRoutedRequest(method, params, credential, opts, route, remoteUrl) {
-        return {
-            method,
-            params: params ?? {},
-            credential,
-            timeout: opts?.timeout ?? this.defaultTimeout,
-            signal: opts?.signal,
-            correlationId: opts?.correlationId,
-            route,
-            remoteUrl,
-        };
+        return authenticated((bound, request, options) => this.dispatchWith(bound, request, options), credential);
     }
-    /**
-     * Unary dispatch (call / stream / binary). Selects transport, fires
-     * `onBeforeSend`, awaits the transport, freezes the result (deeply,
-     * including `meta.wire`), wraps streams in the observability
-     * iterator, fires `onAfterReceive`, and decorates errors with
-     * `ClientErrorDetails` if the transport didn't already.
-     */
-    async dispatchUnary(kind, method, params, credential, opts) {
-        const schemaEntry = this.lookupSchema(method, opts);
-        const selection = this.selectTransport(kind, method, params, credential, opts, schemaEntry);
-        try {
-            return await this.dispatchOnce(kind, method, params, credential, opts, selection, !selection.canFallback);
-        }
-        catch (err) {
-            if (selection.canFallback && err instanceof ConnectionError) {
-                this.wsState = 'unavailable';
-                const httpSel = this.selectTransport(kind, method, params, credential, opts, schemaEntry);
-                return this.dispatchOnce(kind, method, params, credential, opts, httpSel, true);
-            }
-            throw err;
-        }
-    }
-    /**
-     * One dispatch attempt: hooks + wire + freeze. `fireErrorHook = false`
-     * suppresses `onError` so a recovered auto-mode WS probe failure doesn't
-     * surface as a phantom error when the fallback HTTP call succeeds.
-     */
-    async dispatchOnce(kind, method, params, credential, opts, selection, fireErrorHook) {
-        const { transport, transportReq } = selection;
-        const beforeCtx = this.beforeCtx(method, params, credential, transport.name, transportReq, opts);
-        await this.runHooks('onBeforeSend', beforeCtx);
-        try {
-            const raw = kind === 'call'
-                ? await transport.call(transportReq)
-                : kind === 'stream'
-                    ? await transport.stream(transportReq)
-                    : await transport.binary(transportReq);
-            if (transport.name === 'ws-envelope' && this.wsState === 'unknown') {
-                this.wsState = 'proven';
-            }
-            // For streams, wrap `chunks` in the instrumented iterable BEFORE
-            // freezing — hook and caller must see the same iterable so a hook
-            // that iterates doesn't steal frames from the caller.
-            const toFreeze = raw.kind === 'stream' && this.hooks.onStreamFrame
-                ? {
-                    ...raw,
-                    chunks: this.instrumentStream(raw.chunks, beforeCtx, raw.meta),
-                }
-                : raw;
-            const frozen = freezeResult(toFreeze);
-            await this.runHooks('onAfterReceive', {
-                ...beforeCtx,
-                result: frozen,
-                meta: frozen.meta,
-            });
-            return frozen;
-        }
-        catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
-            if (error instanceof WebOSError && !error.details) {
-                withDetails(error, {
-                    method,
-                    params,
-                    url: transport.url ?? this.url,
-                    transport: transport.name,
-                    correlationId: opts?.correlationId,
-                });
-            }
-            if (fireErrorHook) {
-                await this.runHooks('onError', {
-                    ...beforeCtx,
-                    error,
-                    meta: error.details?.meta,
-                });
-            }
-            throw error;
-        }
-    }
-    beforeCtx(method, params, credential, transport, transportReq, opts) {
-        return {
-            method,
-            params,
-            credential,
-            transport,
-            url: transportReq.url ?? this.url,
-            correlationId: opts?.correlationId,
-        };
-    }
-    /**
-     * Wrap a stream iterable so each chunk fires `onStreamFrame`. Errors
-     * during hook evaluation are swallowed per the hook contract (pure
-     * observation); a hook that misbehaves never aborts the stream.
-     */
-    async *instrumentStream(chunks, beforeCtx, meta) {
-        let index = 0;
-        for await (const data of chunks) {
-            if (this.hooks.onStreamFrame) {
-                try {
-                    await this.hooks.onStreamFrame({ ...beforeCtx, index, data, meta });
-                }
-                catch (err) {
-                    this.logHookError('onStreamFrame', err);
-                }
-            }
-            index++;
-            yield data;
-        }
-    }
-    async runHooks(key, ctx) {
-        const hook = this.hooks[key];
-        if (!hook)
+    close() {
+        if (this.closed)
             return;
-        try {
-            await hook(ctx);
-        }
-        catch (err) {
-            this.logHookError(key, err);
-        }
-    }
-    /**
-     * Log a hook-layer failure. Only the error's name + message are
-     * surfaced — the error may chain a `cause` that captured a credential
-     * or other sensitive ref by closure, and the client never leaks those
-     * per §9.0.1. Consumers who need full diagnostics provide a
-     * `logger` with their own redaction policy.
-     */
-    logHookError(key, err) {
-        const e = err instanceof Error ? err : new Error(String(err));
-        this.logger.error(`[kernel-client] hook "${key}" threw: ${e.name}: ${e.message}`);
+        this.closed = true;
+        const failure = new ClientError('Client is closed.');
+        this.lifecycle.abort(failure);
+        this.transport.close?.();
+    }
+    async dispatchWith(credential, input, options, trace) {
+        if (this.closed)
+            throw new ClientError('Client is closed.');
+        const request = admitRequest(input, options, this.lifecycle.signal);
+        const resolved = credential === undefined
+            ? undefined
+            : await resolveCredential(credential, request.options.signal);
+        requireRequestLive(request.options.signal);
+        const result = await this.transport.dispatch(invocation(request, resolved, trace), request.options);
+        if (result.kind === 'stale')
+            throw admittedStaleRouteError(result.current, result.invocation);
+        if (result.kind === 'miss')
+            throw admittedMissError(result.invocation);
+        return result;
     }
 }
-function isRoutedOnly(schema) {
-    if (!schema)
-        return false;
-    const binding = schema.binding;
-    return !!binding?.route;
+function requireRequestLive(signal) {
+    if (signal?.aborted !== true)
+        return;
+    const reason = signal.reason;
+    throw reason instanceof Error
+        ? reason
+        : new ClientError('Client request was cancelled.', { cause: reason });
+}
+function admitTransport(input) {
+    if (input === null || typeof input !== 'object') {
+        throw new TypeError('Client transport must be an object.');
+    }
+    const dispatch = input.dispatch;
+    if (typeof dispatch !== 'function') {
+        throw new TypeError('Client transport must implement dispatch().');
+    }
+    const close = input.close;
+    if (close !== undefined && typeof close !== 'function') {
+        throw new TypeError('Client transport close capability is invalid.');
+    }
+    return Object.freeze({
+        dispatch: dispatch.bind(input),
+        ...(close === undefined ? {} : { close: close.bind(input) }),
+    });
 }
-//# sourceMappingURL=client.js.map

package/dist/client/credential.d.ts

@@ -0,0 +1,12 @@
+import type { Call, ClientDispatchOptions } from './request.js';
+import type { BinaryResponse, Result, StreamResult, ValueResult } from './result.js';
+export type RemoteCredential = string | (() => string | Promise<string>);
+export interface AuthenticatedClient {
+    dispatch(call: Call, options?: ClientDispatchOptions): Promise<Result>;
+    call(call: Call, options?: ClientDispatchOptions): Promise<ValueResult>;
+    stream(call: Call, options?: ClientDispatchOptions): Promise<StreamResult>;
+    binary(call: Call, options?: ClientDispatchOptions): Promise<BinaryResponse>;
+}
+export type CredentialDispatch = (credential: RemoteCredential, call: Call, options?: ClientDispatchOptions) => Promise<Result>;
+export declare function authenticated(dispatchWith: CredentialDispatch, credential: RemoteCredential): AuthenticatedClient;
+export declare function resolveCredential(input: RemoteCredential, signal?: AbortSignal): Promise<string>;

package/dist/client/credential.js

@@ -0,0 +1,51 @@
+import { ClientError } from '../errors/index.js';
+import { requireBinary, requireStream, requireValue } from './result.js';
+export function authenticated(dispatchWith, credential) {
+    const dispatch = (call, options) => dispatchWith(credential, call, options);
+    return Object.freeze({
+        dispatch,
+        call: (call, options) => requireValue(dispatch(call, options)),
+        stream: (call, options) => requireStream(dispatch(call, options)),
+        binary: (call, options) => requireBinary(dispatch(call, options)),
+    });
+}
+export async function resolveCredential(input, signal) {
+    requireLive(signal);
+    const pending = Promise.resolve(typeof input === 'function' ? input() : input);
+    const credential = await observeWhileLive(pending, signal);
+    if (typeof credential !== 'string' || credential.length === 0) {
+        throw new TypeError('Remote credentials must be non-empty strings.');
+    }
+    return credential;
+}
+function observeWhileLive(pending, signal) {
+    if (signal === undefined)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const cancelled = () => {
+            signal.removeEventListener('abort', cancelled);
+            reject(cancellation(signal.reason));
+        };
+        signal.addEventListener('abort', cancelled, { once: true });
+        if (signal.aborted) {
+            cancelled();
+            return;
+        }
+        void pending.then((value) => {
+            signal.removeEventListener('abort', cancelled);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', cancelled);
+            reject(error);
+        });
+    });
+}
+function requireLive(signal) {
+    if (signal?.aborted === true)
+        throw cancellation(signal.reason);
+}
+function cancellation(reason) {
+    return reason instanceof Error
+        ? reason
+        : new ClientError('Client request was cancelled.', { cause: reason });
+}

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+export { Client, dispatchTrace, type ClientOptions } from './client.js';
+export { acceptCall } from './admission.js';
+export type { AuthenticatedClient, RemoteCredential } from './credential.js';
+export { call, type Call, type ClientDispatchOptions } from './request.js';
+export type { Binary, BinaryResponse, Input, RedirectResult, Result, Stream, StreamResult, ValueResult, } from './result.js';
+export { isAdmittedMissError, isAdmittedStaleRouteError } from './routing-control.js';

package/dist/client/index.js

@@ -0,0 +1,4 @@
+export { Client, dispatchTrace } from './client.js';
+export { acceptCall } from './admission.js';
+export { call } from './request.js';
+export { isAdmittedMissError, isAdmittedStaleRouteError } from './routing-control.js';

package/dist/client/request.d.ts

@@ -0,0 +1,26 @@
+import type { PathLike } from '@astrale-os/kernel-core/path';
+import type * as protocol from '@astrale-os/kernel-protocol/invocation';
+import type { RequestOptions, TransportRequest } from '../transport/index.js';
+import type { Input } from './result.js';
+/** One portable call before Path canonicalization, correlation, and credential binding. */
+export interface Call {
+    readonly target: PathLike;
+    readonly input: Input;
+}
+export interface ClientDispatchOptions extends RequestOptions {
+    /** Untrusted delivery context; it changes neither Call meaning nor authority. */
+    readonly delegate?: protocol.Delegate;
+    readonly routing?: protocol.Routing;
+    /** Package-owned local-target or remote-revision precondition for a bound invocation. */
+    readonly schema?: protocol.SchemaTarget;
+}
+export interface AdmittedRequest {
+    readonly call: protocol.Call;
+    readonly delegate?: protocol.Delegate;
+    readonly routing?: protocol.Routing;
+    readonly schema?: protocol.SchemaTarget;
+    readonly options: RequestOptions;
+}
+export declare function call(target: PathLike, input: Input): Call;
+export declare function admitRequest(input: Call, options: ClientDispatchOptions | undefined, lifecycle: AbortSignal): AdmittedRequest;
+export declare function invocation(request: AdmittedRequest, credential?: string, trace?: protocol.Trace): TransportRequest;