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

package/dist/invocation/admission.d.ts

@@ -0,0 +1,23 @@
+import { type IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import { NodePath } from '@astrale-os/kernel-core/path';
+import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { type Object as ValueObject } from '@astrale-os/kernel-dsl/value';
+import type { ErrorPayload } from '../errors/index.js';
+import type { Etag } from '../publication/index.js';
+import { type RequestId } from './correlation.js';
+import { type InvocationId } from './identity.js';
+export declare function portableObject(input: unknown, label: string): ValueObject;
+export declare function exactDataObject(input: unknown, label: string): Record<string, unknown>;
+export declare function exactFields(object: Record<string, unknown>, allowed: ReadonlySet<string>, label: string): void;
+export declare function required(object: Record<string, unknown>, fields: readonly string[], label: string): void;
+export declare function requestId(input: unknown, label: string): RequestId;
+export declare function invocation(input: unknown, label: string): InvocationId;
+export declare function nodePath(input: unknown, label: string): NodePath;
+export declare function issuerId(input: unknown, label: string): IssuerId;
+export declare function string(input: unknown, label: string): string;
+export declare function count(input: unknown, label: string): number;
+export declare function digest(input: unknown, label: string): Etag;
+export declare function callableKey(input: unknown, label: string): Key.Callable;
+export declare function errorPayload(input: unknown, label: string): ErrorPayload;
+export declare function acceptHeaders(input: unknown): Readonly<Record<string, string>>;
+export declare function invalid(message: string): never;

package/dist/invocation/admission.js

@@ -0,0 +1,177 @@
+import { AuthValueError } from '@astrale-os/kernel-core/auth/error';
+import { accept as acceptIssuer } from '@astrale-os/kernel-core/auth/issuer';
+import { NodePath, PathError } from '@astrale-os/kernel-core/path';
+import { callableAddress, Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { accept as acceptValue, BoundaryError, } from '@astrale-os/kernel-dsl/value';
+import { CODES, acceptPayload, ProtocolError } from '../errors/index.js';
+import { acceptRequestId } from './correlation.js';
+import { acceptInvocationId, InvocationError } from './identity.js';
+export function portableObject(input, label) {
+    let cloned;
+    try {
+        cloned = acceptValue(input);
+    }
+    catch (cause) {
+        if (cause instanceof BoundaryError) {
+            return invalid(`${label} must be a portable value object`);
+        }
+        throw cause;
+    }
+    if (!isValueObject(cloned))
+        invalid(`${label} must be an object`);
+    return cloned;
+}
+export function exactDataObject(input, label) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        invalid(`${label} must be an object`);
+    }
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null) {
+        invalid(`${label} must be a plain object`);
+    }
+    const output = {};
+    for (const key of Reflect.ownKeys(input)) {
+        if (typeof key !== 'string')
+            invalid(`${label} cannot contain symbol fields`);
+        const descriptor = Object.getOwnPropertyDescriptor(input, key);
+        if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor)) {
+            invalid(`${label}.${key} must be an enumerable data field`);
+        }
+        output[key] = descriptor.value;
+    }
+    return output;
+}
+export function exactFields(object, allowed, label) {
+    for (const key of Object.keys(object)) {
+        if (!allowed.has(key))
+            invalid(`${label} contains unexpected field ${JSON.stringify(key)}`);
+    }
+}
+export function required(object, fields, label) {
+    for (const field of fields) {
+        if (!Object.hasOwn(object, field))
+            invalid(`${label}.${field} is required`);
+    }
+}
+export function requestId(input, label) {
+    try {
+        return acceptRequestId(input, label);
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            return invalid(cause.message);
+        throw cause;
+    }
+}
+export function invocation(input, label) {
+    try {
+        return acceptInvocationId(input);
+    }
+    catch (cause) {
+        if (cause instanceof InvocationError)
+            return invalid(`${label} must be a valid Invocation`);
+        throw cause;
+    }
+}
+export function nodePath(input, label) {
+    if (typeof input !== 'string')
+        invalid(`${label} must be a NodePath string`);
+    try {
+        return NodePath(input);
+    }
+    catch (cause) {
+        if (cause instanceof PathError)
+            return invalid(`${label} must be a valid NodePath`);
+        throw cause;
+    }
+}
+export function issuerId(input, label) {
+    if (typeof input !== 'string')
+        invalid(`${label} must be an issuer identifier`);
+    try {
+        return acceptIssuer(input);
+    }
+    catch (cause) {
+        if (cause instanceof AuthValueError)
+            return invalid(`${label} must be a valid issuer identifier`);
+        throw cause;
+    }
+}
+export function string(input, label) {
+    if (typeof input !== 'string')
+        invalid(`${label} must be a string`);
+    return input;
+}
+export function count(input, label) {
+    if (!Number.isSafeInteger(input) || input < 0) {
+        invalid(`${label} must be a non-negative safe integer`);
+    }
+    return input;
+}
+export function digest(input, label) {
+    const value = string(input, label);
+    if (!/^sha256:[0-9a-f]{64}$/u.test(value))
+        invalid(`${label} must be a SHA-256 digest`);
+    return value;
+}
+export function callableKey(input, label) {
+    if (typeof input !== 'string')
+        invalid(`${label} must be a callable Key string`);
+    try {
+        const callable = Key(input);
+        callableAddress(callable);
+        return callable;
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            return invalid(`${label} must be a valid callable Key`);
+        throw cause;
+    }
+}
+export function errorPayload(input, label) {
+    try {
+        return acceptPayload(input, label);
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            return invalid(cause.message);
+        throw cause;
+    }
+}
+export function acceptHeaders(input) {
+    const object = exactDataObject(input, 'binary response.headers');
+    const headers = {};
+    for (const [name, rawValue] of Object.entries(object)) {
+        if (!HEADER_NAME.test(name)) {
+            invalid(`binary response header name ${JSON.stringify(name)} is invalid`);
+        }
+        const value = string(rawValue, `binary response.headers.${name}`);
+        if (hasControlCharacter(value)) {
+            invalid(`binary response header ${JSON.stringify(name)} contains a control character`);
+        }
+        const lower = name.toLowerCase();
+        if (Object.hasOwn(headers, lower)) {
+            invalid(`binary response header ${JSON.stringify(name)} occurs more than once`);
+        }
+        if (lower === 'content-length' || lower === 'transfer-encoding' || lower === 'connection') {
+            invalid(`binary response header ${JSON.stringify(name)} is transport-reserved`);
+        }
+        headers[lower] = value;
+    }
+    return Object.freeze(headers);
+}
+export function invalid(message) {
+    throw new ProtocolError({ code: CODES.INVALID_REQUEST, message });
+}
+function isValueObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+function hasControlCharacter(input) {
+    for (let index = 0; index < input.length; index += 1) {
+        const code = input.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}

package/dist/invocation/binary.d.ts

@@ -0,0 +1,11 @@
+import type { RequestId } from './correlation.js';
+import type { InvocationId } from './identity.js';
+export interface BinaryResponse {
+    readonly kind: 'binary';
+    readonly requestId: RequestId;
+    readonly invocation: InvocationId;
+    readonly body: Uint8Array;
+    readonly mediaType: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export declare function decodeBinaryResponse(input: unknown): BinaryResponse;

package/dist/invocation/binary.js

@@ -0,0 +1,24 @@
+import { acceptHeaders, exactDataObject, exactFields, invalid, invocation, requestId, required, string, } from './admission.js';
+const FIELDS = new Set(['kind', 'requestId', 'invocation', 'body', 'mediaType', 'headers']);
+const MEDIA_TYPE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+export function decodeBinaryResponse(input) {
+    const object = exactDataObject(input, 'binary response');
+    exactFields(object, FIELDS, 'binary response');
+    required(object, ['kind', 'requestId', 'invocation', 'body', 'mediaType'], 'binary response');
+    if (object.kind !== 'binary')
+        invalid('binary response.kind must be "binary"');
+    if (!(object.body instanceof Uint8Array))
+        invalid('binary response.body must be a Uint8Array');
+    const mediaType = string(object.mediaType, 'binary response.mediaType');
+    if (!MEDIA_TYPE.test(mediaType))
+        invalid('binary response.mediaType is invalid');
+    const headers = object.headers === undefined ? undefined : acceptHeaders(object.headers);
+    return Object.freeze({
+        kind: 'binary',
+        requestId: requestId(object.requestId, 'binary response.requestId'),
+        invocation: invocation(object.invocation, 'binary response.invocation'),
+        body: new Uint8Array(object.body),
+        mediaType,
+        ...(headers === undefined ? {} : { headers }),
+    });
+}

package/dist/invocation/binding-codecs.d.ts

@@ -0,0 +1,8 @@
+import type { Codec } from '../codecs/codec.js';
+export type CodecProfile = 'json' | 'msgpack';
+export interface SupportedCodec {
+    readonly codec: Codec;
+    readonly profile: CodecProfile;
+}
+export declare function codecProfile(codec: Codec): CodecProfile | undefined;
+export declare function admitSupportedCodecs(supported: readonly Codec[]): readonly SupportedCodec[];

package/dist/invocation/binding-codecs.js

@@ -0,0 +1,27 @@
+import { json } from '../codecs/json.js';
+import { isMsgpackCodec } from '../codecs/msgpack.js';
+export function codecProfile(codec) {
+    if (codec === json)
+        return 'json';
+    if (isMsgpackCodec(codec))
+        return 'msgpack';
+    return undefined;
+}
+export function admitSupportedCodecs(supported) {
+    if (!Array.isArray(supported))
+        throw new TypeError('supported codecs must be an array.');
+    const admitted = [];
+    const profiles = new Set();
+    for (const codec of supported) {
+        const profile = codecProfile(codec);
+        if (profile === undefined)
+            throw new TypeError('supported contains a foreign codec.');
+        if (profiles.has(profile))
+            throw new TypeError(`supported contains duplicate ${profile}.`);
+        profiles.add(profile);
+        admitted.push(Object.freeze({ codec, profile }));
+    }
+    if (!profiles.has('json'))
+        throw new TypeError('supported must contain the canonical JSON codec.');
+    return Object.freeze(admitted);
+}

package/dist/invocation/cancellation.d.ts

@@ -0,0 +1,8 @@
+import type { RequestId } from './correlation.js';
+import type { Version } from './version.js';
+export interface CancelRequest {
+    readonly version: Version;
+    readonly kind: 'cancel';
+    readonly requestId: RequestId;
+}
+export declare function decodeCancelRequest(input: unknown): CancelRequest;

package/dist/invocation/cancellation.js

@@ -0,0 +1,16 @@
+import { exactFields, invalid, portableObject, requestId, required } from './admission.js';
+const FIELDS = new Set(['version', 'kind', 'requestId']);
+export function decodeCancelRequest(input) {
+    const object = portableObject(input, 'cancel request');
+    exactFields(object, FIELDS, 'cancel request');
+    required(object, ['version', 'kind', 'requestId'], 'cancel request');
+    if (object.version !== 2)
+        invalid('cancel request.version must be 2');
+    if (object.kind !== 'cancel')
+        invalid('cancel request.kind must be "cancel"');
+    return Object.freeze({
+        version: 2,
+        kind: 'cancel',
+        requestId: requestId(object.requestId, 'cancel request.requestId'),
+    });
+}

package/dist/invocation/correlation.d.ts

@@ -0,0 +1,2 @@
+export type RequestId = string | number | null;
+export declare function acceptRequestId(input: unknown, label: string): RequestId;

package/dist/invocation/correlation.js

@@ -0,0 +1,7 @@
+export function acceptRequestId(input, label) {
+    if (input === null || typeof input === 'string')
+        return input;
+    if (typeof input === 'number' && Number.isFinite(input) && !Object.is(input, -0))
+        return input;
+    throw new TypeError(`${label} must be a string, finite number, or null`);
+}

package/dist/invocation/delegate.d.ts

@@ -0,0 +1,24 @@
+export declare namespace Delegate {
+    type Expr = {
+        readonly kind: 'identity';
+        readonly self: true;
+    } | {
+        readonly kind: 'identity';
+        readonly credential: string;
+    } | {
+        readonly kind: 'union';
+        readonly operands: readonly Expr[];
+    } | {
+        readonly kind: 'intersect';
+        readonly operands: readonly Expr[];
+    } | {
+        readonly kind: 'exclude';
+        readonly base: Expr;
+        readonly excluded: readonly Expr[];
+    };
+}
+export interface Delegate {
+    readonly ttlSeconds: number;
+    readonly attenuation?: Delegate.Expr;
+}
+export declare function acceptDelegate(input: unknown): Delegate;

package/dist/invocation/delegate.js

@@ -0,0 +1,43 @@
+import { AuthValueError, grant } from '@astrale-os/kernel-core/auth';
+import { exactDataObject, exactFields, invalid, required } from './admission.js';
+const FIELDS = new Set(['ttlSeconds', 'attenuation']);
+export function acceptDelegate(input) {
+    const object = exactDataObject(input, 'delegate');
+    exactFields(object, FIELDS, 'delegate');
+    required(object, ['ttlSeconds'], 'delegate');
+    if (!Number.isSafeInteger(object.ttlSeconds) || object.ttlSeconds < 1) {
+        invalid('delegate.ttlSeconds must be a positive safe integer');
+    }
+    let attenuation;
+    if (object.attenuation !== undefined) {
+        try {
+            attenuation = grant.acceptUnresolved({ v: 1, expr: object.attenuation }).expr;
+        }
+        catch (cause) {
+            if (cause instanceof AuthValueError)
+                invalid('delegate.attenuation must be a valid expression');
+            throw cause;
+        }
+        requireTextCredentials(attenuation);
+    }
+    return Object.freeze({
+        ttlSeconds: object.ttlSeconds,
+        ...(attenuation === undefined ? {} : { attenuation: attenuation }),
+    });
+}
+function requireTextCredentials(input) {
+    if (input.kind === 'identity') {
+        if ('credential' in input && typeof input.credential !== 'string') {
+            invalid('delegate.attenuation credentials must be non-empty text');
+        }
+        return;
+    }
+    if (input.kind === 'exclude') {
+        requireTextCredentials(input.base);
+        for (const operand of input.excluded)
+            requireTextCredentials(operand);
+        return;
+    }
+    for (const operand of input.operands)
+        requireTextCredentials(operand);
+}

package/dist/invocation/http/binary.d.ts

@@ -0,0 +1,12 @@
+import { type InvocationId } from '../identity.js';
+export declare const BINARY_HEADERS_FIELD: 'x-astrale-binary-headers';
+export declare const REQUEST_ID_FIELD: 'x-astrale-request-id';
+export declare const INVOCATION_FIELD: 'x-astrale-invocation';
+export declare const MAXIMUM_INVOCATION_FIELD_BYTES = 8192;
+/** Encode one admitted InvocationId as percent-encoded source plus opaque ID. */
+export declare function encodeInvocationId(input: InvocationId): string;
+/** Decode one complete finite-binary InvocationId field. */
+export declare function decodeInvocationId(input: string | null): InvocationId;
+export declare function isApplicationBinaryHeader(name: string): boolean;
+export declare function encodeBinaryHeaderNames(headers: Readonly<Record<string, string>> | undefined): string;
+export declare function decodeBinaryHeaderNames(input: string | null): readonly string[];

package/dist/invocation/http/binary.js

@@ -0,0 +1,132 @@
+import { CODES, ProtocolError } from '../../errors/index.js';
+import { acceptInvocationId } from '../identity.js';
+export const BINARY_HEADERS_FIELD = 'x-astrale-binary-headers';
+export const REQUEST_ID_FIELD = 'x-astrale-request-id';
+export const INVOCATION_FIELD = 'x-astrale-invocation';
+export const MAXIMUM_INVOCATION_FIELD_BYTES = 8_192;
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+const MAXIMUM_MANIFEST_BYTES = 8_192;
+const MAXIMUM_MANIFEST_NAMES = 128;
+const EMPTY_MANIFEST = '-';
+const RESERVED = new Set([
+    'authorization',
+    'cache-control',
+    'connection',
+    'content-encoding',
+    'content-length',
+    'content-type',
+    'cookie',
+    'date',
+    'etag',
+    'host',
+    'keep-alive',
+    'location',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'referrer-policy',
+    'server',
+    'set-cookie',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    'vary',
+    'www-authenticate',
+    EMPTY_MANIFEST,
+    BINARY_HEADERS_FIELD,
+    INVOCATION_FIELD,
+    REQUEST_ID_FIELD,
+    'x-astrale-stream-framing',
+]);
+/** Encode one admitted InvocationId as percent-encoded source plus opaque ID. */
+export function encodeInvocationId(input) {
+    let source;
+    try {
+        source = encodeURIComponent(input.source);
+    }
+    catch {
+        return invalid('HTTP binary InvocationId field is invalid.');
+    }
+    const encoded = `${source};${input.id}`;
+    if (new TextEncoder().encode(encoded).byteLength > MAXIMUM_INVOCATION_FIELD_BYTES) {
+        invalid('HTTP binary InvocationId field is invalid.');
+    }
+    return encoded;
+}
+/** Decode one complete finite-binary InvocationId field. */
+export function decodeInvocationId(input) {
+    if (input === null ||
+        input.length === 0 ||
+        new TextEncoder().encode(input).byteLength > MAXIMUM_INVOCATION_FIELD_BYTES) {
+        return invalid('HTTP binary InvocationId field is invalid.');
+    }
+    const separator = input.indexOf(';');
+    if (separator < 1 || input.indexOf(';', separator + 1) !== -1) {
+        invalid('HTTP binary InvocationId field is invalid.');
+    }
+    let source;
+    try {
+        source = decodeURIComponent(input.slice(0, separator));
+    }
+    catch {
+        return invalid('HTTP binary InvocationId field is invalid.');
+    }
+    try {
+        return acceptInvocationId({ source, id: input.slice(separator + 1) });
+    }
+    catch {
+        return invalid('HTTP binary InvocationId field is invalid.');
+    }
+}
+export function isApplicationBinaryHeader(name) {
+    const normalized = name.toLowerCase();
+    return (HEADER_NAME.test(normalized) &&
+        !normalized.startsWith('access-control-') &&
+        !normalized.startsWith('sec-websocket-') &&
+        !RESERVED.has(normalized));
+}
+export function encodeBinaryHeaderNames(headers) {
+    const names = [];
+    const seen = new Set();
+    for (const input of Object.keys(headers ?? {})) {
+        const name = input.toLowerCase();
+        if (!HEADER_NAME.test(name) || seen.has(name))
+            invalid();
+        seen.add(name);
+        if (!isApplicationBinaryHeader(name))
+            continue;
+        names.push(name);
+    }
+    if (names.length > MAXIMUM_MANIFEST_NAMES)
+        invalid();
+    const manifest = names.length === 0 ? EMPTY_MANIFEST : names.sort().join(', ');
+    if (new TextEncoder().encode(manifest).byteLength > MAXIMUM_MANIFEST_BYTES)
+        invalid();
+    return manifest;
+}
+export function decodeBinaryHeaderNames(input) {
+    if (input === EMPTY_MANIFEST)
+        return Object.freeze([]);
+    if (input === null || input === '')
+        invalid();
+    if (new TextEncoder().encode(input).byteLength > MAXIMUM_MANIFEST_BYTES)
+        invalid();
+    const names = input.split(',');
+    if (names.length > MAXIMUM_MANIFEST_NAMES)
+        invalid();
+    const admitted = [];
+    const seen = new Set();
+    for (const item of names) {
+        const name = item.trim().toLowerCase();
+        if (!isApplicationBinaryHeader(name) || seen.has(name))
+            invalid();
+        seen.add(name);
+        admitted.push(name);
+    }
+    return Object.freeze(admitted);
+}
+function invalid(message = 'HTTP binary application-header manifest is invalid.') {
+    throw new ProtocolError({
+        code: CODES.INVALID_REQUEST,
+        message,
+    });
+}

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

@@ -0,0 +1,4 @@
+export { BINARY_HEADERS_FIELD, decodeBinaryHeaderNames, decodeInvocationId, encodeBinaryHeaderNames, encodeInvocationId, isApplicationBinaryHeader, MAXIMUM_INVOCATION_FIELD_BYTES, INVOCATION_FIELD, REQUEST_ID_FIELD, } from './binary.js';
+export { codecForContentType, negotiateResponseCodec } from './negotiation.js';
+export { encodeStreamFrame, LENGTH_PREFIX_V1, STREAM_FRAMING_FIELD } from './stream.js';
+export { BAGGAGE_FIELD, decodeTraceHeaders, encodeTraceHeaders, TRACEPARENT_FIELD, TRACESTATE_FIELD, } from './trace.js';

package/dist/invocation/http/index.js

@@ -0,0 +1,4 @@
+export { BINARY_HEADERS_FIELD, decodeBinaryHeaderNames, decodeInvocationId, encodeBinaryHeaderNames, encodeInvocationId, isApplicationBinaryHeader, MAXIMUM_INVOCATION_FIELD_BYTES, INVOCATION_FIELD, REQUEST_ID_FIELD, } from './binary.js';
+export { codecForContentType, negotiateResponseCodec } from './negotiation.js';
+export { encodeStreamFrame, LENGTH_PREFIX_V1, STREAM_FRAMING_FIELD } from './stream.js';
+export { BAGGAGE_FIELD, decodeTraceHeaders, encodeTraceHeaders, TRACEPARENT_FIELD, TRACESTATE_FIELD, } from './trace.js';

package/dist/invocation/http/negotiation.d.ts

@@ -0,0 +1,3 @@
+import type { Codec } from '../../codecs/index.js';
+export declare function codecForContentType(contentType: string | null, supported: readonly Codec[]): Codec | undefined;
+export declare function negotiateResponseCodec(accept: string | null, requestCodec: Codec, supported: readonly Codec[]): Codec | undefined;