@astrale-os/kernel-server 0.5.0-beta.62 → 0.5.0-beta.64

package/dist/errors/admission.d.ts

@@ -0,0 +1,7 @@
+import * as errors from '@astrale-os/kernel-protocol/errors';
+/** Advisory delay before a request the Server did not admit is sent again. */
+export declare const ADMISSION_RETRY_AFTER_MS = 1000;
+/** Public refusal of an operation the Server did not admit; nothing ran. */
+export declare function admissionRefusal(accepting: boolean): errors.ErrorPayload;
+/** HTTP presentation of a public error's retry delay, when it has one. */
+export declare function retryAfterHeaders(error: errors.ErrorPayload): Readonly<Record<string, string>>;

package/dist/errors/admission.js

@@ -0,0 +1,22 @@
+import * as errors from '@astrale-os/kernel-protocol/errors';
+/** Advisory delay before a request the Server did not admit is sent again. */
+export const ADMISSION_RETRY_AFTER_MS = 1_000;
+/** Public refusal of an operation the Server did not admit; nothing ran. */
+export function admissionRefusal(accepting) {
+    return accepting
+        ? {
+            code: errors.CODES.BACKEND_UNAVAILABLE,
+            message: 'Server is at capacity; retry later.',
+            data: errors.retryReason(errors.RETRY_REASONS.CAPACITY_EXHAUSTED, ADMISSION_RETRY_AFTER_MS),
+        }
+        : {
+            code: errors.CODES.BACKEND_UNAVAILABLE,
+            message: 'Server is draining; retry later.',
+            data: errors.retryReason(errors.RETRY_REASONS.SERVER_DRAINING, ADMISSION_RETRY_AFTER_MS),
+        };
+}
+/** HTTP presentation of a public error's retry delay, when it has one. */
+export function retryAfterHeaders(error) {
+    const retryAfterMs = errors.retryAfterOf(error);
+    return retryAfterMs === undefined ? {} : { 'retry-after': errors.retryAfterField(retryAfterMs) };
+}

package/dist/errors/index.d.ts

@@ -1,3 +1,4 @@
+export { ADMISSION_RETRY_AFTER_MS, admissionRefusal, retryAfterHeaders } from './admission.js';
 export { DeliveryUnavailableError, IssuerKeysUnavailableError } from './availability.js';
 export { classifyError } from './classify.js';
 export { RequestBodyInvalidError, RequestBodyTooLargeError } from './request-body.js';

package/dist/errors/index.js

@@ -1,3 +1,4 @@
+export { ADMISSION_RETRY_AFTER_MS, admissionRefusal, retryAfterHeaders } from './admission.js';
 export { DeliveryUnavailableError, IssuerKeysUnavailableError } from './availability.js';
 export { classifyError } from './classify.js';
 export { RequestBodyInvalidError, RequestBodyTooLargeError } from './request-body.js';

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/issuer/exchange.js

@@ -2,6 +2,7 @@ import { inspect as inspectCredential } from '@astrale-os/kernel-core/auth/crede
 import * as errors from '@astrale-os/kernel-protocol/errors';
 import * as exchangeProtocol from '@astrale-os/kernel-protocol/issuer/exchange';
 import { paths as issuerPaths } from '@astrale-os/kernel-protocol/issuer/paths';
+import { admissionRefusal, retryAfterHeaders } from '../errors/index.js';
 const PROVIDER_CODES = new Set([
     errors.CODES.AUTH_INVALID,
     errors.CODES.AUTH_EXPIRED,
@@ -24,7 +25,10 @@ export function mount(app, issuer, provider, cors, active, timeoutMs) {
     }
     app.all(path, async (context) => {
         const request = context.req.raw;
-        const respond = (payload, extra) => json(payload, errors.httpStatusOf(payload.error), request, cors, extra);
+        const respond = (payload, extra) => json(payload, errors.httpStatusOf(payload.error), request, cors, {
+            ...retryAfterHeaders(payload.error),
+            ...extra,
+        });
         let admitted;
         try {
             admitted = exchangeProtocol.acceptHttpRequest({
@@ -40,12 +44,9 @@ export function mount(app, issuer, provider, cors, active, timeoutMs) {
             }
             throw cause;
         }
-        if (!active.isAccepting) {
-            return respond(error('BACKEND_UNAVAILABLE', 'Token exchange is unavailable.'));
-        }
         const operation = active.begin(timeoutMs, request.signal);
         if (operation === undefined) {
-            return respond(error('LIMIT_EXCEEDED', 'Token-exchange limit exceeded.'));
+            return respond(exchangeProtocol.acceptErrorResponse({ error: admissionRefusal(active.isAccepting) }));
         }
         try {
             try {
@@ -134,12 +135,13 @@ function error(code, message) {
     });
 }
 function json(value, status, request, cors, extra) {
+    const additional = new Headers(extra);
     const headers = new Headers(exchangeProtocol.responseHeaders());
-    for (const [name, value] of Object.entries(cors.response(request)))
+    const exposed = additional.has('retry-after') ? ['retry-after'] : [];
+    for (const [name, value] of Object.entries(cors.response(request, exposed))) {
         headers.set(name, value);
-    if (extra !== undefined) {
-        for (const [name, value] of new Headers(extra))
-            headers.set(name, value);
     }
+    for (const [name, value] of additional)
+        headers.set(name, value);
     return new Response(JSON.stringify(value), { status, headers });
 }

package/dist/issuer/routes.js

@@ -2,7 +2,7 @@ import { configuration } from '@astrale-os/kernel-protocol/issuer/configuration'
 import { hosted } from '@astrale-os/kernel-protocol/issuer/hosted';
 import { keySet } from '@astrale-os/kernel-protocol/issuer/key-set';
 import { paths as issuerPaths } from '@astrale-os/kernel-protocol/issuer/paths';
-import { IssuerKeysUnavailableError } from '../errors/index.js';
+import { admissionRefusal, IssuerKeysUnavailableError, retryAfterHeaders } from '../errors/index.js';
 import { mount } from './exchange.js';
 export function issuerRouteReservations(input, tokenExchange = false) {
     const paths = issuerPaths(input.issuer);
@@ -32,6 +32,19 @@ export function mountIssuer(app, input, cors, active, timeoutMs, tokenExchange)
         ...cors.response(request),
         'cache-control': 'no-cache',
     });
+    // A lifecycle refusal names saturation or drain and presents its retry delay.
+    const refusal = (request) => {
+        const refused = admissionRefusal(active.isAccepting);
+        const retry = retryAfterHeaders(refused);
+        return {
+            body: { error: refused.message },
+            headers: {
+                ...cors.response(request, Object.keys(retry)),
+                'cache-control': 'no-cache',
+                ...retry,
+            },
+        };
+    };
     const algorithm = input.signingAlgorithm ?? 'ES256';
     const discovery = configuration(issuer, [algorithm], {
         tokenExchange: tokenExchange !== undefined,
@@ -44,7 +57,8 @@ export function mountIssuer(app, input, cors, active, timeoutMs, tokenExchange)
     app.get(paths.keys, async (context) => {
         const operation = active.begin(timeoutMs, context.req.raw.signal);
         if (operation === undefined) {
-            return context.json({ error: 'Issuer is unavailable while draining.' }, 503, headers(context.req.raw));
+            const refused = refusal(context.req.raw);
+            return context.json(refused.body, 503, refused.headers);
         }
         try {
             const keys = await input.loadPublicKeys(operation.signal);
@@ -76,7 +90,8 @@ export function mountIssuer(app, input, cors, active, timeoutMs, tokenExchange)
                 return context.json({ error: 'Issuer not found.' }, 404, headers(context.req.raw));
             const operation = active.begin(timeoutMs, context.req.raw.signal);
             if (operation === undefined) {
-                return context.json({ error: 'Issuer is unavailable while draining.' }, 503, headers(context.req.raw));
+                const refused = refusal(context.req.raw);
+                return context.json(refused.body, 503, refused.headers);
             }
             try {
                 const keys = await hostedKeys(loadIssuerPublicKeys, hostedIssuer, operation.signal, algorithm);
@@ -100,7 +115,8 @@ export function mountIssuer(app, input, cors, active, timeoutMs, tokenExchange)
                 return context.json({ error: 'Issuer not found.' }, 404, headers(context.req.raw));
             const operation = active.begin(timeoutMs, context.req.raw.signal);
             if (operation === undefined) {
-                return context.json({ error: 'Issuer is unavailable while draining.' }, 503, headers(context.req.raw));
+                const refused = refusal(context.req.raw);
+                return context.json(refused.body, 503, refused.headers);
             }
             try {
                 const keys = await hostedKeys(loadIssuerPublicKeys, hostedIssuer, operation.signal, algorithm);

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/publication/delivery/handler.d.ts

@@ -6,4 +6,4 @@ export interface Limits {
     readonly invocationTimeoutMs: number;
 }
 /** Serve one delivery request against the exact Publication snapshot that selected its URL. */
-export declare function handleDelivery(request: Request, snapshot: PreparedPublicationSnapshot, provider: Provider | undefined, active: ActiveOperations, limits: Limits, cors: Readonly<Record<string, string>>): Promise<Response>;
+export declare function handleDelivery(request: Request, snapshot: PreparedPublicationSnapshot, provider: Provider | undefined, active: ActiveOperations, limits: Limits, corsFor: (exposedHeaders?: readonly string[]) => Readonly<Record<string, string>>): Promise<Response>;

package/dist/publication/delivery/handler.js

@@ -1,11 +1,12 @@
 import * as codecs from '@astrale-os/kernel-protocol/codecs';
 import * as protocolPublication from '@astrale-os/kernel-protocol/publication';
-import { DeliveryUnavailableError } from '../../errors/index.js';
+import { admissionRefusal, DeliveryUnavailableError, retryAfterHeaders, } from '../../errors/index.js';
 import { RequestBodyInvalidError, RequestBodyTooLargeError } from '../../errors/index.js';
 import { readBoundedBody } from '../../transport/index.js';
 const delivery = protocolPublication.delivery;
 /** Serve one delivery request against the exact Publication snapshot that selected its URL. */
-export async function handleDelivery(request, snapshot, provider, active, limits, cors) {
+export async function handleDelivery(request, snapshot, provider, active, limits, corsFor) {
+    const cors = corsFor();
     if (request.method !== 'POST') {
         return response({ error: 'Delivery requires POST.' }, 405, cors);
     }
@@ -17,8 +18,11 @@ export async function handleDelivery(request, snapshot, provider, active, limits
         return response({ error: 'Delivery is unavailable.' }, 404, cors);
     }
     const operation = active.begin(limits.invocationTimeoutMs, request.signal);
-    if (operation === undefined)
-        return response({ error: 'Server is draining.' }, 503, cors);
+    if (operation === undefined) {
+        const refusal = admissionRefusal(active.isAccepting);
+        const retry = retryAfterHeaders(refusal);
+        return response({ error: refusal.message }, 503, { ...corsFor(Object.keys(retry)), ...retry });
+    }
     try {
         const authorization = request.headers.get('authorization');
         const token = bearer(authorization);

package/dist/routes/routes.js

@@ -5,7 +5,7 @@ import { bundleUrl } from '@astrale-os/kernel-protocol/publication';
 import { mediaType as publicationMediaType, PATH as PUBLICATION_PATH, url as publicationUrl, } from '@astrale-os/kernel-protocol/publication/publication';
 import { reference as publicationReference } from '@astrale-os/kernel-protocol/publication/reference';
 import * as routes from '@astrale-os/kernel-protocol/routes';
-import { classifyError, RequestBodyInvalidError, RequestBodyTooLargeError, } from '../errors/index.js';
+import { admissionRefusal, classifyError, RequestBodyInvalidError, RequestBodyTooLargeError, retryAfterHeaders, } from '../errors/index.js';
 import { invocationContext } from '../invocation/index.js';
 import { handleDelivery } from '../publication/delivery/index.js';
 import { readPreparedPublicationSnapshot, } from '../publication/index.js';
@@ -25,8 +25,9 @@ export function mountRoutes(app, source, deliveryProvider, handler, active, next
     }
     app.get(publicationPath, (context) => {
         const responseCors = cors.response(context.req.raw, ['etag']);
-        if (!active.isAccepting)
-            return response({ error: 'Publication is unavailable while draining.' }, 503, responseCors);
+        if (!active.isAccepting) {
+            return drained('Publication is unavailable while draining.', (exposed) => cors.response(context.req.raw, exposed));
+        }
         const snapshot = servingSnapshot(source, limits, context.req.raw, reservations, externalIssuer, externalOrigin);
         if (snapshot === undefined)
             return response({ error: 'Publication is not ready.' }, 503, responseCors);
@@ -60,12 +61,13 @@ export function mountRoutes(app, source, deliveryProvider, handler, active, next
             return publicationPreflight(cors, request, snapshot, externalOrigin);
         }
         const responseCors = cors.response(request);
+        const corsFor = (exposed) => cors.response(request, exposed);
         const descriptor = snapshot.publication.schema.bundle;
         const addressed = bundleUrl(snapshot.publication.identity.issuer, descriptor.ref);
         const immutable = descriptor.href === addressed;
         if (sameRoute(request.url, snapshot.publication.schema.bundle.href, externalOrigin)) {
             if (!active.isAccepting)
-                return response({ error: 'Publication artifact is unavailable while draining.' }, 503, responseCors);
+                return drained('Publication artifact is unavailable while draining.', corsFor);
             if (request.method !== 'GET')
                 return response({ error: 'Bundle retrieval requires GET.' }, 405, responseCors);
             const body = snapshot.bundle;
@@ -100,7 +102,7 @@ export function mountRoutes(app, source, deliveryProvider, handler, active, next
         }
         const deliveryUrl = snapshot.publication.delivery?.href;
         if (deliveryUrl !== undefined && sameRoute(request.url, deliveryUrl, externalOrigin)) {
-            return handleDelivery(request, snapshot, deliveryProvider, active, limits, cors.response(request));
+            return handleDelivery(request, snapshot, deliveryProvider, active, limits, corsFor);
         }
         let routing;
         try {
@@ -120,7 +122,7 @@ export function mountRoutes(app, source, deliveryProvider, handler, active, next
         }
         catch (cause) {
             if (cause instanceof routes.RouteError) {
-                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Native route routing is invalid.' }, 400, responseCors);
+                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Native route routing is invalid.' }, 400, corsFor);
             }
             throw cause;
         }
@@ -130,10 +132,7 @@ export function mountRoutes(app, source, deliveryProvider, handler, active, next
         const assigned = nextInvocation();
         const operation = active.begin(limits.invocationTimeoutMs, request.signal);
         if (operation === undefined)
-            return nativeError({
-                code: errors.CODES.BACKEND_UNAVAILABLE,
-                message: 'Server is draining.',
-            }, 503, responseCors);
+            return nativeError(admissionRefusal(active.isAccepting), 503, corsFor);
         let handedOff = false;
         try {
             const body = await readBoundedBody(request, limits.maximumRequestBytes, operation.signal);
@@ -178,7 +177,7 @@ export function mountRoutes(app, source, deliveryProvider, handler, active, next
             }
             if (result.kind === 'stream') {
                 handedOff = true;
-                return await streamResponse(result.stream, operation, responseCors);
+                return await streamResponse(result.stream, operation, corsFor);
             }
             if (result.kind === 'miss') {
                 return new Response(null, {
@@ -192,29 +191,29 @@ export function mountRoutes(app, source, deliveryProvider, handler, active, next
             return nativeError({
                 code: errors.CODES.UNSUPPORTED,
                 message: 'Native routes do not forward Runtime redirects.',
-            }, 502, responseCors);
+            }, 502, corsFor);
         }
         catch (cause) {
             if (cause instanceof RequestBodyTooLargeError) {
-                return nativeError({ code: errors.CODES.LIMIT_EXCEEDED, message: 'Request body is too large.' }, 413, responseCors);
+                return nativeError({ code: errors.CODES.LIMIT_EXCEEDED, message: 'Request body is too large.' }, 413, corsFor);
             }
             if (cause instanceof RequestBodyInvalidError) {
-                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Request body is invalid.' }, 400, responseCors);
+                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Request body is invalid.' }, 400, corsFor);
             }
             if (cause instanceof routes.RouteError) {
-                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Native route request is invalid.' }, 400, responseCors);
+                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Native route request is invalid.' }, 400, corsFor);
             }
             if (operation.timedOut) {
                 return nativeError({
                     code: errors.CODES.DEADLINE_EXCEEDED,
                     message: 'Invocation deadline exceeded.',
-                }, 504, responseCors);
+                }, 504, corsFor);
             }
             if (operation.signal.aborted) {
-                return nativeError({ code: errors.CODES.CANCELLED, message: 'Invocation was cancelled.' }, 408, responseCors);
+                return nativeError({ code: errors.CODES.CANCELLED, message: 'Invocation was cancelled.' }, 408, corsFor);
             }
             const payload = classifyError(cause);
-            return nativeError(payload, errors.httpStatusOf(payload), responseCors);
+            return nativeError(payload, errors.httpStatusOf(payload), corsFor);
         }
         finally {
             if (!handedOff)
@@ -404,7 +403,7 @@ async function streamResponse(stream, operation, cors) {
     if (operation.signal.aborted) {
         void cancelSetup('native stream setup cancelled');
         const payload = preStreamError(operation.signal.reason, operation);
-        return response({ error: payload }, errors.httpStatusOf(payload), cors);
+        return response({ error: payload }, errors.httpStatusOf(payload), cors());
     }
     const encoder = new TextEncoder();
     let pending = first;
@@ -482,7 +481,7 @@ async function streamResponse(stream, operation, cors) {
     operation.onCancel((reason) => stop(reason, interruptedStreamError(operation.timedOut)));
     return new Response(body, {
         headers: {
-            ...cors,
+            ...cors(),
             'content-type': routes.STREAM_MEDIA_TYPE,
             'cache-control': 'no-cache',
         },
@@ -529,9 +528,16 @@ function response(body, status, cors) {
         headers: { ...cors, 'content-type': 'application/json' },
     });
 }
+/** A Publication artifact refused while draining presents the lifecycle retry delay. */
+function drained(message, cors) {
+    const retry = retryAfterHeaders(admissionRefusal(false));
+    return response({ error: message }, 503, { ...cors(Object.keys(retry)), ...retry });
+}
+/** Every native error, including a capacity refusal raised by dispatch, presents its retry delay. */
 function nativeError(error, status, cors) {
     const admitted = routes.decodeErrorResponse({ error });
-    return response(admitted, status, cors);
+    const retry = retryAfterHeaders(error);
+    return response(admitted, status, { ...cors(Object.keys(retry)), ...retry });
 }
 function encodedBody(input) {
     return typeof input === 'string' ? input : toBody(input);

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

@@ -1,11 +1,12 @@
 import * as codecs from '@astrale-os/kernel-protocol/codecs';
 import * as errors from '@astrale-os/kernel-protocol/errors';
 import * as protocol from '@astrale-os/kernel-protocol/invocation';
-import { classifyError, RequestBodyInvalidError, RequestBodyTooLargeError, } from '../../errors/index.js';
+import { admissionRefusal, classifyError, RequestBodyInvalidError, RequestBodyTooLargeError, } from '../../errors/index.js';
 import { invocationContext, publicationRouteDecision, } from '../../invocation/index.js';
 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) {
-            return renderError(null, {
-                code: errors.CODES.BACKEND_UNAVAILABLE,
-                message: 'server is unavailable.',
-            }, codecs.json, { status: 503, negotiated: false });
+            if (binaryRequest && request.body !== null && !request.body.locked) {
+                void request.body.cancel('binary request rejected').catch(() => undefined);
+            }
+            return renderError(null, admissionRefusal(config.active.isAccepting), 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

@@ -1,7 +1,7 @@
 import * as errors from '@astrale-os/kernel-protocol/errors';
 import * as protocol from '@astrale-os/kernel-protocol/invocation';
 import { HTTP_ROUTE_MISS, HTTP_ROUTE_STALE } from '@astrale-os/kernel-protocol/routes/routing';
-import { classifyError } from '../../errors/index.js';
+import { classifyError, retryAfterHeaders } from '../../errors/index.js';
 import { ResponseBodyTooLargeError } from '../../errors/index.js';
 import { interruptedStreamError } from '../stream-error.js';
 export function renderHttpResult(result, context) {
@@ -57,8 +57,9 @@ export function renderRedirect(requestId, invocation, redirect) {
 }
 export function renderHttpError(requestId, invocation, error, codec, cors, options = {}) {
     const status = options.status ?? errors.httpStatusOf(error);
-    const extra = status === 401 ? { 'www-authenticate': 'Bearer realm="astrale-invocation"' } : {};
-    return errorEnvelopeResponse(codec, { error, requestId, invocation }, { ...cors(), ...extra }, status, options.negotiated ?? true, options.maximumResponseBytes);
+    const retry = retryAfterHeaders(error);
+    const extra = status === 401 ? { 'www-authenticate': 'Bearer realm="astrale-invocation"' } : retry;
+    return errorEnvelopeResponse(codec, { error, requestId, invocation }, { ...cors(Object.keys(retry)), ...extra }, status, options.negotiated ?? true, options.maximumResponseBytes);
 }
 export function renderHttpStale(requestId, invocation, current, codec, cors, maximumResponseBytes) {
     return envelopeResponse(codec, protocol.stale(requestId, invocation, current), cors(), 200, true, maximumResponseBytes);
@@ -82,6 +83,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 +105,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 +140,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 +164,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/transport/websocket/session.js

@@ -1,6 +1,6 @@
 import * as errors from '@astrale-os/kernel-protocol/errors';
 import * as protocol from '@astrale-os/kernel-protocol/invocation';
-import { classifyError } from '../../errors/index.js';
+import { admissionRefusal, classifyError } from '../../errors/index.js';
 import { ResponseBodyTooLargeError } from '../../errors/index.js';
 import { invocationContext, publicationRouteDecision, } from '../../invocation/index.js';
 import { byteLength } from '../body.js';
@@ -129,10 +129,7 @@ export function createWebSocketSession(config) {
             }
             const operation = config.active.begin(config.invocationTimeoutMs);
             if (operation === undefined) {
-                await sendError(socket, admittedCodec, envelope.requestId, assigned, {
-                    code: errors.CODES.BACKEND_UNAVAILABLE,
-                    message: 'server is unavailable.',
-                }, sendOutput);
+                await sendError(socket, admittedCodec, envelope.requestId, assigned, admissionRefusal(config.active.isAccepting), sendOutput);
                 return;
             }
             operations.set(key, operation);

package/dist/transport/websocket/upgrade.js

@@ -1,12 +1,15 @@
 import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import { admissionRefusal, retryAfterHeaders } from '../../errors/index.js';
 import { loadCodecs } from '../codecs.js';
 import { createWebSocketSession } from './session.js';
 export async function handleWebSocketUpgrade(config) {
     if (!config.cors.allowsBrowserOrigin(config.request))
         return failure(403);
     const operation = config.active.begin(config.invocationTimeoutMs, config.request.signal);
-    if (operation === undefined)
-        return failure(503, config.cors.response(config.request));
+    if (operation === undefined) {
+        const retry = retryAfterHeaders(admissionRefusal(config.active.isAccepting));
+        return failure(503, { ...config.cors.response(config.request, Object.keys(retry)), ...retry });
+    }
     try {
         const supported = await loadCodecs();
         const selection = protocol.websocket.selectSubprotocol(config.request.headers.get('sec-websocket-protocol'), supported);

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.62",
+  "version": "0.5.0-beta.64",
   "description": "Portable HTTP and WebSocket boundary for Astrale invocation, publication, installation, and issuer protocols",
   "license": "Apache-2.0",
   "repository": {
@@ -33,9 +33,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.54",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.39",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.60",
+    "@astrale-os/kernel-core": "0.9.0-beta.56",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.41",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.62",
     "hono": "^4.6.20",
     "msgpackr": "^2.0.5"
   },