@korajs/server 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { SchemaDefinition, KoraEventEmitter, Operation, VersionVector } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
-import { SyncStore, MessageSerializer, SyncMessage, ApplyResult } from '@korajs/sync';
+import { SyncStore, MessageSerializer, SyncMessage, AwarenessUpdateMessage, 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';
@@ -252,6 +252,10 @@ type SessionState = 'connected' | 'authenticated' | 'syncing' | 'streaming' | 'c
  * Callback invoked when a session has new operations to relay to other sessions.
  */
 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;
 /**
  * Options for creating a ClientSession.
  */
@@ -274,6 +278,8 @@ interface ClientSessionOptions {
     schemaVersion?: 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 closes */
     onClose?: (sessionId: string) => void;
 }
@@ -304,6 +310,7 @@ declare class ClientSession {
     private readonly batchSize;
     private readonly schemaVersion;
     private readonly onRelay;
+    private readonly onAwarenessUpdate;
     private readonly onClose;
     constructor(options: ClientSessionOptions);
     /**
@@ -324,10 +331,16 @@ declare class ClientSession {
     getClientNodeId(): string | null;
     getAuthContext(): AuthContext | null;
     isStreaming(): boolean;
+    /**
+     * Get the transport for this session.
+     * Used by the awareness relay to send messages to this client.
+     */
+    getTransport(): ServerTransport;
     private handleMessage;
     private handleHandshake;
     private handleOperationBatch;
     private sendDelta;
+    private handleAwarenessUpdate;
     private sendError;
     private setSerializerWireFormat;
     private handleTransportClose;
@@ -372,6 +385,7 @@ declare class KoraSyncServer {
     private readonly port;
     private readonly host;
     private readonly path;
+    private readonly awarenessRelay;
     private readonly sessions;
     private readonly httpClients;
     private readonly httpSessionToClient;
@@ -412,6 +426,7 @@ declare class KoraSyncServer {
     getConnectionCount(): number;
     private handleRelay;
     private handleSessionClose;
+    private handleAwarenessRelay;
     private getOrCreateHttpClient;
 }
 
@@ -585,6 +600,88 @@ declare class KoraAuthProvider implements AuthProvider {
     authenticate(token: string): Promise<AuthContext | null>;
 }
 
+/**
+ * Configuration for creating a MixedAuthProvider.
+ */
+interface MixedAuthProviderOptions {
+    /**
+     * Primary auth provider that validates tokens from authenticated users.
+     * Typically a `KoraAuthProvider`, `TokenAuthProvider`, or the result of
+     * `authRoutes.toSyncAuthProvider()`.
+     */
+    primary: AuthProvider;
+    /**
+     * Scopes to apply to anonymous connections.
+     * Each key is a collection name; the value is a filter object
+     * (use `{}` for unrestricted access to that collection).
+     *
+     * @example
+     * ```typescript
+     * // Anonymous users can only sync the 'responses' collection
+     * anonymousScopes: { responses: {} }
+     *
+     * // Anonymous users can read published forms
+     * anonymousScopes: { forms: { status: 'published' } }
+     * ```
+     */
+    anonymousScopes: Record<string, Record<string, unknown>>;
+    /**
+     * Prefix for generated anonymous user IDs.
+     * A unique suffix is appended to each connection.
+     * @default 'anon'
+     */
+    anonymousPrefix?: string;
+}
+/**
+ * Auth provider that supports both authenticated and anonymous connections.
+ *
+ * When a client connects with a valid token, the primary auth provider
+ * handles authentication normally. When a client connects without a token
+ * (or with an invalid one), the connection is accepted as anonymous with
+ * restricted sync scopes.
+ *
+ * This is the recommended pattern for apps that need public data access
+ * alongside authenticated users — for example, a form builder where
+ * authenticated users create forms but anyone can submit responses.
+ *
+ * @example
+ * ```typescript
+ * import { MixedAuthProvider, KoraAuthProvider } from '@korajs/server'
+ *
+ * const auth = new MixedAuthProvider({
+ *   primary: authRoutes.toSyncAuthProvider(),
+ *   anonymousScopes: {
+ *     // Anonymous users can only sync the 'responses' collection
+ *     responses: {},
+ *   },
+ * })
+ *
+ * const server = new KoraSyncServer({ store, auth })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // On the client, return an empty token for unauthenticated users:
+ * const app = createApp({
+ *   schema,
+ *   sync: {
+ *     url: 'wss://my-server.com/kora',
+ *     auth: async () => ({
+ *       token: (await authClient.getAccessToken()) ?? '',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+declare class MixedAuthProvider implements AuthProvider {
+    private readonly primary;
+    private readonly anonymousScopes;
+    private readonly anonymousPrefix;
+    private anonymousCounter;
+    constructor(options: MixedAuthProviderOptions);
+    authenticate(token: string): Promise<AuthContext>;
+}
+
 /**
  * In-memory server store for testing and quick prototyping.
  * Not suitable for production — data does not survive process restart.
@@ -782,6 +879,49 @@ declare class NoAuthProvider implements AuthProvider {
     authenticate(_token: string): Promise<AuthContext>;
 }
 
+/**
+ * Server-side awareness relay. Broadcasts ephemeral awareness states
+ * (cursor positions, user presence) between connected clients.
+ *
+ * Awareness data is never persisted. The relay simply forwards awareness
+ * updates from one client to all other connected clients, and broadcasts
+ * removal notifications when a client disconnects.
+ */
+declare class AwarenessRelay {
+    private readonly clients;
+    /**
+     * Register a client for awareness broadcasting.
+     *
+     * @param sessionId - Unique session identifier
+     * @param clientId - Client-assigned awareness ID
+     * @param transport - Transport for sending messages to this client
+     */
+    addClient(sessionId: string, clientId: number, transport: ServerTransport): void;
+    /**
+     * Remove a client and broadcast its removal to all remaining clients.
+     *
+     * @param sessionId - Session ID of the disconnecting client
+     */
+    removeClient(sessionId: string): void;
+    /**
+     * Handle an incoming awareness update from a client.
+     * Stores the state and relays to all other connected clients.
+     *
+     * @param sessionId - Session ID of the sending client
+     * @param message - The awareness update message
+     */
+    handleUpdate(sessionId: string, message: AwarenessUpdateMessage): void;
+    /**
+     * Get the number of registered awareness clients.
+     */
+    getClientCount(): number;
+    /**
+     * Remove all clients and clear all state.
+     */
+    clear(): void;
+    private broadcastExcept;
+}
+
 /**
  * Factory function to create a KoraSyncServer.
  *
@@ -799,4 +939,4 @@ declare class NoAuthProvider implements AuthProvider {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-export { type AuthContext, type AuthProvider, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type MaterializedRecord, MemoryServerStore, 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, 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 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { SchemaDefinition, KoraEventEmitter, Operation, VersionVector } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
-import { SyncStore, MessageSerializer, SyncMessage, ApplyResult } from '@korajs/sync';
+import { SyncStore, MessageSerializer, SyncMessage, AwarenessUpdateMessage, 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';
@@ -252,6 +252,10 @@ type SessionState = 'connected' | 'authenticated' | 'syncing' | 'streaming' | 'c
  * Callback invoked when a session has new operations to relay to other sessions.
  */
 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;
 /**
  * Options for creating a ClientSession.
  */
@@ -274,6 +278,8 @@ interface ClientSessionOptions {
     schemaVersion?: 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 closes */
     onClose?: (sessionId: string) => void;
 }
@@ -304,6 +310,7 @@ declare class ClientSession {
     private readonly batchSize;
     private readonly schemaVersion;
     private readonly onRelay;
+    private readonly onAwarenessUpdate;
     private readonly onClose;
     constructor(options: ClientSessionOptions);
     /**
@@ -324,10 +331,16 @@ declare class ClientSession {
     getClientNodeId(): string | null;
     getAuthContext(): AuthContext | null;
     isStreaming(): boolean;
+    /**
+     * Get the transport for this session.
+     * Used by the awareness relay to send messages to this client.
+     */
+    getTransport(): ServerTransport;
     private handleMessage;
     private handleHandshake;
     private handleOperationBatch;
     private sendDelta;
+    private handleAwarenessUpdate;
     private sendError;
     private setSerializerWireFormat;
     private handleTransportClose;
@@ -372,6 +385,7 @@ declare class KoraSyncServer {
     private readonly port;
     private readonly host;
     private readonly path;
+    private readonly awarenessRelay;
     private readonly sessions;
     private readonly httpClients;
     private readonly httpSessionToClient;
@@ -412,6 +426,7 @@ declare class KoraSyncServer {
     getConnectionCount(): number;
     private handleRelay;
     private handleSessionClose;
+    private handleAwarenessRelay;
     private getOrCreateHttpClient;
 }
 
@@ -585,6 +600,88 @@ declare class KoraAuthProvider implements AuthProvider {
     authenticate(token: string): Promise<AuthContext | null>;
 }
 
+/**
+ * Configuration for creating a MixedAuthProvider.
+ */
+interface MixedAuthProviderOptions {
+    /**
+     * Primary auth provider that validates tokens from authenticated users.
+     * Typically a `KoraAuthProvider`, `TokenAuthProvider`, or the result of
+     * `authRoutes.toSyncAuthProvider()`.
+     */
+    primary: AuthProvider;
+    /**
+     * Scopes to apply to anonymous connections.
+     * Each key is a collection name; the value is a filter object
+     * (use `{}` for unrestricted access to that collection).
+     *
+     * @example
+     * ```typescript
+     * // Anonymous users can only sync the 'responses' collection
+     * anonymousScopes: { responses: {} }
+     *
+     * // Anonymous users can read published forms
+     * anonymousScopes: { forms: { status: 'published' } }
+     * ```
+     */
+    anonymousScopes: Record<string, Record<string, unknown>>;
+    /**
+     * Prefix for generated anonymous user IDs.
+     * A unique suffix is appended to each connection.
+     * @default 'anon'
+     */
+    anonymousPrefix?: string;
+}
+/**
+ * Auth provider that supports both authenticated and anonymous connections.
+ *
+ * When a client connects with a valid token, the primary auth provider
+ * handles authentication normally. When a client connects without a token
+ * (or with an invalid one), the connection is accepted as anonymous with
+ * restricted sync scopes.
+ *
+ * This is the recommended pattern for apps that need public data access
+ * alongside authenticated users — for example, a form builder where
+ * authenticated users create forms but anyone can submit responses.
+ *
+ * @example
+ * ```typescript
+ * import { MixedAuthProvider, KoraAuthProvider } from '@korajs/server'
+ *
+ * const auth = new MixedAuthProvider({
+ *   primary: authRoutes.toSyncAuthProvider(),
+ *   anonymousScopes: {
+ *     // Anonymous users can only sync the 'responses' collection
+ *     responses: {},
+ *   },
+ * })
+ *
+ * const server = new KoraSyncServer({ store, auth })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // On the client, return an empty token for unauthenticated users:
+ * const app = createApp({
+ *   schema,
+ *   sync: {
+ *     url: 'wss://my-server.com/kora',
+ *     auth: async () => ({
+ *       token: (await authClient.getAccessToken()) ?? '',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+declare class MixedAuthProvider implements AuthProvider {
+    private readonly primary;
+    private readonly anonymousScopes;
+    private readonly anonymousPrefix;
+    private anonymousCounter;
+    constructor(options: MixedAuthProviderOptions);
+    authenticate(token: string): Promise<AuthContext>;
+}
+
 /**
  * In-memory server store for testing and quick prototyping.
  * Not suitable for production — data does not survive process restart.
@@ -782,6 +879,49 @@ declare class NoAuthProvider implements AuthProvider {
     authenticate(_token: string): Promise<AuthContext>;
 }
 
+/**
+ * Server-side awareness relay. Broadcasts ephemeral awareness states
+ * (cursor positions, user presence) between connected clients.
+ *
+ * Awareness data is never persisted. The relay simply forwards awareness
+ * updates from one client to all other connected clients, and broadcasts
+ * removal notifications when a client disconnects.
+ */
+declare class AwarenessRelay {
+    private readonly clients;
+    /**
+     * Register a client for awareness broadcasting.
+     *
+     * @param sessionId - Unique session identifier
+     * @param clientId - Client-assigned awareness ID
+     * @param transport - Transport for sending messages to this client
+     */
+    addClient(sessionId: string, clientId: number, transport: ServerTransport): void;
+    /**
+     * Remove a client and broadcast its removal to all remaining clients.
+     *
+     * @param sessionId - Session ID of the disconnecting client
+     */
+    removeClient(sessionId: string): void;
+    /**
+     * Handle an incoming awareness update from a client.
+     * Stores the state and relays to all other connected clients.
+     *
+     * @param sessionId - Session ID of the sending client
+     * @param message - The awareness update message
+     */
+    handleUpdate(sessionId: string, message: AwarenessUpdateMessage): void;
+    /**
+     * Get the number of registered awareness clients.
+     */
+    getClientCount(): number;
+    /**
+     * Remove all clients and clear all state.
+     */
+    clear(): void;
+    private broadcastExcept;
+}
+
 /**
  * Factory function to create a KoraSyncServer.
  *
@@ -799,4 +939,4 @@ declare class NoAuthProvider implements AuthProvider {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-export { type AuthContext, type AuthProvider, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type MaterializedRecord, MemoryServerStore, 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, 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 };