@syncular/server 0.1.3 → 0.2.1

package/dist/realtime.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Realtime channel (SPEC.md §8) — transport-agnostic.
+ *
+ * A `RealtimeSession` wraps a connected socket's send/receive callbacks:
+ * the host feeds inbound text frames to `handleMessage`, binary frames to
+ * `handleBinary`, and wires `session.close()` to socket close. Initial
+ * subscription registration comes from the client's most recent pull
+ * (§8.1, loaded from the client record); a sync round completed on the
+ * connection replaces it at round end (§8.7). Deltas are complete SSP2
+ * response messages pushed as `0x00`-tagged binary (§8.2/§8.7); sync
+ * rounds ride the same socket as `0x01`-tagged byte-stream chunks driven
+ * through the SAME `createSyncResponseStream` as `POST /sync` (§8.7 —
+ * one handler, two framings); the only JSON data-plane server event is
+ * the `sync` wake-up (§8.3).
+ */
+import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/core';
+import type { LeaseConfig, ResolveScopes, ServerLimits, SyncRequestContext } from './context.js';
+import { type SyncularServerEvents } from './events.js';
+import type { ServerSchema } from './schema.js';
+import type { SegmentStore } from './segment-store.js';
+import type { SegmentUrlConfig } from './signed-url.js';
+import type { ServerStorage, StoredCommit } from './storage.js';
+export interface RealtimeHubConfig {
+    readonly schema: ServerSchema;
+    readonly storage: ServerStorage;
+    readonly resolveScopes: ResolveScopes;
+    readonly clock?: () => number;
+    /** Deltas larger than this become `delta-too-large` wake-ups (§8.2). */
+    readonly maxDeltaBytes?: number;
+    /** Optional structured-events sink (`realtime.*` events). */
+    readonly events?: SyncularServerEvents;
+    /**
+     * Segment store for sync rounds over the socket (§8.7). Without it a
+     * socket round fails loudly with an in-band ERROR — provide the same
+     * store the HTTP binding uses (one handler, two framings).
+     */
+    readonly segments?: SegmentStore;
+    /** Request limits for socket rounds; defaults match the HTTP binding. */
+    readonly limits?: Partial<ServerLimits>;
+    readonly signedUrls?: SegmentUrlConfig;
+    /** §7.3 auth leases for socket sync rounds (§8.7) — same config the
+     * HTTP binding uses, so rounds over the socket are lease-aware too. */
+    readonly leases?: LeaseConfig;
+    /**
+     * §8.6 presence: cap on the serialized size (bytes) of a published
+     * presence document. An over-cap publish is rejected loudly to the
+     * publisher with `presence.too_large` and fans out nothing. Default 16 KiB.
+     */
+    readonly maxPresenceBytes?: number;
+    /**
+     * §8.6.4 presence rate cap: minimum ms between fanned-out publishes per
+     * connection per scope key. Absent ⇒ off (the reference default): every
+     * publish fans out immediately. When set, publishes exceeding the cap
+     * coalesce latest-wins into at most one `update` per window (never an
+     * error, never a stale or lost latest document).
+     */
+    readonly presenceMinIntervalMs?: number;
+}
+export interface RealtimeConnectOptions {
+    readonly partition: string;
+    readonly actorId: string;
+    readonly clientId: string;
+    /**
+     * Socket send: JSON control messages as text, tagged binary otherwise
+     * (§8.7). A host MAY return a promise that resolves when the socket
+     * has drained — the session awaits it between round-response chunks
+     * (§8.7 backpressure: bounded buffering, mechanics host-owned).
+     */
+    readonly send: (data: string | Uint8Array) => void | Promise<void>;
+    /**
+     * Close the underlying socket — invoked on §8.7 protocol violations
+     * (pipelined rounds, unframed streams). The host must still call
+     * `session.close()` from its socket-close handler as usual.
+     */
+    readonly closeSocket?: () => void;
+}
+interface Registration {
+    readonly id: string;
+    readonly table: string;
+    readonly effective: ScopeMap;
+}
+type PresenceDoc = Record<string, unknown>;
+/**
+ * §8.6 presence registry — pure in-memory ephemeral state, keyed per
+ * `(partition, scopeKey)` → the set of present sessions and their
+ * documents. It never touches `ServerStorage`; a server restart loses all
+ * presence (§8.6.1). Fanout is scoped to registered peers only — the
+ * privacy floor (§8.6.3).
+ */
+declare class PresenceRegistry {
+    #private;
+    /** Current documents on a key, excluding one session (the snapshot,
+     * §8.6.4). */
+    snapshot(partition: string, scopeKey: string, exclude: RealtimeSession): Array<{
+        session: RealtimeSession;
+        doc: PresenceDoc;
+    }>;
+    /** Store/replace a session's document for a key. Returns whether this is
+     * the session's FIRST document on the key (join) or a replacement
+     * (update). */
+    set(partition: string, scopeKey: string, session: RealtimeSession, doc: PresenceDoc): 'join' | 'update';
+    /** Remove a session's document for a key. Returns true if one existed. */
+    clear(partition: string, scopeKey: string, session: RealtimeSession): boolean;
+    /** Every key a session currently holds a document on (for leave-on-drop
+     * and registration-change re-derivation). */
+    keysOf(partition: string, session: RealtimeSession): string[];
+    /** Sessions currently registered as peers on a key (for fanout). */
+    peers(partition: string, scopeKey: string): RealtimeSession[];
+}
+export declare class RealtimeSession {
+    #private;
+    readonly sessionId: string;
+    readonly partition: string;
+    readonly actorId: string;
+    readonly clientId: string;
+    /** Highest contiguously applied commitSeq acknowledged by the client. */
+    cursor: number;
+    /** Suppress deltas until the client catches up via pull + ack (§8.2). */
+    wakePending: boolean;
+    lastKnownSeq: number;
+    /** Replaced at socket-round completion (§8.7); initial set from §8.1. */
+    registrations: readonly Registration[];
+    /** Epoch-ms (hub clock) at registration, for `realtime.closed`. */
+    readonly openedAtMs: number;
+    constructor(hub: RealtimeHub, options: RealtimeConnectOptions, registrations: readonly Registration[], cursor: number, latestSeq: number, clock: () => number, maxDeltaBytes: number, storage: ServerStorage, events: SyncularServerEvents | undefined);
+    /** Feed an inbound text frame (client → server control message, §8.2
+     * ack, §8.6.2 presence). */
+    handleMessage(text: string): void;
+    /** Deliver a fanout event to this session (called by the hub for peers,
+     * §8.6.3 receive authorization checked by the caller). */
+    receivePresence(scopeKey: string, kind: PresenceKind, actorId: string, clientId: string, doc: PresenceDoc | null): void;
+    /** §8.6.3: drop presence on keys the connection no longer holds and
+     * deliver the snapshot on keys it newly holds. Called after a
+     * registration change (§8.7 round end, §8.1 reconnect handled by
+     * connect's snapshot). */
+    reconcilePresence(previousKeys: ReadonlySet<string>): void;
+    /** §8.6.1: on disconnect, leave every key this session was present on. */
+    dropAllPresence(): void;
+    /** Snapshot delivery on connect (§8.6.4) — the newly-registered
+     * connection sees who is already present on each of its keys. */
+    deliverInitialPresence(): void;
+    /**
+     * Feed an inbound binary frame: a `0x01`-tagged chunk of the sync
+     * round's request byte stream (§8.7). Synchronous entry — assembly and
+     * violation detection happen inline so a pipelined chunk arriving
+     * while a response streams is caught deterministically; the round
+     * itself runs async once the request is complete.
+     */
+    handleBinary(bytes: Uint8Array): void;
+    sendHeartbeat(): void;
+    sendWake(reason: WakeReason): void;
+    /** Called by the hub for every applied commit, in commitSeq order. */
+    deliverCommit(commit: StoredCommit): void;
+    close(): void;
+}
+export declare class RealtimeHub {
+    #private;
+    /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
+    readonly presence: PresenceRegistry;
+    constructor(config: RealtimeHubConfig);
+    get sessionCount(): number;
+    /** §8.6.2 published-document size cap (bytes). */
+    get maxPresenceBytes(): number;
+    /** §8.6.4 presence rate cap (ms); 0 = off (reference default). */
+    get presenceMinIntervalMs(): number;
+    /** §8.6.3: the scope keys a set of registrations covers. */
+    scopeKeysOf(registrations: readonly Registration[]): Set<string>;
+    /**
+     * §8.6.3 fanout: deliver a presence change to every OTHER session
+     * registered on the key (the privacy floor — only current scope-mates).
+     * The publisher does not receive its own fanout.
+     */
+    fanoutPresence(origin: RealtimeSession, scopeKey: string, kind: PresenceKind, doc: PresenceDoc | null): void;
+    /**
+     * Resolve the client record's subscription list into per-connection
+     * registrations (§8.1 at upgrade; §8.7 at socket-round end).
+     */
+    loadRegistrations(partition: string, actorId: string, clientId: string): Promise<Registration[]>;
+    /**
+     * Build the per-round request context for a socket sync round (§8.7):
+     * the same shape the HTTP adapter builds, so the round drives the
+     * SAME handler with zero semantic divergence.
+     */
+    requestContext(session: RealtimeSession): SyncRequestContext;
+    /**
+     * Register a connected socket (§8.1): load the client's last pull's
+     * subscription list, resolve + intersect scopes, send `hello`.
+     */
+    connect(options: RealtimeConnectOptions): Promise<RealtimeSession>;
+    disconnect(session: RealtimeSession): void;
+    /** RealtimeNotifier: fan an applied commit out to matching sessions. */
+    notifyCommit(partition: string, commit: StoredCommit): Promise<void>;
+    /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
+    wake(partition: string, reason: WakeReason): void;
+}
+export declare function createRealtimeHub(config: RealtimeHubConfig): RealtimeHub;
+export {};