@astrale-os/kernel-server 0.5.0-beta.8 → 0.5.0

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() },
+    });
+}

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

@@ -1,18 +1,23 @@
 import type { CorsPolicy } from '../../cors/index.js';
 import type { NextInvocationId } from '../../invocation/index.js';
 import type { ActiveOperations } from '../../lifecycle/index.js';
-import type { PublicationSnapshot } from '../../publication/index.js';
+import type { RequestServing } from '../../release/served.js';
 import { type ApplicationHost, type Handler } from '../../invocation/index.js';
 export interface HttpHandlerConfig {
     readonly handler: Handler;
     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;
+    /** Present exactly when the Server serves a Release. */
+    readonly serving?: (request: Request) => RequestServing;
 }
 export declare function createHttpHandler(config: HttpHandlerConfig): (request: Request, host?: ApplicationHost) => Promise<Response>;
-//# sourceMappingURL=handler.d.ts.map

package/dist/transport/http/handler.js

@@ -1,12 +1,16 @@
 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 { invocationContext, publicationRouteDecision, } from '../../invocation/index.js';
+import { admissionRefusal, classifyError, classifyRequestError, RequestBodyInvalidError, RequestBodyTooLargeError, } from '../../errors/index.js';
+import { admitVia, invocationContext, } from '../../invocation/index.js';
+import { pinned } from '../../release/served.js';
 import { readBoundedBody } from '../body.js';
 import { loadCodecs } from '../codecs.js';
 import { resolveCredential } from '../credential.js';
-import { renderHttpError, renderHttpResult } from './render.js';
+import { isStreamingBinary } from '../result.js';
+import { binaryRequestBody } from './binary-request.js';
+import { renderDeploymentRetired, renderHttpError } from './control.js';
+import { renderHttpResult } from './render.js';
 export function createHttpHandler(config) {
     return async (request, host) => {
         const cors = (exposedHeaders) => config.cors.response(request, exposedHeaders);
@@ -21,6 +25,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,24 +43,34 @@ 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 supported = loadCodecs();
             const contentType = request.headers.get('content-type');
-            const incoming = contentType === null || contentType.trim() === ''
+            // No default representation: a body without a declared Astrale type is never decoded, so a
+            // browser cannot send an admissible invocation from another origin without a CORS preflight.
+            const incoming = binaryRequest
                 ? codecs.json
                 : protocol.http.codecForContentType(contentType, supported);
             if (incoming === undefined) {
                 return renderError(null, {
                     code: errors.CODES.UNSUPPORTED,
-                    message: 'Unsupported request Content-Type.',
+                    message: contentType === null || contentType.trim() === ''
+                        ? 'Missing request Content-Type.'
+                        : 'Unsupported request Content-Type.',
                 }, codecs.json, { status: 415, negotiated: false });
             }
             const outgoing = protocol.http.negotiateResponseCodec(request.headers.get('accept'), incoming, supported);
@@ -66,7 +82,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,37 +111,54 @@ 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);
             }
-            const publication = config.currentPublication?.(request);
-            if (config.currentPublication !== undefined && publication === undefined) {
+            if (!binaryRequest &&
+                config.binaryDownloadTarget !== undefined &&
+                protocol.targetPath(envelope.call.target) === config.binaryDownloadTarget) {
+                active.extend(config.binaryDownloadTimeoutMs);
+            }
+            if (active.signal.aborted) {
+                return renderError(envelope.requestId, classifyRequestError(active.signal.reason, active), outgoing);
+            }
+            const serving = config.serving?.(request);
+            const served = serving?.current();
+            if (serving !== undefined && served === undefined) {
                 return renderError(envelope.requestId, {
                     code: errors.CODES.BACKEND_UNAVAILABLE,
-                    message: 'Publication is unavailable.',
+                    message: 'Release is unavailable.',
                 }, outgoing, { status: 503 });
             }
             if (envelope.routing?.kind === 'via') {
-                if (publication === undefined) {
-                    return renderError(envelope.requestId, {
-                        code: errors.CODES.INVALID_REQUEST,
-                        message: 'Publication routing requires a Publication-backed destination.',
-                    }, outgoing);
+                const decision = admitVia(served, envelope.routing);
+                if (decision.kind === 'retired') {
+                    return renderDeploymentRetired(serving.deployment(), decision.release, cors);
                 }
-                const decision = publicationRouteDecision(publication.publication, envelope.routing.publication);
                 if (decision.kind === 'rejected') {
                     return renderError(envelope.requestId, decision.error, outgoing);
                 }
@@ -135,9 +176,21 @@ export function createHttpHandler(config) {
                     ...(envelope.delegate === undefined ? {} : { delegate: envelope.delegate }),
                     ...(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),
+                    ...(envelope.maintenance === undefined ? {} : { maintenance: envelope.maintenance }),
+                    ...(served === undefined ? {} : pinned(served)),
+                    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,
@@ -146,20 +199,12 @@ export function createHttpHandler(config) {
                     active,
                     maximumResponseBytes: config.maximumResponseBytes,
                 });
-                handedOff = result.kind === 'stream';
+                handedOff =
+                    result.kind === 'stream' || (result.kind === 'binary' && isStreamingBinary(result.value));
                 return response;
             }
             catch (input) {
-                if (active.timedOut) {
-                    return renderError(envelope.requestId, {
-                        code: errors.CODES.DEADLINE_EXCEEDED,
-                        message: 'Invocation deadline exceeded.',
-                    }, outgoing, { status: 504 });
-                }
-                if (active.signal.aborted) {
-                    return renderError(envelope.requestId, { code: errors.CODES.CANCELLED, message: 'Invocation was cancelled.' }, outgoing, { status: 408 });
-                }
-                return renderError(envelope.requestId, classifyError(input), outgoing);
+                return renderError(envelope.requestId, classifyRequestError(input, active), outgoing);
             }
         }
         catch (input) {
@@ -168,6 +213,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();
         }
@@ -178,4 +232,3 @@ function noStore(response) {
     headers.set('cache-control', 'no-store');
     return new Response(response.body, { status: response.status, headers });
 }
-//# sourceMappingURL=handler.js.map

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

@@ -1,3 +1,4 @@
 export { createHttpHandler, type HttpHandlerConfig } from './handler.js';
-export { encodeEnvelope, renderBinary, renderHttpError, renderHttpResult, renderHttpStale, renderRedirect, type CorsHeaders, type ErrorRenderOptions, type RenderContext, } from './render.js';
-//# sourceMappingURL=index.d.ts.map
+export { renderHttpResult } from './render.js';
+export { renderHttpError, renderHttpStale } from './control.js';
+export type { CorsHeaders, ErrorRenderOptions, RenderContext } from './model.js';

package/dist/transport/http/index.js

@@ -1,3 +1,3 @@
 export { createHttpHandler } from './handler.js';
-export { encodeEnvelope, renderBinary, renderHttpError, renderHttpResult, renderHttpStale, renderRedirect, } from './render.js';
-//# sourceMappingURL=index.js.map
+export { renderHttpResult } from './render.js';
+export { renderHttpError, renderHttpStale } from './control.js';

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

@@ -0,0 +1,20 @@
+import type { Codec } from '@astrale-os/kernel-protocol/codecs';
+import type * as protocol from '@astrale-os/kernel-protocol/invocation';
+import type { ActiveOperation } from '../../lifecycle/index.js';
+/** Correlation, binding and active lifetime retained while presenting one result. */
+export interface RenderContext {
+    readonly requestId: protocol.RequestId;
+    readonly codec: Codec;
+    readonly cors: CorsHeaders;
+    readonly invocation: protocol.InvocationId;
+    readonly active: ActiveOperation;
+    readonly maximumResponseBytes: number;
+}
+/** Derive response headers with the transport fields exposed to the browser. */
+export type CorsHeaders = (exposedHeaders?: readonly string[]) => Readonly<Record<string, string>>;
+/** Bound and negotiate an error using the admitted request presentation. */
+export interface ErrorRenderOptions {
+    readonly status?: number;
+    readonly negotiated?: boolean;
+    readonly maximumResponseBytes?: number;
+}

package/dist/transport/http/model.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,32 +1,4 @@
-import type { Codec } 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 type { Handler } from '../../invocation/index.js';
-import type { ActiveOperation } from '../../lifecycle/index.js';
-export interface RenderContext {
-    readonly requestId: protocol.RequestId;
-    readonly codec: Codec;
-    readonly cors: CorsHeaders;
-    readonly invocation: protocol.InvocationId;
-    readonly active: ActiveOperation;
-    readonly maximumResponseBytes: number;
-}
-export type CorsHeaders = (exposedHeaders?: readonly string[]) => Readonly<Record<string, string>>;
-export interface ErrorRenderOptions {
-    readonly status?: number;
-    readonly negotiated?: boolean;
-    readonly maximumResponseBytes?: number;
-}
-type HandlerResult = Awaited<ReturnType<Handler['dispatch']>>;
+import type { HandlerResult } from '../../invocation/index.js';
+import type { RenderContext } from './model.js';
+/** Render one admitted Handler result and retain only live producers in the active operation. */
 export declare function renderHttpResult(result: HandlerResult, context: RenderContext): Response;
-export declare function renderBinary(requestId: protocol.RequestId, invocation: protocol.InvocationId, binary: Extract<HandlerResult, {
-    readonly kind: 'binary';
-}>['value']): protocol.BinaryResponse;
-export declare function renderRedirect(requestId: protocol.RequestId, invocation: protocol.InvocationId, redirect: Extract<HandlerResult, {
-    readonly kind: 'redirect';
-}>['redirect']): protocol.RedirectResponse;
-export declare function renderHttpError(requestId: protocol.RequestId, invocation: protocol.InvocationId, error: errors.ErrorPayload, codec: Codec, cors: CorsHeaders, options?: ErrorRenderOptions): Response;
-export declare function renderHttpStale(requestId: protocol.RequestId, invocation: protocol.InvocationId, current: protocol.Stale['current'], codec: Codec, cors: CorsHeaders, maximumResponseBytes?: number): Response;
-export declare function encodeEnvelope(codec: Codec, input: unknown): string | Uint8Array;
-export {};
-//# sourceMappingURL=render.d.ts.map