@korajs/server 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,513 @@
+import { KoraEventEmitter, Operation, VersionVector } from '@korajs/core';
+import * as _korajs_sync from '@korajs/sync';
+import { SyncStore, MessageSerializer, SyncMessage, ApplyResult } from '@korajs/sync';
+import { S as ServerTransport, a as ServerMessageHandler, b as ServerCloseHandler, c as ServerErrorHandler } from './server-transport-CU1BLWgr.cjs';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+
+/**
+ * Server-side store interface. Extends SyncStore with lifecycle
+ * and introspection methods needed by the sync server.
+ */
+interface ServerStore extends SyncStore {
+    /** Close the store and release resources */
+    close(): Promise<void>;
+    /** Get the total number of stored operations */
+    getOperationCount(): Promise<number>;
+}
+
+/**
+ * Authenticated client context. Returned by an AuthProvider after validation.
+ */
+interface AuthContext {
+    /** Unique user identifier */
+    userId: string;
+    /** Per-collection sync scopes (optional) */
+    scopes?: Record<string, Record<string, unknown>>;
+    /** Arbitrary metadata about the authenticated user */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Interface for authenticating incoming client connections.
+ * Implementations validate tokens and return an AuthContext on success.
+ */
+interface AuthProvider {
+    /**
+     * Validate an authentication token.
+     * @param token - The token to validate
+     * @returns AuthContext if valid, null if rejected
+     */
+    authenticate(token: string): Promise<AuthContext | null>;
+}
+/**
+ * Configuration for creating a KoraSyncServer.
+ */
+interface KoraSyncServerConfig {
+    /** Server-side operation store */
+    store: ServerStore;
+    /** WebSocket server port (standalone mode) */
+    port?: number;
+    /** Host to bind to (standalone mode). Defaults to '0.0.0.0'. */
+    host?: string;
+    /** Authentication provider. If omitted, all connections are accepted. */
+    auth?: AuthProvider;
+    /** Message serializer. Defaults to JsonMessageSerializer. */
+    serializer?: MessageSerializer;
+    /** Event emitter for DevTools integration */
+    emitter?: KoraEventEmitter;
+    /** Maximum concurrent client connections. 0 = unlimited. Defaults to 0. */
+    maxConnections?: number;
+    /** Maximum operations per sync batch. Defaults to 100. */
+    batchSize?: number;
+    /** Schema version the server expects. Defaults to 1. */
+    schemaVersion?: number;
+    /** WebSocket path (standalone mode). Defaults to '/'. */
+    path?: string;
+}
+/**
+ * Request envelope for the server-side HTTP sync endpoint.
+ */
+interface HttpSyncRequest {
+    /** Stable client identifier for binding HTTP requests to a server session */
+    clientId: string;
+    /** HTTP method */
+    method: 'GET' | 'POST';
+    /** Optional raw request payload for POST */
+    body?: string | Uint8Array;
+    /** Value of the Content-Type header for POST payloads */
+    contentType?: string;
+    /** Value of the If-None-Match header for GET polling */
+    ifNoneMatch?: string;
+}
+/**
+ * Response envelope for the server-side HTTP sync endpoint.
+ */
+interface HttpSyncResponse {
+    /** HTTP status code */
+    status: 200 | 202 | 204 | 304 | 400 | 405 | 410;
+    /** Optional raw response payload */
+    body?: string | Uint8Array;
+    /** Optional response headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Runtime status of a KoraSyncServer.
+ */
+interface ServerStatus {
+    /** Whether the server is running */
+    running: boolean;
+    /** Number of currently connected clients */
+    connectedClients: number;
+    /** Port the server is listening on (null if attach mode) */
+    port: number | null;
+    /** Total operations stored */
+    totalOperations: number;
+}
+
+interface HttpPollResponse {
+    status: 200 | 204 | 304 | 410;
+    body?: string | Uint8Array;
+    headers?: Record<string, string>;
+}
+/**
+ * Server-side transport for HTTP long-polling clients.
+ *
+ * Incoming client messages are pushed via POST, while outbound server
+ * messages are pulled via GET long-poll requests.
+ */
+declare class HttpServerTransport implements ServerTransport {
+    private readonly serializer;
+    private messageHandler;
+    private closeHandler;
+    private errorHandler;
+    private connected;
+    private nextSequence;
+    private readonly queue;
+    constructor(serializer: MessageSerializer);
+    send(message: _korajs_sync.SyncMessage): void;
+    onMessage(handler: ServerMessageHandler): void;
+    onClose(handler: ServerCloseHandler): void;
+    onError(handler: ServerErrorHandler): void;
+    isConnected(): boolean;
+    close(code?: number, reason?: string): void;
+    receive(payload: string | Uint8Array): void;
+    poll(ifNoneMatch?: string): HttpPollResponse;
+    private makeEtag;
+}
+
+/**
+ * Minimal interface for a ws.WebSocket instance.
+ * Allows dependency injection for testing without importing ws directly.
+ */
+interface WsWebSocket {
+    readyState: number;
+    send(data: string | Uint8Array, callback?: (err?: Error) => void): void;
+    close(code?: number, reason?: string): void;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    removeAllListeners(): void;
+}
+/**
+ * Options for WsServerTransport.
+ */
+interface WsServerTransportOptions {
+    /** Message serializer. Defaults to JsonMessageSerializer. */
+    serializer?: MessageSerializer;
+}
+/**
+ * Server-side transport wrapping a ws.WebSocket connection.
+ * Created for each incoming client connection.
+ */
+declare class WsServerTransport implements ServerTransport {
+    private readonly ws;
+    private readonly serializer;
+    private messageHandler;
+    private closeHandler;
+    private errorHandler;
+    constructor(ws: WsWebSocket, options?: WsServerTransportOptions);
+    send(message: SyncMessage): void;
+    onMessage(handler: ServerMessageHandler): void;
+    onClose(handler: ServerCloseHandler): void;
+    onError(handler: ServerErrorHandler): void;
+    isConnected(): boolean;
+    close(code?: number, reason?: string): void;
+    private setupListeners;
+}
+
+/**
+ * Possible states for a client session.
+ */
+type SessionState = 'connected' | 'authenticated' | 'syncing' | 'streaming' | 'closed';
+/**
+ * Callback invoked when a session has new operations to relay to other sessions.
+ */
+type RelayCallback = (sourceSessionId: string, operations: Operation[]) => void;
+/**
+ * Options for creating a ClientSession.
+ */
+interface ClientSessionOptions {
+    /** Unique session identifier */
+    sessionId: string;
+    /** Transport for this client connection */
+    transport: ServerTransport;
+    /** Server-side operation store */
+    store: ServerStore;
+    /** Authentication provider (optional) */
+    auth?: AuthProvider;
+    /** Message serializer */
+    serializer?: MessageSerializer;
+    /** Event emitter for DevTools integration */
+    emitter?: KoraEventEmitter;
+    /** Max operations per sync batch */
+    batchSize?: number;
+    /** Schema version the server expects */
+    schemaVersion?: number;
+    /** Called when this session has operations to relay to other sessions */
+    onRelay?: RelayCallback;
+    /** Called when this session closes */
+    onClose?: (sessionId: string) => void;
+}
+/**
+ * Handles the sync protocol for a single connected client.
+ *
+ * Lifecycle: connected → (authenticated) → syncing → streaming → closed
+ *
+ * The session:
+ * 1. Receives a handshake from the client
+ * 2. Authenticates if an AuthProvider is configured
+ * 3. Sends back a HandshakeResponse with the server's version vector
+ * 4. Computes and sends the server's delta to the client (paginated)
+ * 5. Processes incoming operation batches from the client
+ * 6. Transitions to streaming for real-time bidirectional sync
+ * 7. Relays new operations to other sessions via the RelayCallback
+ */
+declare class ClientSession {
+    private state;
+    private clientNodeId;
+    private authContext;
+    private readonly sessionId;
+    private readonly transport;
+    private readonly store;
+    private readonly auth;
+    private readonly serializer;
+    private readonly emitter;
+    private readonly batchSize;
+    private readonly schemaVersion;
+    private readonly onRelay;
+    private readonly onClose;
+    constructor(options: ClientSessionOptions);
+    /**
+     * Start handling messages from the client transport.
+     */
+    start(): void;
+    /**
+     * Relay operations from another session to this client.
+     * Only relays if the session is in streaming state and transport is connected.
+     */
+    relayOperations(operations: Operation[]): void;
+    /**
+     * Close this session.
+     */
+    close(reason?: string): void;
+    getState(): SessionState;
+    getSessionId(): string;
+    getClientNodeId(): string | null;
+    getAuthContext(): AuthContext | null;
+    isStreaming(): boolean;
+    private handleMessage;
+    private handleHandshake;
+    private handleOperationBatch;
+    private sendDelta;
+    private sendError;
+    private setSerializerWireFormat;
+    private handleTransportClose;
+}
+
+/**
+ * Minimal interface for a ws.WebSocketServer instance.
+ * Allows dependency injection for testing without importing ws directly.
+ */
+interface WsServerLike {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    close(callback?: (err?: Error) => void): void;
+    address(): {
+        port: number;
+    } | string | null;
+}
+/**
+ * Constructor type for creating a WebSocket server.
+ */
+type WsServerConstructor = new (options: {
+    port?: number;
+    host?: string;
+    path?: string;
+}) => WsServerLike;
+/**
+ * Self-hosted sync server. Accepts WebSocket connections from clients,
+ * handles the sync protocol, stores operations, and relays changes
+ * between connected clients.
+ *
+ * Two modes of operation:
+ * 1. **Standalone**: Call `start()` with a port — creates its own WebSocket server.
+ * 2. **Attach**: Call `handleConnection(transport)` — attach to an existing HTTP server.
+ */
+declare class KoraSyncServer {
+    private readonly store;
+    private readonly auth;
+    private readonly serializer;
+    private readonly emitter;
+    private readonly maxConnections;
+    private readonly batchSize;
+    private readonly schemaVersion;
+    private readonly port;
+    private readonly host;
+    private readonly path;
+    private readonly sessions;
+    private readonly httpClients;
+    private readonly httpSessionToClient;
+    private wsServer;
+    private running;
+    constructor(config: KoraSyncServerConfig);
+    /**
+     * Start the WebSocket server in standalone mode.
+     *
+     * @param wsServerImpl - Optional WebSocket server constructor for testing
+     */
+    start(wsServerImpl?: WsServerConstructor): Promise<void>;
+    /**
+     * Stop the server. Closes all sessions and the WebSocket server.
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle one HTTP sync request for a long-polling client.
+     *
+     * A stable `clientId` identifies the logical connection across requests.
+     */
+    handleHttpRequest(request: HttpSyncRequest): Promise<HttpSyncResponse>;
+    /**
+     * Handle an incoming client connection (attach mode).
+     * Creates a new ClientSession for the transport.
+     *
+     * @param transport - The server transport for the new connection
+     * @returns The session ID
+     */
+    handleConnection(transport: ServerTransport): string;
+    /**
+     * Get the current server status.
+     */
+    getStatus(): Promise<ServerStatus>;
+    /**
+     * Get the number of currently connected clients.
+     */
+    getConnectionCount(): number;
+    private handleRelay;
+    private handleSessionClose;
+    private getOrCreateHttpClient;
+}
+
+/**
+ * Options for creating a TokenAuthProvider.
+ */
+interface TokenAuthProviderOptions {
+    /**
+     * Validate a token and return an AuthContext if valid, or null if rejected.
+     * This is where you implement your auth logic (JWT verification, database lookup, etc.).
+     */
+    validate: (token: string) => Promise<AuthContext | null>;
+}
+/**
+ * Token-based auth provider that delegates validation to a user-provided function.
+ *
+ * @example
+ * ```typescript
+ * const auth = new TokenAuthProvider({
+ *   validate: async (token) => {
+ *     const user = await verifyJWT(token)
+ *     return user ? { userId: user.id } : null
+ *   }
+ * })
+ * ```
+ */
+declare class TokenAuthProvider implements AuthProvider {
+    private readonly validate;
+    constructor(options: TokenAuthProviderOptions);
+    authenticate(token: string): Promise<AuthContext | null>;
+}
+
+/**
+ * In-memory server store for testing and quick prototyping.
+ * Not suitable for production — data does not survive process restart.
+ */
+declare class MemoryServerStore implements ServerStore {
+    private readonly nodeId;
+    private readonly operations;
+    private readonly operationIndex;
+    private readonly versionVector;
+    private closed;
+    constructor(nodeId?: string);
+    getVersionVector(): VersionVector;
+    getNodeId(): string;
+    applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    getOperationCount(): Promise<number>;
+    close(): Promise<void>;
+    /**
+     * Get all stored operations (for test assertions).
+     */
+    getAllOperations(): Operation[];
+    private assertOpen;
+}
+
+/**
+ * PostgreSQL-backed server store using Drizzle ORM.
+ * All reads and writes go through Drizzle's typed query builder.
+ * DDL stays as raw SQL via Drizzle's sql template (standard practice without drizzle-kit).
+ */
+declare class PostgresServerStore implements ServerStore {
+    private readonly nodeId;
+    private readonly db;
+    private readonly versionVector;
+    private readonly ready;
+    private closed;
+    constructor(db: PostgresJsDatabase, nodeId?: string);
+    getVersionVector(): VersionVector;
+    getNodeId(): string;
+    applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    getOperationCount(): Promise<number>;
+    close(): Promise<void>;
+    private initialize;
+    /**
+     * Create tables if they don't exist.
+     * Uses raw SQL via Drizzle's sql template — standard DDL practice without drizzle-kit.
+     */
+    private ensureTables;
+    private serializeOperation;
+    private deserializeOperation;
+    private assertOpen;
+}
+/**
+ * Creates a PostgresServerStore from a PostgreSQL connection string.
+ *
+ * Uses runtime dynamic imports so projects that do not use PostgreSQL
+ * do not need to install `postgres`. Wraps the postgres client with
+ * Drizzle ORM for typed query building.
+ */
+declare function createPostgresServerStore(options: {
+    connectionString: string;
+    nodeId?: string;
+}): Promise<PostgresServerStore>;
+
+/**
+ * SQLite-backed server store using Drizzle ORM.
+ * Persists operations and version vectors to a real database file,
+ * surviving process restarts.
+ */
+declare class SqliteServerStore implements ServerStore {
+    private readonly nodeId;
+    private readonly db;
+    private closed;
+    constructor(db: BetterSQLite3Database, nodeId?: string);
+    getVersionVector(): VersionVector;
+    getNodeId(): string;
+    applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    getOperationCount(): Promise<number>;
+    close(): Promise<void>;
+    /**
+     * Create the operations and sync_state tables if they don't exist.
+     * Uses raw SQL via Drizzle's sql template — standard practice for DDL without drizzle-kit.
+     */
+    private ensureTables;
+    private serializeOperation;
+    private deserializeOperation;
+    private assertOpen;
+}
+/**
+ * Creates a SqliteServerStore with a file-backed or in-memory database.
+ * Handles database creation, Drizzle wrapping, and table setup.
+ *
+ * @param options - Configuration options
+ * @param options.filename - Path to SQLite database file. Defaults to ':memory:' for testing.
+ * @param options.nodeId - Server node ID. Auto-generated if not provided.
+ * @returns A ready-to-use SqliteServerStore
+ *
+ * @example
+ * ```typescript
+ * import { createSqliteServerStore } from '@korajs/server'
+ *
+ * const store = createSqliteServerStore({ filename: './kora-server.db' })
+ * const server = createKoraServer({ store, port: 3001 })
+ * ```
+ */
+declare function createSqliteServerStore(options: {
+    filename?: string;
+    nodeId?: string;
+}): SqliteServerStore;
+
+/**
+ * Auth provider that accepts all connections.
+ * Returns a default anonymous context for any token.
+ * Useful for development and testing.
+ */
+declare class NoAuthProvider implements AuthProvider {
+    authenticate(_token: string): Promise<AuthContext>;
+}
+
+/**
+ * Factory function to create a KoraSyncServer.
+ *
+ * @param config - Server configuration
+ * @returns A new KoraSyncServer instance
+ *
+ * @example
+ * ```typescript
+ * const server = createKoraServer({
+ *   store: new MemoryServerStore(),
+ *   port: 3000,
+ * })
+ * await server.start()
+ * ```
+ */
+declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
+
+export { type AuthContext, type AuthProvider, ClientSession, type ClientSessionOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraSyncServer, type KoraSyncServerConfig, MemoryServerStore, NoAuthProvider, PostgresServerStore, type RelayCallback, ServerCloseHandler, ServerErrorHandler, ServerMessageHandler, type ServerStatus, type ServerStore, ServerTransport, type SessionState, SqliteServerStore, TokenAuthProvider, type TokenAuthProviderOptions, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, createKoraServer, createPostgresServerStore, createSqliteServerStore };