@astrale-os/kernel-server 0.5.0-beta.61 → 0.5.0-beta.63

package/dist/invocation/context.d.ts

@@ -1,6 +1,7 @@
+import type { BinaryRequestBody } from '@astrale-os/kernel-core/callable';
 import type * as protocol from '@astrale-os/kernel-protocol/invocation';
 import type { ActiveOperation, ActiveOperations } from '../lifecycle/index.js';
 import type { ApplicationHost, InvocationContext } from './types.js';
-export declare function invocationContext(assigned: protocol.InvocationId, operation: ActiveOperation, active: ActiveOperations, host?: ApplicationHost, requestBody?: Uint8Array, idempotencyKey?: protocol.IdempotencyKey): InvocationContext;
+export declare function invocationContext(assigned: protocol.InvocationId, operation: ActiveOperation, active: ActiveOperations, host?: ApplicationHost, requestBody?: Uint8Array, idempotencyKey?: protocol.IdempotencyKey, binary?: BinaryRequestBody): InvocationContext;
 /** Default non-durable timer used when the application host supplies no timer capability. */
 export declare function defaultSleep(durationMs: number): Promise<void>;

package/dist/invocation/context.js

@@ -1,4 +1,4 @@
-export function invocationContext(assigned, operation, active, host, requestBody, idempotencyKey) {
+export function invocationContext(assigned, operation, active, host, requestBody, idempotencyKey, binary) {
     const body = requestBody?.slice();
     return Object.freeze({
         invocation: assigned,
@@ -9,6 +9,7 @@ export function invocationContext(assigned, operation, active, host, requestBody
         },
         ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
         ...(body === undefined ? {} : { request: Object.freeze({ body: () => body.slice() }) }),
+        ...(binary === undefined ? {} : { binary }),
     });
 }
 /** Default non-durable timer used when the application host supplies no timer capability. */

package/dist/invocation/types.d.ts

@@ -1,5 +1,5 @@
 import type { CredentialInput } from '@astrale-os/kernel-core/auth';
-import type { CallableResult } from '@astrale-os/kernel-core/callable';
+import type { BinaryRequestBody, CallableResult } from '@astrale-os/kernel-core/callable';
 import type { Value } from '@astrale-os/kernel-dsl/value';
 import type * as protocol from '@astrale-os/kernel-protocol/invocation';
 import type { PublicationSnapshot } from '../publication/index.js';
@@ -27,6 +27,8 @@ export interface InvocationContext {
     readonly execution: ExecutionControl;
     readonly idempotencyKey?: protocol.IdempotencyKey;
     readonly request?: RequestEvidence;
+    /** Root-only binary HTTP ingress; ordinary envelopes and WebSocket carry none. */
+    readonly binary?: BinaryRequestBody;
     readonly background: RequestBackground;
     /** Rejects promptly when execution is cancelled or reaches its deadline. */
     readonly sleep: RequestSleep;

package/dist/lifecycle/active.d.ts

@@ -12,6 +12,8 @@ export interface ActiveOperation {
     /** Register cooperative cleanup and return an idempotent unregistration function. */
     onCancel(cancel: CancelWork): () => void;
     cancel(reason: string): void;
+    /** Replace the remaining budget after a trusted transport binding is admitted. */
+    extend(timeoutMs: number): void;
     settle(): void;
     readonly finished: Promise<void>;
 }

package/dist/lifecycle/active.js

@@ -1,3 +1,6 @@
+// Streaming iterators can need several microtasks to return after cancellation. Keep the
+// cleanup join bounded even when a producer ignores its cancellation signal.
+const CANCELLATION_CLEANUP_GRACE_MS = 250;
 export class ActiveOperations {
     maximumConcurrentOperations;
     accepting = true;
@@ -66,19 +69,32 @@ export class ActiveOperations {
     }
     close(deadline) {
         this.drain();
-        this.closing ??= this.closeOnce(deadline);
+        if (this.closing === undefined) {
+            const flight = this.closeOnce(deadline);
+            this.closing = flight;
+            void flight.catch(() => {
+                // A failed close leaves admission terminal, but residual work may settle later.
+                // Let the same owner join that cleanup on its next close attempt.
+                if (this.closing === flight)
+                    this.closing = undefined;
+            });
+        }
         return this.closing;
     }
     async closeOnce(deadline) {
         await this.waitUntilIdleOr(deadline);
+        const hasCancellationWork = [...this.operations].some((operation) => operation.hasCancellationWork);
         if (this.operations.size > 0) {
             for (const operation of this.operations)
                 operation.cancel('server closing');
         }
         this.closeSockets();
-        // Give cooperative cancellation and iterator returns one turn to settle. The absolute deadline
-        // has already elapsed; an uncooperative operation must reject close rather than pin Host forever.
-        await Promise.resolve();
+        if (hasCancellationWork) {
+            await this.waitUntilIdleOr(Date.now() + CANCELLATION_CLEANUP_GRACE_MS);
+        }
+        else {
+            await Promise.resolve();
+        }
         if (this.operations.size > 0 || this.backgroundTasks.size > 0) {
             this.closed = true;
             throw new Error(`Server close deadline elapsed with ${this.operations.size} active operation(s) and ${this.backgroundTasks.size} background task(s).`);
@@ -113,11 +129,11 @@ export class ActiveOperations {
     }
 }
 class Operation {
-    deadline;
     onSettled;
     controller = new AbortController();
     cancelWork = new Set();
     timer;
+    deadlineValue;
     external;
     settled = false;
     cancelled = false;
@@ -125,15 +141,31 @@ class Operation {
     resolveFinished;
     finished;
     constructor(deadline, onSettled) {
-        this.deadline = deadline;
         this.onSettled = onSettled;
+        this.deadlineValue = deadline;
         this.finished = new Promise((resolve) => {
             this.resolveFinished = resolve;
         });
-        this.timer = setTimeout(() => {
+        this.timer = this.arm();
+    }
+    get deadline() {
+        return this.deadlineValue;
+    }
+    extend(timeoutMs) {
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+            throw new TypeError('Active operation timeout is invalid.');
+        }
+        if (this.cancelled || this.settled)
+            return;
+        clearTimeout(this.timer);
+        this.deadlineValue = Date.now() + timeoutMs;
+        this.timer = this.arm();
+    }
+    arm() {
+        return setTimeout(() => {
             this.timeout = true;
             this.cancel('invocation deadline exceeded');
-        }, Math.min(Math.max(0, deadline - Date.now()), 2_147_483_647));
+        }, Math.min(Math.max(0, this.deadlineValue - Date.now()), 2_147_483_647));
     }
     link(signal) {
         if (signal === undefined)
@@ -151,6 +183,9 @@ class Operation {
     get timedOut() {
         return this.timeout;
     }
+    get hasCancellationWork() {
+        return this.cancelWork.size > 0;
+    }
     onCancel(cancel) {
         if (this.cancelled) {
             void settleCancellation(cancel, abortReason(this.controller.signal));

package/dist/server.js

@@ -1,3 +1,4 @@
+import { Path } from '@astrale-os/kernel-core/path';
 import { PATH as PUBLICATION_PATH, url as publicationUrl, } from '@astrale-os/kernel-protocol/publication/publication';
 import { captureMethod } from './capture.js';
 import { prepareCors } from './cors/index.js';
@@ -244,16 +245,42 @@ function admitLimits(limits) {
     if (limits.invocationTimeoutMs > 2_147_483_647) {
         throw new TypeError('invocationTimeoutMs exceeds the platform timer range.');
     }
+    if ((limits.binaryDownloadTarget === undefined) !==
+        (limits.binaryDownloadTimeoutMs === undefined)) {
+        throw new TypeError('binaryDownloadTarget and binaryDownloadTimeoutMs must be configured together.');
+    }
+    const binaryDownloadTarget = limits.binaryDownloadTarget === undefined
+        ? undefined
+        : Path.parse(limits.binaryDownloadTarget).raw;
+    const binaryDownloadTimeoutMs = limits.binaryDownloadTimeoutMs === undefined
+        ? undefined
+        : admitTimerLimit(limits.binaryDownloadTimeoutMs, 'binaryDownloadTimeoutMs');
     return Object.freeze({
         maximumRequestBytes: limits.maximumRequestBytes,
+        maximumBinaryRequestBytes: admitOptionalLimit(limits.maximumBinaryRequestBytes, limits.maximumRequestBytes, 'maximumBinaryRequestBytes'),
         maximumResponseBytes: admitOptionalLimit(limits.maximumResponseBytes, 16 * 1024 * 1024, 'maximumResponseBytes'),
         maximumConcurrentOperations: admitOptionalLimit(limits.maximumConcurrentOperations, 1_024, 'maximumConcurrentOperations'),
         maximumPublicationBytes: admitOptionalLimit(limits.maximumPublicationBytes, limits.maximumRequestBytes, 'maximumPublicationBytes'),
         maximumBundleBytes: admitOptionalLimit(limits.maximumBundleBytes, 16 * 1024 * 1024, 'maximumBundleBytes'),
         maximumDeliveryBytes: admitOptionalLimit(limits.maximumDeliveryBytes, limits.maximumRequestBytes, 'maximumDeliveryBytes'),
         invocationTimeoutMs: limits.invocationTimeoutMs,
+        binaryRequestTimeoutMs: admitTimerLimit(limits.binaryRequestTimeoutMs ?? limits.invocationTimeoutMs, 'binaryRequestTimeoutMs'),
+        ...(limits.binaryRequestIdleTimeoutMs === undefined
+            ? {}
+            : {
+                binaryRequestIdleTimeoutMs: admitTimerLimit(limits.binaryRequestIdleTimeoutMs, 'binaryRequestIdleTimeoutMs'),
+            }),
+        ...(binaryDownloadTarget === undefined
+            ? {}
+            : { binaryDownloadTarget, binaryDownloadTimeoutMs }),
     });
 }
+function admitTimerLimit(input, label) {
+    if (!Number.isSafeInteger(input) || input <= 0 || input > 2_147_483_647) {
+        throw new TypeError(`${label} must be a positive platform timer duration.`);
+    }
+    return input;
+}
 function admitOptionalLimit(input, fallback, label) {
     const value = input ?? fallback;
     if (!Number.isSafeInteger(value) || value <= 0) {

package/dist/transport/http/binary-request.d.ts

@@ -0,0 +1,11 @@
+import { type BinaryRequestBody } from '@astrale-os/kernel-core/callable';
+interface IdleBudget {
+    readonly timeoutMs: number;
+    readonly cancel: () => void;
+}
+/** Admit a declared length before dispatch and expose one counted, non-buffering body. */
+export declare function binaryRequestBody(request: Request, maximumBytes: number, signal: AbortSignal, idle?: IdleBudget): BinaryRequestBody & {
+    readonly completed: () => boolean;
+    readonly cancel: (reason: unknown) => void;
+};
+export {};

package/dist/transport/http/binary-request.js

@@ -0,0 +1,102 @@
+import { BinaryBodyLengthError } from '@astrale-os/kernel-core/callable';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import { RequestBodyInvalidError, RequestBodyTooLargeError } from '../../errors/index.js';
+/** Admit a declared length before dispatch and expose one counted, non-buffering body. */
+export function binaryRequestBody(request, maximumBytes, signal, idle) {
+    const declared = request.headers.get(protocol.http.BINARY_LENGTH_FIELD);
+    if (declared === null || !/^(?:0|[1-9][0-9]*)$/u.test(declared)) {
+        throw new RequestBodyInvalidError('Binary request length is required and must be exact.');
+    }
+    const length = Number(declared);
+    if (!Number.isSafeInteger(length)) {
+        throw new RequestBodyInvalidError('Binary request length is invalid.');
+    }
+    const contentLength = request.headers.get('content-length');
+    if (contentLength !== null && contentLength !== declared) {
+        throw new RequestBodyInvalidError('Binary request length differs from Content-Length.');
+    }
+    if (length > maximumBytes)
+        throw new RequestBodyTooLargeError(maximumBytes);
+    if (request.body === null) {
+        if (length !== 0)
+            throw new RequestBodyInvalidError('Binary request body is missing.');
+        return Object.freeze({
+            body: new ReadableStream({ start: (controller) => controller.close() }),
+            length,
+            completed: () => true,
+            cancel: () => undefined,
+        });
+    }
+    const reader = request.body.getReader();
+    let size = 0;
+    let finished = false;
+    let completed = false;
+    let idleTimer;
+    const clearIdle = () => {
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        idleTimer = undefined;
+    };
+    const release = () => {
+        if (finished)
+            return;
+        finished = true;
+        clearIdle();
+        signal.removeEventListener('abort', abort);
+        reader.releaseLock();
+    };
+    const cancelSource = (reason) => {
+        if (finished)
+            return;
+        clearIdle();
+        void reader.cancel(reason).then(release, release);
+    };
+    const abort = () => cancelSource(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted)
+        abort();
+    const startIdle = () => {
+        if (idle !== undefined && idleTimer === undefined) {
+            idleTimer = setTimeout(idle.cancel, idle.timeoutMs);
+        }
+    };
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                if (signal.aborted)
+                    throw signal.reason;
+                startIdle();
+                const next = await reader.read();
+                if (signal.aborted)
+                    throw signal.reason;
+                if (next.done) {
+                    if (size !== length)
+                        throw new BinaryBodyLengthError();
+                    completed = true;
+                    release();
+                    controller.close();
+                    return;
+                }
+                if (!(next.value instanceof Uint8Array)) {
+                    throw new RequestBodyInvalidError('Binary request yielded a non-byte chunk.');
+                }
+                size += next.value.byteLength;
+                if (size > length)
+                    throw new BinaryBodyLengthError();
+                if (next.value.byteLength > 0)
+                    clearIdle();
+                controller.enqueue(next.value);
+            }
+            catch (cause) {
+                cancelSource(cause);
+                release();
+                controller.error(cause);
+            }
+        },
+        cancel(reason) {
+            cancelSource(reason);
+            release();
+        },
+    }, { highWaterMark: 0 });
+    return Object.freeze({ body, length, completed: () => completed, cancel: cancelSource });
+}

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

@@ -8,8 +8,13 @@ export interface HttpHandlerConfig {
     readonly active: ActiveOperations;
     readonly invocation: NextInvocationId;
     readonly maximumRequestBytes: number;
+    readonly maximumBinaryRequestBytes: number;
     readonly maximumResponseBytes: number;
     readonly invocationTimeoutMs: number;
+    readonly binaryRequestTimeoutMs: number;
+    readonly binaryRequestIdleTimeoutMs?: number;
+    readonly binaryDownloadTarget?: string;
+    readonly binaryDownloadTimeoutMs?: number;
     readonly cors: CorsPolicy;
     readonly websocket: boolean;
     readonly currentPublication?: (request: Request) => PublicationSnapshot | undefined;

package/dist/transport/http/handler.js

@@ -6,6 +6,7 @@ import { invocationContext, publicationRouteDecision, } from '../../invocation/i
 import { readBoundedBody } from '../body.js';
 import { loadCodecs } from '../codecs.js';
 import { resolveCredential } from '../credential.js';
+import { binaryRequestBody } from './binary-request.js';
 import { isStreamingBinary, renderHttpError, renderHttpResult, } from './render.js';
 export function createHttpHandler(config) {
     return async (request, host) => {
@@ -21,6 +22,8 @@ export function createHttpHandler(config) {
                 headers: [
                     'authorization',
                     'content-type',
+                    protocol.http.REQUEST_ENVELOPE_FIELD,
+                    protocol.http.BINARY_LENGTH_FIELD,
                     protocol.http.TRACEPARENT_FIELD,
                     protocol.http.TRACESTATE_FIELD,
                 ],
@@ -37,18 +40,24 @@ export function createHttpHandler(config) {
             ...options,
             maximumResponseBytes: config.maximumResponseBytes,
         });
-        const active = config.active.begin(config.invocationTimeoutMs, request.signal);
+        const binaryRequest = request.headers.get('content-type')?.trim().toLowerCase() ===
+            protocol.http.BINARY_REQUEST_CONTENT_TYPE;
+        const active = config.active.begin(binaryRequest ? config.binaryRequestTimeoutMs : config.invocationTimeoutMs, request.signal);
         if (active === undefined) {
+            if (binaryRequest && request.body !== null && !request.body.locked) {
+                void request.body.cancel('binary request rejected').catch(() => undefined);
+            }
             return renderError(null, {
                 code: errors.CODES.BACKEND_UNAVAILABLE,
                 message: 'server is unavailable.',
             }, codecs.json, { status: 503, negotiated: false });
         }
         let handedOff = false;
+        let binary;
         try {
             const supported = await loadCodecs();
             const contentType = request.headers.get('content-type');
-            const incoming = contentType === null || contentType.trim() === ''
+            const incoming = binaryRequest || contentType === null || contentType.trim() === ''
                 ? codecs.json
                 : protocol.http.codecForContentType(contentType, supported);
             if (incoming === undefined) {
@@ -66,7 +75,15 @@ export function createHttpHandler(config) {
             }
             let body;
             try {
-                body = await readBoundedBody(request, config.maximumRequestBytes, active.signal);
+                if (binaryRequest)
+                    binary = binaryRequestBody(request, config.maximumBinaryRequestBytes, active.signal, config.binaryRequestIdleTimeoutMs === undefined
+                        ? undefined
+                        : {
+                            timeoutMs: config.binaryRequestIdleTimeoutMs,
+                            cancel: () => active.cancel('binary request idle timeout exceeded'),
+                        });
+                else
+                    body = await readBoundedBody(request, config.maximumRequestBytes, active.signal);
             }
             catch (input) {
                 const payload = input instanceof RequestBodyTooLargeError
@@ -87,22 +104,45 @@ export function createHttpHandler(config) {
                     status: input instanceof RequestBodyTooLargeError ? 413 : errors.httpStatusOf(payload),
                 });
             }
-            let decoded;
-            try {
-                decoded = incoming.decode(body);
-            }
-            catch (input) {
-                if (!(input instanceof codecs.DecodeError))
-                    throw input;
-                return renderError(null, { code: errors.CODES.PARSE_ERROR, message: 'Request body is invalid.' }, outgoing);
-            }
             let envelope;
             try {
-                envelope = protocol.decodeRequest(decoded);
+                if (binaryRequest) {
+                    envelope = protocol.http.decodeBinaryRequestEnvelope(request.headers.get(protocol.http.REQUEST_ENVELOPE_FIELD));
+                    if (envelope.idempotencyKey !== undefined) {
+                        return renderError(envelope.requestId, {
+                            code: errors.CODES.INVALID_REQUEST,
+                            message: 'Binary requests forbid idempotencyKey.',
+                        }, outgoing);
+                    }
+                }
+                else {
+                    let decoded;
+                    try {
+                        decoded = incoming.decode(body);
+                    }
+                    catch (input) {
+                        if (!(input instanceof codecs.DecodeError))
+                            throw input;
+                        return renderError(null, { code: errors.CODES.PARSE_ERROR, message: 'Request body is invalid.' }, outgoing);
+                    }
+                    envelope = protocol.decodeRequest(decoded);
+                }
             }
             catch (input) {
                 return renderError(null, classifyError(input), outgoing);
             }
+            if (!binaryRequest &&
+                config.binaryDownloadTarget !== undefined &&
+                protocol.targetPath(envelope.call.target) === config.binaryDownloadTarget) {
+                active.extend(config.binaryDownloadTimeoutMs);
+            }
+            if (active.signal.aborted) {
+                const timedOut = active.timedOut;
+                return renderError(envelope.requestId, {
+                    code: timedOut ? errors.CODES.DEADLINE_EXCEEDED : errors.CODES.CANCELLED,
+                    message: timedOut ? 'Invocation deadline exceeded.' : 'Invocation was cancelled.',
+                }, outgoing, { status: timedOut ? 504 : 408 });
+            }
             const publication = config.currentPublication?.(request);
             if (config.currentPublication !== undefined && publication === undefined) {
                 return renderError(envelope.requestId, {
@@ -136,8 +176,19 @@ export function createHttpHandler(config) {
                     ...(envelope.routing?.kind === 'via' ? { via: envelope.routing } : {}),
                     ...(envelope.schema === undefined ? {} : { schema: envelope.schema }),
                     ...(publication === undefined ? {} : { publication }),
-                    context: invocationContext(assigned, active, config.active, host, undefined, envelope.idempotencyKey),
+                    context: invocationContext(assigned, active, config.active, host, undefined, envelope.idempotencyKey, binary),
                 }));
+                if (binary !== undefined && result.kind !== 'redirect' && result.kind !== 'miss') {
+                    if (!binary.completed()) {
+                        if (result.kind === 'stream') {
+                            await result.stream.cancel('Binary request body was not fully consumed.');
+                        }
+                        else if (result.kind === 'binary' && isStreamingBinary(result.value)) {
+                            await result.value.body[Symbol.asyncIterator]().return?.();
+                        }
+                        throw new Error('Binary Function returned before consuming its request body.');
+                    }
+                }
                 const response = renderHttpResult(result, {
                     requestId: envelope.requestId,
                     codec: outgoing,
@@ -169,6 +220,15 @@ export function createHttpHandler(config) {
             });
         }
         finally {
+            if (binary !== undefined) {
+                binary.cancel('binary invocation completed');
+            }
+            else if (binaryRequest &&
+                binary === undefined &&
+                request.body !== null &&
+                !request.body.locked) {
+                void request.body.cancel('binary request rejected').catch(() => undefined);
+            }
             if (!handedOff)
                 active.settle();
         }

package/dist/transport/http/render.js

@@ -82,6 +82,21 @@ function binaryHttpResponse(binary, cors, maximumResponseBytes) {
     return new Response(toBody(binary.body), { status: binary.status, headers });
 }
 function streamingBinaryHttpResponse(binary, context) {
+    if (binary.length !== undefined && (!Number.isSafeInteger(binary.length) || binary.length < 0)) {
+        throw new TypeError('Streaming binary length must be a non-negative safe integer.');
+    }
+    const delivery = binary.delivery;
+    if (delivery !== undefined) {
+        if (!Number.isSafeInteger(delivery.maximumDurationMs) ||
+            delivery.maximumDurationMs <= 0 ||
+            delivery.maximumDurationMs > 2_147_483_647 ||
+            !Number.isSafeInteger(delivery.idleTimeoutMs) ||
+            delivery.idleTimeoutMs <= 0 ||
+            delivery.idleTimeoutMs > 2_147_483_647) {
+            throw new TypeError('Streaming binary delivery budget is invalid.');
+        }
+        context.active.extend(delivery.maximumDurationMs);
+    }
     const iterator = binary.body[Symbol.asyncIterator]();
     const headers = binaryHttpHeaders(Object.freeze({
         requestId: context.requestId,
@@ -89,13 +104,30 @@ function streamingBinaryHttpResponse(binary, context) {
         mediaType: binary.mediaType,
         headers: binary.headers,
     }), context.cors, true);
+    if (binary.length !== undefined)
+        headers.set('content-length', String(binary.length));
+    if (delivery !== undefined)
+        headers.set('cache-control', 'private, no-store');
     let terminal = false;
+    let delivered = 0;
     let controller;
     let stopping;
+    let idleTimer;
+    const clearIdle = () => {
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+    };
+    const resetIdle = () => {
+        if (delivery === undefined || terminal)
+            return;
+        clearIdle();
+        idleTimer = setTimeout(() => context.active.cancel('binary response idle timeout exceeded'), delivery.idleTimeoutMs);
+    };
     const stop = (reason = 'Binary response was interrupted.') => {
         if (terminal)
             return stopping ?? Promise.resolve();
         terminal = true;
+        clearIdle();
         controller?.error(new Error(reason));
         stopping = Promise.resolve().then(async () => {
             try {
@@ -107,9 +139,21 @@ function streamingBinaryHttpResponse(binary, context) {
         });
         return stopping;
     };
+    const fail = (cause) => {
+        if (terminal)
+            return;
+        terminal = true;
+        clearIdle();
+        controller?.error(cause);
+        stopping = Promise.resolve()
+            .then(() => iterator.return?.())
+            .catch(() => undefined)
+            .then(() => context.active.settle());
+    };
     const body = new ReadableStream({
         start(output) {
             controller = output;
+            resetIdle();
         },
         async pull(controller) {
             if (terminal)
@@ -119,19 +163,29 @@ function streamingBinaryHttpResponse(binary, context) {
                 if (terminal)
                     return;
                 if (next.done) {
+                    if (binary.length !== undefined && delivered !== binary.length) {
+                        fail(new Error('OUTCOME_UNKNOWN: streaming binary ended before its declared length.'));
+                        return;
+                    }
                     terminal = true;
+                    clearIdle();
                     controller.close();
                     context.active.settle();
                     return;
                 }
+                if (!(next.value instanceof Uint8Array)) {
+                    throw new TypeError('Streaming binary yielded a non-byte chunk.');
+                }
+                delivered += next.value.byteLength;
+                if (binary.length !== undefined && delivered > binary.length) {
+                    fail(new Error('OUTCOME_UNKNOWN: streaming binary exceeded its declared length.'));
+                    return;
+                }
                 controller.enqueue(next.value);
+                resetIdle();
             }
             catch (cause) {
-                if (terminal)
-                    return;
-                terminal = true;
-                controller.error(cause);
-                context.active.settle();
+                fail(cause);
             }
         },
         async cancel(reason) {

package/dist/types.d.ts

@@ -6,6 +6,8 @@ import type { PublicationSource } from './publication/index.js';
 import type { Application, WebSocketAdapter } from './transport/index.js';
 export interface ServerLimits {
     readonly maximumRequestBytes: number;
+    /** Deployment cap for a streamed binary HTTP request; defaults to maximumRequestBytes. */
+    readonly maximumBinaryRequestBytes?: number;
     /** Maximum bytes in one encoded envelope, buffered binary body, or stream frame. */
     readonly maximumResponseBytes?: number;
     /** Maximum Server-owned active operations across all mounted protocol surfaces. */
@@ -15,6 +17,14 @@ export interface ServerLimits {
     readonly maximumDeliveryBytes?: number;
     /** Maximum lifetime of one invocation, including a returned stream. */
     readonly invocationTimeoutMs: number;
+    /** Binary request lifetime; defaults to invocationTimeoutMs. */
+    readonly binaryRequestTimeoutMs?: number;
+    /** Maximum wait for the next binary body chunk while a consumer is reading. */
+    readonly binaryRequestIdleTimeoutMs?: number;
+    /** Exact Host-selected callable Path whose ordinary JSON invocation may stream a large result. */
+    readonly binaryDownloadTarget?: string;
+    /** Required with binaryDownloadTarget; selected before semantic dispatch. */
+    readonly binaryDownloadTimeoutMs?: number;
 }
 export interface ServerCloseOptions {
     /** Absolute Unix time in milliseconds after which active work is cancelled. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-server",
-  "version": "0.5.0-beta.61",
+  "version": "0.5.0-beta.63",
   "description": "Portable HTTP and WebSocket boundary for Astrale invocation, publication, installation, and issuer protocols",
   "license": "Apache-2.0",
   "repository": {
@@ -33,16 +33,16 @@
     "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",
     "hono": "^4.6.20",
     "msgpackr": "^2.0.5"
   },
   "devDependencies": {
     "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
     "typescript": "7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "build": "tsc",