@topgunbuild/server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,311 @@
+import { LWWRecord, ORMapRecord, Principal, PermissionPolicy, LWWMap, ORMap, PermissionType } from '@topgunbuild/core';
+import { WebSocket } from 'ws';
+import { PoolConfig, Pool } from 'pg';
+import pino from 'pino';
+
+type ORMapValue<V> = {
+    type: 'OR';
+    records: ORMapRecord<V>[];
+};
+type ORMapTombstones = {
+    type: 'OR_TOMBSTONES';
+    tags: string[];
+};
+type StorageValue<V> = LWWRecord<V> | ORMapValue<V> | ORMapTombstones;
+/**
+ * Server Persistence Interface (MapStore).
+ * Aligned with specifications/06_SERVER_INTEGRATIONS.md
+ *
+ * Note: We include mapName in all methods because a single storage adapter
+ * instance typically handles multiple maps in the system (e.g. single DB connection).
+ */
+interface IServerStorage {
+    /**
+     * Initialize the storage connection.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Close the storage connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Loads the value of a given key.
+     * Called when a client requests a key that is not in the Server RAM (if using partial loading),
+     * or during sync.
+     */
+    load(mapName: string, key: string): Promise<StorageValue<any> | undefined>;
+    /**
+     * Loads multiple keys.
+     * Optimization for batch requests.
+     */
+    loadAll(mapName: string, keys: string[]): Promise<Map<string, StorageValue<any>>>;
+    /**
+     * Loads all keys from the store for a specific map.
+     * Used for pre-loading the cache on startup or understanding dataset size.
+     */
+    loadAllKeys(mapName: string): Promise<string[]>;
+    /**
+     * Stores the key-value pair.
+     */
+    store(mapName: string, key: string, record: StorageValue<any>): Promise<void>;
+    /**
+     * Stores multiple entries.
+     * Used for efficient batch writes to the DB.
+     */
+    storeAll(mapName: string, records: Map<string, StorageValue<any>>): Promise<void>;
+    /**
+     * Deletes the entry with the given key.
+     */
+    delete(mapName: string, key: string): Promise<void>;
+    /**
+     * Deletes multiple entries.
+     */
+    deleteAll(mapName: string, keys: string[]): Promise<void>;
+}
+
+interface ServerOp {
+    mapName: string;
+    key: string;
+    opType: 'PUT' | 'REMOVE' | 'OR_ADD' | 'OR_REMOVE';
+    record?: LWWRecord<any>;
+    orRecord?: ORMapRecord<any>;
+    orTag?: string;
+    id?: string;
+}
+interface ConnectionContext {
+    clientId: string;
+    socket?: WebSocket;
+    principal?: Principal;
+    isAuthenticated: boolean;
+}
+interface OpContext extends ConnectionContext {
+    fromCluster: boolean;
+    originalSenderId?: string;
+}
+interface IInterceptor {
+    /**
+     * Name of the interceptor for logging and debugging.
+     */
+    name: string;
+    /**
+     * Called when a new client connects.
+     * Throwing an error here will reject the connection.
+     */
+    onConnection?(context: ConnectionContext): Promise<void>;
+    /**
+     * Called when a client disconnects.
+     */
+    onDisconnect?(context: ConnectionContext): Promise<void>;
+    /**
+     * Called before an operation is applied to the local map/storage.
+     * Return the (possibly modified) op.
+     * Return null to silently drop the operation (no error sent to client, no persistence).
+     * Throwing an error will reject the operation and notify the client.
+     */
+    onBeforeOp?(op: ServerOp, context: OpContext): Promise<ServerOp | null>;
+    /**
+     * Called after an operation has been successfully applied and stored.
+     */
+    onAfterOp?(op: ServerOp, context: OpContext): Promise<void>;
+}
+
+interface TLSConfig {
+    /**
+     * Enable TLS for client-facing server (HTTPS + WSS)
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Path to certificate file (PEM format)
+     * Supports chain certificates
+     */
+    certPath: string;
+    /**
+     * Path to private key file (PEM format)
+     */
+    keyPath: string;
+    /**
+     * Path to CA certificate for verifying client certificates
+     * Required for mTLS
+     * @optional
+     */
+    caCertPath?: string;
+    /**
+     * Minimum TLS version
+     * @default 'TLSv1.2'
+     */
+    minVersion?: 'TLSv1.2' | 'TLSv1.3';
+    /**
+     * List of allowed cipher suites
+     * @optional - use Node.js defaults if not specified
+     */
+    ciphers?: string;
+    /**
+     * Passphrase for encrypted private key
+     * @optional
+     */
+    passphrase?: string;
+}
+interface ClusterTLSConfig extends TLSConfig {
+    /**
+     * Require client certificate (mTLS)
+     * @default false
+     */
+    requireClientCert?: boolean;
+    /**
+     * Verify peer certificates
+     * Can be disabled in development for self-signed certs
+     * @default true
+     */
+    rejectUnauthorized?: boolean;
+}
+
+interface ServerCoordinatorConfig {
+    port: number;
+    nodeId: string;
+    storage?: IServerStorage;
+    jwtSecret?: string;
+    host?: string;
+    clusterPort?: number;
+    peers?: string[];
+    securityPolicies?: PermissionPolicy[];
+    /** Callback to resolve dynamic peer addresses after ports are known */
+    resolvePeers?: () => string[];
+    interceptors?: IInterceptor[];
+    metricsPort?: number;
+    discovery?: 'manual' | 'kubernetes';
+    serviceName?: string;
+    discoveryInterval?: number;
+    tls?: TLSConfig;
+    clusterTls?: ClusterTLSConfig;
+}
+declare class ServerCoordinator {
+    private httpServer;
+    private metricsServer?;
+    private metricsService;
+    private wss;
+    private clients;
+    private interceptors;
+    private maps;
+    private hlc;
+    private storage?;
+    private jwtSecret;
+    private queryRegistry;
+    private cluster;
+    private partitionService;
+    private lockManager;
+    private topicManager;
+    private securityManager;
+    private systemManager;
+    private pendingClusterQueries;
+    private gcInterval?;
+    private gcReports;
+    private mapLoadingPromises;
+    private _actualPort;
+    private _actualClusterPort;
+    private _readyPromise;
+    private _readyResolve;
+    constructor(config: ServerCoordinatorConfig);
+    /** Wait for server to be fully ready (ports assigned) */
+    ready(): Promise<void>;
+    /** Get the actual port the server is listening on */
+    get port(): number;
+    /** Get the actual cluster port */
+    get clusterPort(): number;
+    shutdown(): Promise<void>;
+    private handleConnection;
+    private handleMessage;
+    private updateClientHlc;
+    private broadcast;
+    private setupClusterListeners;
+    private executeLocalQuery;
+    private finalizeClusterQuery;
+    private handleLockGranted;
+    private processLocalOp;
+    private handleClusterEvent;
+    getMap(name: string, typeHint?: 'LWW' | 'OR'): LWWMap<string, any> | ORMap<string, any>;
+    /**
+     * Returns map after ensuring it's fully loaded from storage.
+     * Use this for queries to avoid returning empty results during initial load.
+     */
+    getMapAsync(name: string, typeHint?: 'LWW' | 'OR'): Promise<LWWMap<string, any> | ORMap<string, any>>;
+    private loadMapFromStorage;
+    private startGarbageCollection;
+    private reportLocalHlc;
+    private handleGcReport;
+    private performGarbageCollection;
+    private buildTLSOptions;
+}
+
+interface PostgresAdapterOptions {
+    tableName?: string;
+}
+declare class PostgresAdapter implements IServerStorage {
+    private pool;
+    private tableName;
+    constructor(configOrPool: PoolConfig | Pool, options?: PostgresAdapterOptions);
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    load(mapName: string, key: string): Promise<StorageValue<any> | undefined>;
+    loadAll(mapName: string, keys: string[]): Promise<Map<string, StorageValue<any>>>;
+    loadAllKeys(mapName: string): Promise<string[]>;
+    store(mapName: string, key: string, record: StorageValue<any>): Promise<void>;
+    storeAll(mapName: string, records: Map<string, StorageValue<any>>): Promise<void>;
+    delete(mapName: string, key: string): Promise<void>;
+    deleteAll(mapName: string, keys: string[]): Promise<void>;
+    private mapRowToRecord;
+    private isORMapValue;
+}
+
+/**
+ * In-memory implementation of IServerStorage.
+ * Useful for development, testing, and demos without requiring a database.
+ *
+ * Note: Data is lost when the server restarts.
+ */
+declare class MemoryServerAdapter implements IServerStorage {
+    private storage;
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    private getMap;
+    load(mapName: string, key: string): Promise<StorageValue<any> | undefined>;
+    loadAll(mapName: string, keys: string[]): Promise<Map<string, StorageValue<any>>>;
+    loadAllKeys(mapName: string): Promise<string[]>;
+    store(mapName: string, key: string, record: StorageValue<any>): Promise<void>;
+    storeAll(mapName: string, records: Map<string, StorageValue<any>>): Promise<void>;
+    delete(mapName: string, key: string): Promise<void>;
+    deleteAll(mapName: string, keys: string[]): Promise<void>;
+}
+
+declare class SecurityManager {
+    private policies;
+    constructor(policies?: PermissionPolicy[]);
+    addPolicy(policy: PermissionPolicy): void;
+    checkPermission(principal: Principal, mapName: string, action: PermissionType): boolean;
+    filterObject(object: any, principal: Principal, mapName: string): any;
+    private hasRole;
+    private matchesMap;
+}
+
+declare const logger: pino.Logger<never, boolean>;
+type Logger = typeof logger;
+
+declare class TimestampInterceptor implements IInterceptor {
+    name: string;
+    onBeforeOp(op: ServerOp, context: OpContext): Promise<ServerOp>;
+}
+
+interface RateLimitConfig {
+    windowMs: number;
+    maxOps: number;
+}
+declare class RateLimitInterceptor implements IInterceptor {
+    name: string;
+    private limits;
+    private config;
+    constructor(config?: RateLimitConfig);
+    onBeforeOp(op: ServerOp, context: OpContext): Promise<ServerOp | null>;
+    onDisconnect(context: any): Promise<void>;
+}
+
+export { type ConnectionContext, type IInterceptor, type IServerStorage, type Logger, MemoryServerAdapter, type ORMapTombstones, type ORMapValue, type OpContext, PostgresAdapter, type PostgresAdapterOptions, RateLimitInterceptor, SecurityManager, ServerCoordinator, type ServerCoordinatorConfig, type ServerOp, type StorageValue, TimestampInterceptor, logger };