@korajs/server 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,10 +1,129 @@
 import { SchemaDefinition, KoraEventEmitter, Operation, VersionVector } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
-import { SyncStore, MessageSerializer, SyncMessage, AwarenessUpdateMessage, ApplyResult } from '@korajs/sync';
+import { SyncStore, MessageSerializer, SyncMessage, AwarenessUpdateMessage, YjsDocUpdateMessage, ApplyResult } from '@korajs/sync';
 import { S as ServerTransport, a as ServerMessageHandler, b as ServerCloseHandler, c as ServerErrorHandler } from './server-transport-CU1BLWgr.js';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
 
+/**
+ * Snapshot of server-side sync metrics at a point in time.
+ */
+interface ServerMetricsSnapshot {
+    connectedClients: number;
+    connectedNodeIds: string[];
+    peakConnections: number;
+    connectionsTotal: number;
+    operationsReceived: number;
+    operationsSent: number;
+    bytesReceived: number;
+    bytesSent: number;
+    clients: ClientMetrics[];
+    uptime: number;
+    totalOperations: number;
+    errorCount: number;
+    schemaVersion: number;
+}
+/**
+ * Per-client metrics tracked by the server.
+ */
+interface ClientMetrics {
+    sessionId: string;
+    nodeId: string | null;
+    state: SessionState$1;
+    connectedAt: number;
+    operationsReceived: number;
+    operationsSent: number;
+    authContext: AuthContext | null;
+}
+declare class ServerMetricsCollector {
+    private startedAt;
+    private peakConnections;
+    private connectionsTotal;
+    private operationsReceived;
+    private operationsSent;
+    private bytesReceived;
+    private bytesSent;
+    private errorCount;
+    private schemaVersion;
+    private readonly clientMetrics;
+    /** Record a new client connection. */
+    recordConnection(sessionId: string): void;
+    /** Record a client disconnection. */
+    recordDisconnection(sessionId: string): void;
+    /** Update the node ID after a handshake completes. */
+    recordHandshake(sessionId: string, nodeId: string): void;
+    /** Update session state. */
+    updateSessionState(sessionId: string, state: SessionState$1): void;
+    /** Record authentication context for a session. */
+    recordAuth(sessionId: string, authContext: AuthContext | null): void;
+    /** Record operations received from a client. */
+    recordReceived(sessionId: string, count: number, byteSize: number): void;
+    /** Record operations sent to a client. */
+    recordSent(sessionId: string, count: number, byteSize: number): void;
+    /** Record an error. */
+    recordError(): void;
+    /** Set the schema version. */
+    setSchemaVersion(version: number): void;
+    /** Return a full snapshot of current metrics. */
+    getSnapshot(totalOperations: number): ServerMetricsSnapshot;
+    /** Reset all metrics. */
+    reset(): void;
+}
+
+/**
+ * Log severity levels.
+ */
+type LogLevel = 'info' | 'warn' | 'error';
+/**
+ * A structured log entry with timestamp and metadata.
+ */
+interface LogEntry {
+    timestamp: number;
+    level: LogLevel;
+    event: string;
+    sessionId?: string;
+    nodeId?: string;
+    duration?: number;
+    count?: number;
+    bytes?: number;
+    error?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Logger interface for structured logging.
+ * Implementations control output format and destination.
+ */
+interface Logger {
+    log(entry: LogEntry): void;
+    child?(context: Partial<LogEntry>): Logger;
+}
+/**
+ * Creates a JSON-lines logger that writes to stdout/stderr.
+ * Suitable for production use where log aggregators (Datadog, Loki, etc.) consume JSON.
+ */
+declare function createJsonLogger(writer?: {
+    info: (s: string) => void;
+    error: (s: string) => void;
+}): Logger;
+/**
+ * Creates a pretty-printed logger for development use.
+ * Writes human-readable colored output to the terminal.
+ */
+declare function createPrettyLogger(writer?: {
+    write: (s: string) => void;
+}): Logger;
+/**
+ * A logger that discards all entries (for testing or when logging is disabled).
+ */
+declare function createSilentLogger(): Logger;
+/**
+ * Creates a logger based on the NODE_ENV environment variable.
+ * - production: JSON lines to stdout/stderr
+ * - test: silent
+ * - otherwise: pretty-printed to stdout
+ */
+declare function createDefaultLogger(): Logger;
+
 /**
  * A materialized record reconstructed from the operation log
  * or read from a materialized collection table.
@@ -48,6 +167,8 @@ interface ServerStore extends SyncStore {
      * @param schema - The schema definition describing all collections
      */
     setSchema(schema: SchemaDefinition): Promise<void>;
+    /** Schema used for materialized tables and server-side validation, if set. */
+    getSchema(): SchemaDefinition | null;
     /**
      * Get all records from a materialized collection.
      * When schema is set, reads directly from the collection table (O(1) indexed).
@@ -85,6 +206,23 @@ interface ServerStore extends SyncStore {
      * @returns Number of matching records
      */
     countCollection(collection: string, where?: Record<string, unknown>): Promise<number>;
+    /**
+     * Export all data as a portable backup binary.
+     * Ships operations, version vector, and metadata in a self-describing format
+     * with SHA-256 checksum.
+     */
+    exportBackup(): Promise<Uint8Array>;
+    /**
+     * Restore data from a portable backup binary.
+     * Operations are applied through applyRemoteOperation for safe merge.
+     *
+     * @param data - Backup binary
+     * @param merge - If true, merge with existing operations; if false, replace all
+     */
+    importBackup(data: Uint8Array, merge?: boolean): Promise<{
+        operationsRestored: number;
+        success: boolean;
+    }>;
 }
 
 /**
@@ -132,8 +270,22 @@ interface KoraSyncServerConfig {
     batchSize?: number;
     /** Schema version the server expects. Defaults to 1. */
     schemaVersion?: number;
+    /**
+     * Inclusive range of client schema versions accepted at handshake.
+     * Defaults to `{ min: schemaVersion, max: schemaVersion }`.
+     */
+    supportedSchemaVersions?: {
+        min: number;
+        max: number;
+    };
     /** WebSocket path (standalone mode). Defaults to '/'. */
     path?: string;
+    /** Structured logger. Defaults to pretty-print in dev, JSON lines in production. */
+    logger?: Logger;
+    /** Server metrics collector. Created automatically if omitted. */
+    metricsCollector?: ServerMetricsCollector;
+    /** Enable built-in dashboard and metrics endpoints. Defaults to true. */
+    enableDashboard?: boolean;
 }
 /**
  * Request envelope for the server-side HTTP sync endpoint.
@@ -161,6 +313,15 @@ interface HttpSyncResponse {
     /** Optional response headers */
     headers?: Record<string, string>;
 }
+/**
+ * Session state machine states.
+ * - connected: initial state after transport connects
+ * - authenticated: auth check passed (or skipped)
+ * - syncing: exchanging delta operations during handshake
+ * - streaming: steady state, real-time operation relay
+ * - closed: session terminated
+ */
+type SessionState$1 = 'connected' | 'authenticated' | 'syncing' | 'streaming' | 'closed';
 /**
  * Runtime status of a KoraSyncServer.
  */
@@ -173,6 +334,24 @@ interface ServerStatus {
     port: number | null;
     /** Total operations stored */
     totalOperations: number;
+    /** Server uptime in milliseconds */
+    uptime: number;
+    /** Server package version */
+    version: string;
+    /** Schema version the server expects */
+    schemaVersion: number;
+    /** Array of connected node IDs */
+    connectedNodeIds: string[];
+    /** Peak connections since server start */
+    peakConnections: number;
+    /** Total connections handled since server start */
+    connectionsTotal: number;
+    /** Operations received since server start */
+    operationsReceived: number;
+    /** Operations sent since server start */
+    operationsSent: number;
+    /** Error count since server start */
+    errorCount: number;
 }
 
 interface HttpPollResponse {
@@ -256,6 +435,10 @@ type RelayCallback = (sourceSessionId: string, operations: Operation[]) => void;
  * Callback invoked when a session receives an awareness update to relay to other sessions.
  */
 type AwarenessRelayCallback = (sourceSessionId: string, message: AwarenessUpdateMessage) => void;
+/**
+ * Callback invoked when a session receives a Yjs doc channel update to relay.
+ */
+type YjsDocRelayCallback = (sourceSessionId: string, message: YjsDocUpdateMessage) => void;
 /**
  * Options for creating a ClientSession.
  */
@@ -276,12 +459,23 @@ interface ClientSessionOptions {
     batchSize?: number;
     /** Schema version the server expects */
     schemaVersion?: number;
+    /** Inclusive client schema versions accepted at handshake */
+    supportedSchemaVersions?: {
+        min: number;
+        max: number;
+    };
     /** Called when this session has operations to relay to other sessions */
     onRelay?: RelayCallback;
     /** Called when this session receives an awareness update to broadcast */
     onAwarenessUpdate?: AwarenessRelayCallback;
+    /** Called when this session receives a Yjs doc channel update to broadcast */
+    onYjsDocUpdate?: YjsDocRelayCallback;
     /** Called when this session closes */
     onClose?: (sessionId: string) => void;
+    /** Maximum serialized operation size in bytes. Defaults to 256 KiB. */
+    maxOperationBytes?: number;
+    /** Maximum operations accepted per minute for this session. Defaults to 600. */
+    maxOpsPerMinute?: number;
 }
 /**
  * Handles the sync protocol for a single connected client.
@@ -301,6 +495,8 @@ declare class ClientSession {
     private state;
     private clientNodeId;
     private authContext;
+    private syncQuerySubsets;
+    private resumeDeltaCursor;
     private readonly sessionId;
     private readonly transport;
     private readonly store;
@@ -309,9 +505,14 @@ declare class ClientSession {
     private readonly emitter;
     private readonly batchSize;
     private readonly schemaVersion;
+    private readonly supportedSchemaVersions;
     private readonly onRelay;
     private readonly onAwarenessUpdate;
+    private readonly onYjsDocUpdate;
     private readonly onClose;
+    private readonly maxOperationBytes;
+    private readonly maxOpsPerMinute;
+    private readonly rateLimiter;
     constructor(options: ClientSessionOptions);
     /**
      * Start handling messages from the client transport.
@@ -336,11 +537,18 @@ declare class ClientSession {
      * Used by the awareness relay to send messages to this client.
      */
     getTransport(): ServerTransport;
-    private handleMessage;
+    private messageChain;
+    /** Send to the client when the transport is still connected; no-op otherwise. */
+    private sendToClient;
+    private enqueueMessage;
+    private handleMessageAsync;
+    private handleMessageFailure;
     private handleHandshake;
     private handleOperationBatch;
     private sendDelta;
+    private operationVisibleToClient;
     private handleAwarenessUpdate;
+    private handleYjsDocUpdate;
     private sendError;
     private setSerializerWireFormat;
     private handleTransportClose;
@@ -382,16 +590,34 @@ declare class KoraSyncServer {
     private readonly maxConnections;
     private readonly batchSize;
     private readonly schemaVersion;
+    private readonly supportedSchemaVersions;
     private readonly port;
     private readonly host;
     private readonly path;
+    private readonly logger;
+    private readonly metrics;
     private readonly awarenessRelay;
+    private readonly yjsDocRelay;
     private readonly sessions;
     private readonly httpClients;
     private readonly httpSessionToClient;
+    private readonly serverVersion;
     private wsServer;
     private running;
     constructor(config: KoraSyncServerConfig);
+    /**
+     * Subscribe to session-level events for metrics collection and logging.
+     * Called when a new session is created.
+     */
+    private attachSessionEvents;
+    /**
+     * Get the metrics collector for external access (e.g., HTTP endpoints).
+     */
+    getMetricsCollector(): ServerMetricsCollector;
+    /**
+     * Get the logger for external access (e.g., event streaming).
+     */
+    getLogger(): Logger;
     /**
      * Start the WebSocket server in standalone mode.
      *
@@ -427,6 +653,7 @@ declare class KoraSyncServer {
     private handleRelay;
     private handleSessionClose;
     private handleAwarenessRelay;
+    private handleYjsDocRelay;
     private getOrCreateHttpClient;
 }
 
@@ -445,6 +672,48 @@ interface ProductionServerConfig {
     syncPath?: string;
     /** Additional KoraSyncServer options */
     syncOptions?: Omit<KoraSyncServerConfig, 'store' | 'port' | 'host' | 'path'>;
+    /**
+     * Optional HTTP route handlers mounted before static file serving.
+     *
+     * This is intentionally framework-agnostic so packages such as
+     * `@korajs/auth` can plug into the production server without requiring
+     * Express, Hono, or another HTTP framework.
+     */
+    httpRoutes?: ProductionHttpRoute[];
+    /**
+     * Optional token protection for operational endpoints.
+     *
+     * When a token is omitted, the matching endpoint group remains public for
+     * backward compatibility. Production apps should set at least adminToken and
+     * backupToken.
+     */
+    operationalAuth?: ProductionOperationalAuth;
+}
+interface ProductionOperationalAuth {
+    /** Protects /__kora, /__kora/status, and /__kora/events. */
+    adminToken?: string;
+    /** Protects /__kora/metrics. Falls back to adminToken when omitted. */
+    metricsToken?: string;
+    /** Protects /__kora/backup/*. Falls back to adminToken when omitted. */
+    backupToken?: string;
+}
+interface ProductionHttpRouteRequest {
+    method: string;
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string | string[] | undefined>;
+    query?: Record<string, string | string[] | undefined>;
+    ip?: string;
+}
+interface ProductionHttpRouteResponse {
+    status: number;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+interface ProductionHttpRoute {
+    /** URL path prefix, for example `/auth`. */
+    path: string;
+    handle(request: ProductionHttpRouteRequest): Promise<ProductionHttpRouteResponse>;
 }
 /**
  * A production server handle returned by createProductionServer.
@@ -457,22 +726,17 @@ interface ProductionServer {
 }
 /**
  * Creates a production server that serves both static files and WebSocket sync
- * on a single port. This is the recommended way to deploy a Kora app — one port
- * means one tunnel (ngrok, cloudflared) handles everything.
+ * on a single port, plus built-in dashboard and observability endpoints.
  *
  * @param config - Production server configuration
  * @returns A ProductionServer instance
  *
  * @example
  * ```typescript
- * import { createProductionServer, createSqliteServerStore } from '@korajs/server'
- *
  * const server = createProductionServer({
  *   store: createSqliteServerStore({ filename: './kora-server.db' }),
  * })
- *
  * const url = await server.start()
- * console.log(`App running at ${url}`)
  * ```
  */
 declare function createProductionServer(config: ProductionServerConfig): ProductionServer;
@@ -517,6 +781,11 @@ interface TokenValidator {
         dev: string;
         type: string;
     } | null;
+    validateTokenWithRevocation?(token: string): Promise<{
+        sub: string;
+        dev: string;
+        type: string;
+    } | null>;
 }
 /**
  * Looks up a user by ID. Returns null if the user doesn't exist.
@@ -543,6 +812,8 @@ interface KoraAuthProviderOptions {
     /**
      * Token validator that verifies JWT signatures and returns claims.
      * Typically a `TokenManager` instance from `@korajs/auth/server`.
+     * If the validator also implements `validateTokenWithRevocation`, the sync
+     * server uses it so signed-out sessions and revoked devices are rejected.
      */
     tokenValidator: TokenValidator;
     /**
@@ -701,6 +972,7 @@ declare class MemoryServerStore implements ServerStore {
     constructor(nodeId?: string);
     getVersionVector(): VersionVector;
     getNodeId(): string;
+    getSchema(): SchemaDefinition | null;
     setSchema(schema: SchemaDefinition): Promise<void>;
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
@@ -710,6 +982,15 @@ declare class MemoryServerStore implements ServerStore {
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
     countCollection(collection: string, where?: Record<string, unknown>): Promise<number>;
     close(): Promise<void>;
+    /**
+     * Wipes all in-memory state. For tests and E2E isolation only.
+     */
+    resetForTests(): void;
+    exportBackup(): Promise<Uint8Array>;
+    importBackup(data: Uint8Array, merge?: boolean): Promise<{
+        operationsRestored: number;
+        success: boolean;
+    }>;
     /**
      * Get all stored operations (for test assertions).
      */
@@ -739,6 +1020,7 @@ declare class PostgresServerStore implements ServerStore {
     constructor(db: PostgresJsDatabase, nodeId?: string);
     getVersionVector(): VersionVector;
     getNodeId(): string;
+    getSchema(): SchemaDefinition | null;
     setSchema(schema: SchemaDefinition): Promise<void>;
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
@@ -748,6 +1030,11 @@ declare class PostgresServerStore implements ServerStore {
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
     countCollection(collection: string, where?: Record<string, unknown>): Promise<number>;
     close(): Promise<void>;
+    exportBackup(): Promise<Uint8Array>;
+    importBackup(data: Uint8Array, merge?: boolean): Promise<{
+        operationsRestored: number;
+        success: boolean;
+    }>;
     /**
      * Rebuild a single record in the materialized collection table by replaying
      * all operations for that record.
@@ -801,6 +1088,7 @@ declare class SqliteServerStore implements ServerStore {
     constructor(db: BetterSQLite3Database, nodeId?: string);
     getVersionVector(): VersionVector;
     getNodeId(): string;
+    getSchema(): SchemaDefinition | null;
     setSchema(schema: SchemaDefinition): Promise<void>;
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
@@ -810,6 +1098,11 @@ declare class SqliteServerStore implements ServerStore {
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
     countCollection(collection: string, where?: Record<string, unknown>): Promise<number>;
     close(): Promise<void>;
+    exportBackup(): Promise<Uint8Array>;
+    importBackup(data: Uint8Array, merge?: boolean): Promise<{
+        operationsRestored: number;
+        success: boolean;
+    }>;
     /**
      * Rebuild a single record in the materialized collection table by replaying
      * all operations for that record. Called within the applyRemoteOperation
@@ -939,4 +1232,4 @@ declare class AwarenessRelay {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type MaterializedRecord, MemoryServerStore, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, PostgresServerStore, type ProductionServer, type ProductionServerConfig, 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, createProductionServer, createSqliteServerStore };
+export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, type RelayCallback, ServerCloseHandler, ServerErrorHandler, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerStatus, type ServerStore, ServerTransport, type SessionState, SqliteServerStore, TokenAuthProvider, type TokenAuthProviderOptions, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore };