@pgxsinkit/pgwasm/dist/opfs/broker/protocol.d.ts

/**
 * The synchronous broker wire protocol.
 *
 * ## Why a wire protocol at all
 *
 * A repacked store is a single-owner object: it holds four exclusive file handles and one in-memory
 * metadata generation, and it is not shareable across JavaScript agents. A multi-backend engine needs
 * several worker threads to reach ONE store, and a worker running wasm parks in futexes, so it cannot
 * await a promise to get a file answered. The store therefore lives alone in a coordinator worker and
 * every other thread asks for file operations over a `SharedArrayBuffer`, blocking in `Atomics.wait`
 * until the coordinator answers. Nothing here knows about the engine, wasm, or OPFS.
 *
 * ## Topology
 *
 * One CHANNEL per client, plus one DOORBELL shared by every channel of one broker:
 *
 *     client A ─ channel A ─┐
 *     client B ─ channel B ─┼─→ doorbell ─→ RepackedSyncBroker (owns the RepackedVfs)
 *     client C ─ channel C ─┘
 *
 * A client publishes its request into its own channel and then bumps the doorbell, so one blocking
 * server loop can wait on a single word and still service any number of clients.
 *
 * ## Channel layout
 *
 * One `SharedArrayBuffer`, `CHANNEL_HEADER_BYTES` (64) of `Int32Array` header followed by a byte
 * payload region (`DEFAULT_PAYLOAD_BYTES`, 64 KiB, chosen at channel creation):
 *
 *     offset  size  as        name
 *     ------  ----  --------  ------------------------------------------------------------------
 *          0     4  int32     HEADER_STATE      the word both sides `Atomics.wait` / `notify` on
 *          4     4  int32     HEADER_OPCODE     `OPCODE_*`, written by the client
 *          8     4  int32     HEADER_REQUEST    request bytes valid in the payload region
 *         12     4  int32     HEADER_RESPONSE   response bytes valid in the payload region
 *         16     4  int32     HEADER_ERRNO      0, or the WASI preview1 errno of a file rejection
 *         20     4  int32     HEADER_RESULT_LO  low  32 bits of the unsigned 64-bit result
 *         24     4  int32     HEADER_RESULT_HI  high 32 bits of the unsigned 64-bit result
 *         28     4  int32     HEADER_SEQUENCE   the client's monotonic request number
 *         32     4  int32     HEADER_FAULT      `FAULT_*` — a transport/store failure, not a file one
 *         36     4  int32     HEADER_PAYLOAD    payload capacity in bytes (written once at creation)
 *         40    24  int32[6]  reserved, always zero
 *         64     …  bytes     payload region
 *
 * `HEADER_STATE` is the whole handshake:
 *
 *     STATE_IDLE (0) ──client publishes──→ STATE_REQUEST (1) ──server answers──→ STATE_RESPONSE (2)
 *          ↑                                     │                                     │
 *          └─────────────client consumes─────────┼─────────────────────────────────────┘
 *                                                └──server rejects the client──→ STATE_DETACHED (3)
 *
 * `STATE_DETACHED` is terminal: the server has closed the client's descriptors and dropped it, and
 * every later client call throws instead of blocking forever.
 *
 * ## Doorbell layout
 *
 * A small separate `SharedArrayBuffer`, `DOORBELL_BYTES` (16) of `Int32Array`:
 *
 *     index  name              meaning
 *     -----  ----------------  ----------------------------------------------------------------
 *         0  DOORBELL_TICKET   incremented by any client that publishes a request; the word the
 *                              server's blocking loop waits on
 *         1  DOORBELL_RUNNING  1 while the server should keep looping, 0 to ask it to return
 *         2  reserved
 *         3  reserved
 *
 * The server reads `DOORBELL_TICKET` BEFORE it scans the channels and waits on that observed value,
 * so a request published during the scan makes the wait return `not-equal` immediately rather than
 * being missed.
 *
 * ## Ordering
 *
 * Nothing in the payload region is atomic, and nothing needs to be. Each side writes its payload with
 * ordinary stores and then publishes with `Atomics.store` on `HEADER_STATE`; the other side observes
 * with `Atomics.load` on the same word before touching the payload. That store/load pair is the
 * release/acquire edge, so every payload byte written before the publish is visible after the observe.
 *
 * ## Encoding
 *
 * Payloads are little-endian. Paths — and a symbolic link's TARGET, which is a path the store never
 * walks — are `u32` byte length followed by UTF-8 bytes; sizes, offsets and
 * timestamps are unsigned 64-bit (`bigint`) because a virtual file may exceed 2^53 in principle and
 * the core store speaks `bigint` throughout. Byte counts that cannot exceed the payload region stay
 * `u32`. The single numeric answer of an operation travels in the header's 64-bit result pair, not in
 * the payload, so a read reply is nothing but its bytes.
 */
import type { FsErrorName } from "../core/errors";
/** Int32 slot indices of the channel header. */
export declare const HEADER_STATE = 0;
export declare const HEADER_OPCODE = 1;
export declare const HEADER_REQUEST = 2;
export declare const HEADER_RESPONSE = 3;
export declare const HEADER_ERRNO = 4;
export declare const HEADER_RESULT_LO = 5;
export declare const HEADER_RESULT_HI = 6;
export declare const HEADER_SEQUENCE = 7;
export declare const HEADER_FAULT = 8;
export declare const HEADER_PAYLOAD = 9;
export declare const CHANNEL_HEADER_SLOTS = 16;
export declare const CHANNEL_HEADER_BYTES: number;
/** `HEADER_STATE` values. */
export declare const STATE_IDLE = 0;
export declare const STATE_REQUEST = 1;
export declare const STATE_RESPONSE = 2;
export declare const STATE_DETACHED = 3;
/** Int32 slot indices of the doorbell. */
export declare const DOORBELL_TICKET = 0;
export declare const DOORBELL_RUNNING = 1;
export declare const DOORBELL_SLOTS = 4;
export declare const DOORBELL_BYTES: number;
/** The default payload region: large enough that a Postgres 8 KiB page round-trips in one request. */
export declare const DEFAULT_PAYLOAD_BYTES: number;
/** A payload region below this cannot hold the fixed part of every request. */
export declare const MIN_PAYLOAD_BYTES = 1024;
/**
 * `HEADER_FAULT` values. A fault is NOT a file rejection: `HEADER_ERRNO` carries those and leaves the
 * client working. A fault means the transport or the store itself failed.
 */
export declare const FAULT_NONE = 0;
/** The client violated the protocol (unknown opcode, impossible length, truncated payload). */
export declare const FAULT_PROTOCOL = 1;
/** The store threw something that is not an `FsError` — it is very likely poisoned. */
export declare const FAULT_STORE = 2;
/** The server rejected or dropped the client for a reason of its own (explicit `detach`). */
export declare const FAULT_DETACHED = 3;
/** Every operation the broker speaks. */
export declare const OPCODE_OPEN = 1;
export declare const OPCODE_CLOSE = 2;
export declare const OPCODE_READ = 3;
export declare const OPCODE_WRITE = 4;
export declare const OPCODE_FSYNC = 5;
export declare const OPCODE_FSTAT = 6;
export declare const OPCODE_STAT = 7;
export declare const OPCODE_LSTAT = 8;
export declare const OPCODE_READDIR = 9;
export declare const OPCODE_MKDIR = 10;
export declare const OPCODE_RMDIR = 11;
export declare const OPCODE_UNLINK = 12;
export declare const OPCODE_RENAME = 13;
export declare const OPCODE_TRUNCATE = 14;
export declare const OPCODE_SIZE = 15;
export declare const OPCODE_SYMLINK = 16;
export declare const OPCODE_READLINK = 17;
export declare function isKnownOpcode(opcode: number): boolean;
/**
 * POSIX/WASI-shaped open bits. The wire carries these, never the core's node-style flag string: a WASI
 * `path_open` maps its `oflags`/`fdflags`/`fs_rights_base` onto them directly, and the server is the
 * only place that has to know the core's string vocabulary.
 */
export declare const O_RDONLY = 0;
export declare const O_WRONLY = 1;
export declare const O_RDWR = 2;
export declare const O_ACCMODE = 3;
export declare const O_CREAT = 64;
export declare const O_EXCL = 128;
export declare const O_TRUNC = 512;
export declare const O_APPEND = 1024;
/**
 * Refuse to follow a symbolic link on the FINAL component. Linux's own bit value, and the wire form
 * of a WASI `path_open` whose lookup flags omit `SYMLINK_FOLLOW`.
 */
export declare const O_NOFOLLOW = 131072;
/** The stat shape on the wire: `kind` + mode + size + the three timestamps. */
export declare const STAT_KIND_FILE = 0;
export declare const STAT_KIND_DIRECTORY = 1;
export declare const STAT_KIND_SYMLINK = 2;
export declare const STAT_BYTES: number;
/** A `readdir` reply that ran out of payload room reports the cursor to resume from; -1 means done. */
export declare const READDIR_DONE = -1;
/**
 * How the server should satisfy one open request with the core's fixed flag-string vocabulary
 * (`r`, `r+`, `w`, `w+`, `wx`, `wx+`, `a`, `a+`, `ax`, `ax+`).
 *
 * `readable`/`writable` are the access the CLIENT asked for, which is not always what `coreFlags`
 * grants: the core has no "create without truncating and without appending" and no write-only
 * non-truncating mode, so those requests open a wider core descriptor and the broker enforces the
 * requested access itself on every later read/write.
 */
export interface OpenPlan {
    /** The core flag string to try first. */
    readonly coreFlags: string;
    /** Used only when `coreFlags` fails with ENOENT — the create-without-truncate two-step. */
    readonly fallbackFlags: string | undefined;
    /** `O_TRUNC` without `O_CREAT`: truncate the existing path to zero before opening. */
    readonly truncateFirst: boolean;
    /** No `O_CREAT`, but `coreFlags` would create: the server must prove the path exists first. */
    readonly requireExisting: boolean;
    /** The access the client asked for, enforced by the broker on top of the core descriptor. */
    readonly readable: boolean;
    readonly writable: boolean;
    /** `false` for `O_NOFOLLOW`: a final component that IS a symbolic link must answer `ELOOP`. */
    readonly follow: boolean;
}
/**
 * Translate POSIX open bits into the core's vocabulary, or reject the combination with `EINVAL`.
 *
 * Rejected because they are meaningless rather than merely unsupported: an unknown bit, `O_EXCL`
 * without `O_CREAT`, `O_TRUNC` with `O_APPEND`, and a read-only request that also creates,
 * truncates, or appends.
 */
export declare function planOpen(flags: number): OpenPlan;
/** Thrown when a payload cannot hold what a caller is trying to put in it. */
export declare class PayloadOverflowError extends Error {
    constructor(needed: number, capacity: number);
}
/** Thrown when a payload does not decode — always a protocol violation by the peer that wrote it. */
export declare class PayloadDecodeError extends Error {
    constructor(message: string);
}
/** Sequential little-endian writer over a channel's payload region. */
export declare class PayloadWriter {
    #private;
    constructor(payload: Uint8Array);
    get length(): number;
    get remaining(): number;
    u8(value: number): void;
    u32(value: number): void;
    i32(value: number): void;
    u64(value: bigint): void;
    bytes(source: Uint8Array): void;
    string(value: string): void;
    /**
     * Discard everything written after `to`, backing out a field that did not fit. A `string` reserves
     * its length prefix before its bytes, so a name that overflows can leave four bytes behind.
     */
    rewind(to: number): void;
    /**
     * A mutable view over `count` bytes already written at `at` — for a counter that has to be reserved
     * before its value is known (a `readdir` page fills until the payload runs out).
     */
    patch(at: number, count: number): DataView;
}
/** Sequential little-endian reader over a channel's payload region. */
export declare class PayloadReader {
    #private;
    constructor(payload: Uint8Array, length: number);
    get remaining(): number;
    u8(): number;
    u32(): number;
    i32(): number;
    u64(): bigint;
    bytes(count: number): Uint8Array;
    string(): string;
}
/** Split an unsigned 64-bit result into the header's low/high `int32` pair. */
export declare function splitResult(value: bigint): {
    readonly lo: number;
    readonly hi: number;
};
/** Rejoin the header's low/high `int32` pair into an unsigned 64-bit result. */
export declare function joinResult(lo: number, hi: number): bigint;
/** The stat shape both sides exchange; `bigint` everywhere the core is `bigint`. */
export interface BrokerStat {
    /** `symlink` only ever comes back from `lstat`; `size` is then the target's UTF-8 byte length. */
    readonly kind: "directory" | "file" | "symlink";
    readonly mode: number;
    readonly size: bigint;
    readonly atimeMs: bigint;
    readonly mtimeMs: bigint;
    readonly ctimeMs: bigint;
}
export declare function writeStat(writer: PayloadWriter, stat: BrokerStat): void;
export declare function readStat(reader: PayloadReader): BrokerStat;
/** A channel's two shared buffers, in the form that survives `postMessage`. */
export interface RepackedChannelTransfer {
    readonly id: number;
    readonly channel: SharedArrayBuffer;
    readonly doorbell: SharedArrayBuffer;
}
/**
 * The shared word one blocking server loop waits on. Both sides hold the same buffer; a client only
 * ever rings it, and only the host that created it may ask the loop to stop.
 */
export declare class RepackedDoorbell {
    #private;
    readonly buffer: SharedArrayBuffer;
    private constructor();
    static create(): RepackedDoorbell;
    /** Rebuild the doorbell around a buffer that arrived over `postMessage`. */
    static attach(buffer: SharedArrayBuffer): RepackedDoorbell;
    /** The value a server must observe BEFORE it scans, so a concurrent request cannot be missed. */
    ticket(): number;
    /** Announce that some channel now holds a request. */
    ring(): void;
    running(): boolean;
    /**
     * Ask a blocking `serveForever()` to return. This is the only way to stop it from another thread:
     * once inside the loop the server never reaches its own event loop, so `postMessage` cannot reach it.
     */
    requestStop(): void;
    /** Undo a `requestStop()` so the same doorbell can drive another loop. */
    resume(): void;
    /** Block until the ticket leaves `observed`, or the timeout elapses. */
    wait(observed: number, timeoutMs: number): "ok" | "not-equal" | "timed-out";
    /** The non-blocking form, for a host that must not park its thread. */
    waitAsync(observed: number, timeoutMs: number): Promise<"ok" | "not-equal" | "timed-out">;
}
/**
 * One client's request/response channel. Both the client and the server hold an instance over the
 * same `SharedArrayBuffer`; neither owns the memory, and nothing but the header words is atomic.
 */
export declare class RepackedChannel {
    readonly id: number;
    readonly buffer: SharedArrayBuffer;
    readonly doorbell: RepackedDoorbell;
    readonly header: Int32Array;
    readonly payload: Uint8Array;
    private constructor();
    static create(options: {
        id: number;
        doorbell: RepackedDoorbell;
        payloadBytes?: number;
    }): RepackedChannel;
    /** Rebuild a channel around buffers that arrived over `postMessage`. */
    static attach(transfer: RepackedChannelTransfer): RepackedChannel;
    /** The shape to hand to `postMessage`. */
    transfer(): RepackedChannelTransfer;
    get payloadBytes(): number;
    state(): number;
}
/** The errno of a rejection, or `undefined` when it is not a plain file rejection. */
export declare function errnoOf(cause: unknown): number | undefined;
/** The core error name behind a wire errno, or `undefined` for a code the core never produces. */
export declare function fsErrorNameOf(code: number): FsErrorName | undefined;
/** Readable form of a wire errno, for a message. */
export declare function errnoName(code: number): string;
//# sourceMappingURL=protocol.d.ts.map