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

package/dist/publication/delivery/handler.js

@@ -0,0 +1,127 @@
+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 { 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) {
+    if (request.method !== 'POST') {
+        return response({ error: 'Delivery requires POST.' }, 405, cors);
+    }
+    if (provider === undefined) {
+        return response({ error: 'Delivery is unavailable.' }, 503, cors);
+    }
+    const advertised = snapshot.publication.delivery;
+    if (advertised === undefined) {
+        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);
+    try {
+        const authorization = request.headers.get('authorization');
+        const token = bearer(authorization);
+        if (advertised.authentication.kind === 'bearer' && token === undefined) {
+            return response({ error: 'Bearer authentication is required.' }, 401, cors);
+        }
+        if (advertised.authentication.kind === 'public' && authorization !== null) {
+            return response({ error: 'This delivery endpoint is public.' }, 400, cors);
+        }
+        let body;
+        try {
+            body = await readBoundedBody(request, limits.maximumDeliveryBytes, operation.signal);
+        }
+        catch (cause) {
+            if (cause instanceof RequestBodyTooLargeError) {
+                return response({ error: 'Delivery request is too large.' }, 413, cors);
+            }
+            if (cause instanceof RequestBodyInvalidError) {
+                return response({ error: 'Delivery request is invalid.' }, 400, cors);
+            }
+            if (operation.signal.aborted) {
+                return response({ error: 'Delivery request was cancelled.' }, 503, cors);
+            }
+            throw cause;
+        }
+        let decoded;
+        try {
+            decoded = codecs.json.decode(body);
+        }
+        catch (cause) {
+            if (cause instanceof codecs.DecodeError) {
+                return response({ error: 'Delivery request is invalid.' }, 400, cors);
+            }
+            throw cause;
+        }
+        let input;
+        try {
+            input = delivery.acceptRequest(decoded);
+        }
+        catch (cause) {
+            if (cause instanceof delivery.Error && cause.code === 'DELIVERY_REQUEST_INVALID') {
+                return response({ error: 'Delivery request is invalid.' }, 400, cors);
+            }
+            throw cause;
+        }
+        if (input.etag !== snapshot.publication.etag) {
+            return response({ error: 'Publication ETag differs from request.' }, 409, cors);
+        }
+        let candidate;
+        try {
+            candidate = await provider.create(input, {
+                ...(token === undefined ? {} : { token: Object.freeze({ kind: 'bearer', token }) }),
+                signal: operation.signal,
+            });
+        }
+        catch (cause) {
+            if (cause instanceof DeliveryUnavailableError) {
+                return response({ error: 'Delivery provider is unavailable.' }, 503, cors);
+            }
+            throw cause;
+        }
+        let created;
+        try {
+            created = delivery.accept(candidate);
+        }
+        catch (cause) {
+            if (cause instanceof delivery.Error) {
+                return response({ error: 'Delivery provider returned an invalid response.' }, 500, cors);
+            }
+            throw cause;
+        }
+        if (created.publication.etag !== snapshot.publication.etag) {
+            return response({ error: 'Delivery provider returned a different Publication.' }, 500, cors);
+        }
+        const encoded = codecs.json.encode(created);
+        if (encodedSize(encoded) > limits.maximumDeliveryBytes) {
+            return response({ error: 'Delivery response exceeds its serving limit.' }, 500, cors);
+        }
+        return new Response(encodedBody(encoded), {
+            headers: { ...cors, 'content-type': 'application/json' },
+        });
+    }
+    finally {
+        operation.settle();
+    }
+}
+function bearer(input) {
+    if (input === null)
+        return undefined;
+    return /^Bearer[ \t]+([^\s]+)$/iu.exec(input.trim())?.[1];
+}
+function response(body, status, cors) {
+    return new Response(encodedBody(codecs.json.encode(body)), {
+        status,
+        headers: { ...cors, 'content-type': 'application/json' },
+    });
+}
+function encodedBody(input) {
+    return typeof input === 'string' ? input : toBody(input);
+}
+function encodedSize(input) {
+    return typeof input === 'string' ? new TextEncoder().encode(input).byteLength : input.byteLength;
+}
+function toBody(input) {
+    return input.buffer.slice(input.byteOffset, input.byteOffset + input.byteLength);
+}

package/dist/publication/delivery/index.d.ts

@@ -0,0 +1,2 @@
+export { handleDelivery, type Limits } from './handler.js';
+export type { Context, Provider } from './types.js';

package/dist/publication/delivery/index.js

@@ -0,0 +1 @@
+export { handleDelivery } from './handler.js';

package/dist/publication/delivery/types.d.ts

@@ -0,0 +1,11 @@
+import type * as publication from '@astrale-os/kernel-protocol/publication';
+export interface Context {
+    /** Omitted for a public endpoint; otherwise the exact admitted retrieval credential. */
+    readonly token?: publication.delivery.Token;
+    readonly signal: AbortSignal;
+}
+/** Provider-owned retrieval, construction, and attestation signing. */
+export interface Provider {
+    /** Throw DeliveryUnavailableError only for an expected dependency outage. */
+    create(request: publication.delivery.Request, context: Context): Promise<publication.delivery.Delivery>;
+}

package/dist/publication/delivery/types.js

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

package/dist/publication/index.d.ts

@@ -0,0 +1,3 @@
+export { preparePublicationSnapshot, readPreparedPublicationSnapshot, type PreparedPublicationSnapshot, } from './snapshot.js';
+export type { PublicationSnapshot, PublicationSnapshotInput, PublicationSource } from './types.js';
+export * as delivery from './delivery/index.js';

package/dist/publication/index.js

@@ -0,0 +1,2 @@
+export { preparePublicationSnapshot, readPreparedPublicationSnapshot, } from './snapshot.js';
+export * as delivery from './delivery/index.js';

package/dist/publication/snapshot.d.ts

@@ -0,0 +1,16 @@
+import type { Domain } from '@astrale-os/kernel-dsl/v1';
+import type * as publication from '@astrale-os/kernel-protocol/publication';
+import type * as routes from '@astrale-os/kernel-protocol/routes';
+import type { PublicationSnapshot, PublicationSnapshotInput } from './types.js';
+export interface PreparedPublicationSnapshot {
+    readonly snapshot: PublicationSnapshot;
+    readonly publication: publication.Publication;
+    readonly publicationBytes: Uint8Array;
+    readonly bundle: Uint8Array;
+    readonly table: routes.Table;
+    readonly domain: Domain;
+}
+/** Admit and detach one revision-coherent serving snapshot before publication. */
+export declare function preparePublicationSnapshot(input: PublicationSnapshotInput): PublicationSnapshot;
+/** Internal proof that a PublicationSource returned a Server-prepared snapshot without cloning it. */
+export declare function readPreparedPublicationSnapshot(input: unknown): PreparedPublicationSnapshot | undefined;

package/dist/publication/snapshot.js

@@ -0,0 +1,37 @@
+import { verifyBundleBytes } from '@astrale-os/kernel-protocol/publication/bundle-evidence';
+import { accept as acceptPublication, encode as encodePublication, } from '@astrale-os/kernel-protocol/publication/publication';
+import { admitTable } from './table.js';
+const snapshots = new WeakMap();
+/** Admit and detach one revision-coherent serving snapshot before publication. */
+export function preparePublicationSnapshot(input) {
+    if (input === null || typeof input !== 'object' || !(input.bundle instanceof Uint8Array)) {
+        throw new TypeError('Publication snapshot input is invalid.');
+    }
+    const admittedPublication = acceptPublication(input.publication);
+    const bundleBytes = new Uint8Array(input.bundle);
+    verifyBundleBytes(admittedPublication, bundleBytes);
+    const domain = input.domain;
+    if (domain.origin !== admittedPublication.origin ||
+        domain.revision !== admittedPublication.schema.revision) {
+        throw new TypeError('Publication snapshot Domain identity differs from its Publication.');
+    }
+    const table = admitTable(admittedPublication, input.table, domain);
+    const publicationBytes = encodePublication(admittedPublication);
+    const snapshot = Object.freeze({ publication: admittedPublication });
+    const prepared = Object.freeze({
+        snapshot,
+        publication: admittedPublication,
+        publicationBytes,
+        bundle: bundleBytes,
+        table,
+        domain,
+    });
+    snapshots.set(snapshot, prepared);
+    return snapshot;
+}
+/** Internal proof that a PublicationSource returned a Server-prepared snapshot without cloning it. */
+export function readPreparedPublicationSnapshot(input) {
+    if (input === null || typeof input !== 'object')
+        return undefined;
+    return snapshots.get(input);
+}

package/dist/publication/table.d.ts

@@ -0,0 +1,4 @@
+import type { Domain } from '@astrale-os/kernel-dsl/v1';
+import type * as publication from '@astrale-os/kernel-protocol/publication';
+import type * as routes from '@astrale-os/kernel-protocol/routes';
+export declare function admitTable(deployed: publication.Publication, input: routes.Table | undefined, domain: Domain): routes.Table;

package/dist/publication/table.js

@@ -0,0 +1,16 @@
+import { reference } from '@astrale-os/kernel-protocol/publication/reference';
+import { acceptTable } from '@astrale-os/kernel-protocol/routes/admission';
+import { verifyTable } from '@astrale-os/kernel-protocol/routes/evidence';
+export function admitTable(deployed, input, domain) {
+    if (input === undefined) {
+        if (deployed.routes.length !== 0) {
+            throw new TypeError('A Publication with native routes requires a Route Table.');
+        }
+        return verifyTable(Object.freeze({
+            publication: reference(deployed),
+            entries: Object.freeze([]),
+        }), deployed, domain);
+    }
+    const table = acceptTable(input);
+    return verifyTable(table, deployed, domain);
+}

package/dist/publication/types.d.ts

@@ -0,0 +1,22 @@
+import type { Domain } from '@astrale-os/kernel-dsl/v1';
+import type * as publication from '@astrale-os/kernel-protocol/publication';
+import type * as routes from '@astrale-os/kernel-protocol/routes';
+declare const PUBLICATION_SNAPSHOT: unique symbol;
+export interface PublicationSnapshotInput {
+    readonly publication: publication.Publication;
+    /** Exact artifact served at Publication.schema.bundle.href. */
+    readonly bundle: Uint8Array;
+    readonly table?: routes.Table;
+    readonly domain: Domain;
+}
+/** Immutable admitted serving identity; bundle and compiled routes remain Server-private. */
+export interface PublicationSnapshot {
+    readonly publication: publication.Publication;
+    readonly [PUBLICATION_SNAPSHOT]: true;
+}
+/** Atomically readable source swapped only after a complete snapshot is prepared. */
+export interface PublicationSource {
+    /** Undefined until the first revision-coherent snapshot is ready. */
+    current(): PublicationSnapshot | undefined;
+}
+export {};

package/dist/publication/types.js

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

package/dist/routes/index.d.ts

@@ -0,0 +1 @@
+export { currentPublicationSnapshot, mountRoutes, type RouteLimits, type RouteReservation, } from './routes.js';

package/dist/routes/index.js

@@ -0,0 +1 @@
+export { currentPublicationSnapshot, mountRoutes, } from './routes.js';

package/dist/routes/routes.d.ts

@@ -0,0 +1,25 @@
+import type { CorsPolicy } from '../cors/index.js';
+import type { NextInvocationId } from '../invocation/index.js';
+import type { ActiveOperations } from '../lifecycle/index.js';
+import type { Provider as DeliveryProvider } from '../publication/delivery/index.js';
+import type { PublicationSource } from '../publication/index.js';
+import { type ApplicationHost, type Handler } from '../invocation/index.js';
+import { type PreparedPublicationSnapshot } from '../publication/index.js';
+import { type ServerRouter } from '../transport/router.js';
+export interface RouteLimits {
+    readonly maximumRequestBytes: number;
+    readonly maximumPublicationBytes: number;
+    readonly maximumBundleBytes: number;
+    readonly maximumDeliveryBytes: number;
+    readonly invocationTimeoutMs: number;
+}
+export interface RouteReservation {
+    readonly path: string;
+    readonly methods: readonly string[];
+}
+export declare function mountRoutes(app: ServerRouter, source: PublicationSource, deliveryProvider: DeliveryProvider | undefined, handler: Handler, active: ActiveOperations, nextInvocation: NextInvocationId, limits: RouteLimits, cors: CorsPolicy, hostFor: (request: Request) => ApplicationHost | undefined, reservations: readonly RouteReservation[], externalIssuer?: string): void;
+export declare function currentPublicationSnapshot(source: PublicationSource, limits: Pick<RouteLimits, 'maximumPublicationBytes' | 'maximumBundleBytes'>, serving?: {
+    readonly origin: string;
+    readonly issuer?: string;
+    readonly reservations: readonly RouteReservation[];
+}): PreparedPublicationSnapshot | undefined;