@astrale-os/kernel-client 0.6.0-beta.70 → 0.6.0-beta.72

package/dist/session/session.js

@@ -1,6 +1,7 @@
 import { Path } from '@astrale-os/kernel-core/path';
 import { callableFingerprint } from '@astrale-os/kernel-dsl/v1/schema/fingerprint';
-import { Client } from '../client/index.js';
+import { createAuth } from '../auth/auth.js';
+import { Client, acceptCall } from '../client/index.js';
 import { SessionError } from '../errors/index.js';
 import { createDomainBinding } from '../graph/domain/binding.js';
 import { createGraph } from '../graph/index.js';
@@ -9,10 +10,12 @@ import { createSchema, DEFAULT_SCHEMA_LIFECYCLE_TIMEOUT_MS } from '../schema/ind
 import { AutoTransport } from '../transport/auto/index.js';
 import { HttpTransport } from '../transport/http/index.js';
 import { WebSocketTransport } from '../transport/websocket/index.js';
-import { admitControlOptions, admitPolicy, createSessionOperation, DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, admitKernel, kernelInvocationEndpoint, platformDuration, positive, } from './context/index.js';
+import { admitFunction } from './admission.js';
+import { createContentApi } from './content.js';
+import { admitControlOptions, admitPolicy, createSessionOperation, DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, admitKernel, allowEndpoint, kernelInvocationEndpoint, platformDuration, positive, } from './context/index.js';
 import { createSessionDiscovery } from './discovery/index.js';
 import { admitReference } from './reference.js';
-import { admitEnvelopeTransport, admitRequestOptions, admitSessionAuth, requireResultKind, RouteCache, SessionDispatcher, } from './routing/index.js';
+import { admitEnvelopeTransport, admitInvocationOptions, admitSessionAuth, requireResultKind, RouteCache, SessionDispatcher, } from './routing/index.js';
 import { resolveViewsFor, targetViewCatalog } from './views/index.js';
 const DEFAULT_SESSION_POLICY = Object.freeze({ maximumRouteAgeMs: 60_000 });
 /** Caller-owned discovery and redirect-following conversation with one exact source Kernel. */
@@ -20,6 +23,8 @@ export class ClientSession {
     kernel;
     schema;
     graph;
+    auth;
+    content;
     ownedPool;
     discovery;
     dispatcher;
@@ -80,16 +85,39 @@ export class ClientSession {
             acquisitionOperation: () => this.operation(undefined),
         });
         this.routes = new RouteCache(policy.maximumRouteAgeMs, undefined, options.routeStore);
+        const auth = admitSessionAuth(options.auth);
+        const admission = {
+            kernel: this.kernel,
+            auth,
+            source: () => {
+                allowEndpoint(sourceEndpoint, policy);
+                return pool.clientFor({ transport: 'http', url: sourceEndpoint });
+            },
+            fetch: fetchImpl,
+            policy,
+            limits: { maximumPublicationBytes, maximumBundleBytes },
+            maximumResponseBytes,
+        };
         this.dispatcher = new SessionDispatcher({
             kernel: this.kernel,
             sourceEndpoint,
             pool,
             websocketAvailable,
-            auth: admitSessionAuth(options.auth),
+            auth,
             cache: this.routes,
             policy,
             envelopeTransport: admitEnvelopeTransport(options.envelopeTransport ?? 'http'),
             requireOpen: () => this.requireOpen(),
+            streamingHttp: {
+                fetch: fetchImpl,
+                maximumResponseBytes: 100 * 1024 * 1024,
+                timeoutMs: 30 * 60 * 1_000,
+            },
+        });
+        this.content = createContentApi({
+            operation: (options) => this.operation(options),
+            invoke: (reference, input, options, operation) => this.invokeWith(reference, input, options, operation),
+            dispatch: (target, input, operation, body) => this.dispatcher.dispatchHttp({ target, input }, {}, operation, body),
         });
         this.schema = createSchema((request, options) => this.dispatch(request, options), {
             maximumPublicationBytes,
@@ -97,6 +125,10 @@ export class ClientSession {
             lifecycleTimeoutMs: schemaLifecycleTimeoutMs,
         });
         this.graph = createGraph((call, options) => this.call(call, options));
+        this.auth = createAuth((target, input, options) => this.call({ target, input }, options), (call, options) => {
+            const operation = this.operation(admitControlOptions(options));
+            return admitFunction(admission, acceptCall(call), options, operation);
+        });
     }
     /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
     bind(domain) {
@@ -114,23 +146,32 @@ export class ClientSession {
         return resolveViewsFor(async (call, operation) => requireResultKind('value', await this.dispatcher.dispatch(call, {}, operation)).value, this.admitTargetViews, target, this.operation(admitControlOptions(options)));
     }
     dispatch(call, options) {
-        const admitted = admitRequestOptions(options);
-        return this.dispatcher.dispatch(call, admitted, this.operation(admitted));
+        return this.dispatchWith(call, options);
     }
     async call(call, options) {
-        const result = await this.dispatch(call, options);
+        const result = await this.dispatchWith(call, options);
         return requireResultKind('value', result).value;
     }
     async invoke(reference, input, options) {
+        return this.invokeWith(reference, input, options);
+    }
+    dispatchWith(call, options, requireHttp = false) {
+        const admitted = admitInvocationOptions(options);
+        const operation = this.operation(admitted.options);
+        return admitted.body === undefined && !requireHttp
+            ? this.dispatcher.dispatch(call, admitted.options, operation)
+            : this.dispatcher.dispatchHttp(call, admitted.options, operation, admitted.body);
+    }
+    async invokeWith(reference, input, options, sharedOperation) {
         const admittedReference = admitReference(reference);
-        const admittedOptions = admitRequestOptions(options);
+        const admitted = admitInvocationOptions(options);
         const { anchor, steps } = admittedReference.target.ast;
         const last = steps.at(-1);
         const instance = last?.kind === 'method' && last.dispatch === 'instance'
             ? Path.fromAST({ anchor, steps: steps.slice(0, -1) }).raw
             : undefined;
         // A generated reference pins the callable meaning; a hand-written one still pins the revision.
-        const result = await this.dispatcher.dispatch({
+        const call = {
             target: Object.freeze({
                 callable: admittedReference.callable,
                 ...(admittedReference.fingerprint === undefined
@@ -139,20 +180,24 @@ export class ClientSession {
                 ...(instance === undefined ? {} : { instance }),
             }),
             input,
-        }, admittedOptions, this.operation(admittedOptions));
+        };
+        const operation = sharedOperation ?? this.operation(admitted.options);
+        const result = await (admitted.body === undefined && admittedReference.outputMode !== 'binary'
+            ? this.dispatcher.dispatch(call, admitted.options, operation)
+            : this.dispatcher.dispatchHttp(call, admitted.options, operation, admitted.body));
         const narrowed = requireResultKind(admittedReference.outputMode, result);
-        return (narrowed.kind === 'value'
+        return narrowed.kind === 'value'
             ? narrowed.value
             : narrowed.kind === 'stream'
                 ? narrowed.stream
-                : narrowed.value);
+                : narrowed.value;
     }
     async stream(call, options) {
         const result = await this.dispatch(call, options);
         return requireResultKind('stream', result).stream;
     }
     async binary(call, options) {
-        const result = await this.dispatch(call, options);
+        const result = await this.dispatchWith(call, options, true);
         return requireResultKind('binary', result).value;
     }
     close() {

package/dist/session/session.typecheck.js

@@ -2,6 +2,8 @@ import { NodeId } from '@astrale-os/kernel-core/graph/node';
 import { Path } from '@astrale-os/kernel-core/path';
 import { K, KernelSchema } from '@astrale-os/kernel-core/schema';
 import { defineSchema, func, method, nodeClass, schema, valueSchema, } from '@astrale-os/kernel-dsl/v1';
+import { isBinaryInput } from '@astrale-os/kernel-dsl/v1/language';
+import { call } from '../client/index.js';
 import { ClientSession, createSessionCredentialProvider, reference } from './index.js';
 void new ClientSession(options);
 void auth;
@@ -12,6 +14,13 @@ void request;
 void snapshot;
 const observedPublication = session.publication(control);
 void observedPublication;
+const admitted = session.auth.admit({
+    target: Path.parse('/:example.test:function.write'),
+    input: {},
+}, { attenuation: { kind: 'identity', self: true }, ...control });
+void admitted;
+// @ts-expect-error Admission belongs to Auth, not the top-level Session.
+void session.admit({ target: Path.parse('/:example.test:function.write'), input: {} });
 const credentials = createSessionCredentialProvider({
     ttlSeconds: 60,
     mint: async () => minted,
@@ -33,7 +42,10 @@ const renameInput = valueSchema()({
     required: ['name'],
     additionalProperties: false,
 });
-const registrationInput = valueSchema()(K.functions.register.input);
+const registerInput = K.functions.register.input;
+if (isBinaryInput(registerInput))
+    throw new TypeError('Register input must be a Value.');
+const registrationInput = valueSchema()(registerInput);
 const booleanOutput = valueSchema()({ type: 'boolean' });
 const typedDomain = schema.resolve(defineSchema('client.input-witness.typecheck', {
     dependencies: { kernel: KernelSchema },
@@ -61,9 +73,42 @@ const typedDomain = schema.resolve(defineSchema('client.input-witness.typecheck'
 const registerReference = reference(typedDomain, typedDomain.functions.registerIdentity);
 const staticRegisterReference = reference(typedDomain, typedDomain.classes.Person.static.methods.registerIdentity);
 const renameReference = reference(typedDomain, typedDomain.classes.Person.methods.rename)(Path.id(NodeId('person')));
+const blobReceipt = session.content
+    .upload(blobBytes, { mediaType: 'image/png' })
+    .then(({ receipt }) => receipt);
+const boundBlobReceipt = boundSession.content
+    .upload(blobBytes, { mediaType: 'image/png' })
+    .then(({ receipt }) => receipt);
+void blobReceipt;
+void boundBlobReceipt;
 void session.invoke(registerReference, registration);
 void boundSession.invoke(staticRegisterReference, registration);
 void session.invoke(renameReference, renameRequest);
+const binaryUploadReference = reference(K, K.functions.upload);
+void session.invoke(binaryUploadReference, { mediaType: 'image/png' }, { body: new Blob() });
+void boundSession.invoke(binaryUploadReference, { mediaType: 'image/png' }, { body: new Blob() });
+const rawBinaryCall = call(Path.parse('/:example.test:function.write'), { mediaType: 'image/png' });
+void client.dispatch(rawBinaryCall, { body: new Blob() });
+void client.as('credential').call(rawBinaryCall, { body: new Blob() });
+// @ts-expect-error Binary Functions require a byte source.
+void session.invoke(binaryUploadReference, { mediaType: 'image/png' });
+// @ts-expect-error Value Functions reject binary bodies.
+void session.invoke(registerReference, registration, { body: new Blob() });
+// @ts-expect-error Bound binary Functions require a byte source.
+void boundSession.invoke(binaryUploadReference, { mediaType: 'image/png' });
+// @ts-expect-error Bound value Functions reject binary bodies.
+void boundSession.invoke(registerReference, registration, { body: new Blob() });
+void session.invoke(binaryUploadReference, { mediaType: 'image/png' }, 
+// @ts-expect-error Binary invocations cannot carry an idempotency key.
+{ body: new Blob(), idempotencyKey: 'retry' });
+// @ts-expect-error Raw Session binary calls cannot carry an idempotency key.
+void session.dispatch(rawBinaryCall, { body: new Blob(), idempotencyKey: 'retry' });
+// @ts-expect-error Raw Client binary calls cannot carry an idempotency key.
+void client.dispatch(rawBinaryCall, { body: new Blob(), idempotencyKey: 'retry' });
+// @ts-expect-error Authenticated Client binary calls cannot carry an idempotency key.
+void client.as('credential').call(rawBinaryCall, { body: new Blob(), idempotencyKey: 'retry' });
+void session.dispatch({ target: Path.parse('/:example.test:function.write'), input: {} }, { body: new Blob() });
+void session.call({ target: Path.parse('/:example.test:function.write'), input: {} }, { body: new Blob() });
 const registerInputIsRequest = true;
 const renameInputIsInterface = true;
 const renameOutputIsBoolean = true;

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

@@ -3,12 +3,13 @@ import type { ControlledSignal } from '../index.js';
 export declare class HttpByteStream implements AsyncIterable<Uint8Array> {
     private readonly maximumBytes;
     private readonly control;
+    private readonly expectedBytes?;
     private readonly reader;
     private claimed;
     private terminal;
     private bytes;
     private interruption;
-    constructor(body: ReadableStream<Uint8Array>, maximumBytes: number, control: ControlledSignal);
+    constructor(body: ReadableStream<Uint8Array>, maximumBytes: number, control: ControlledSignal, expectedBytes?: number | undefined);
     [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
     cancel(reason?: unknown): Promise<void>;
     private next;

package/dist/transport/http/byte-stream.js

@@ -4,14 +4,16 @@ import { asError } from '../index.js';
 export class HttpByteStream {
     maximumBytes;
     control;
+    expectedBytes;
     reader;
     claimed = false;
     terminal = false;
     bytes = 0;
     interruption;
-    constructor(body, maximumBytes, control) {
+    constructor(body, maximumBytes, control, expectedBytes) {
         this.maximumBytes = maximumBytes;
         this.control = control;
+        this.expectedBytes = expectedBytes;
         this.reader = body.getReader();
         const abort = () => void this.interrupt(control.signal.reason);
         if (control.signal.aborted)
@@ -53,11 +55,17 @@ export class HttpByteStream {
             if (this.interruption !== undefined)
                 throw this.interruption;
             if (next.done) {
+                if (this.expectedBytes !== undefined && this.bytes !== this.expectedBytes) {
+                    throw new ProtocolError(`streaming binary ended after ${this.bytes} bytes; expected ${this.expectedBytes}.`);
+                }
                 this.terminal = true;
                 this.control.close();
                 return { done: true, value: undefined };
             }
             this.bytes += next.value.byteLength;
+            if (this.expectedBytes !== undefined && this.bytes > this.expectedBytes) {
+                throw new ProtocolError(`streaming binary exceeded declared Content-Length (${this.expectedBytes}).`);
+            }
             if (this.bytes > this.maximumBytes) {
                 throw new ProtocolError(`streaming binary exceeds maximumResponseBytes (${this.maximumBytes}).`);
             }

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

@@ -25,6 +25,9 @@ export declare class HttpTransport implements Transport {
     private nextId;
     constructor(options: HttpTransportOptions);
     dispatch(input: TransportRequest, options?: RequestOptions): Promise<TransportResult>;
+    /** HTTP-only binary invocation; each call may replay a re-readable Blob. */
+    dispatchBinary(input: TransportRequest, body: Blob, options?: RequestOptions): Promise<TransportResult>;
+    private dispatchWith;
     private fetchResponse;
     private decodeBinary;
     private nextRequestId;

package/dist/transport/http/transport.js

@@ -1,10 +1,11 @@
+import { canonicalMediaType } from '@astrale-os/kernel-protocol/artifact';
 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 { binaryHeaders, codecForResponse, decodeProtocol, readBoundedBody, requireId, } from './response.js';
 import { HttpStream } from './stream.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAXIMUM_REQUEST_BYTES = 16 * 1024 * 1024;
@@ -32,6 +33,18 @@ export class HttpTransport {
         this.maximumResponseBytes = positiveInteger(options.maximumResponseBytes ?? DEFAULT_MAXIMUM_RESPONSE_BYTES, 'maximumResponseBytes');
     }
     async dispatch(input, options = {}) {
+        return this.dispatchWith(input, options);
+    }
+    /** HTTP-only binary invocation; each call may replay a re-readable Blob. */
+    async dispatchBinary(input, body, options = {}) {
+        if (!(body instanceof Blob))
+            throw new TypeError('Binary request body must be a Blob.');
+        if (options.idempotencyKey !== undefined) {
+            throw new TypeError('Binary requests cannot carry an idempotency key.');
+        }
+        return this.dispatchWith(input, options, body);
+    }
+    async dispatchWith(input, options, binaryBody) {
         const requestId = this.nextRequestId();
         const timeoutMs = positiveInteger(options.timeoutMs ?? this.timeoutMs, 'timeoutMs');
         const codec = await this.requestCodec();
@@ -43,19 +56,21 @@ export class HttpTransport {
             ...invocationInput,
             ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
         });
-        const encoded = codec.encode(request);
+        const encoded = binaryBody === undefined
+            ? codec.encode(request)
+            : protocol.http.encodeBinaryRequestEnvelope(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) {
+            if (binaryBody === undefined && 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);
+            const response = await this.fetchResponse(codec, encoded, trace, control, binaryBody);
             phase = 'receive';
             requireLive(control);
             if (response.status >= 300 && response.status < 400) {
@@ -143,20 +158,27 @@ export class HttpTransport {
                 control.close();
         }
     }
-    async fetchResponse(codec, encoded, trace, control) {
+    async fetchResponse(codec, encoded, trace, control, binaryBody) {
         const init = {
             method: 'POST',
             redirect: 'manual',
             credentials: 'omit',
             cache: 'no-store',
             referrerPolicy: 'no-referrer',
+            // Fetch owns Content-Length; the protocol carries Blob.size across Fetch runtimes.
             headers: {
                 ...this.headers,
                 ...protocol.http.encodeTraceHeaders(trace),
-                'content-type': codec.contentType,
+                'content-type': binaryBody === undefined ? codec.contentType : protocol.http.BINARY_REQUEST_CONTENT_TYPE,
                 accept: codec.contentType,
+                ...(binaryBody === undefined
+                    ? {}
+                    : {
+                        [protocol.http.REQUEST_ENVELOPE_FIELD]: encoded,
+                        [protocol.http.BINARY_LENGTH_FIELD]: String(binaryBody.size),
+                    }),
             },
-            body: toBody(encoded),
+            body: binaryBody ?? toBody(encoded),
             signal: control.signal,
         };
         return this.fetchImpl(this.url, init);
@@ -165,22 +187,32 @@ export class HttpTransport {
         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) {
+        const contentType = response.headers.get('content-type');
+        if (contentType === null) {
             throw new ProtocolError('binary response has no media type.');
         }
+        const mediaType = decodeProtocol('binary media type', () => canonicalMediaType(contentType));
         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.');
+            const length = response.headers.get('content-length');
+            const expectedBytes = length === null ? undefined : Number(length);
+            if (length !== null &&
+                (!/^(?:0|[1-9][0-9]*)$/u.test(length) || !Number.isSafeInteger(expectedBytes))) {
+                throw new ProtocolError('streaming binary has an invalid Content-Length.');
+            }
+            if (expectedBytes !== undefined && expectedBytes > this.maximumResponseBytes) {
+                throw new ProtocolError(`streaming binary exceeds maximumResponseBytes (${this.maximumResponseBytes}).`);
+            }
             requireLive(control);
             return {
                 kind: 'binary',
                 invocation,
                 value: {
-                    body: new HttpByteStream(response.body, this.maximumResponseBytes, control),
+                    body: new HttpByteStream(response.body, this.maximumResponseBytes, control, expectedBytes),
                     mediaType,
                     ...(response.status === 200 ? {} : { status: response.status }),
                     ...(Object.keys(headers).length === 0 ? {} : { headers }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-client",
-  "version": "0.6.0-beta.70",
+  "version": "0.6.0-beta.72",
   "description": "Universal Client — protocol-first, transport-agnostic",
   "keywords": [
     "astrale",
@@ -65,18 +65,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.53",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.38",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.59",
+    "@astrale-os/kernel-core": "0.9.0-beta.55",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.40",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.61",
     "@tanstack/pacer": "0.20.1",
     "msgpackr": "^2.0.5"
   },
   "devDependencies": {
-    "@astrale-os/kernel-server": "0.5.0-beta.61",
+    "@astrale-os/kernel-server": "0.5.0-beta.63",
     "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
     "@types/node": "^22.0.0",
     "typescript": "7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "build": "tsc",