@soulcraft/brainy 2.15.0 → 3.0.1

package/dist/distributed/cacheSync.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Distributed Cache Synchronization
+ * Provides cache coherence across multiple Brainy instances
+ */
+import { EventEmitter } from 'events';
+export interface CacheSyncConfig {
+    nodeId: string;
+    syncInterval?: number;
+    maxSyncBatchSize?: number;
+    compressionEnabled?: boolean;
+}
+export interface CacheEntry {
+    key: string;
+    value: any;
+    version: number;
+    timestamp: number;
+    ttl?: number;
+    nodeId: string;
+}
+export interface SyncMessage {
+    type: 'invalidate' | 'update' | 'delete' | 'batch';
+    entries: CacheEntry[];
+    source: string;
+    timestamp: number;
+}
+/**
+ * Distributed Cache Synchronizer
+ */
+export declare class CacheSync extends EventEmitter {
+    private nodeId;
+    private localCache;
+    private versionVector;
+    private syncQueue;
+    private syncInterval;
+    private maxSyncBatchSize;
+    private syncTimer?;
+    private isRunning;
+    constructor(config: CacheSyncConfig);
+    /**
+     * Start cache synchronization
+     */
+    start(): void;
+    /**
+     * Stop cache synchronization
+     */
+    stop(): void;
+    /**
+     * Get a value from cache
+     */
+    get(key: string): any | undefined;
+    /**
+     * Set a value in cache and propagate
+     */
+    set(key: string, value: any, ttl?: number): void;
+    /**
+     * Delete a value from cache and propagate
+     */
+    delete(key: string): boolean;
+    /**
+     * Invalidate a cache entry across all nodes
+     */
+    invalidate(key: string): void;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Handle incoming sync message from another node
+     */
+    handleSyncMessage(message: SyncMessage): void;
+    /**
+     * Handle a remote cache entry
+     */
+    private handleRemoteEntry;
+    /**
+     * Queue a sync message
+     */
+    private queueSync;
+    /**
+     * Start sync timer
+     */
+    private startSyncTimer;
+    /**
+     * Perform sync operation
+     */
+    private performSync;
+    /**
+     * Increment version for a key
+     */
+    private incrementVersion;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        entries: number;
+        pendingSync: number;
+        versionedKeys: number;
+        memoryUsage: number;
+    };
+    /**
+     * Get cache entries for debugging
+     */
+    getEntries(): CacheEntry[];
+    /**
+     * Merge cache state from another node (for recovery)
+     */
+    mergeState(entries: CacheEntry[]): void;
+}
+/**
+ * Create a cache sync instance
+ */
+export declare function createCacheSync(config: CacheSyncConfig): CacheSync;

package/dist/distributed/cacheSync.js

@@ -0,0 +1,265 @@
+/**
+ * Distributed Cache Synchronization
+ * Provides cache coherence across multiple Brainy instances
+ */
+import { EventEmitter } from 'events';
+/**
+ * Distributed Cache Synchronizer
+ */
+export class CacheSync extends EventEmitter {
+    constructor(config) {
+        super();
+        this.localCache = new Map();
+        this.versionVector = new Map();
+        this.syncQueue = [];
+        this.isRunning = false;
+        this.nodeId = config.nodeId;
+        this.syncInterval = config.syncInterval || 1000;
+        this.maxSyncBatchSize = config.maxSyncBatchSize || 100;
+    }
+    /**
+     * Start cache synchronization
+     */
+    start() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        this.startSyncTimer();
+        this.emit('started', { nodeId: this.nodeId });
+    }
+    /**
+     * Stop cache synchronization
+     */
+    stop() {
+        if (!this.isRunning)
+            return;
+        this.isRunning = false;
+        if (this.syncTimer) {
+            clearInterval(this.syncTimer);
+            this.syncTimer = undefined;
+        }
+        this.emit('stopped', { nodeId: this.nodeId });
+    }
+    /**
+     * Get a value from cache
+     */
+    get(key) {
+        const entry = this.localCache.get(key);
+        if (!entry)
+            return undefined;
+        // Check TTL
+        if (entry.ttl && Date.now() - entry.timestamp > entry.ttl) {
+            this.localCache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /**
+     * Set a value in cache and propagate
+     */
+    set(key, value, ttl) {
+        const version = this.incrementVersion(key);
+        const entry = {
+            key,
+            value,
+            version,
+            timestamp: Date.now(),
+            ttl,
+            nodeId: this.nodeId
+        };
+        this.localCache.set(key, entry);
+        // Queue for sync
+        this.queueSync('update', [entry]);
+    }
+    /**
+     * Delete a value from cache and propagate
+     */
+    delete(key) {
+        const existed = this.localCache.has(key);
+        if (existed) {
+            const version = this.incrementVersion(key);
+            this.localCache.delete(key);
+            // Queue deletion for sync
+            this.queueSync('delete', [{
+                    key,
+                    value: null,
+                    version,
+                    timestamp: Date.now(),
+                    nodeId: this.nodeId
+                }]);
+        }
+        return existed;
+    }
+    /**
+     * Invalidate a cache entry across all nodes
+     */
+    invalidate(key) {
+        const version = this.incrementVersion(key);
+        this.localCache.delete(key);
+        // Queue invalidation
+        this.queueSync('invalidate', [{
+                key,
+                value: null,
+                version,
+                timestamp: Date.now(),
+                nodeId: this.nodeId
+            }]);
+    }
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        const entries = [];
+        for (const key of this.localCache.keys()) {
+            const version = this.incrementVersion(key);
+            entries.push({
+                key,
+                value: null,
+                version,
+                timestamp: Date.now(),
+                nodeId: this.nodeId
+            });
+        }
+        this.localCache.clear();
+        if (entries.length > 0) {
+            this.queueSync('delete', entries);
+        }
+    }
+    /**
+     * Handle incoming sync message from another node
+     */
+    handleSyncMessage(message) {
+        if (message.source === this.nodeId)
+            return; // Ignore own messages
+        for (const entry of message.entries) {
+            this.handleRemoteEntry(message.type, entry);
+        }
+        this.emit('synced', {
+            type: message.type,
+            entries: message.entries.length,
+            source: message.source
+        });
+    }
+    /**
+     * Handle a remote cache entry
+     */
+    handleRemoteEntry(type, entry) {
+        const localEntry = this.localCache.get(entry.key);
+        const localVersion = this.versionVector.get(entry.key) || 0;
+        // Version vector check - only accept if remote version is newer
+        if (entry.version <= localVersion) {
+            return; // Our version is newer or same, ignore
+        }
+        // Update version vector
+        this.versionVector.set(entry.key, entry.version);
+        switch (type) {
+            case 'update':
+            case 'batch':
+                // Update local cache with remote value
+                this.localCache.set(entry.key, entry);
+                break;
+            case 'delete':
+            case 'invalidate':
+                // Remove from local cache
+                this.localCache.delete(entry.key);
+                break;
+        }
+    }
+    /**
+     * Queue a sync message
+     */
+    queueSync(type, entries) {
+        const message = {
+            type,
+            entries,
+            source: this.nodeId,
+            timestamp: Date.now()
+        };
+        this.syncQueue.push(message);
+        // If queue is getting large, sync immediately
+        if (this.syncQueue.length >= this.maxSyncBatchSize) {
+            this.performSync();
+        }
+    }
+    /**
+     * Start sync timer
+     */
+    startSyncTimer() {
+        this.syncTimer = setInterval(() => {
+            this.performSync();
+        }, this.syncInterval);
+    }
+    /**
+     * Perform sync operation
+     */
+    performSync() {
+        if (this.syncQueue.length === 0)
+            return;
+        // Batch multiple messages if possible
+        const messages = this.syncQueue.splice(0, this.maxSyncBatchSize);
+        if (messages.length === 1) {
+            // Single message
+            this.emit('sync', messages[0]);
+        }
+        else {
+            // Batch multiple messages
+            const batchedEntries = [];
+            for (const msg of messages) {
+                batchedEntries.push(...msg.entries);
+            }
+            const batchMessage = {
+                type: 'batch',
+                entries: batchedEntries,
+                source: this.nodeId,
+                timestamp: Date.now()
+            };
+            this.emit('sync', batchMessage);
+        }
+    }
+    /**
+     * Increment version for a key
+     */
+    incrementVersion(key) {
+        const current = this.versionVector.get(key) || 0;
+        const next = current + 1;
+        this.versionVector.set(key, next);
+        return next;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        // Estimate memory usage (rough approximation)
+        let memoryUsage = 0;
+        for (const entry of this.localCache.values()) {
+            memoryUsage += JSON.stringify(entry).length;
+        }
+        return {
+            entries: this.localCache.size,
+            pendingSync: this.syncQueue.length,
+            versionedKeys: this.versionVector.size,
+            memoryUsage
+        };
+    }
+    /**
+     * Get cache entries for debugging
+     */
+    getEntries() {
+        return Array.from(this.localCache.values());
+    }
+    /**
+     * Merge cache state from another node (for recovery)
+     */
+    mergeState(entries) {
+        for (const entry of entries) {
+            this.handleRemoteEntry('update', entry);
+        }
+    }
+}
+/**
+ * Create a cache sync instance
+ */
+export function createCacheSync(config) {
+    return new CacheSync(config);
+}
+//# sourceMappingURL=cacheSync.js.map

package/dist/distributed/coordinator.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Distributed Coordinator for Brainy 3.0
+ * Provides leader election, consensus, and coordination for distributed instances
+ */
+import { EventEmitter } from 'events';
+import { NetworkTransport } from './networkTransport.js';
+export interface NodeInfo {
+    id: string;
+    address: string;
+    port: number;
+    lastSeen: number;
+    status: 'active' | 'inactive' | 'suspected';
+    state?: 'follower' | 'candidate' | 'leader';
+    lastHeartbeat?: number;
+}
+export interface CoordinatorConfig {
+    nodeId?: string;
+    address?: string;
+    port?: number;
+    heartbeatInterval?: number;
+    electionTimeout?: number;
+    nodes?: string[];
+}
+export interface ConsensusState {
+    term: number;
+    votedFor: string | null;
+    leader: string | null;
+    state: 'follower' | 'candidate' | 'leader';
+}
+export interface RaftMessage {
+    type: 'requestVote' | 'voteResponse' | 'appendEntries' | 'appendResponse';
+    term: number;
+    from: string;
+    to?: string;
+    data?: any;
+}
+/**
+ * Distributed Coordinator implementing Raft-like consensus
+ */
+export declare class DistributedCoordinator extends EventEmitter {
+    private nodeId;
+    private nodes;
+    private consensusState;
+    private heartbeatInterval;
+    private electionTimeout;
+    private electionTimer?;
+    private heartbeatTimer?;
+    private isRunning;
+    private networkTransport?;
+    private votesReceived;
+    private currentTerm;
+    private lastLogIndex;
+    private lastLogTerm;
+    private logEntries;
+    private transport;
+    private pendingMigrations;
+    private committedMigrations;
+    constructor(config?: CoordinatorConfig);
+    /**
+     * Start the coordinator
+     */
+    start(networkTransport?: NetworkTransport): Promise<void>;
+    /**
+     * Setup network message handlers
+     */
+    private setupNetworkHandlers;
+    /**
+     * Stop the coordinator
+     */
+    stop(): Promise<void>;
+    /**
+     * Register additional nodes
+     */
+    registerNodes(nodes: string[]): void;
+    /**
+     * Become a follower
+     */
+    private becomeFollower;
+    /**
+     * Become a candidate and start election
+     */
+    private becomeCandidate;
+    /**
+     * Become the leader
+     */
+    private becomeLeader;
+    /**
+     * Request votes from all nodes
+     */
+    private requestVotes;
+    /**
+     * Handle vote request from another node
+     */
+    private handleVoteRequest;
+    /**
+     * Handle vote response
+     */
+    private handleVoteResponse;
+    /**
+     * Check if we have majority votes
+     */
+    private checkVoteMajority;
+    /**
+     * Handle append entries (heartbeat) from leader
+     */
+    private handleAppendEntries;
+    /**
+     * Handle append response from follower
+     */
+    private handleAppendResponse;
+    /**
+     * Send heartbeat to followers
+     */
+    private sendHeartbeat;
+    /**
+     * Start heartbeat timer as leader
+     */
+    private startHeartbeat;
+    /**
+     * Reset election timeout
+     */
+    private resetElectionTimeout;
+    /**
+     * Check if log is up to date
+     */
+    private isLogUpToDate;
+    /**
+     * Check log consistency
+     */
+    private checkLogConsistency;
+    /**
+     * Append log entries
+     */
+    private appendLogEntries;
+    /**
+     * Get last log index
+     */
+    private getLastLogIndex;
+    /**
+     * Get last log term
+     */
+    private getLastLogTerm;
+    /**
+     * Generate a unique node ID
+     */
+    private generateNodeId;
+    /**
+     * Get current leader
+     */
+    getLeader(): string | null;
+    /**
+     * Propose a shard migration to the cluster
+     */
+    proposeMigration(migration: {
+        shardId: string;
+        fromNode: string;
+        toNode: string;
+        migrationId: string;
+    }): Promise<void>;
+    /**
+     * Get migration status
+     */
+    getMigrationStatus(migrationId: string): Promise<'pending' | 'committed' | 'rejected'>;
+    /**
+     * Check if this node is the leader
+     */
+    isLeader(): boolean;
+    /**
+     * Get all nodes in the cluster
+     */
+    getNodes(): NodeInfo[];
+    /**
+     * Get cluster health status
+     */
+    getHealth(): {
+        healthy: boolean;
+        leader: string | null;
+        nodes: number;
+        activeNodes: number;
+    };
+    /**
+     * Propose a command to the cluster
+     */
+    proposeCommand(command: any): Promise<void>;
+    /**
+     * Get current state
+     */
+    getState(): ConsensusState;
+}
+/**
+ * Create a coordinator instance
+ */
+export declare function createCoordinator(config?: CoordinatorConfig): DistributedCoordinator;