@openlfcp/wire 0.1.0-rc.1

package/dist/message.d.ts

@@ -0,0 +1,367 @@
+import { type ControlRecordId, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CborValue } from "./cbor/index.js";
+import { type SequenceRange } from "./have.js";
+import { type PrincipalDescriptor } from "./principal.js";
+import { type ControlPutBody } from "./transition.js";
+/**
+ * The LFCP message codec (LFCP-WIRE-01 §31-§62): the §32 envelope, the §33
+ * registry and every body. Representation only: no sockets, no session
+ * state and no server logic.
+ *
+ * Decoding is strict, in this order:
+ *  1. the frame is binary (§31; a text frame is MALFORMED_MESSAGE and the
+ *     connection closes, G-MSG7) and no larger than the limit in force
+ *     (MESSAGE_TOO_LARGE, checked before any decoding);
+ *  2. one deterministic CBOR map (§5.2, §32) → MALFORMED_MESSAGE;
+ *  3. the envelope: keys 0, 1 and 4 present; 2 and 3 optional; any other
+ *     key from 0 to 15 is MALFORMED_MESSAGE; keys above 15 are ignored and
+ *     dropped (G-MSG2); 16-byte message and correlation IDs; flags are a
+ *     uint and otherwise ignored (G-MSG3);
+ *  4. the type is assigned in §33, or a negotiated extension (128+);
+ *     anything else is PROTOCOL_UNSUPPORTED (G-MSG1);
+ *  5. the body is the closed map its section defines → MALFORMED_MESSAGE.
+ *
+ * Persistent objects inside bodies (Genesis, Control Records, Data Units,
+ * Key Packages, Snapshots, the AUTH proof) stay the exact received byte
+ * strings: they are parsed lazily with parseControlRecord, parseDataUnit
+ * and the like, and are never re-encoded. Live actor-haves are decoded as
+ * received, except that a reversed range or one containing sequence 0 is
+ * refused (§48, G-HV1, checkLiveHave); normalizeLiveHaves merges them
+ * losslessly (have.ts).
+ */
+/** §33 message type codes. */
+export declare const MESSAGE_TYPE: Readonly<{
+    HELLO: 0n;
+    CHALLENGE: 1n;
+    AUTH: 2n;
+    READY: 3n;
+    ERROR: 4n;
+    PING: 5n;
+    PONG: 6n;
+    RESOURCE_HOST: 10n;
+    RESOURCE_HOSTED: 11n;
+    RESOURCE_OPEN: 12n;
+    RESOURCE_OPENED: 13n;
+    RESOURCE_CLOSE: 14n;
+    CONTROL_HAVE: 20n;
+    CONTROL_GET: 21n;
+    CONTROL_BATCH: 22n;
+    CONTROL_PUT: 23n;
+    DATA_HAVE: 30n;
+    DATA_GET: 31n;
+    DATA_BATCH: 32n;
+    DATA_PUT: 33n;
+    KEY_PACKAGE_GET: 40n;
+    KEY_PACKAGE_BATCH: 41n;
+    KEY_PACKAGE_PUT: 42n;
+    SNAPSHOT_GET: 50n;
+    SNAPSHOT: 51n;
+    SNAPSHOT_PUT: 52n;
+    PRESENCE: 60n;
+    PRESENCE_LEAVE: 61n;
+    ACK: 90n;
+    NACK: 91n;
+}>;
+export type CoreMessageType = keyof typeof MESSAGE_TYPE;
+/** Codes 128 and up are extension message types; they must be negotiated (§33). */
+export declare const FIRST_EXTENSION_MESSAGE_TYPE = 128n;
+/** §62 error codes. */
+export declare const ERROR_CODE: Readonly<{
+    PROTOCOL_UNSUPPORTED: 1n;
+    MALFORMED_MESSAGE: 2n;
+    AUTH_FAILED: 3n;
+    AUTHORIZATION_FAILED: 4n;
+    RESOURCE_NOT_FOUND: 5n;
+    RESOURCE_NOT_HOSTED: 6n;
+    INVALID_SIGNATURE: 7n;
+    INVALID_CONTROL_CHAIN: 8n;
+    CONTROL_CONFLICT: 9n;
+    CONTROL_HEAD_MISMATCH: 10n;
+    NOT_CONTROL_COORDINATOR: 11n;
+    PROFILE_UNSUPPORTED: 12n;
+    KEY_PACKAGE_UNAVAILABLE: 13n;
+    STALE_DATA_EPOCH: 14n;
+    MISSING_DEPENDENCY: 15n;
+    ACTOR_EQUIVOCATION: 16n;
+    RATE_LIMITED: 17n;
+    QUOTA_EXCEEDED: 18n;
+    MESSAGE_TOO_LARGE: 19n;
+    HOSTING_DENIED: 20n;
+    RESOURCE_TOMBSTONED: 21n;
+    INTERNAL_ERROR: 22n;
+}>;
+export type WireErrorName = keyof typeof ERROR_CODE;
+/** §31: the default maximum LFCP message size, unless READY advertises another. */
+export declare const DEFAULT_MAX_MESSAGE_BYTES: number;
+/** A §41 `control-head`. */
+export interface ControlHeadRef {
+    readonly seq: bigint;
+    readonly recordId: ControlRecordId;
+}
+/**
+ * A live `actor-have` as received (§48): ranges may be unsorted,
+ * overlapping or adjacent (never reversed or containing 0, G-HV1);
+ * normalizeLiveHaves merges them. `ranges` is undefined when the CBOR
+ * omits key 2.
+ */
+export interface LiveActorHave {
+    readonly principalId: PrincipalId;
+    readonly contiguous: bigint;
+    readonly ranges?: readonly SequenceRange[];
+}
+export interface HelloBody {
+    readonly wireProfiles: readonly string[];
+    readonly principal: PrincipalDescriptor;
+    readonly clientNonce: Uint8Array;
+    readonly dataProfiles?: readonly string[];
+}
+export interface ChallengeBody {
+    readonly wireProfile: string;
+    readonly serverNonce: Uint8Array;
+    readonly sessionId: Uint8Array;
+    readonly serverId: Uint8Array;
+}
+export interface AuthBody {
+    /** The exact COSE_Sign1 auth proof bytes (§36), verified by LFCP-027. */
+    readonly proof: Uint8Array;
+    /** An opaque hosting/account credential: server policy, never Resource authority. */
+    readonly credential?: Uint8Array;
+}
+export interface ReadyBody {
+    readonly wireProfile: string;
+    readonly serverId: Uint8Array;
+    readonly maxMessageBytes: bigint;
+    readonly durability: bigint;
+    readonly heartbeatMs: bigint;
+    readonly extensions?: readonly string[];
+}
+/** ERROR (§61) and NACK (§60). Diagnostics never carry secrets. */
+export interface ErrorBody {
+    readonly code: bigint;
+    readonly diagnostic?: string;
+    readonly details?: CborValue;
+}
+export interface PingBody {
+    readonly payload: Uint8Array;
+}
+export interface ResourceHostBody {
+    /** The exact Genesis COSE bytes. */
+    readonly genesis: Uint8Array;
+    readonly credential?: Uint8Array;
+}
+export interface ResourceHostedBody {
+    readonly resourceId: ResourceId;
+    readonly durability: bigint;
+}
+export interface ResourceOpenBody {
+    readonly resourceId: ResourceId;
+    readonly heads: readonly ControlHeadRef[];
+    readonly haves: readonly LiveActorHave[];
+    readonly grantIds?: readonly Hash32[];
+    readonly flags?: bigint;
+}
+export interface SnapshotSummary {
+    readonly snapshotId: Hash32;
+    readonly dataEpoch: bigint;
+    readonly frontier: readonly LiveActorHave[];
+}
+export interface ResourceOpenedBody {
+    readonly resourceId: ResourceId;
+    readonly heads: readonly ControlHeadRef[];
+    readonly haves: readonly LiveActorHave[];
+    readonly snapshot?: SnapshotSummary;
+    readonly routeVersion?: bigint;
+    readonly coordinatorUrl?: string;
+}
+export interface ResourceBody {
+    readonly resourceId: ResourceId;
+}
+export interface ControlHaveBody {
+    readonly resourceId: ResourceId;
+    readonly heads: readonly ControlHeadRef[];
+}
+export interface ControlGetBody {
+    readonly resourceId: ResourceId;
+    readonly start: bigint;
+    readonly end: bigint;
+}
+/** CONTROL_BATCH, DATA_BATCH/PUT, KEY_PACKAGE_BATCH/PUT: exact signed object bytes. */
+export interface ObjectListBody {
+    readonly resourceId: ResourceId;
+    readonly objects: readonly Uint8Array[];
+}
+export interface DataHaveBody {
+    readonly resourceId: ResourceId;
+    readonly haves: readonly LiveActorHave[];
+}
+export interface DataRange {
+    readonly actor: PrincipalId;
+    readonly start: bigint;
+    readonly end: bigint;
+}
+export interface DataGetBody {
+    readonly resourceId: ResourceId;
+    readonly ranges: readonly DataRange[];
+}
+export interface KeyPackageGetBody {
+    readonly resourceId: ResourceId;
+    readonly recipient: PrincipalId;
+    readonly epochs: readonly bigint[];
+}
+export interface SnapshotGetBody {
+    readonly resourceId: ResourceId;
+    readonly snapshotId?: Hash32;
+}
+/** SNAPSHOT and SNAPSHOT_PUT: the exact signed Snapshot bytes. */
+export interface SnapshotBody {
+    readonly resourceId: ResourceId;
+    readonly snapshot: Uint8Array;
+}
+export interface PresenceBody {
+    readonly resourceId: ResourceId;
+    readonly principalId: PrincipalId;
+    readonly ttlMs: bigint;
+    readonly payload: Uint8Array;
+}
+export interface PresenceLeaveBody {
+    readonly resourceId: ResourceId;
+    readonly principalId: PrincipalId;
+}
+export interface AckBody {
+    /** The §33 type code of the acknowledged request (A1), e.g. 33 for DATA_PUT. */
+    readonly requestType: bigint;
+    readonly objectIds?: readonly Hash32[];
+    /** Durable under the advertised server policy; never stronger than READY's level (§37). */
+    readonly durable?: boolean;
+}
+/** The body of each §33 message type. */
+export interface MessageBodies {
+    HELLO: HelloBody;
+    CHALLENGE: ChallengeBody;
+    AUTH: AuthBody;
+    READY: ReadyBody;
+    ERROR: ErrorBody;
+    PING: PingBody;
+    PONG: PingBody;
+    RESOURCE_HOST: ResourceHostBody;
+    RESOURCE_HOSTED: ResourceHostedBody;
+    RESOURCE_OPEN: ResourceOpenBody;
+    RESOURCE_OPENED: ResourceOpenedBody;
+    RESOURCE_CLOSE: ResourceBody;
+    CONTROL_HAVE: ControlHaveBody;
+    CONTROL_GET: ControlGetBody;
+    CONTROL_BATCH: ObjectListBody;
+    CONTROL_PUT: ControlPutBody;
+    DATA_HAVE: DataHaveBody;
+    DATA_GET: DataGetBody;
+    DATA_BATCH: ObjectListBody;
+    DATA_PUT: ObjectListBody;
+    KEY_PACKAGE_GET: KeyPackageGetBody;
+    KEY_PACKAGE_BATCH: ObjectListBody;
+    KEY_PACKAGE_PUT: ObjectListBody;
+    SNAPSHOT_GET: SnapshotGetBody;
+    SNAPSHOT: SnapshotBody;
+    SNAPSHOT_PUT: SnapshotBody;
+    PRESENCE: PresenceBody;
+    PRESENCE_LEAVE: PresenceLeaveBody;
+    ACK: AckBody;
+    NACK: ErrorBody;
+}
+interface Envelope {
+    /** 16 random bytes: transport correlation only, not a security identifier (§32). */
+    readonly messageId: Uint8Array;
+    readonly correlationId?: Uint8Array;
+    /** The flags as received; a receiver ignores them and a sender omits them (G-MSG3). */
+    readonly flags?: bigint;
+}
+/** A typed LFCP message. */
+export type LfcpMessage<T extends CoreMessageType = CoreMessageType> = {
+    [K in T]: Envelope & {
+        readonly type: K;
+        readonly body: MessageBodies[K];
+    };
+}[T];
+/** A negotiated extension message (128+): the body is opaque to this codec. */
+export type ExtensionMessage = Envelope & {
+    readonly type: "EXTENSION";
+    readonly code: bigint;
+    readonly body: CborValue;
+};
+export type AnyMessage = LfcpMessage | ExtensionMessage;
+export interface DecodeOptions {
+    /** The maximum message size in force (§31): READY's advertised value, or the default 8 MiB. */
+    readonly maxMessageBytes?: number;
+    /** Extension message types (128+) negotiated for the session; others are PROTOCOL_UNSUPPORTED. */
+    readonly extensions?: ReadonlySet<bigint>;
+    /** Called for every live actor-have after checkLiveHave; throws to reject it. */
+    readonly liveHave?: (have: LiveActorHave) => void;
+}
+/** A fresh random 128-bit Message ID (§32). */
+export declare const newMessageId: () => Uint8Array;
+/**
+ * Decodes one LFCP message: size, deterministic CBOR, envelope, registry
+ * and body, in that order (see the module comment). Throws LfcpError:
+ * MESSAGE_TOO_LARGE, PROTOCOL_UNSUPPORTED, or a structural code (CBOR_*,
+ * INVALID_STRUCTURE, INVALID_PRINCIPAL_DESCRIPTOR, ...) that
+ * messageErrorWireCode maps to its §62 code.
+ */
+export declare function decodeMessage(bytes: Uint8Array, options?: DecodeOptions): AnyMessage;
+/** The §32 envelope of a message, with its type code and its body still untyped. */
+export interface DecodedEnvelope extends Envelope {
+    readonly code: bigint;
+    readonly body: CborValue;
+}
+/**
+ * Steps 1-3 of decodeMessage: the size limit (before any decoding), one
+ * deterministic CBOR map, and the §32 envelope. Keys above 15 are dropped
+ * (G-MSG2). The type is not checked against the registry and the body is
+ * not decoded, so a router can read the type and IDs first.
+ */
+export declare function decodeEnvelope(bytes: Uint8Array, options?: DecodeOptions): DecodedEnvelope;
+/**
+ * Encodes a message as deterministic CBOR. Flags are written only when
+ * given, and only as 0 (§32: a sender sets flags to 0 or omits them).
+ * Persistent objects in the body are written as the exact bytes given.
+ */
+export declare function encodeMessage(message: AnyMessage): Uint8Array;
+/** A new message of `type` with a fresh Message ID. */
+export declare function createMessage<T extends CoreMessageType>(type: T, body: MessageBodies[T]): LfcpMessage<T>;
+/** A response to `request`: a fresh Message ID, correlated to the request's (§32). */
+export declare function replyTo<T extends CoreMessageType>(request: Pick<AnyMessage, "messageId">, type: T, body: MessageBodies[T]): LfcpMessage<T>;
+/**
+ * The §62 code for a message decoding failure: MESSAGE_TOO_LARGE and
+ * PROTOCOL_UNSUPPORTED as such; an invalid Principal Descriptor in HELLO
+ * is AUTH_FAILED (§7, P3); everything else is MALFORMED_MESSAGE.
+ */
+export declare function messageErrorWireCode(error: unknown, messageType?: bigint): WireErrorName;
+/** One received WebSocket message (§31). */
+export type Frame = {
+    readonly kind: "binary";
+    readonly data: Uint8Array;
+} | {
+    readonly kind: "text";
+    readonly data: string;
+};
+export type FrameResult = {
+    readonly kind: "message";
+    readonly message: AnyMessage;
+} | {
+    readonly kind: "error";
+    readonly wireCode: WireErrorName;
+    readonly errorCode: bigint;
+    /** True when the receiver must close the connection after sending ERROR (§31, G-MSG7). */
+    readonly closesConnection: boolean;
+    readonly reason: string;
+};
+/**
+ * The receive side of §31 for one WebSocket message, without I/O: a text
+ * frame is MALFORMED_MESSAGE and closes the connection (G-MSG7); a binary
+ * frame is decoded with decodeMessage. A message above the size limit is
+ * MESSAGE_TOO_LARGE and closes the connection too (§31): with the message
+ * dropped, the stream's framing can no longer be trusted. Whether to
+ * answer another failure with NACK (a correlated request) or ERROR is the
+ * session's decision (LFCP-027).
+ */
+export declare function decodeFrame(frame: Frame, options?: DecodeOptions): FrameResult;
+export {};
+//# sourceMappingURL=message.d.ts.map