@astrale-os/kernel-server 0.5.0-beta.9 → 1.0.0-beta.2

package/dist/server.js

@@ -1,11 +1,13 @@
-import { PATH as PUBLICATION_PATH, url as publicationUrl, } from '@astrale-os/kernel-protocol/publication/publication';
+import { accept as acceptIssuer } from '@astrale-os/kernel-core/auth/issuer';
+import { Path } from '@astrale-os/kernel-core/path';
+import { PATH as RELEASE_PATH, url as releaseUrl } from '@astrale-os/kernel-protocol/release';
 import { captureMethod } from './capture.js';
 import { prepareCors } from './cors/index.js';
 import { captureInvocationSource } from './invocation/index.js';
 import { capture as captureExchangeProvider } from './issuer/exchange.js';
 import { admitIssuer, issuerRouteReservations, mountIssuer } from './issuer/index.js';
 import { ActiveOperations } from './lifecycle/index.js';
-import { currentPublicationSnapshot, mountRoutes } from './routes/index.js';
+import { currentServed, mountRoutes } from './routes/index.js';
 import { createHttpHandler } from './transport/http/handler.js';
 import { createServerRouter } from './transport/router.js';
 import { handleWebSocketUpgrade } from './transport/websocket/upgrade.js';
@@ -26,7 +28,23 @@ function createPreparedServer(input, config) {
     const app = createServerRouter();
     const hosts = new WeakMap();
     const externalIssuer = config.issuer?.issuer;
-    const externalOrigin = externalIssuer === undefined ? undefined : new URL(externalIssuer).origin;
+    const externalOrigin = config.publicOrigin ??
+        (externalIssuer === undefined ? undefined : new URL(externalIssuer).origin);
+    const source = config.serving;
+    const serving = source === undefined
+        ? undefined
+        : (request) => {
+            const origin = externalOrigin ?? new URL(request.url).origin;
+            return Object.freeze({
+                kind: source.kind,
+                current: () => currentServed(source, config.limits, {
+                    origin,
+                    ...(externalIssuer === undefined ? {} : { issuer: externalIssuer }),
+                    reservations: config.routeReservations,
+                }),
+                deployment: () => acceptIssuer(origin),
+            });
+        };
     const handleHttp = createHttpHandler({
         handler,
         active,
@@ -34,15 +52,7 @@ function createPreparedServer(input, config) {
         ...config.limits,
         cors: config.cors,
         websocket: config.websocket !== undefined,
-        ...(config.publication === undefined
-            ? {}
-            : {
-                currentPublication: (request) => currentPublicationSnapshot(config.publication, config.limits, {
-                    origin: externalOrigin ?? new URL(request.url).origin,
-                    ...(externalIssuer === undefined ? {} : { issuer: externalIssuer }),
-                    reservations: config.routeReservations,
-                })?.snapshot,
-            }),
+        ...(serving === undefined ? {} : { serving }),
     });
     if (config.websocket !== undefined) {
         app.get(config.path, (context) => handleWebSocketUpgrade({
@@ -53,22 +63,14 @@ function createPreparedServer(input, config) {
             invocation: config.invocation,
             ...config.limits,
             cors: config.cors,
-            ...(config.publication === undefined
-                ? {}
-                : {
-                    currentPublication: () => currentPublicationSnapshot(config.publication, config.limits, {
-                        origin: externalOrigin ?? new URL(context.req.raw.url).origin,
-                        ...(externalIssuer === undefined ? {} : { issuer: externalIssuer }),
-                        reservations: config.routeReservations,
-                    })?.snapshot,
-                }),
+            ...(serving === undefined ? {} : { serving: serving(context.req.raw) }),
             host: hosts.get(context.req.raw),
         }));
     }
     app.all(config.path, (context) => handleHttp(context.req.raw, hosts.get(context.req.raw)));
     if (config.health !== undefined) {
         app.get(config.health.path, (context) => {
-            const ready = active.isAccepting && config.health.probe.check();
+            const ready = active.isAvailable && config.health.probe.check();
             return context.json({ status: ready ? 'ready' : 'not-ready' }, ready ? 200 : 503, {
                 ...config.cors.response(context.req.raw),
                 'cache-control': 'no-store',
@@ -81,8 +83,8 @@ function createPreparedServer(input, config) {
     if (config.issuer !== undefined) {
         mountIssuer(app, config.issuer, config.cors, active, config.limits.invocationTimeoutMs, config.tokenExchange);
     }
-    if (config.publication !== undefined) {
-        mountRoutes(app, config.publication, config.delivery, handler, active, config.invocation, config.limits, config.cors, (request) => hosts.get(request), config.routeReservations, externalIssuer);
+    if (config.serving !== undefined) {
+        mountRoutes(app, config.serving, config.delivery, handler, active, config.invocation, config.limits, config.cors, (request) => hosts.get(request), config.routeReservations, externalIssuer, externalOrigin);
     }
     app.onError((_error, context) => new Response('{"error":"Internal server error."}', {
         status: 500,
@@ -131,6 +133,7 @@ function captureHandler(input) {
     return Object.freeze({ dispatch });
 }
 function admitOptions(config) {
+    const publicOrigin = config.publicOrigin === undefined ? undefined : admitPublicOrigin(config.publicOrigin);
     const invocation = captureInvocationSource(config.invocation);
     const limits = admitLimits(config.limits);
     const path = admitRoute(config.path ?? '/', 'invocation path');
@@ -146,23 +149,23 @@ function admitOptions(config) {
             probe: captureHealthProbe(config.health.probe),
         });
     const websocket = config.websocket === undefined ? undefined : captureWebSocket(config.websocket);
-    const publication = config.publication === undefined ? undefined : capturePublicationSource(config.publication);
+    const serving = config.release === undefined
+        ? undefined
+        : Object.freeze({ kind: 'release', source: captureReleaseSource(config.release) });
     const delivery = config.delivery === undefined ? undefined : captureDeliveryProvider(config.delivery);
-    if (delivery !== undefined && publication === undefined) {
-        throw new TypeError('Publication Delivery requires a Publication source.');
+    if (delivery !== undefined && serving === undefined) {
+        throw new TypeError('Delivery requires a release source.');
     }
-    const publicationPath = publication === undefined
-        ? undefined
-        : issuer === undefined
-            ? protocolPublicationPath()
-            : protocolPublicationPath(issuer.issuer);
+    const documentPaths = serving === undefined ? [] : servedDocumentPaths(serving.kind, issuer?.issuer);
     if (health?.path === path)
         throw new TypeError('Health and invocation paths must be distinct.');
-    if (publicationPath === path) {
-        throw new TypeError('Publication and invocation paths must be distinct.');
-    }
-    if (health !== undefined && publicationPath === health.path) {
-        throw new TypeError('Health and Publication paths must be distinct.');
+    for (const { name, path: documentPath } of documentPaths) {
+        if (documentPath === path) {
+            throw new TypeError(`${name} and invocation paths must be distinct.`);
+        }
+        if (health !== undefined && documentPath === health.path) {
+            throw new TypeError(`Health and ${name} paths must be distinct.`);
+        }
     }
     if (issuer !== undefined) {
         const issuerReservations = issuerRouteReservations(issuer, tokenExchange !== undefined);
@@ -180,19 +183,20 @@ function admitOptions(config) {
     }
     return Object.freeze({
         invocation,
+        ...(publicOrigin === undefined ? {} : { publicOrigin }),
         limits,
         path,
         cors: prepareCors(config.cors),
         ...(health === undefined ? {} : { health }),
         ...(issuer === undefined ? {} : { issuer }),
         ...(tokenExchange === undefined ? {} : { tokenExchange }),
-        ...(publication === undefined ? {} : { publication }),
+        ...(serving === undefined ? {} : { serving }),
         ...(delivery === undefined ? {} : { delivery }),
-        routeReservations: routeReservations(path, health?.path, issuer, websocket !== undefined, tokenExchange !== undefined, publicationPath),
+        routeReservations: routeReservations(path, health?.path, issuer, websocket !== undefined, tokenExchange !== undefined, documentPaths.map(({ path: documentPath }) => documentPath)),
         ...(websocket === undefined ? {} : { websocket }),
     });
 }
-function routeReservations(invocationPath, healthPath, issuer, websocket, tokenExchange, publicationPath) {
+function routeReservations(invocationPath, healthPath, issuer, websocket, tokenExchange, documentPaths) {
     const reservations = [
         Object.freeze({
             path: invocationPath,
@@ -205,15 +209,18 @@ function routeReservations(invocationPath, healthPath, issuer, websocket, tokenE
     if (issuer !== undefined) {
         reservations.push(...issuerRouteReservations(issuer, tokenExchange));
     }
-    if (publicationPath !== undefined) {
-        reservations.push(Object.freeze({ path: publicationPath, methods: Object.freeze(['GET']) }));
+    for (const documentPath of documentPaths) {
+        reservations.push(Object.freeze({ path: documentPath, methods: Object.freeze(['GET']) }));
     }
     return Object.freeze(reservations);
 }
-function protocolPublicationPath(issuer) {
-    if (issuer === undefined)
-        return PUBLICATION_PATH;
-    return new URL(publicationUrl(issuer)).pathname;
+function servedDocumentPaths(_kind, issuer) {
+    return [
+        {
+            name: 'Release',
+            path: issuer === undefined ? RELEASE_PATH : new URL(releaseUrl(issuer)).pathname,
+        },
+    ];
 }
 function captureHealthProbe(probe) {
     const check = captureMethod(probe, 'check', 'Health probe is invalid.');
@@ -223,12 +230,12 @@ function captureWebSocket(adapter) {
     const upgrade = captureMethod(adapter, 'upgrade', 'WebSocket adapter is invalid.');
     return Object.freeze({ upgrade });
 }
-function capturePublicationSource(input) {
-    const current = captureMethod(input, 'current', 'Publication source is invalid.');
+function captureReleaseSource(input) {
+    const current = captureMethod(input, 'current', 'Release source is invalid.');
     return Object.freeze({ current });
 }
 function captureDeliveryProvider(input) {
-    const create = captureMethod(input, 'create', 'Publication Delivery provider is invalid.');
+    const create = captureMethod(input, 'create', 'Delivery provider is invalid.');
     return Object.freeze({ create });
 }
 function admitLimits(limits) {
@@ -241,16 +248,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'),
+        maximumReleaseBytes: admitOptionalLimit(limits.maximumReleaseBytes, limits.maximumRequestBytes, 'maximumReleaseBytes'),
         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) {
@@ -264,4 +297,15 @@ function admitRoute(path, label) {
     }
     return path;
 }
-//# sourceMappingURL=server.js.map
+function admitPublicOrigin(input) {
+    const url = new URL(input);
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.pathname !== '/' ||
+        url.search !== '' ||
+        url.hash !== '') {
+        throw new TypeError('Server publicOrigin must be an HTTP(S) origin.');
+    }
+    return url.origin;
+}

package/dist/transport/body.d.ts

@@ -2,4 +2,3 @@ export { RequestBodyInvalidError, RequestBodyTooLargeError } from '../errors/ind
 /** Read a request body while enforcing the limit before retaining excess bytes. */
 export declare function readBoundedBody(request: Request, maximumBytes: number, signal: AbortSignal): Promise<Uint8Array>;
 export declare function byteLength(input: string | Uint8Array): number;
-//# sourceMappingURL=body.d.ts.map

package/dist/transport/body.js

@@ -48,4 +48,3 @@ export async function readBoundedBody(request, maximumBytes, signal) {
 export function byteLength(input) {
     return typeof input === 'string' ? new TextEncoder().encode(input).byteLength : input.byteLength;
 }
-//# sourceMappingURL=body.js.map

package/dist/transport/codecs.d.ts

@@ -1,5 +1,4 @@
 import * as codecs from '@astrale-os/kernel-protocol/codecs';
 export type LoadedCodec = codecs.Codec;
-/** Load the built-in Server representation set before pure Protocol binding selection. */
-export declare function loadCodecs(): Promise<readonly [codecs.Codec, codecs.Codec]>;
-//# sourceMappingURL=codecs.d.ts.map
+/** The built-in Server representation set before pure Protocol binding selection. */
+export declare function loadCodecs(): readonly [codecs.Codec];

package/dist/transport/codecs.js

@@ -1,6 +1,6 @@
 import * as codecs from '@astrale-os/kernel-protocol/codecs';
-/** Load the built-in Server representation set before pure Protocol binding selection. */
-export async function loadCodecs() {
-    return Object.freeze([codecs.json, await codecs.loadMsgpack()]);
+const SUPPORTED = Object.freeze([codecs.json]);
+/** The built-in Server representation set before pure Protocol binding selection. */
+export function loadCodecs() {
+    return SUPPORTED;
 }
-//# sourceMappingURL=codecs.js.map

package/dist/transport/credential.d.ts

@@ -8,4 +8,3 @@ export type CredentialResult = {
 };
 /** Resolve exactly zero or one untrusted credential channel without authenticating it. */
 export declare function resolveCredential(envelope: string | undefined, authorization: string | null): CredentialResult;
-//# sourceMappingURL=credential.d.ts.map

package/dist/transport/credential.js

@@ -26,4 +26,3 @@ function failure(message) {
         error: { code: errors.CODES.INVALID_REQUEST, message },
     };
 }
-//# sourceMappingURL=credential.js.map

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) {
+        throw new RequestBodyInvalidError('Binary request length is required and must be exact.');
+    }
+    const length = protocol.http.decodeBinaryLength(declared);
+    if (length === undefined) {
+        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/binary.d.ts

@@ -0,0 +1,6 @@
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import type { CorsHeaders } from './model.js';
+/** Present admitted buffered bytes under the response budget and binary manifest. */
+export declare function binaryHttpResponse(binary: protocol.BinaryResponse, cors: CorsHeaders, maximumResponseBytes: number): Response;
+/** Bind binary correlation and application headers to the HTTP response. */
+export declare function binaryHttpHeaders(binary: Pick<protocol.BinaryResponse, 'headers' | 'invocation' | 'mediaType' | 'requestId'>, cors: CorsHeaders, streaming: boolean): Headers;

package/dist/transport/http/binary.js

@@ -0,0 +1,35 @@
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import { appendVary, requireResponseBound, toBody } from './response.js';
+/** Present admitted buffered bytes under the response budget and binary manifest. */
+export function binaryHttpResponse(binary, cors, maximumResponseBytes) {
+    requireResponseBound(binary.body, maximumResponseBytes);
+    const headers = binaryHttpHeaders(binary, cors, false);
+    return new Response(toBody(binary.body), { status: binary.status, headers });
+}
+/** Bind binary correlation and application headers to the HTTP response. */
+export function binaryHttpHeaders(binary, cors, streaming) {
+    const applicationHeaders = Object.keys(binary.headers ?? {}).filter((name) => protocol.http.isApplicationBinaryHeader(name));
+    const headers = new Headers(cors([
+        protocol.http.REQUEST_ID_FIELD,
+        protocol.http.INVOCATION_FIELD,
+        protocol.http.BINARY_HEADERS_FIELD,
+        ...(streaming
+            ? [protocol.http.BINARY_DELIVERY_FIELD, protocol.http.BINARY_LENGTH_FIELD]
+            : []),
+        ...applicationHeaders,
+    ]));
+    for (const [name, value] of Object.entries(binary.headers ?? {})) {
+        if (protocol.http.isApplicationBinaryHeader(name))
+            headers.set(name, value);
+    }
+    headers.set('content-type', binary.mediaType);
+    headers.set(protocol.http.BINARY_HEADERS_FIELD, protocol.http.encodeBinaryHeaderNames(binary.headers));
+    headers.set(protocol.http.REQUEST_ID_FIELD, String(binary.requestId));
+    headers.set(protocol.http.INVOCATION_FIELD, protocol.http.encodeInvocationId(binary.invocation));
+    if (streaming) {
+        headers.set(protocol.http.BINARY_DELIVERY_FIELD, protocol.http.STREAMING_BINARY_DELIVERY);
+    }
+    headers.set('cache-control', 'no-store');
+    appendVary(headers, 'accept');
+    return headers;
+}

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

@@ -0,0 +1,4 @@
+import type { StreamingBinaryResult } from '@astrale-os/kernel-core/callable';
+import type { RenderContext } from './model.js';
+/** Deliver raw binary chunks with exact length, idle budget and producer cleanup. */
+export declare function streamingBinaryHttpResponse(binary: StreamingBinaryResult, context: RenderContext): Response;

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

@@ -0,0 +1,123 @@
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import { binaryHttpHeaders } from './binary.js';
+/** Deliver raw binary chunks with exact length, idle budget and producer cleanup. */
+export 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,
+        invocation: context.invocation,
+        mediaType: binary.mediaType,
+        headers: binary.headers,
+    }), context.cors, true);
+    if (binary.length !== undefined) {
+        headers.set('content-length', String(binary.length));
+        // Content-Length belongs to HTTP and an intermediary may rewrite it; the Client counts the
+        // delivered bytes against this protocol field instead.
+        headers.set(protocol.http.BINARY_LENGTH_FIELD, 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 {
+                await iterator.return?.();
+            }
+            finally {
+                context.active.settle();
+            }
+        });
+        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)
+                return;
+            try {
+                const next = await iterator.next();
+                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) {
+                fail(cause);
+            }
+        },
+        async cancel(reason) {
+            const message = typeof reason === 'string' ? reason : 'binary response consumer cancelled';
+            context.active.cancel(message);
+            await stop();
+        },
+    });
+    context.active.onCancel(stop);
+    return new Response(body, { status: binary.status ?? 200, headers });
+}

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

@@ -0,0 +1,12 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { Codec } from '@astrale-os/kernel-protocol/codecs';
+import type { ReleaseDigest } from '@astrale-os/kernel-protocol/release';
+import * as errors from '@astrale-os/kernel-protocol/errors';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import type { CorsHeaders, ErrorRenderOptions } from './model.js';
+/** Render a correlated error with its status, authentication challenge and retry delay. */
+export declare function renderHttpError(requestId: protocol.RequestId, invocation: protocol.InvocationId, error: errors.ErrorPayload, codec: Codec, cors: CorsHeaders, options?: ErrorRenderOptions): Response;
+/** Present stale routing as a bounded status-200 Invocation envelope. */
+export declare function renderHttpStale(requestId: protocol.RequestId, invocation: protocol.InvocationId, current: protocol.Stale['current'], codec: Codec, cors: CorsHeaders, maximumResponseBytes?: number): Response;
+/** Retirement controls always use JSON, regardless of the negotiated request codec. */
+export declare function renderDeploymentRetired(deployment: IssuerId, release: ReleaseDigest | undefined, cors: CorsHeaders): Response;

package/dist/transport/http/control.js

@@ -0,0 +1,24 @@
+import { json } 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 { deploymentRetiredBody, deploymentRetiredHeaders, HTTP_DEPLOYMENT_RETIRED, HTTP_DEPLOYMENT_RETIRED_STATUS, } from '@astrale-os/kernel-protocol/routes';
+import { retryAfterHeaders } from '../../errors/index.js';
+import { envelopeResponse, errorEnvelopeResponse, toBody } from './response.js';
+/** Render a correlated error with its status, authentication challenge and retry delay. */
+export function renderHttpError(requestId, invocation, error, codec, cors, options = {}) {
+    const status = options.status ?? errors.httpStatusOf(error);
+    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);
+}
+/** Present stale routing as a bounded status-200 Invocation envelope. */
+export function renderHttpStale(requestId, invocation, current, codec, cors, maximumResponseBytes) {
+    return envelopeResponse(codec, protocol.stale(requestId, invocation, current), cors(), 200, true, maximumResponseBytes);
+}
+/** Retirement controls always use JSON, regardless of the negotiated request codec. */
+export function renderDeploymentRetired(deployment, release, cors) {
+    return new Response(toBody(json.encode(deploymentRetiredBody(deployment, release))), {
+        status: HTTP_DEPLOYMENT_RETIRED_STATUS,
+        headers: { ...cors([HTTP_DEPLOYMENT_RETIRED]), ...deploymentRetiredHeaders() },
+    });
+}