@topgunbuild/server 0.1.0

package/LICENSE

@@ -0,0 +1,97 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             TopGun Contributors
+Licensed Work:        TopGun
+                      The Licensed Work is (c) 2024 TopGun Contributors.
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided Your use does not include offering the
+                      Licensed Work to third parties as a commercial
+                      managed database service, database-as-a-service,
+                      or similar hosted database offering that competes
+                      with TopGun products or services.
+
+                      For purposes of this license:
+                      - "Managed database service" means a service that
+                        allows third parties to create, manage, or operate
+                        databases using TopGun as the underlying technology.
+                      - Internal use within your organization is permitted.
+                      - Using TopGun as part of your application's backend
+                        (not exposed as a database service) is permitted.
+                      - Consulting and professional services around TopGun
+                        are permitted.
+
+Change Date:          Four years from the date of each version release
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an Additional Use Grant (above) that does not impose
+   any additional restriction on the right granted in this License, as the
+   Additional Use Grant; or (b) insert the text "None" to specify a Change Date.
+
+3. Not to modify this License in any other way.

package/dist/index.d.mts

@@ -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 };