@astrale-os/kernel-server 0.4.17 → 0.5.0-beta.10

package/dist/routes/routes.js

@@ -0,0 +1,448 @@
+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 { 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 { invocationContext } from '../invocation/index.js';
+import { handleDelivery } from '../publication/delivery/index.js';
+import { readPreparedPublicationSnapshot, } from '../publication/index.js';
+import { readBoundedBody } from '../transport/body.js';
+import {} from '../transport/router.js';
+import { interruptedStreamError } from '../transport/stream-error.js';
+export function mountRoutes(app, source, deliveryProvider, handler, active, nextInvocation, limits, cors, hostFor, reservations, externalIssuer) {
+    const publicationPath = externalIssuer === undefined
+        ? PUBLICATION_PATH
+        : new URL(publicationUrl(externalIssuer)).pathname;
+    const externalOrigin = externalIssuer === undefined ? undefined : new URL(externalIssuer).origin;
+    if (cors.enabled) {
+        app.options(publicationPath, (context) => cors.preflight(context.req.raw, {
+            methods: ['GET'],
+            headers: ['if-none-match'],
+        }));
+    }
+    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);
+        const snapshot = servingSnapshot(source, limits, context.req.raw, reservations, externalIssuer);
+        if (snapshot === undefined)
+            return response({ error: 'Publication is not ready.' }, 503, responseCors);
+        const body = snapshot.publicationBytes;
+        if (context.req.raw.headers.get('if-none-match') === quoteEtag(snapshot.publication.etag)) {
+            return new Response(null, {
+                status: 304,
+                headers: {
+                    ...responseCors,
+                    etag: quoteEtag(snapshot.publication.etag),
+                    'cache-control': 'public, max-age=0, must-revalidate, no-transform',
+                },
+            });
+        }
+        return new Response(toBody(body), {
+            status: 200,
+            headers: {
+                ...responseCors,
+                'content-type': 'application/json',
+                etag: quoteEtag(snapshot.publication.etag),
+                'cache-control': 'public, max-age=0, must-revalidate, no-transform',
+            },
+        });
+    });
+    app.all('*', async (context) => {
+        const snapshot = servingSnapshot(source, limits, context.req.raw, reservations, externalIssuer);
+        if (snapshot === undefined)
+            return context.notFound();
+        const request = context.req.raw;
+        if (request.method === 'OPTIONS' && cors.enabled) {
+            return publicationPreflight(cors, request, snapshot, externalOrigin);
+        }
+        const responseCors = cors.response(request);
+        if (sameRoute(request.url, snapshot.publication.schema.bundle.href, externalOrigin)) {
+            if (!active.isAccepting)
+                return response({ error: 'Publication artifact is unavailable while draining.' }, 503, responseCors);
+            if (request.method !== 'GET')
+                return response({ error: 'Bundle retrieval requires GET.' }, 405, responseCors);
+            const body = snapshot.bundle;
+            if (body.byteLength !== snapshot.publication.schema.bundle.ref.size) {
+                return response({ error: 'Bundle differs from its Publication.' }, 500, responseCors);
+            }
+            return new Response(toBody(body), {
+                status: 200,
+                headers: {
+                    ...responseCors,
+                    'content-type': snapshot.publication.schema.bundle.ref.mediaType,
+                    etag: quoteEtag(snapshot.publication.schema.bundle.ref.digest),
+                    'cache-control': 'public, max-age=31536000, immutable, no-transform',
+                },
+            });
+        }
+        const deliveryUrl = snapshot.publication.delivery?.href;
+        if (deliveryUrl !== undefined && sameRoute(request.url, deliveryUrl, externalOrigin)) {
+            return handleDelivery(request, snapshot, deliveryProvider, active, limits, cors.response(request));
+        }
+        let routing;
+        try {
+            const ifMatch = request.headers.get(routes.HTTP_ROUTE_PUBLICATION);
+            if (ifMatch !== null &&
+                /^"sha256:[0-9a-f]{64}"$/u.test(ifMatch) &&
+                ifMatch !== quoteEtag(snapshot.publication.etag)) {
+                return new Response(null, {
+                    status: routes.HTTP_ROUTE_STALE_STATUS,
+                    headers: {
+                        ...cors.response(request, [routes.HTTP_ROUTE_STALE]),
+                        ...routes.staleHeaders(snapshot.publication.etag),
+                    },
+                });
+            }
+            routing = routes.decodeRouting(request, publicationReference(snapshot.publication));
+        }
+        catch (cause) {
+            if (cause instanceof routes.RouteError) {
+                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Native route routing is invalid.' }, 400, responseCors);
+            }
+            throw cause;
+        }
+        const route = routes.match(snapshot.table, request);
+        if (route === undefined)
+            return context.notFound();
+        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);
+        let handedOff = false;
+        try {
+            const body = await readBoundedBody(request, limits.maximumRequestBytes, operation.signal);
+            const invocation = routes.decode(route, { url: request.url, method: request.method, headers: request.headers, body }, snapshot.domain, snapshot.table.publication);
+            const idempotencyHeader = request.headers.get(protocol.HTTP_IDEMPOTENCY_KEY);
+            const idempotencyKey = idempotencyHeader === null
+                ? undefined
+                : protocol.acceptIdempotencyKey(idempotencyHeader, protocol.HTTP_IDEMPOTENCY_KEY);
+            const result = await handler.dispatch(Object.freeze({
+                call: invocation.call,
+                ...(invocation.credential === undefined ? {} : { credential: invocation.credential }),
+                ...(routing === undefined ? {} : { via: routing }),
+                publication: snapshot.snapshot,
+                context: invocationContext(assigned, operation, active, hostFor(request), body, idempotencyKey),
+            }));
+            if (result.kind === 'value') {
+                return new Response(encodedBody(codecs.json.encode(result.value)), {
+                    headers: {
+                        ...responseCors,
+                        'content-type': 'application/json',
+                    },
+                });
+            }
+            if (result.kind === 'binary') {
+                const applicationHeaders = applicationBinaryHeaders(result.value.headers);
+                return new Response(toBody(result.value.body), {
+                    headers: {
+                        ...cors.response(request, [
+                            protocol.http.BINARY_HEADERS_FIELD,
+                            ...Object.keys(applicationHeaders),
+                        ]),
+                        ...applicationHeaders,
+                        'content-type': result.value.mediaType,
+                        [protocol.http.BINARY_HEADERS_FIELD]: protocol.http.encodeBinaryHeaderNames(applicationHeaders),
+                    },
+                });
+            }
+            if (result.kind === 'stream') {
+                handedOff = true;
+                return await streamResponse(result.stream, operation, responseCors);
+            }
+            if (result.kind === 'miss') {
+                return new Response(null, {
+                    status: routes.HTTP_ROUTE_MISS_STATUS,
+                    headers: {
+                        ...cors.response(request, [routes.HTTP_ROUTE_MISS]),
+                        ...routes.missHeaders(),
+                    },
+                });
+            }
+            return nativeError({
+                code: errors.CODES.UNSUPPORTED,
+                message: 'Native routes do not forward Runtime redirects.',
+            }, 502, responseCors);
+        }
+        catch (cause) {
+            if (cause instanceof RequestBodyTooLargeError) {
+                return nativeError({ code: errors.CODES.LIMIT_EXCEEDED, message: 'Request body is too large.' }, 413, responseCors);
+            }
+            if (cause instanceof RequestBodyInvalidError) {
+                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Request body is invalid.' }, 400, responseCors);
+            }
+            if (cause instanceof routes.RouteError) {
+                return nativeError({ code: errors.CODES.INVALID_REQUEST, message: 'Native route request is invalid.' }, 400, responseCors);
+            }
+            if (operation.timedOut) {
+                return nativeError({
+                    code: errors.CODES.DEADLINE_EXCEEDED,
+                    message: 'Invocation deadline exceeded.',
+                }, 504, responseCors);
+            }
+            if (operation.signal.aborted) {
+                return nativeError({ code: errors.CODES.CANCELLED, message: 'Invocation was cancelled.' }, 408, responseCors);
+            }
+            const payload = classifyError(cause);
+            return nativeError(payload, errors.httpStatusOf(payload), responseCors);
+        }
+        finally {
+            if (!handedOff)
+                operation.settle();
+        }
+    });
+}
+function publicationPreflight(cors, request, snapshot, externalOrigin) {
+    if (sameRoute(request.url, snapshot.publication.schema.bundle.href, externalOrigin)) {
+        return cors.preflight(request, { methods: ['GET'], headers: ['if-none-match'] });
+    }
+    const deliveryUrl = snapshot.publication.delivery?.href;
+    if (deliveryUrl !== undefined && sameRoute(request.url, deliveryUrl, externalOrigin)) {
+        return cors.preflight(request, {
+            methods: ['POST'],
+            headers: ['authorization', 'content-type'],
+        });
+    }
+    const requestedMethod = request.headers.get('access-control-request-method');
+    const route = requestedMethod === null
+        ? undefined
+        : routes.match(snapshot.table, { url: request.url, method: requestedMethod });
+    return cors.preflight(request, route === undefined ? undefined : nativeCorsRoute(route, requestedMethod));
+}
+function nativeCorsRoute(entry, requestedMethod) {
+    const headers = new Set([
+        'accept',
+        routes.HTTP_ROUTE_PUBLICATION,
+        routes.HTTP_ROUTE_ISSUER,
+        protocol.HTTP_IDEMPOTENCY_KEY,
+    ]);
+    if (entry.body !== undefined)
+        headers.add('content-type');
+    let allowAnyHeaders = false;
+    for (const pick of Object.values(entry.headers ?? {})) {
+        if (pick === '*')
+            allowAnyHeaders = true;
+        else
+            headers.add(pick.toLowerCase());
+    }
+    const credential = entry.credential;
+    const sources = credential === undefined
+        ? [{ in: 'header' }]
+        : Array.isArray(credential)
+            ? credential
+            : [credential];
+    for (const source of sources) {
+        if (source.in === 'header')
+            headers.add((source.name ?? 'authorization').toLowerCase());
+    }
+    return Object.freeze({
+        methods: Object.freeze([entry.method === '*' ? requestedMethod.toUpperCase() : entry.method]),
+        headers: Object.freeze([...headers]),
+        ...(allowAnyHeaders ? { allowAnyHeaders: true } : {}),
+    });
+}
+export function currentPublicationSnapshot(source, limits, serving) {
+    const snapshot = source.current();
+    if (snapshot === undefined)
+        return undefined;
+    const prepared = readPreparedPublicationSnapshot(snapshot);
+    if (prepared === undefined ||
+        prepared.publicationBytes.byteLength > limits.maximumPublicationBytes ||
+        prepared.bundle.byteLength > limits.maximumBundleBytes ||
+        (serving?.issuer !== undefined && prepared.publication.identity.issuer !== serving.issuer) ||
+        (serving !== undefined && conflictsWithServingRoutes(prepared, serving))) {
+        return undefined;
+    }
+    return prepared;
+}
+function servingSnapshot(source, limits, request, reservations, externalIssuer) {
+    return currentPublicationSnapshot(source, limits, {
+        origin: externalIssuer === undefined ? new URL(request.url).origin : new URL(externalIssuer).origin,
+        ...(externalIssuer === undefined ? {} : { issuer: externalIssuer }),
+        reservations,
+    });
+}
+function conflictsWithServingRoutes(snapshot, serving) {
+    for (const reservation of serving.reservations) {
+        const href = `${serving.origin}${reservation.path}`;
+        for (const entry of snapshot.table.entries) {
+            if (reservation.methods.some((method) => entry.method === '*' || entry.method === method) &&
+                routes.templatesOverlap(entry.href, href)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+async function streamResponse(stream, operation, cors) {
+    const iterator = stream[Symbol.asyncIterator]();
+    let rejectSetup;
+    const setupInterrupted = new Promise((_resolve, reject) => {
+        rejectSetup = reject;
+    });
+    let setupCleanup;
+    const cancelSetup = (reason) => {
+        rejectSetup(operation.signal.reason ?? new Error(reason));
+        setupCleanup ??= Promise.allSettled([
+            Promise.resolve().then(() => stream.cancel(reason)),
+            Promise.resolve().then(() => iterator.return?.()),
+        ]).then(() => operation.settle());
+        return setupCleanup;
+    };
+    const unregisterSetupCancellation = operation.onCancel(cancelSetup);
+    let first;
+    try {
+        first = await Promise.race([iterator.next(), setupInterrupted]);
+    }
+    catch (cause) {
+        unregisterSetupCancellation();
+        const cleanup = cancelSetup('native stream setup failed');
+        if (!operation.signal.aborted)
+            await cleanup;
+        const payload = preStreamError(cause, operation);
+        return nativeError(payload, errors.httpStatusOf(payload), cors);
+    }
+    unregisterSetupCancellation();
+    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);
+    }
+    const encoder = new TextEncoder();
+    let pending = first;
+    let terminal = false;
+    let controller;
+    let stopping;
+    const encoded = (frame) => encoder.encode(routes.encodeStreamFrame(frame));
+    const stop = (reason, error) => {
+        stopping ??= (async () => {
+            if (terminal)
+                return;
+            terminal = true;
+            if (controller !== undefined) {
+                if (error !== undefined) {
+                    try {
+                        controller.enqueue(encoded({ kind: 'error', error }));
+                    }
+                    catch {
+                        // The transport consumer may already have disconnected.
+                    }
+                }
+                try {
+                    controller.close();
+                }
+                catch {
+                    // A cancelled response body is already terminal.
+                }
+            }
+            try {
+                await Promise.allSettled([
+                    Promise.resolve().then(() => stream.cancel(reason)),
+                    Promise.resolve().then(() => iterator.return?.()),
+                ]);
+            }
+            finally {
+                operation.settle();
+            }
+        })();
+        return stopping;
+    };
+    const body = new ReadableStream({
+        start(output) {
+            controller = output;
+        },
+        async pull(output) {
+            if (terminal)
+                return;
+            try {
+                const next = pending ?? (await iterator.next());
+                pending = undefined;
+                if (terminal)
+                    return;
+                if (next.done) {
+                    terminal = true;
+                    output.enqueue(encoded({ kind: 'end' }));
+                    output.close();
+                    operation.settle();
+                }
+                else {
+                    output.enqueue(encoded({ kind: 'item', value: next.value }));
+                }
+            }
+            catch (cause) {
+                await stop('native stream failed', operation.signal.aborted
+                    ? interruptedStreamError(operation.timedOut)
+                    : classifyError(cause));
+            }
+        },
+        async cancel(reason) {
+            const message = typeof reason === 'string' ? reason : 'native response cancelled';
+            operation.cancel(message);
+            await stop(message);
+        },
+    });
+    operation.onCancel((reason) => stop(reason, interruptedStreamError(operation.timedOut)));
+    return new Response(body, {
+        headers: {
+            ...cors,
+            'content-type': routes.STREAM_MEDIA_TYPE,
+            'cache-control': 'no-cache',
+        },
+    });
+}
+function preStreamError(cause, operation) {
+    if (operation.timedOut) {
+        return {
+            code: errors.CODES.DEADLINE_EXCEEDED,
+            message: 'Invocation deadline exceeded before the native stream began.',
+        };
+    }
+    if (operation.signal.aborted) {
+        return {
+            code: errors.CODES.CANCELLED,
+            message: 'Invocation was cancelled before the native stream began.',
+        };
+    }
+    return classifyError(cause);
+}
+function sameRoute(left, right, externalOrigin) {
+    const a = new URL(left);
+    const b = new URL(right);
+    return ((externalOrigin ?? a.origin) === b.origin && a.pathname === b.pathname && a.search === b.search);
+}
+function applicationBinaryHeaders(input) {
+    const output = {};
+    for (const [name, value] of Object.entries(input ?? {})) {
+        if (name.toLowerCase() === routes.HTTP_ROUTE_STALE ||
+            name.toLowerCase() === routes.HTTP_ROUTE_MISS) {
+            throw new TypeError(`${name.toLowerCase()} is reserved for native routing control.`);
+        }
+        if (protocol.http.isApplicationBinaryHeader(name))
+            output[name] = value;
+    }
+    return output;
+}
+function quoteEtag(digest) {
+    return `"${digest}"`;
+}
+function response(body, status, cors) {
+    return new Response(encodedBody(codecs.json.encode(body)), {
+        status,
+        headers: { ...cors, 'content-type': 'application/json' },
+    });
+}
+function nativeError(error, status, cors) {
+    const admitted = routes.decodeErrorResponse({ error });
+    return response(admitted, status, cors);
+}
+function encodedBody(input) {
+    return typeof input === 'string' ? input : toBody(input);
+}
+function toBody(input) {
+    return input.buffer.slice(input.byteOffset, input.byteOffset + input.byteLength);
+}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import type { Server, ServerConfig, ServerOptions, PreparedServer } from './types.js';
+export declare function createServer(config: ServerConfig): Server;
+/** Validate all static transport configuration before a Host starts Runtime recovery/bootstrap. */
+export declare function prepareServer(options: ServerOptions): PreparedServer;