@korajs/server 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SchemaDefinition, Operation, BlobRef, KoraEventEmitter, VersionVector } from '@korajs/core';
+import { Operation, HybridLogicalClock, SchemaDefinition, BlobRef, KoraEventEmitter, VersionVector, TimeSource } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
 import { SyncStore, ApplyResult, MessageSerializer, SyncMessage, AwarenessUpdateMessage, YjsDocUpdateMessage, BlobChunkRequestMessage, BlobChunkResponseMessage } from '@korajs/sync';
 import { S as ServerTransport, a as ServerMessageHandler, b as ServerCloseHandler, c as ServerErrorHandler } from './server-transport-CU1BLWgr.js';
@@ -44,6 +44,70 @@ interface MaterializedRecord {
     id: string;
     [key: string]: unknown;
 }
+/**
+ * A conditional, atomic multi-operation apply. The store reads the target under a
+ * cross-instance lock, lets the caller decide admission and build the operations
+ * against that locked state, and applies them in one transaction, or applies
+ * nothing. `admit` and `buildOperations` run inside the locked transaction so the
+ * predicate check and any atomic-op resolution see the authoritative current value
+ * even when multiple server instances race on the same target.
+ */
+interface ConditionalApplyInput {
+    /** Record the admission lock and predicate are keyed on. */
+    target: {
+        collection: string;
+        id: string;
+    };
+    /** Decides admission against the target's locked current state. */
+    admit: (current: MaterializedRecord | null) => boolean;
+    /**
+     * Builds the operations to apply, given the locked current state and a clock the
+     * store has already advanced past the target record's latest committed operation.
+     * Stamping the built operations with this clock guarantees they sort strictly
+     * after every prior write to the target, so last-write-wins materialization
+     * reflects the serialized commit order even when two instances commit in the same
+     * millisecond. Without it, a same-millisecond tie could let materialization pick
+     * an earlier resolved value and undercount an atomic counter, admitting past a cap.
+     */
+    buildOperations: (current: MaterializedRecord | null, context: ConditionalApplyContext) => Promise<Operation[]>;
+    /**
+     * When set, a record whose prior existence proves this set already committed.
+     * Checked under the same lock as admission, so a retry is idempotent even across
+     * instances: it returns `idempotent: true` without re-running the operations.
+     */
+    idempotencyKey?: {
+        collection: string;
+        id: string;
+    };
+}
+/** Context passed to {@link ConditionalApplyInput.buildOperations}. */
+interface ConditionalApplyContext {
+    /**
+     * A clock the store has advanced past the target record's latest committed
+     * operation. Operations built here must be stamped with it (route context threads
+     * it into operation creation) so they sort strictly after every prior write.
+     */
+    clock: HybridLogicalClock;
+}
+/** Result of {@link ServerStore.applyConditional}. */
+interface ConditionalApplyResult {
+    /** True when the predicate held (or the set was already committed). */
+    admitted: boolean;
+    /** True when the idempotency key already existed and nothing was re-applied. */
+    idempotent: boolean;
+    /** The operations that were applied (empty when not admitted or idempotent). */
+    applied: Operation[];
+}
+/**
+ * A stored operation paired with its server-assigned delivery sequence. The
+ * delivery sequence is monotonic in commit order, so a batch of these can be
+ * chained (each batch's base links to the previous batch's max) to give the
+ * client a gap-free, scope-agnostic recovery stream.
+ */
+interface DeliveredOperation {
+    operation: Operation;
+    deliverySequence: number;
+}
 /**
  * Options for querying a materialized collection table.
  */
@@ -70,6 +134,41 @@ interface ServerStore extends SyncStore {
     close(): Promise<void>;
     /** Get the total number of stored operations */
     getOperationCount(): Promise<number>;
+    /**
+     * The highest delivery sequence currently visible in the store (0 when empty).
+     * Used to initialize a fresh client's watermark baseline and for diagnostics.
+     */
+    getMaxDeliverySequence(): Promise<number>;
+    /**
+     * Operations with `deliverySequence > afterDeliverySequence`, ordered ascending
+     * by delivery sequence, at most `limit` of them. This is the substrate for the
+     * gap-free server->client stream: the caller (a client session) applies its own
+     * scope filter and chains the results into batches, advancing the client's
+     * durable watermark as batches are acknowledged. Because delivery sequence is
+     * assigned in commit order, a lower sequence is always visible before any higher
+     * one, so this scan can never skip an operation that later appears below the
+     * cursor.
+     */
+    getOperationsAfterDelivery(afterDeliverySequence: number, limit: number): Promise<DeliveredOperation[]>;
+    /**
+     * Conditionally apply a set of operations atomically, serialized across server
+     * instances on the target record. Optional: stores that can only run in a single
+     * process (or do not back a shared database) may omit it, and callers fall back
+     * to per-instance serialization. The Postgres store implements it with a
+     * transaction-scoped advisory lock so concurrent admissions cannot both pass a
+     * cap check (`applyConditional` returns `admitted: false` for the loser).
+     */
+    applyConditional?(input: ConditionalApplyInput): Promise<ConditionalApplyResult>;
+    /**
+     * Atomically reserve the next sequence number for a server-originated operation
+     * on this store's own node. Stores that serve conditional applies concurrently
+     * (the Postgres store, which does not serialize behind a single mutation tail)
+     * must implement this so two in-flight server operations cannot be handed the
+     * same sequence number, which would let one shadow the other during version-vector
+     * delta sync. Stores whose server writes are fully serialized may omit it, and
+     * callers fall back to reading the version vector.
+     */
+    reserveSequenceNumber?(): number;
     /**
      * Set the schema for materialized collection tables.
      * Creates collection tables and indexes based on the schema definition.
@@ -369,7 +468,37 @@ declare class KoraSyncServer {
     private readonly serverVersion;
     private wsServer;
     private running;
+    /**
+     * Periodic tick that retransmits relay batches connected clients have not
+     * acknowledged, so a relay dropped by a lossy transport is redelivered instead of
+     * leaving that client with a permanent version-vector gap (a lost operation).
+     */
+    private relayRetransmitTimer;
+    /**
+     * Relay operations a client never acknowledged before it disconnected, buffered by
+     * client node id so they can be redelivered on its next connection. Bounded per
+     * node and expired by age so a client that never returns cannot grow this forever.
+     */
+    private readonly orphanedRelaysByNode;
+    private static readonly MAX_ORPHANED_RELAY_OPS_PER_NODE;
+    private static readonly ORPHANED_RELAY_TTL_MS;
     constructor(config: KoraSyncServerConfig);
+    /**
+     * Retransmit relay batches that connected clients have not acknowledged within
+     * `staleMs`. Called on a periodic tick and directly by tests. Redelivering an
+     * already-applied operation is harmless (clients dedup by content-addressed id).
+     */
+    retransmitPendingRelays(staleMs?: number): void;
+    /**
+     * Buffer relay operations a disconnected client never acknowledged, keyed by its
+     * node id, deduped by operation id and bounded by count. Redelivered when the
+     * client reconnects (see {@link takeOrphanedRelays}).
+     */
+    private bufferOrphanedRelays;
+    /** Remove and return a node's buffered orphaned relay operations, if any. */
+    private takeOrphanedRelays;
+    /** Drop buffered orphaned relays older than the TTL (client never returned). */
+    private expireOrphanedRelays;
     /**
      * The trusted, scoped data-plane context (`apply` / `query` / `findById`).
      * Shared with the production server so HTTP routes, the operation validator,
@@ -432,6 +561,15 @@ declare class KoraSyncServer {
      * @returns The apply result, including any server-generated side-effect ops
      */
     applyLocalOperation(op: Operation): Promise<ApplyServerOperationResult>;
+    /**
+     * Relay already-applied, server-originated operations to every connected client.
+     * Used by the conditional route apply, which commits its operations atomically
+     * through the store (bypassing {@link applyLocalOperation}) and then fans them
+     * out. Each session still enforces its own per-scope visibility filter.
+     *
+     * @param operations - Operations that have already been committed to the store
+     */
+    relayServerOperations(operations: Operation[]): void;
     /**
      * Collect every blob reference still reachable from live records on the server.
      *
@@ -913,6 +1051,8 @@ interface ClientSessionOptions {
     serializer?: MessageSerializer;
     /** Event emitter for DevTools integration */
     emitter?: KoraEventEmitter;
+    /** Structured logger used for protocol and persistence failures */
+    logger?: Logger;
     /** Max operations per sync batch */
     batchSize?: number;
     /** Schema version the server expects */
@@ -936,6 +1076,19 @@ interface ClientSessionOptions {
     persistBlobChunk?: PersistBlobChunk;
     /** Called when this session closes */
     onClose?: (sessionId: string) => void;
+    /**
+     * Called on close with relay operations this client never acknowledged, so the
+     * server can buffer them per node id and redeliver on the client's next
+     * connection. Closes the window where a relay dropped just before a reconnect
+     * would otherwise be lost (the per-session retransmit tick never fires in time).
+     */
+    onOrphanedRelays?: (nodeId: string, ops: Operation[]) => void;
+    /**
+     * Called once this session reaches streaming to pull any relay operations buffered
+     * for its node id while it was disconnected. They are re-sent through the normal
+     * relay path (re-filtered by this session's current scope).
+     */
+    takeOrphanedRelays?: (nodeId: string) => Operation[];
     /** Maximum serialized operation size in bytes. Defaults to 256 KiB. */
     maxOperationBytes?: number;
     /** Maximum operations accepted per minute for this session. Defaults to 600. */
@@ -969,12 +1122,42 @@ declare class ClientSession {
     private authContext;
     private syncQuerySubsets;
     private resumeDeltaCursor;
+    /**
+     * The delivery watermark the client reported at handshake, or null when the client
+     * does not use the delivery watermark (old client, or no watermark yet). When set,
+     * the server drives the gap-free server->client stream from delivery sequences
+     * instead of the version-vector delta.
+     */
+    private clientDeliveryWatermark;
+    /**
+     * The highest delivery sequence this client has ACKNOWLEDGED (its confirmed
+     * watermark, as reported in acks). Incremental streaming pushes resume from here, not
+     * from the highest sequence sent, so a dropped or unapplied batch is always
+     * re-included by the next push (which re-scans from the acknowledged position). This
+     * is what makes streaming recovery independent of any bounded retransmit buffer: there
+     * is no sent-but-unacked window that a buffer eviction could strand. Seeded from the
+     * client's reported watermark at handshake.
+     */
+    private lastAckedDeliverySeq;
+    /** Serializes incremental delivery pushes so their batches never interleave. */
+    private deliveryPushChain;
+    /**
+     * Relay batches sent to this client but not yet acknowledged, keyed by messageId.
+     * The client acks every operation-batch it applies; on ack the entry is cleared.
+     * {@link retransmitPendingRelays} re-sends anything still unacked, so a relay
+     * dropped by a lossy transport is redelivered instead of leaving the client with a
+     * permanent version-vector gap (a lost operation) that delta sync cannot recover.
+     * Bounded so a silent client cannot grow it without limit.
+     */
+    private readonly pendingRelays;
+    private static readonly MAX_PENDING_RELAYS;
     private readonly sessionId;
     private readonly transport;
     private readonly store;
     private readonly auth;
     private readonly serializer;
     private readonly emitter;
+    private readonly logger;
     private readonly batchSize;
     private readonly schemaVersion;
     private readonly supportedSchemaVersions;
@@ -985,6 +1168,8 @@ declare class ClientSession {
     private readonly onBlobChunkResponse;
     private readonly persistBlobChunk;
     private readonly onClose;
+    private readonly onOrphanedRelays;
+    private readonly takeOrphanedRelays;
     private readonly maxOperationBytes;
     private readonly maxOpsPerMinute;
     private readonly rateLimiter;
@@ -1000,9 +1185,30 @@ declare class ClientSession {
      * Only relays if the session is in streaming state and transport is connected.
      */
     relayOperations(operations: Operation[]): void;
+    /**
+     * Push newly-available in-scope operations to a delivery-watermark client, resuming
+     * from the highest delivery sequence already sent. Pushes are serialized so their
+     * batches never interleave (which would break the base/max chain).
+     */
+    private pushDeliveryStream;
+    private relayVisibleOperations;
+    /** Record a relay batch as awaiting acknowledgment, evicting the oldest if full. */
+    private trackPendingRelay;
+    /**
+     * Retransmit relay batches this client has not acknowledged within `staleMs`.
+     * Called on a periodic tick by the server (and directly by tests). Redelivering an
+     * already-applied op is harmless: the client dedups by content-addressed id.
+     */
+    retransmitPendingRelays(staleMs?: number): void;
     /**
      * Close this session.
      */
+    /**
+     * Hand any unacknowledged relays to the server so they survive this session and are
+     * redelivered when this client reconnects (per-node buffer), then clear them. Called
+     * from every session-teardown path (explicit close and transport close).
+     */
+    private flushOrphanedRelays;
     close(reason?: string): void;
     getState(): SessionState;
     getSessionId(): string;
@@ -1029,7 +1235,34 @@ declare class ClientSession {
     private handleHandshake;
     private handleOperationBatch;
     private sendDelta;
+    /**
+     * Send the gap-free server->client delivery stream, resuming just after
+     * `fromDeliverySeq`. Operations are scanned in server delivery-sequence order
+     * (commit order), scope-filtered for this session, and sent in batches that chain:
+     * each batch's `baseDeliverySequence` equals the previous batch's
+     * `maxDeliverySequence` (the first batch bases on `fromDeliverySeq`). The client
+     * applies a batch only when its watermark equals the base and advances the
+     * watermark to the max, so a dropped batch stalls the watermark and is recovered by
+     * the next handshake resend. Because delivery-sequence order respects causal order
+     * (a dependency is always committed, and thus sequenced, before its dependent), no
+     * topological sort is needed and the client never defers on a missing dependency
+     * that is itself in this stream.
+     *
+     * The final batch advances the watermark to the highest delivery sequence scanned,
+     * not merely the last in-scope one, so an out-of-scope tail is not re-scanned on the
+     * next reconnect. Returns the number of operations actually sent.
+     */
+    private sendDeliveryStream;
+    /** Build, track, and send one chained delivery-stream batch. */
+    private sendDeliveryBatch;
     private operationVisibleToClient;
+    /**
+     * Read a record's current field values from the materialized store for scope /
+     * query-subset backfill. Includes soft-deleted rows so a relayed delete (whose op
+     * carries no fields) is still judged against the record's actual scope. Returns
+     * undefined when the record cannot be read (never materialized, or no schema).
+     */
+    private lookupRecordFields;
     private handleAwarenessUpdate;
     private handleYjsDocUpdate;
     private sendError;
@@ -1059,6 +1292,13 @@ interface ProductionServerConfig {
     syncPath?: string;
     /** Additional KoraSyncServer options */
     syncOptions?: Omit<KoraSyncServerConfig, 'store' | 'port' | 'host' | 'path'>;
+    /**
+     * Cross-Origin-Embedder-Policy for static and route responses. Defaults to
+     * `credentialless`, which keeps third-party embeds usable while allowing
+     * capable browsers to enable cross-origin isolation. Use `require-corp` only
+     * when every embedded resource explicitly opts in with CORP/CORS headers.
+     */
+    crossOriginEmbedderPolicy?: 'credentialless' | 'require-corp' | 'unsafe-none';
     /**
      * Optional HTTP route handlers mounted before static file serving.
      *
@@ -1382,6 +1622,14 @@ declare class MemoryServerStore implements ServerStore {
     private readonly operations;
     private readonly operationIndex;
     private readonly versionVector;
+    /**
+     * Server-assigned delivery sequence per operation id. Single-process, so a plain
+     * counter incremented at insert time gives commit-order delivery sequence with no
+     * gaps. `operations` is kept in insertion (== delivery) order, so a delivery scan
+     * is a forward walk.
+     */
+    private readonly deliverySeqByOpId;
+    private deliverySeqCounter;
     private schema;
     /** Materialized records: collection -> recordId -> record data */
     private readonly materializedRecords;
@@ -1394,6 +1642,8 @@ declare class MemoryServerStore implements ServerStore {
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
     getOperationCount(): Promise<number>;
+    getMaxDeliverySequence(): Promise<number>;
+    getOperationsAfterDelivery(afterDeliverySequence: number, limit: number): Promise<DeliveredOperation[]>;
     materializeCollection(collection: string): Promise<MaterializedRecord[]>;
     queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
@@ -1434,14 +1684,44 @@ declare class PostgresServerStore implements ServerStore {
     private readonly ready;
     private schema;
     private closed;
-    constructor(db: PostgresJsDatabase, nodeId?: string);
+    /**
+     * Monotonic counter for this node's server-originated sequence numbers. Lazily
+     * seeded from the persisted version vector on first use, then advanced in memory
+     * (a synchronous `++`, atomic on the single JS thread) so concurrent conditional
+     * applies never receive the same number. Null means "not yet seeded"; reset to
+     * null after a backup import so it re-seeds from the restored version vector.
+     */
+    private sequenceCounter;
+    /**
+     * Time source for HLC timestamps on server-originated operations. Injectable so a
+     * test can freeze wall-clock time and prove the conditional-apply ordering holds
+     * under same-millisecond commits (the case the advisory lock and clock advance
+     * exist to make correct). Defaults to the system clock in production.
+     */
+    private readonly timeSource;
+    constructor(db: PostgresJsDatabase, nodeId?: string, timeSource?: TimeSource);
     getVersionVector(): VersionVector;
+    /**
+     * Atomically reserve this node's next server-operation sequence number. The
+     * synchronous increment cannot interleave on the single JS thread, so two
+     * concurrent conditional applies are always handed distinct numbers.
+     */
+    reserveSequenceNumber(): number;
     getNodeId(): string;
     getSchema(): SchemaDefinition | null;
     setSchema(schema: SchemaDefinition): Promise<void>;
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    /**
+     * Conditionally apply operations atomically, serialized across server instances
+     * on the target record via a transaction-scoped advisory lock. The lock makes
+     * the read-decide-write cycle atomic against concurrent instances, so a cap
+     * check like `responseCount < max` cannot be passed by two admissions at once.
+     */
+    applyConditional(input: ConditionalApplyInput): Promise<ConditionalApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
     getOperationCount(): Promise<number>;
+    getMaxDeliverySequence(): Promise<number>;
+    getOperationsAfterDelivery(afterDeliverySequence: number, limit: number): Promise<DeliveredOperation[]>;
     materializeCollection(collection: string): Promise<MaterializedRecord[]>;
     queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
@@ -1452,6 +1732,13 @@ declare class PostgresServerStore implements ServerStore {
         operationsRestored: number;
         success: boolean;
     }>;
+    /**
+     * The HLC timestamp of the most recent operation on a record, by total order
+     * (wallTime, logical, nodeId), or null when the record has no operations. Used
+     * by {@link applyConditional} to advance its clock past the record's latest
+     * write so newly built operations sort strictly after it.
+     */
+    private latestOperationTimestamp;
     /**
      * Rebuild a single record in the materialized collection table by replaying
      * all operations for that record.
@@ -1475,6 +1762,12 @@ declare class PostgresServerStore implements ServerStore {
     private materializeFromOpsLog;
     private initialize;
     private ensureTables;
+    /**
+     * Reserve the next delivery sequence inside an open append transaction. The
+     * `UPDATE ... RETURNING` locks the counter row until this transaction commits,
+     * serializing assignment into commit order (see the counter table comment).
+     */
+    private nextDeliverySeq;
     private serializeOperation;
     private deserializeOperation;
     private assertOpen;
@@ -1502,6 +1795,12 @@ declare class SqliteServerStore implements ServerStore {
     private readonly db;
     private schema;
     private closed;
+    /**
+     * Next delivery sequence to assign. Single-writer (better-sqlite3 is synchronous),
+     * so a plain in-memory counter, seeded from MAX(delivery_seq) at startup, gives
+     * commit-order delivery sequence. Assigned inside the append transaction.
+     */
+    private deliverySeqCounter;
     constructor(db: BetterSQLite3Database, nodeId?: string);
     getVersionVector(): VersionVector;
     getNodeId(): string;
@@ -1510,6 +1809,8 @@ declare class SqliteServerStore implements ServerStore {
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
     getOperationCount(): Promise<number>;
+    getMaxDeliverySequence(): Promise<number>;
+    getOperationsAfterDelivery(afterDeliverySequence: number, limit: number): Promise<DeliveredOperation[]>;
     materializeCollection(collection: string): Promise<MaterializedRecord[]>;
     queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
@@ -1548,6 +1849,13 @@ declare class SqliteServerStore implements ServerStore {
      * Create the operations and sync_state tables if they don't exist.
      */
     private ensureTables;
+    /**
+     * Assign delivery sequences to any operations written before the column existed,
+     * then seed the in-memory counter from the current max. Ordered by
+     * (received_at, sequence_number, id) so the backfill is deterministic and stable
+     * across restarts. A one-time migration: after it runs, all rows have a value.
+     */
+    private backfillDeliverySequence;
     private serializeOperation;
     private deserializeOperation;
     private assertOpen;