RxDB Server
Interfaces
Interfaces
ReplicationClientOptions
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
database | EpicFlowDatabase | Yes | Local RxDB database to sync |
remoteUrl | string | Yes | Remote WebSocket URL to connect to |
collections | string[] | undefined | No | Collections to replicate (if not specified, replicates all) |
ServerInstance
Server instance returned by createServer
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
rxServer | any | Yes | |
database | EpicFlowDatabase | Yes |
AuthData
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
type | "service" | "jwt" | "api_token" | Yes | |
userId | string | undefined | No | |
serviceAccountId | string | undefined | No | |
email | string | undefined | No | |
domainId | string | Yes | |
orgId | string | undefined | No | |
scopes | string[] | Yes | |
tokenName | string | undefined | No |
AuthValidatorConfig
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
tokenManager | TokenManager | Yes | |
storage | AuthStorageAdapter | Yes | |
domainId | string | Yes | |
internalAuthToken | string | undefined | No |
CollectionReplicationStatus
Status of a collection's replication
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
collectionName | string | Yes | Collection name |
active | boolean | Yes | Whether replication is currently active |
pushed | number | Yes | Number of documents pushed to remote |
pulled | number | Yes | Number of documents pulled from remote |
lastError | string | null | Yes | Last error message (if any) |
lastSync | number | null | Yes | Timestamp of last successful sync |
RemoteReplicationConfig
Remote RxDB server replication configuration types
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
enabled | boolean | Yes | Enable or disable remote replication |
When true, this server will connect to the remote server and sync data. When false, the server operates in standalone mode. | | url | string | Yes | Remote RxDB server WebSocket URL
The WebSocket endpoint of the remote RxDB server to sync with. Must use wss:// protocol for production, ws:// for local testing. | | authToken | string | Yes | JWT authentication token for remote server
A valid JWT token issued by the remote server's authentication system. The token must include claims for domainId, scopes (read/write), and expiration. | | domainId | string | Yes | Domain ID to sync with remote server
Only documents with this domainId will be replicated. Must match a domain that exists on both local and remote servers. | | syncInterval | number | Yes | Sync interval in milliseconds
How often to check for new changes from the remote server. Lower values provide more real-time sync but increase network usage. | | live | boolean | Yes | Enable live (real-time) replication
When true, changes are synced immediately via WebSocket connection. When false, sync only happens at the interval specified by syncInterval. | | retryTime | number | Yes | Retry delay on connection failure (milliseconds)
How long to wait before retrying a failed WebSocket connection. Uses exponential backoff for subsequent retries. | | pushBatchSize | number | Yes | Batch size for push operations
Number of documents to batch together when pushing changes to remote server. Higher values are more efficient but use more memory. | | collections | string[] \| undefined | No | Collections to replicate (optional)
If specified, only these collections will be replicated. If empty or undefined, all collections are replicated. | | excludeCollections | string[] \| undefined | No | Collections to exclude from replication (optional)
Collections listed here will NOT be replicated. Takes precedence over collections if both are specified. |
LoggerConfig
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
level | LogLevel | Yes | |
prefix | string | undefined | No | |
timestamp | boolean | undefined | No | |
colors | boolean | undefined | No |
WebSocketAuthContext
WebSocket authentication context returned after successful authentication
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
data | { domainId: string; permissions: string[]; userId?: string; serviceAccountId?: string; } | Yes | |
validUntil | number | Yes |
WebSocketServerOptions
Configuration options for WebSocket server attachment
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
httpServer | http.Server<typeof http.IncomingMessage, typeof http.ServerResponse> | Yes | HTTP server instance to attach WebSocket upgrade handler to |
database | EpicFlowDatabase | Yes | RxDB database instance containing collections for replication |
path | string | undefined | No | WebSocket server path for upgrade endpoint |
WebSocketServerState
WebSocket server state returned from attachment Provides methods to control the WebSocket server lifecycle
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
close | () => Promise<void> | Yes | Close the WebSocket server and disconnect all clients |
DocumentChange
Change event for a single document modification.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
document | RxDocumentData<RxDocType> | Yes | The document after the change. |
metadata | DocumentMetadata | Yes | Document metadata including sequence number. |
operation | "INSERT" | "UPDATE" | "DELETE" | Yes | Type of operation that caused the change. |
previous | RxDocumentData<RxDocType> | undefined | No | The document before the change (for updates). |
| undefined for inserts. |
FilesystemStorageOptions
Configuration options for filesystem storage.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
basePath | string | Yes | Base directory path where database files will be stored. |
| Each collection will have its own subdirectory. |
DocumentMetadata
Internal document metadata tracked by the storage engine.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
sequence | number | Yes | Monotonically increasing sequence number for change tracking. |
| Used for implementing checkpoints and change feeds. | |||
lastModified | string | Yes | ISO 8601 timestamp when the document was last modified. |
deleted | boolean | Yes | Whether this document has been deleted (tombstone). |
CollectionMetadata
Collection-level metadata stored in .meta.json file.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
collectionName | string | Yes | Name of the collection. |
currentSequence | number | Yes | Current sequence number - incremented on each write. |
createdAt | string | Yes | ISO 8601 timestamp when the collection was created. |
lastModified | string | Yes | ISO 8601 timestamp when metadata was last updated. |
schemaVersion | number | Yes | Schema version of the collection. |
EventFile
Event data written to .events/ directory for multi-instance sync.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
pid | number | Yes | Process ID that generated this event. |
timestamp | string | Yes | ISO 8601 timestamp when event was created. |
documentIds | string[] | Yes | Document IDs that were modified. |
sequenceRange | { start: number; end: number; } | Yes | Sequence number range affected by this event. |
CacheEntry
In-memory document cache entry.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
document | RxDocumentData<RxDocType> | Yes | The document data. |
metadata | DocumentMetadata | Yes | Document metadata. |
lastAccess | number | Yes | When this entry was last accessed (for LRU eviction). |
Checkpoint
Checkpoint used for pagination of change feeds.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
sequence | number | Yes | Sequence number up to which changes have been consumed. |
id | string | Yes | Document ID at this sequence (for stable ordering). |
BulkWriteResult
Result of a bulk write operation.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
success | RxDocumentData<RxDocType>[] | Yes | Documents that were successfully written. |
error | { document: RxDocumentData<RxDocType>; isConflict: boolean; error: Error; }[] | Yes | Documents that failed to write due to conflicts or errors. |
StorageInstanceState
Internal storage state for each instance.
Properties:
| Property | Type | Required | Description |
|---|---|---|---|
collectionPath | string | Yes | Base path for this collection's data. |
metaPath | string | Yes | Path to the .meta.json file. |
eventsPath | string | Yes | Path to the .events/ directory. |
cache | Map<string, CacheEntry<RxDocType>> | Yes | In-memory document cache (LRU). |
maxCacheSize | number | Yes | Maximum cache size (number of documents). |
closed | boolean | Yes | Whether this instance has been closed. |
metadata | CollectionMetadata | Yes | Collection metadata (loaded from disk). |