API index and search · Build metadata

Supporting declarations

packages/room/src/authority.ts. These declarations explain referenced types. Only package-page symbols are package exports.

Exact source

/** One CAS rejection in the authority's `409 conflict` body: the row's authoritative
 *  current image (`null` = absent), keyed by table + pk cells. */
export interface AuthorityConflict {
    table: string;
    pk: unknown[];
    current: unknown[] | null;
}

/** The apply outcome. Anything else — network failure, a 5xx — is a **throw**: plain
 *  errors retry (same body, same id; dedup absorbs a landed retry), errors marked
 *  `fatal: true` (an identity mismatch — same id, different body — or a malformed
 *  refusal) kill the incarnation loudly instead. */
export type AuthorityApplyResult = {
    kind: "ok";
    applied: boolean;
    cv?: number;
} | {
    kind: "conflict";
    conflicts: AuthorityConflict[];
} | {
    kind: "fenced";
    currentEpoch?: number;
};

export interface RoomAuthority {
    /** Claim the placement epoch for `doc` (§2.5) — once per shell process, at boot,
     *  AFTER resubmitting the previous incarnation's unconfirmed batches (their recorded
     *  epochs must still be current to land). */
    claimEpoch(doc: string): Promise<number>;
    /** The authority's ledger lmid per client (0 = none) — the boot probe that lets
     *  journal replay absorb already-durable mutations as dedup. */
    lmids(doc: string, clients: string[]): Promise<Record<string, number>>;
    /** Apply one batch: `body` is the exact journaled `/apply-row-change-txn` body
     *  string, sent verbatim. */
    applyRowChangeTxn(body: string): Promise<AuthorityApplyResult>;
}

/** An apply error the shell must NOT retry (retrying cannot help; something is wrong
 *  with the batch or the room, not the network). */
export interface FatalAuthorityError extends Error {
    fatal: true;
}

export declare function fatalAuthorityError(message: string): FatalAuthorityError;

export interface HttpAuthorityOptions {
    /** The API server's apply endpoint (e.g. `http://…/api/rindle/apply-row-change-txn`). */
    applyUrl: string;
    /** The epoch-claim endpoint (e.g. `http://…/api/rindle/claim-room-epoch`). */
    claimUrl: string;
    /** The lmid-probe endpoint (e.g. `http://…/api/rindle/room-lmids`). */
    lmidsUrl: string;
    /** Extra headers on every call — the epoch-bound flush credential rides here. */
    headers?: Record<string, string>;
    fetch?: typeof fetch;
}

/** The HTTP [`RoomAuthority`]: the API-server host as the room's sole counterpart
 *  (§5.3.1). Maps `409 {error:"fenced"}` / `409 {error:"conflict"}` to their results,
 *  a `500` mentioning a batch-identity mismatch to a fatal error, and anything else
 *  non-OK to a retryable throw. */
export declare function httpAuthority(opts: HttpAuthorityOptions): RoomAuthority;