@openlfcp/client 0.1.0-rc.1

package/dist/outbound.d.ts

@@ -0,0 +1,227 @@
+import { type ActorSequence, type ControlRecordId, type DataEpoch, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import type { LfcpStorage, OutboundBlock, OutboundItem, OutboundKind } from "@openlfcp/storage";
+import { type ControlView, type HaveVector, type LfcpMessage, type WireErrorName } from "@openlfcp/wire";
+/**
+ * The pending outbound queue and its sync state (LFCP-036): a
+ * transport-agnostic state machine over the stored outbound items. The
+ * transport (LFCP-039a) asks for messages, sends them, and reports ACKs,
+ * NACKs and connection loss; time comes from the caller, and nothing here
+ * sleeps or sets timers.
+ *
+ * The object and the message are different things:
+ * - an item is an immutable LFCP object (Data Unit, Control Record, Key
+ *   Package, Snapshot) persisted with its exact bytes before it is ever
+ *   sent (createQueuedDataUnit, queueKeyPackage, …); it leaves the queue
+ *   only when an ACK names its ID, or when the application discards it
+ *   after it was blocked;
+ * - a message is one transport attempt: every send wraps the SAME bytes in
+ *   a NEW message with a new Message ID. Nothing here creates an LFCP
+ *   object, reserves a sequence or touches plaintext, so a retry can never
+ *   reuse a nonce.
+ *
+ * In-flight state is memory only: after a restart (or a lost connection)
+ * every unblocked item is due again and is resent byte for byte.
+ */
+/** Why an item is being retried; given to the RetryPolicy. */
+export type RetryReason = 
+/** The connection went away after send, before an answer. */
+"connection-lost"
+/** A NACK with a transient or unknown code. */
+ | "transient"
+/** An ACK of its message that did not name it, or named it below the required durability. */
+ | "not-acked"
+/** No answer within the request timeout on a live connection (a lost request or reply). */
+ | "timeout";
+export interface RetryPolicy {
+    /**
+     * When the item may be sent again (RFC 3339, caller's clock), or null for
+     * at once. Pure: the caller owns time; the result is stored with the item.
+     */
+    nextAttempt(failure: {
+        readonly item: OutboundItem;
+        readonly reason: RetryReason;
+        readonly code?: WireErrorName | bigint;
+        readonly now: string;
+    }): string | null;
+}
+/** Exponential backoff from `baseMs`, doubling per attempt, capped at `maxMs`. */
+export declare function exponentialBackoff(baseMs: number, maxMs: number): RetryPolicy;
+/** One message to send now, and the queued objects it carries. */
+export interface OutboundMessage {
+    readonly resourceId: ResourceId;
+    readonly message: LfcpMessage;
+    /** The encoded message; send exactly these bytes. */
+    readonly bytes: Uint8Array;
+    readonly itemIds: readonly Hash32[];
+}
+export interface AckOutcome {
+    /** Items the ACK named, now removed from the queue. */
+    readonly acked: readonly Hash32[];
+    /** Items of the acknowledged message the ACK did not name: still queued. */
+    readonly notCovered: readonly Hash32[];
+    /** The durability the ACK established: READY's level when durable, else 0 (§37, §59). */
+    readonly durability: bigint;
+    /** Named, but below the required durability: still queued. */
+    readonly belowDurability: readonly Hash32[];
+    /** False when the ACK answers no message of this session (matched by object ID only). */
+    readonly correlated: boolean;
+}
+/** A blocked item as surfaced to the application. */
+export interface BlockedItem {
+    readonly itemId: Hash32;
+    readonly kind: OutboundKind;
+    readonly reason: OutboundBlock;
+    readonly detail: string | null;
+}
+export type NackOutcome = 
+/** A per-object refusal for a message of several objects: each is now sent alone. */
+{
+    readonly kind: "isolating";
+    readonly code: WireErrorName;
+    readonly items: readonly Hash32[];
+}
+/**
+ * The item is beyond a closed epoch's cutoff (STALE_DATA_EPOCH, G-EP5):
+ * never sent again. Applying the user's intent again is a NEW unit in
+ * the current epoch, made by the application (not here).
+ */
+ | {
+    readonly kind: "stale";
+    readonly items: readonly BlockedItem[];
+}
+/** The server holds another unit for this (actor, seq): our sequence was reused. A safety alarm. */
+ | {
+    readonly kind: "equivocation-alarm";
+    readonly items: readonly BlockedItem[];
+}
+/** Refused for good (authority is judged at the unit's own head, so it will not change). */
+ | {
+    readonly kind: "rejected";
+    readonly code: WireErrorName;
+    readonly items: readonly BlockedItem[];
+}
+/** A Control Record proposed on a head that moved: build a new record on `currentHead`. */
+ | {
+    readonly kind: "repropose";
+    readonly items: readonly BlockedItem[];
+    readonly currentHead: ControlRecordId | null;
+}
+/** The server lacks Control records: retried after the next Control sync (controlSynced). */
+ | {
+    readonly kind: "needs-control-sync";
+    readonly items: readonly Hash32[];
+}
+/** Transient or unknown: retried after the RetryPolicy delay. */
+ | {
+    readonly kind: "retry";
+    readonly code: WireErrorName | bigint;
+    readonly items: readonly Hash32[];
+}
+/** The NACK answers no message of this session. */
+ | {
+    readonly kind: "uncorrelated";
+    readonly code: WireErrorName | bigint;
+};
+/** A queued unit of ours that a newly known Key Epoch puts beyond its cutoff (§88 step 7). */
+export interface StaleOutboundUnit extends BlockedItem {
+    readonly actor: PrincipalId;
+    readonly seq: ActorSequence;
+    readonly epoch: DataEpoch;
+}
+export interface OutboundQueueOptions {
+    readonly storage: Pick<LfcpStorage, "outbound" | "dataUnits" | "syncState" | "commit">;
+    /** Defaults to "at once" (no delay); the caller decides when to ask again. */
+    readonly retry?: RetryPolicy;
+    /** At most this many objects per DATA_PUT / KEY_PACKAGE_PUT (default 64). */
+    readonly maxObjectsPerMessage?: number;
+    /**
+     * The minimum durability (§37 level) for which an ACK removes an item
+     * (default 0: any ACK). The level of an ACK is READY's when it says
+     * durable, else 0 (§59: never stronger than advertised).
+     */
+    readonly minimumDurability?: bigint;
+    /** How many recently ACKed IDs the sync state keeps per Resource (default 256). */
+    readonly recentAckLimit?: number;
+    /**
+     * How long a sent message waits for its answer on a live connection
+     * before its items are due again (a lost request or reply, §70
+     * at-least-once): `baseMs`, doubling per attempt of the item, at most
+     * `maxMs`. Default 10 s to 60 s. A re-put is harmless: the server answers
+     * a repeated object with the same ACK (§47, §70).
+     */
+    readonly requestTimeout?: {
+        readonly baseMs: number;
+        readonly maxMs: number;
+    };
+}
+export declare class OutboundQueue {
+    #private;
+    constructor(options: OutboundQueueOptions);
+    /** READY: the server's durability level and maximum message size for this session (§37). */
+    session(ready: {
+        readonly durability: bigint;
+        readonly maxMessageBytes: bigint;
+    }): void;
+    /**
+     * The messages to send now for `resource`: every unblocked item that is
+     * not in flight, not waiting for a Control sync and due by `now`, in §88
+     * order, batched where the message type allows. Each item's attempt is
+     * recorded durably before the messages are returned. An item too large
+     * for any message is blocked ("too-large") instead.
+     */
+    next(resource: ResourceId, now: string): Promise<OutboundMessage[]>;
+    /**
+     * An ACK (§59): removes the queued items whose IDs it names (field 1),
+     * and records them in the Resource's sync state. Items of the
+     * acknowledged message it does not name stay queued. Idempotent: a
+     * repeated ACK, or one for items already gone, changes nothing.
+     */
+    onAck(message: LfcpMessage<"ACK">, now: string): Promise<AckOutcome>;
+    /**
+     * A NACK (§60) of one of this session's messages. Per-object codes on a
+     * message of several objects resend each object alone, to learn which one
+     * the server meant. Then:
+     * STALE_DATA_EPOCH → blocked "stale-epoch" (G-EP5: never resent);
+     * ACTOR_EQUIVOCATION → blocked "equivocation", surfaced as an alarm;
+     * AUTHORIZATION_FAILED (and other per-object refusals) → blocked "rejected";
+     * MESSAGE_TOO_LARGE → blocked "too-large";
+     * CONTROL_HEAD_MISMATCH → blocked "repropose" with the current head;
+     * MISSING_DEPENDENCY → retried after the next controlSynced();
+     * anything else → retried after the RetryPolicy delay.
+     */
+    onNack(message: LfcpMessage<"NACK">, now: string): Promise<NackOutcome>;
+    /**
+     * The connection is gone: every message in flight is unanswered, so its
+     * items are due again (same bytes, a new message) after the RetryPolicy
+     * delay. Returns the affected item IDs.
+     */
+    connectionLost(now: string): Promise<Hash32[]>;
+    /** The Control Plane of `resource` was synchronized: items held for MISSING_DEPENDENCY are due again. */
+    controlSynced(resource: ResourceId): Promise<void>;
+    /**
+     * §88 step 7, G-EP5: with a newly validated Control view, our queued
+     * Data Units of a closed epoch beyond its final frontier are never sent;
+     * they are blocked "stale-epoch" and surfaced (also when in flight: a
+     * later ACK still removes them). Units within the cutoff stay queued and
+     * are sent as the same bytes.
+     */
+    reconcileEpochs(view: ControlView): Promise<StaleOutboundUnit[]>;
+    /** Removes a blocked item once the application has dealt with it (e.g. re-proposed or re-applied). */
+    discard(itemId: Hash32): Promise<void>;
+}
+/** A Resource's sync state: Have-based, never a global cursor. */
+export interface ResourceSyncState {
+    /** The accepted Data Units this client holds (§28), ours included. */
+    readonly have: HaveVector;
+    /** Queued items still to be sent or answered. */
+    readonly outstanding: readonly OutboundItem[];
+    /** Queued items that will not be sent again, until discarded. */
+    readonly blocked: readonly OutboundItem[];
+    readonly recentlyAcked: readonly Hash32[];
+    readonly ackedDurability: bigint | null;
+}
+/** The sync state of `resource` from storage alone (valid after a restart). */
+export declare function resourceSyncState(storage: Pick<LfcpStorage, "outbound" | "dataUnits" | "syncState" | "snapshots">, resource: ResourceId): Promise<ResourceSyncState>;
+/** The union of the frontiers of the Snapshots stored for `resource` (those loaded or published here). */
+export declare function snapshotFrontier(storage: Pick<LfcpStorage, "snapshots">, resource: ResourceId): Promise<HaveVector>;
+//# sourceMappingURL=outbound.d.ts.map