@astrale-os/kernel-protocol 0.5.0-beta.10

package/dist/routes/error-response.js

@@ -0,0 +1,31 @@
+import { BoundaryError, accept as acceptValue, } from '@astrale-os/kernel-dsl/value';
+import { acceptPayload } from '../errors/index.js';
+import { fail } from './error.js';
+export function decodeErrorResponse(input) {
+    let value;
+    try {
+        value = acceptValue(input);
+    }
+    catch (cause) {
+        if (cause instanceof BoundaryError)
+            return invalid(cause);
+        throw cause;
+    }
+    if (!isValueObject(value) || Object.keys(value).length !== 1 || !Object.hasOwn(value, 'error')) {
+        return invalid();
+    }
+    try {
+        return Object.freeze({ error: acceptPayload(value.error, 'native route error') });
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            return invalid(cause);
+        throw cause;
+    }
+}
+function isValueObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function invalid(cause) {
+    return fail('NATIVE_ROUTE_RESPONSE_INVALID', 'Native route error response is invalid.', cause);
+}

package/dist/routes/error.d.ts

@@ -0,0 +1,8 @@
+export type ErrorCode = 'NATIVE_ROUTE_DECLARATION_INVALID' | 'NATIVE_ROUTE_BINDING_INVALID' | 'NATIVE_ROUTE_MAPPING_INCOMPLETE' | 'NATIVE_ROUTE_MAPPING_AMBIGUOUS' | 'NATIVE_ROUTE_COLLISION' | 'NATIVE_ROUTE_RESERVED' | 'NATIVE_ROUTE_NOT_FOUND' | 'NATIVE_ROUTE_REQUEST_INVALID' | 'NATIVE_ROUTE_RESPONSE_INVALID' | 'NATIVE_ROUTE_ROUTING_INVALID';
+export declare class RouteError extends Error {
+    readonly code: ErrorCode;
+    readonly name = "RouteError";
+    constructor(code: ErrorCode, message: string, options?: ErrorOptions);
+}
+export declare function fail(code: ErrorCode, message: string, cause?: unknown): never;
+export declare function invalidRequest(message: string): never;

package/dist/routes/error.js

@@ -0,0 +1,14 @@
+export class RouteError extends Error {
+    code;
+    name = 'RouteError';
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+export function fail(code, message, cause) {
+    throw new RouteError(code, message, cause === undefined ? undefined : { cause });
+}
+export function invalidRequest(message) {
+    return fail('NATIVE_ROUTE_REQUEST_INVALID', message);
+}

package/dist/routes/evidence.d.ts

@@ -0,0 +1,5 @@
+import type { Domain } from '@astrale-os/kernel-dsl/v1';
+import type { Publication } from '../publication/publication.js';
+import type { Table } from './table.js';
+/** Verify that an admitted Table carries the exact published wire and Domain meaning. */
+export declare function verifyTable(table: Table, deployed: Publication, domain: Pick<Domain, 'origin' | 'revision' | 'callable'>): Table;

package/dist/routes/evidence.js

@@ -0,0 +1,38 @@
+import { json } from '@astrale-os/kernel-dsl/value';
+import { compareReferences, reference } from '../publication/reference.js';
+import { fail } from './error.js';
+/** Verify that an admitted Table carries the exact published wire and Domain meaning. */
+export function verifyTable(table, deployed, domain) {
+    if (compareReferences(table.publication, reference(deployed)) !== 'exact' ||
+        domain.origin !== deployed.origin ||
+        domain.revision !== deployed.schema.revision ||
+        json.serialize(table.entries.map(wireRoute)) !==
+            json.serialize(deployed.routes)) {
+        fail('NATIVE_ROUTE_BINDING_INVALID', 'Route Table evidence differs from its Publication.');
+    }
+    for (const entry of table.entries) {
+        const meaning = domain.callable(entry.callable);
+        const targetMatches = meaning !== undefined &&
+            ((entry.target.kind === 'function' && !isMethod(meaning)) ||
+                (entry.target.kind === 'method' &&
+                    isMethod(meaning) &&
+                    entry.target.dispatch === (meaning.static ? 'static' : 'instance')));
+        if (!targetMatches || meaning.auth !== entry.auth || meaning.output.mode !== entry.output) {
+            fail('NATIVE_ROUTE_BINDING_INVALID', `Route ${entry.name} differs from Domain meaning.`);
+        }
+    }
+    return table;
+}
+function isMethod(meaning) {
+    return 'owner' in meaning;
+}
+function wireRoute(entry) {
+    const { target, auth: _auth, output: _output, default: isDefault, ...wire } = entry;
+    return {
+        ...wire,
+        ...(isDefault ? { default: true } : {}),
+        ...(target.kind === 'method' && target.dispatch === 'instance'
+            ? { receiver: target.receiver }
+            : {}),
+    };
+}

package/dist/routes/index.d.ts

@@ -0,0 +1,19 @@
+export { bind } from './binding.js';
+export { acceptTable } from './admission.js';
+export { compile, type CompileInput } from './compiler.js';
+export { decode } from './decode.js';
+export { decodeErrorResponse, type ErrorResponse } from './error-response.js';
+export { encode } from './encode.js';
+export { verifyTable } from './evidence.js';
+export { type ErrorCode, RouteError } from './error.js';
+export { match } from './match.js';
+export { type HttpRequest, type Invocation, type Request } from './request.js';
+export type { Plan, PlanEntry } from './plan.js';
+export type { Route, Table } from './table.js';
+export type { RouteTarget } from './target.js';
+export { place } from './placement.js';
+export { decodeReleaseUnavailable, HTTP_ROUTE_RELEASE_UNAVAILABLE, HTTP_ROUTE_RELEASE_UNAVAILABLE_STATUS, releaseUnavailableHeaders, type ReleaseUnavailable, } from './release-unavailable.js';
+export { decodeRouting, decodeMiss, decodeStale, HTTP_ROUTE_PUBLICATION, HTTP_ROUTE_ISSUER, HTTP_ROUTE_MISS, HTTP_ROUTE_MISS_STATUS, HTTP_ROUTE_STALE, HTTP_ROUTE_STALE_STATUS, missHeaders, staleHeaders, type MissControl, type StaleControl, } from './routing.js';
+export { select } from './select.js';
+export { decodeStreamFrame, encodeStreamFrame, STREAM_MEDIA_TYPE, type StreamFrame, } from './stream.js';
+export { templatesOverlap } from './template.js';

package/dist/routes/index.js

@@ -0,0 +1,16 @@
+export { bind } from './binding.js';
+export { acceptTable } from './admission.js';
+export { compile } from './compiler.js';
+export { decode } from './decode.js';
+export { decodeErrorResponse } from './error-response.js';
+export { encode } from './encode.js';
+export { verifyTable } from './evidence.js';
+export { RouteError } from './error.js';
+export { match } from './match.js';
+export {} from './request.js';
+export { place } from './placement.js';
+export { decodeReleaseUnavailable, HTTP_ROUTE_RELEASE_UNAVAILABLE, HTTP_ROUTE_RELEASE_UNAVAILABLE_STATUS, releaseUnavailableHeaders, } from './release-unavailable.js';
+export { decodeRouting, decodeMiss, decodeStale, HTTP_ROUTE_PUBLICATION, HTTP_ROUTE_ISSUER, HTTP_ROUTE_MISS, HTTP_ROUTE_MISS_STATUS, HTTP_ROUTE_STALE, HTTP_ROUTE_STALE_STATUS, missHeaders, staleHeaders, } from './routing.js';
+export { select } from './select.js';
+export { decodeStreamFrame, encodeStreamFrame, STREAM_MEDIA_TYPE, } from './stream.js';
+export { templatesOverlap } from './template.js';

package/dist/routes/mapping.d.ts

@@ -0,0 +1,5 @@
+import type { HttpRoute } from '../publication/index.js';
+export declare function validateMapping(route: HttpRoute, fields: readonly string[] | undefined, instanceMethod: boolean): void;
+export declare function validateWireMapping(route: HttpRoute): void;
+export declare function validateCredentialMapping(route: HttpRoute): void;
+export declare function isReservedHeader(input: string): boolean;

package/dist/routes/mapping.js

@@ -0,0 +1,126 @@
+import { HTTP_IDEMPOTENCY_KEY } from '../invocation/index.js';
+import { credentialSources } from './credential.js';
+import { fail } from './error.js';
+import { HTTP_ROUTE_RELEASE_UNAVAILABLE } from './release-unavailable.js';
+import { HTTP_ROUTE_ISSUER, HTTP_ROUTE_MISS, HTTP_ROUTE_PUBLICATION, HTTP_ROUTE_STALE, } from './routing.js';
+import { PLACEHOLDER } from './template.js';
+export function validateMapping(route, fields, instanceMethod) {
+    if (fields === undefined) {
+        fail('NATIVE_ROUTE_DECLARATION_INVALID', `Route ${route.name} requires a closed object input schema.`);
+    }
+    if (route.receiver !== undefined && fields.includes(route.receiver)) {
+        fail('NATIVE_ROUTE_MAPPING_AMBIGUOUS', `Route ${route.name} receiver cannot also be a callable input field.`);
+    }
+    const claims = new Map();
+    const claim = (field) => claims.set(field, (claims.get(field) ?? 0) + 1);
+    for (const match of route.href.matchAll(PLACEHOLDER))
+        claim(match[1]);
+    if (route.requestMethod !== undefined)
+        claim(route.requestMethod);
+    for (const field of Object.keys(route.query ?? {}))
+        claim(field);
+    for (const field of Object.keys(route.headers ?? {}))
+        claim(field);
+    if (route.body === '*') {
+        for (const field of fields)
+            if (!claims.has(field))
+                claim(field);
+        if (route.receiver !== undefined && !claims.has(route.receiver))
+            claim(route.receiver);
+    }
+    else {
+        for (const field of Object.keys(route.body ?? {}))
+            claim(field);
+    }
+    for (const field of claims.keys()) {
+        if (!fields.includes(field) && field !== route.receiver) {
+            fail('NATIVE_ROUTE_DECLARATION_INVALID', `Route ${route.name} maps unknown input field ${field}.`);
+        }
+    }
+    for (const field of fields) {
+        const count = claims.get(field) ?? 0;
+        if (count === 0) {
+            fail('NATIVE_ROUTE_MAPPING_INCOMPLETE', `Route ${route.name} does not map input field ${field}.`);
+        }
+        if (count > 1) {
+            fail('NATIVE_ROUTE_MAPPING_AMBIGUOUS', `Route ${route.name} maps input field ${field} more than once.`);
+        }
+    }
+    if (instanceMethod) {
+        if (route.receiver === undefined || claims.get(route.receiver) !== 1) {
+            fail('NATIVE_ROUTE_MAPPING_INCOMPLETE', `Instance route ${route.name} must map one receiver source.`);
+        }
+        if (route.headers?.[route.receiver] === '*') {
+            fail('NATIVE_ROUTE_DECLARATION_INVALID', `Instance route ${route.name} receiver must use a scalar wire source.`);
+        }
+    }
+    else if (route.receiver !== undefined) {
+        fail('NATIVE_ROUTE_DECLARATION_INVALID', `Route ${route.name} cannot map a receiver for a Function or static Method.`);
+    }
+    const textPicks = route.body === '*' || route.body === undefined
+        ? []
+        : Object.values(route.body).filter((pick) => typeof pick !== 'string');
+    if (textPicks.length > 1 ||
+        (textPicks.length === 1 && Object.keys(route.body).length !== 1)) {
+        fail('NATIVE_ROUTE_MAPPING_AMBIGUOUS', 'Whole-text body mapping must be the only body pick.');
+    }
+}
+export function validateWireMapping(route) {
+    uniqueWires(route, 'query', Object.values(route.query ?? {}));
+    const headerPicks = Object.values(route.headers ?? {});
+    if (headerPicks.filter((wire) => wire === '*').length > 1) {
+        fail('NATIVE_ROUTE_MAPPING_AMBIGUOUS', `Route ${route.name} has more than one wildcard header remainder.`);
+    }
+    uniqueWires(route, 'header', headerPicks.filter((wire) => wire !== '*').map((wire) => wire.toLowerCase()));
+    const reserved = headerPicks.find((wire) => wire !== '*' && RESERVED_HEADERS.has(wire.toLowerCase()));
+    if (reserved !== undefined) {
+        fail('NATIVE_ROUTE_DECLARATION_INVALID', `Route ${route.name} maps the reserved ${reserved.toLowerCase()} header.`);
+    }
+    if (route.body !== undefined && route.body !== '*') {
+        uniqueWires(route, 'body', Object.values(route.body).flatMap((pick) => (typeof pick === 'string' ? [pick] : [])));
+    }
+}
+export function validateCredentialMapping(route) {
+    const queryWires = new Set(Object.values(route.query ?? {}));
+    const headerWires = new Set(Object.values(route.headers ?? {})
+        .filter((wire) => wire !== '*')
+        .map((wire) => wire.toLowerCase()));
+    const credentialWires = new Set();
+    for (const source of credentialSources(route)) {
+        const coordinate = source.in === 'header'
+            ? `header:${(source.name ?? 'authorization').toLowerCase()}`
+            : `${source.in}:${source.name}`;
+        if (credentialWires.has(coordinate)) {
+            fail('NATIVE_ROUTE_MAPPING_AMBIGUOUS', `Route ${route.name} declares one credential wire source more than once.`);
+        }
+        credentialWires.add(coordinate);
+        const credentialHeader = source.in === 'header' ? (source.name ?? 'authorization').toLowerCase() : undefined;
+        if (credentialHeader !== undefined && RESERVED_HEADERS.has(credentialHeader)) {
+            fail('NATIVE_ROUTE_DECLARATION_INVALID', `Route ${route.name} uses the reserved ${credentialHeader} header as a credential.`);
+        }
+        const collision = source.in === 'query'
+            ? queryWires.has(source.name)
+            : source.in === 'cookie'
+                ? headerWires.has('cookie')
+                : headerWires.has((source.name ?? 'authorization').toLowerCase());
+        if (collision) {
+            fail('NATIVE_ROUTE_MAPPING_AMBIGUOUS', `Route ${route.name} maps one wire source as both input and credential.`);
+        }
+    }
+}
+const RESERVED_HEADERS = new Set([
+    HTTP_IDEMPOTENCY_KEY,
+    HTTP_ROUTE_ISSUER,
+    HTTP_ROUTE_MISS,
+    HTTP_ROUTE_PUBLICATION,
+    HTTP_ROUTE_RELEASE_UNAVAILABLE,
+    HTTP_ROUTE_STALE,
+]);
+export function isReservedHeader(input) {
+    return RESERVED_HEADERS.has(input.toLowerCase());
+}
+function uniqueWires(route, kind, wires) {
+    if (new Set(wires).size !== wires.length) {
+        fail('NATIVE_ROUTE_MAPPING_AMBIGUOUS', `Route ${route.name} maps one ${kind} wire source more than once.`);
+    }
+}

package/dist/routes/match.d.ts

@@ -0,0 +1,4 @@
+import type { HttpRequest } from './request.js';
+import type { Route, Table } from './table.js';
+export declare function match(table: Table, request: Pick<HttpRequest, 'url' | 'method'>): Route | undefined;
+export declare function methodMatches(entry: Route, method: string): boolean;

package/dist/routes/match.js

@@ -0,0 +1,7 @@
+import { matchTemplate } from './template.js';
+export function match(table, request) {
+    return table.entries.find((entry) => methodMatches(entry, request.method) && matchTemplate(entry.href, request.url) !== undefined);
+}
+export function methodMatches(entry, method) {
+    return entry.method === '*' || entry.method === method.toUpperCase();
+}

package/dist/routes/placement.d.ts

@@ -0,0 +1,5 @@
+import type * as publication from '../publication/index.js';
+import type { Plan } from './plan.js';
+/** Resolve a provider-neutral Plan beneath one exact serving issuer. */
+export declare function place(plan: Plan, issuer: string): readonly publication.HttpRoute[];
+export declare function placePath(path: string, issuer: string): string;

package/dist/routes/placement.js

@@ -0,0 +1,18 @@
+/** Resolve a provider-neutral Plan beneath one exact serving issuer. */
+export function place(plan, issuer) {
+    return Object.freeze(plan.entries.map((entry) => {
+        const { path, target, auth: _auth, output: _output, default: isDefault, ...wire } = entry;
+        return Object.freeze({
+            ...wire,
+            href: placePath(path, issuer),
+            ...(isDefault ? { default: true } : {}),
+            ...(target.kind === 'method' && target.dispatch === 'instance'
+                ? { receiver: target.receiver }
+                : {}),
+        });
+    }));
+}
+export function placePath(path, issuer) {
+    const base = new URL(issuer);
+    return `${base.origin}${path}`;
+}

package/dist/routes/plan.d.ts

@@ -0,0 +1,24 @@
+import type { FunctionAuth, Key, Revision } from '@astrale-os/kernel-dsl/v1';
+import type { OutputMode } from '@astrale-os/kernel-dsl/v1/language';
+import type { CredentialSource, HttpMethod, RouteBody, RouteHeaders } from '../publication/index.js';
+import type { RouteTarget } from './target.js';
+export interface PlanEntry {
+    readonly name: string;
+    readonly callable: Key.Callable;
+    readonly target: RouteTarget;
+    readonly auth: FunctionAuth;
+    readonly output: OutputMode;
+    readonly path: string;
+    readonly method: HttpMethod;
+    readonly requestMethod?: string;
+    readonly default: boolean;
+    readonly query?: Readonly<Record<string, string>>;
+    readonly headers?: RouteHeaders;
+    readonly body?: RouteBody;
+    readonly credential?: CredentialSource;
+}
+export interface Plan {
+    readonly origin: Key.Origin;
+    readonly revision: Revision;
+    readonly entries: readonly PlanEntry[];
+}

package/dist/routes/plan.js

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

package/dist/routes/release-unavailable.d.ts

@@ -0,0 +1,8 @@
+import type { HttpRequest } from './request.js';
+export interface ReleaseUnavailable {
+    readonly kind: 'release-unavailable';
+}
+export declare const HTTP_ROUTE_RELEASE_UNAVAILABLE: 'x-astrale-release-unavailable';
+export declare const HTTP_ROUTE_RELEASE_UNAVAILABLE_STATUS: 410;
+export declare function releaseUnavailableHeaders(): Readonly<Record<string, string>>;
+export declare function decodeReleaseUnavailable(status: number, headers: HttpRequest['headers']): ReleaseUnavailable | undefined;

package/dist/routes/release-unavailable.js

@@ -0,0 +1,32 @@
+import { fail } from './error.js';
+export const HTTP_ROUTE_RELEASE_UNAVAILABLE = 'x-astrale-release-unavailable';
+export const HTTP_ROUTE_RELEASE_UNAVAILABLE_STATUS = 410;
+export function releaseUnavailableHeaders() {
+    return Object.freeze({
+        [HTTP_ROUTE_RELEASE_UNAVAILABLE]: '1',
+        'cache-control': 'no-store',
+    });
+}
+export function decodeReleaseUnavailable(status, headers) {
+    const encoded = header(headers, HTTP_ROUTE_RELEASE_UNAVAILABLE);
+    if (encoded === undefined)
+        return undefined;
+    if (status !== HTTP_ROUTE_RELEASE_UNAVAILABLE_STATUS || encoded !== '1') {
+        fail('NATIVE_ROUTE_ROUTING_INVALID', `${HTTP_ROUTE_RELEASE_UNAVAILABLE} is reserved for status ${HTTP_ROUTE_RELEASE_UNAVAILABLE_STATUS} with value 1.`);
+    }
+    return Object.freeze({ kind: 'release-unavailable' });
+}
+function header(input, name) {
+    if (input instanceof Headers)
+        return input.get(name) ?? undefined;
+    let found;
+    for (const [candidate, value] of Object.entries(input ?? {})) {
+        if (candidate.toLowerCase() !== name || value === undefined)
+            continue;
+        if (found !== undefined || (Array.isArray(value) && value.length !== 1)) {
+            fail('NATIVE_ROUTE_ROUTING_INVALID', `Header ${name} must occur at most once.`);
+        }
+        found = typeof value === 'string' ? value : value[0];
+    }
+    return found;
+}

package/dist/routes/request.d.ts

@@ -0,0 +1,26 @@
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type { Call, Via } from '../invocation/index.js';
+import type { HttpMethod } from '../publication/index.js';
+/** Canonical invocation values presented to or returned from a native route mapping. */
+export interface Invocation {
+    readonly call: Call;
+    readonly credential?: string;
+    readonly routing?: Via;
+    readonly method?: Exclude<HttpMethod, '*'>;
+}
+export interface Request {
+    readonly url: string;
+    readonly method: Exclude<HttpMethod, '*'>;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly credentials?: 'include';
+}
+export interface HttpRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly headers?: Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+    readonly body?: string | Uint8Array;
+}
+export declare function bodyText(body: HttpRequest['body']): string;
+export declare function parseJsonObject(body: HttpRequest['body']): Record<string, Value>;
+export declare function normalizeHeaders(input: HttpRequest['headers']): Record<string, string>;

package/dist/routes/request.js

@@ -0,0 +1,53 @@
+import { DecodeError, json } from '@astrale-os/kernel-dsl/value';
+import { fail, invalidRequest } from './error.js';
+export function bodyText(body) {
+    if (body === undefined)
+        return '';
+    try {
+        return typeof body === 'string'
+            ? body
+            : new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(body);
+    }
+    catch (cause) {
+        if (cause instanceof TypeError) {
+            return fail('NATIVE_ROUTE_REQUEST_INVALID', 'Native route body is not valid UTF-8.', cause);
+        }
+        throw cause;
+    }
+}
+export function parseJsonObject(body) {
+    let decoded;
+    try {
+        decoded = json.decode(bodyText(body));
+    }
+    catch (cause) {
+        if (cause instanceof DecodeError) {
+            return fail('NATIVE_ROUTE_REQUEST_INVALID', 'Native route body must be a JSON object.', cause);
+        }
+        throw cause;
+    }
+    if (decoded === null || typeof decoded !== 'object' || Array.isArray(decoded)) {
+        fail('NATIVE_ROUTE_REQUEST_INVALID', 'Native route body must be a JSON object.');
+    }
+    return decoded;
+}
+export function normalizeHeaders(input) {
+    const output = {};
+    if (input instanceof Headers) {
+        input.forEach((value, key) => {
+            output[key.toLowerCase()] = value;
+        });
+    }
+    else {
+        for (const [key, value] of Object.entries(input ?? {})) {
+            if (value === undefined)
+                continue;
+            const canonical = key.toLowerCase();
+            if (Object.hasOwn(output, canonical)) {
+                invalidRequest(`Header ${canonical} occurs more than once.`);
+            }
+            output[canonical] = typeof value === 'string' ? value : value.join(', ');
+        }
+    }
+    return output;
+}

package/dist/routes/reservation.d.ts

@@ -0,0 +1,3 @@
+import type { Publication } from '../publication/publication.js';
+import type { Route } from './table.js';
+export declare function rejectReserved(publication: Publication, entries: readonly Route[]): void;

package/dist/routes/reservation.js

@@ -0,0 +1,37 @@
+import * as issuer from '../issuer/index.js';
+import { PATH as PUBLICATION_PATH } from '../publication/publication.js';
+import { fail } from './error.js';
+import { templateUrl, templatesOverlap } from './template.js';
+const STATIC_RESERVED_PATHS = new Set([PUBLICATION_PATH]);
+export function rejectReserved(publication, entries) {
+    const discovery = issuer.paths(publication.identity.issuer);
+    const reservedPaths = new Set([...STATIC_RESERVED_PATHS, discovery.configuration, discovery.keys]);
+    const reservedUrls = [
+        publication.schema.bundle.href,
+        ...(publication.delivery === undefined ? [] : [publication.delivery.href]),
+        ...publication.bindings.callables.flatMap(({ endpoint }) => [
+            endpoint.http,
+            ...(endpoint.websocket === undefined ? [] : [httpUrlForWebSocket(endpoint.websocket)]),
+        ]),
+    ];
+    for (const entry of entries) {
+        const claimed = [...reservedPaths].some((path) => templateClaimsPath(entry.href, path)) ||
+            reservedUrls.some((reserved) => templatesOverlap(entry.href, routeLocation(reserved)));
+        if (claimed) {
+            fail('NATIVE_ROUTE_RESERVED', `Route ${entry.name} claims reserved URL ${templateUrl(entry.href).href}.`);
+        }
+    }
+}
+function httpUrlForWebSocket(input) {
+    const url = new URL(input);
+    url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:';
+    return url.toString();
+}
+function routeLocation(input) {
+    const url = new URL(input);
+    return `${url.origin}${url.pathname}`;
+}
+function templateClaimsPath(template, path) {
+    const url = templateUrl(template);
+    return templatesOverlap(template, `${url.origin}${path}`);
+}

package/dist/routes/routing.d.ts

@@ -0,0 +1,22 @@
+import type * as invocation from '../invocation/index.js';
+import type { Etag, PublicationRef } from '../publication/index.js';
+import type { HttpRequest } from './request.js';
+export interface StaleControl {
+    readonly kind: 'stale';
+    readonly current: Etag;
+}
+export interface MissControl {
+    readonly kind: 'miss';
+}
+export declare const HTTP_ROUTE_PUBLICATION: 'if-match';
+export declare const HTTP_ROUTE_ISSUER: 'x-astrale-issuer';
+export declare const HTTP_ROUTE_STALE: 'x-astrale-route-stale';
+export declare const HTTP_ROUTE_STALE_STATUS: 412;
+export declare const HTTP_ROUTE_MISS: 'x-astrale-route-miss';
+export declare const HTTP_ROUTE_MISS_STATUS: 421;
+export declare function decodeRouting(input: Pick<HttpRequest, 'headers'>, publication: PublicationRef): invocation.Via | undefined;
+export declare function staleHeaders(current: Etag): Readonly<Record<string, string>>;
+export declare function decodeStale(status: number, headers: HttpRequest['headers']): StaleControl | undefined;
+export declare function missHeaders(): Readonly<Record<string, string>>;
+export declare function decodeMiss(status: number, headers: HttpRequest['headers']): MissControl | undefined;
+export declare function encodeStrongEtag(input: Etag): string;

package/dist/routes/routing.js

@@ -0,0 +1,87 @@
+import * as auth from '@astrale-os/kernel-core/auth';
+import { fail } from './error.js';
+export const HTTP_ROUTE_PUBLICATION = 'if-match';
+export const HTTP_ROUTE_ISSUER = 'x-astrale-issuer';
+export const HTTP_ROUTE_STALE = 'x-astrale-route-stale';
+export const HTTP_ROUTE_STALE_STATUS = 412;
+export const HTTP_ROUTE_MISS = 'x-astrale-route-miss';
+export const HTTP_ROUTE_MISS_STATUS = 421;
+const STRONG_ETAG = /^"(sha256:[0-9a-f]{64})"$/u;
+export function decodeRouting(input, publication) {
+    const encodedEtag = routingHeader(input.headers, HTTP_ROUTE_PUBLICATION);
+    const encodedIssuer = routingHeader(input.headers, HTTP_ROUTE_ISSUER);
+    if (encodedEtag === undefined && encodedIssuer === undefined)
+        return undefined;
+    if (encodedEtag === undefined || encodedIssuer === undefined) {
+        fail('NATIVE_ROUTE_ROUTING_INVALID', `${HTTP_ROUTE_PUBLICATION} and ${HTTP_ROUTE_ISSUER} must occur together.`);
+    }
+    const etag = decodeStrongEtag(encodedEtag, 'If-Match');
+    if (etag !== publication.etag) {
+        fail('NATIVE_ROUTE_ROUTING_INVALID', 'If-Match does not name the compiled Publication.');
+    }
+    let issuer;
+    try {
+        issuer = auth.issuer.accept(encodedIssuer);
+    }
+    catch (cause) {
+        if (cause instanceof auth.AuthValueError) {
+            return fail('NATIVE_ROUTE_ROUTING_INVALID', `${HTTP_ROUTE_ISSUER} is invalid.`, cause);
+        }
+        throw cause;
+    }
+    return Object.freeze({ kind: 'via', publication, issuer });
+}
+export function staleHeaders(current) {
+    return Object.freeze({
+        [HTTP_ROUTE_STALE]: encodeStrongEtag(current),
+        'cache-control': 'no-store',
+    });
+}
+export function decodeStale(status, headers) {
+    const encoded = routingHeader(headers, HTTP_ROUTE_STALE);
+    if (encoded === undefined)
+        return undefined;
+    if (status !== HTTP_ROUTE_STALE_STATUS) {
+        fail('NATIVE_ROUTE_ROUTING_INVALID', `Header ${HTTP_ROUTE_STALE} is reserved for status ${HTTP_ROUTE_STALE_STATUS}.`);
+    }
+    return Object.freeze({
+        kind: 'stale',
+        current: decodeStrongEtag(encoded, HTTP_ROUTE_STALE),
+    });
+}
+export function missHeaders() {
+    return Object.freeze({ [HTTP_ROUTE_MISS]: '1', 'cache-control': 'no-store' });
+}
+export function decodeMiss(status, headers) {
+    const encoded = routingHeader(headers, HTTP_ROUTE_MISS);
+    if (encoded === undefined)
+        return undefined;
+    if (status !== HTTP_ROUTE_MISS_STATUS || encoded !== '1') {
+        fail('NATIVE_ROUTE_ROUTING_INVALID', `Header ${HTTP_ROUTE_MISS} is reserved for status ${HTTP_ROUTE_MISS_STATUS} with value 1.`);
+    }
+    return Object.freeze({ kind: 'miss' });
+}
+export function encodeStrongEtag(input) {
+    return `"${input}"`;
+}
+function decodeStrongEtag(input, label) {
+    const matched = STRONG_ETAG.exec(input);
+    if (matched === null) {
+        fail('NATIVE_ROUTE_ROUTING_INVALID', `${label} must contain exactly one strong quoted Publication ETag.`);
+    }
+    return matched[1];
+}
+function routingHeader(input, name) {
+    if (input instanceof Headers)
+        return input.get(name) ?? undefined;
+    let found;
+    for (const [candidate, value] of Object.entries(input ?? {})) {
+        if (candidate.toLowerCase() !== name || value === undefined)
+            continue;
+        if (found !== undefined || (Array.isArray(value) && value.length !== 1)) {
+            fail('NATIVE_ROUTE_ROUTING_INVALID', `Header ${name} must occur at most once.`);
+        }
+        found = typeof value === 'string' ? value : value[0];
+    }
+    return found;
+}

package/dist/routes/scalar.d.ts

@@ -0,0 +1,7 @@
+import type { Domain } from '@astrale-os/kernel-dsl/v1';
+import type * as portable from '@astrale-os/kernel-dsl/value';
+import type { Route } from './table.js';
+export declare function encodeScalar(entry: Route, name: string, value: unknown, domain: Domain): string;
+export declare function decodeScalar(entry: Route, name: string, encoded: string, domain: Domain): portable.Value;
+export declare function scalar(value: unknown): string;
+export declare function asObject(value: unknown): Record<string, portable.Value>;