@korajs/server 1.0.0-beta.10 → 1.0.0-beta.12

package/dist/index.d.cts

@@ -35,6 +35,18 @@ type RoutePredicate = Record<string, RoutePredicateOperators>;
  * Per-collection scope map from auth context.
  */
 type ScopeMap = Record<string, Record<string, unknown>>;
+declare const DEFAULT_MAX_SCOPE_PREDICATE_VALUES = 100;
+/** Canonicalize bounded `$in` predicates so equivalent authorization has one signature. */
+declare function normalizeScopeMap(scopes: ScopeMap, maxValues?: number): ScopeMap;
+/**
+ * Returns true if an operation is visible to a session based on its scopes.
+ *
+ * Rules:
+ * - No scopes configured => visible
+ * - Collection missing from scope map => hidden
+ * - All scoped field/value pairs must match the operation snapshot
+ */
+declare function operationMatchesScopes(op: Operation, scopes: ScopeMap | undefined, fullRecord?: Record<string, unknown> | null): boolean;
 
 /**
  * A materialized record reconstructed from the operation log
@@ -302,6 +314,10 @@ interface ServerMetricsSnapshot {
     peakConnections: number;
     connectionsTotal: number;
     operationsReceived: number;
+    batchesReceived: number;
+    uniqueOperationsReceived: number;
+    duplicateOperationsReceived: number;
+    rejectedOperations: number;
     operationsSent: number;
     bytesReceived: number;
     bytesSent: number;
@@ -320,6 +336,10 @@ interface ClientMetrics {
     state: SessionState$1;
     connectedAt: number;
     operationsReceived: number;
+    batchesReceived: number;
+    uniqueOperationsReceived: number;
+    duplicateOperationsReceived: number;
+    rejectedOperations: number;
     operationsSent: number;
     authContext: AuthContext | null;
 }
@@ -328,6 +348,10 @@ declare class ServerMetricsCollector {
     private peakConnections;
     private connectionsTotal;
     private operationsReceived;
+    private batchesReceived;
+    private uniqueOperationsReceived;
+    private duplicateOperationsReceived;
+    private rejectedOperations;
     private operationsSent;
     private bytesReceived;
     private bytesSent;
@@ -345,7 +369,11 @@ declare class ServerMetricsCollector {
     /** 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;
+    recordReceived(sessionId: string, count: number, byteSize: number, outcomes?: {
+        unique: number;
+        duplicates: number;
+        rejected: number;
+    }): void;
     /** Record operations sent to a client. */
     recordSent(sessionId: string, count: number, byteSize: number): void;
     /** Record an error. */
@@ -786,6 +814,10 @@ interface AuthContext {
     userId: string;
     /** Per-collection sync scopes (optional) */
     scopes?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative records this session may receive. Overrides `scopes`. */
+    downlinkScopes?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative records this session may upload. Overrides `scopes`. */
+    uplinkScopes?: Record<string, Record<string, unknown>>;
     /** Arbitrary metadata about the authenticated user */
     metadata?: Record<string, unknown>;
 }
@@ -1157,6 +1189,7 @@ declare class ClientSession {
     private clientNodeId;
     private authContext;
     private syncQuerySubsets;
+    private scopeExitPolicy;
     private resumeDeltaCursor;
     /**
      * The delivery watermark the client reported at handshake, or null when the client
@@ -1181,7 +1214,7 @@ declare class ClientSession {
      * batches every server tick while the first batch is still being applied.
      */
     private lastDeliveryPushAttemptAtMs;
-    private deliveryStallRepeatCount;
+    private outstandingDelivery;
     /** Serializes incremental delivery pushes so their batches never interleave. */
     private deliveryPushChain;
     /**
@@ -1252,6 +1285,7 @@ declare class ClientSession {
      */
     pushDeliveryStreamIfSupported(staleMs?: number, options?: {
         trackStall?: boolean;
+        serverFrontier?: number;
     }): void;
     /**
      * Close this session.
@@ -1310,6 +1344,9 @@ declare class ClientSession {
     /** Build, track, and send one chained delivery-stream batch. */
     private sendDeliveryBatch;
     private operationVisibleToClient;
+    /** Upload authorization is independent from the client's downloaded/query view. */
+    private operationAllowedFromClient;
+    private scopeRetractionFor;
     /**
      * 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
@@ -2011,4 +2048,4 @@ declare class AwarenessRelay {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-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, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, 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, isRetriableRejection };
+export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, DEFAULT_MAX_SCOPE_PREDICATE_VALUES, 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, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, 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, isRetriableRejection, normalizeScopeMap, operationMatchesScopes };

package/dist/index.d.ts

@@ -35,6 +35,18 @@ type RoutePredicate = Record<string, RoutePredicateOperators>;
  * Per-collection scope map from auth context.
  */
 type ScopeMap = Record<string, Record<string, unknown>>;
+declare const DEFAULT_MAX_SCOPE_PREDICATE_VALUES = 100;
+/** Canonicalize bounded `$in` predicates so equivalent authorization has one signature. */
+declare function normalizeScopeMap(scopes: ScopeMap, maxValues?: number): ScopeMap;
+/**
+ * Returns true if an operation is visible to a session based on its scopes.
+ *
+ * Rules:
+ * - No scopes configured => visible
+ * - Collection missing from scope map => hidden
+ * - All scoped field/value pairs must match the operation snapshot
+ */
+declare function operationMatchesScopes(op: Operation, scopes: ScopeMap | undefined, fullRecord?: Record<string, unknown> | null): boolean;
 
 /**
  * A materialized record reconstructed from the operation log
@@ -302,6 +314,10 @@ interface ServerMetricsSnapshot {
     peakConnections: number;
     connectionsTotal: number;
     operationsReceived: number;
+    batchesReceived: number;
+    uniqueOperationsReceived: number;
+    duplicateOperationsReceived: number;
+    rejectedOperations: number;
     operationsSent: number;
     bytesReceived: number;
     bytesSent: number;
@@ -320,6 +336,10 @@ interface ClientMetrics {
     state: SessionState$1;
     connectedAt: number;
     operationsReceived: number;
+    batchesReceived: number;
+    uniqueOperationsReceived: number;
+    duplicateOperationsReceived: number;
+    rejectedOperations: number;
     operationsSent: number;
     authContext: AuthContext | null;
 }
@@ -328,6 +348,10 @@ declare class ServerMetricsCollector {
     private peakConnections;
     private connectionsTotal;
     private operationsReceived;
+    private batchesReceived;
+    private uniqueOperationsReceived;
+    private duplicateOperationsReceived;
+    private rejectedOperations;
     private operationsSent;
     private bytesReceived;
     private bytesSent;
@@ -345,7 +369,11 @@ declare class ServerMetricsCollector {
     /** 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;
+    recordReceived(sessionId: string, count: number, byteSize: number, outcomes?: {
+        unique: number;
+        duplicates: number;
+        rejected: number;
+    }): void;
     /** Record operations sent to a client. */
     recordSent(sessionId: string, count: number, byteSize: number): void;
     /** Record an error. */
@@ -786,6 +814,10 @@ interface AuthContext {
     userId: string;
     /** Per-collection sync scopes (optional) */
     scopes?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative records this session may receive. Overrides `scopes`. */
+    downlinkScopes?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative records this session may upload. Overrides `scopes`. */
+    uplinkScopes?: Record<string, Record<string, unknown>>;
     /** Arbitrary metadata about the authenticated user */
     metadata?: Record<string, unknown>;
 }
@@ -1157,6 +1189,7 @@ declare class ClientSession {
     private clientNodeId;
     private authContext;
     private syncQuerySubsets;
+    private scopeExitPolicy;
     private resumeDeltaCursor;
     /**
      * The delivery watermark the client reported at handshake, or null when the client
@@ -1181,7 +1214,7 @@ declare class ClientSession {
      * batches every server tick while the first batch is still being applied.
      */
     private lastDeliveryPushAttemptAtMs;
-    private deliveryStallRepeatCount;
+    private outstandingDelivery;
     /** Serializes incremental delivery pushes so their batches never interleave. */
     private deliveryPushChain;
     /**
@@ -1252,6 +1285,7 @@ declare class ClientSession {
      */
     pushDeliveryStreamIfSupported(staleMs?: number, options?: {
         trackStall?: boolean;
+        serverFrontier?: number;
     }): void;
     /**
      * Close this session.
@@ -1310,6 +1344,9 @@ declare class ClientSession {
     /** Build, track, and send one chained delivery-stream batch. */
     private sendDeliveryBatch;
     private operationVisibleToClient;
+    /** Upload authorization is independent from the client's downloaded/query view. */
+    private operationAllowedFromClient;
+    private scopeRetractionFor;
     /**
      * 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
@@ -2011,4 +2048,4 @@ declare class AwarenessRelay {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-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, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, 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, isRetriableRejection };
+export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, DEFAULT_MAX_SCOPE_PREDICATE_VALUES, 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, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, 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, isRetriableRejection, normalizeScopeMap, operationMatchesScopes };