@brightchain/brightchain-api-lib 0.0.1

package/src/lib/availability/discoveryProtocol.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * @fileoverview Discovery Protocol Implementation
+ *
+ * Implements block discovery across the network using Bloom filter pre-checks,
+ * concurrent query limiting, result caching, and latency-based node preference.
+ *
+ * @see Requirements 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscoveryProtocol = exports.DEFAULT_DISCOVERY_CONFIG = void 0;
+// Re-export DEFAULT_DISCOVERY_CONFIG from brightchain-lib for convenience
+var brightchain_lib_1 = require("@brightchain/brightchain-lib");
+Object.defineProperty(exports, "DEFAULT_DISCOVERY_CONFIG", { enumerable: true, get: function () { return brightchain_lib_1.DEFAULT_DISCOVERY_CONFIG; } });
+/**
+ * Default discovery configuration values (local copy for use in this module).
+ */
+const defaultDiscoveryConfig = {
+    queryTimeoutMs: 5000,
+    maxConcurrentQueries: 10,
+    cacheTtlMs: 60000,
+    bloomFilterFalsePositiveRate: 0.01,
+    bloomFilterHashCount: 7,
+};
+/**
+ * Discovery Protocol Implementation
+ *
+ * Handles finding blocks across the network using:
+ * - Bloom filter pre-checks to avoid unnecessary queries
+ * - Concurrent query limiting to manage resources
+ * - Result caching with TTL to reduce network traffic
+ * - Latency-based node preference for optimal retrieval
+ *
+ * @see Requirements 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8
+ */
+class DiscoveryProtocol {
+    /**
+     * Create a new DiscoveryProtocol.
+     *
+     * @param networkProvider - Provider for peer network operations
+     * @param config - Discovery configuration (uses defaults if not provided)
+     */
+    constructor(networkProvider, config = defaultDiscoveryConfig) {
+        this.networkProvider = networkProvider;
+        this.config = config;
+        /**
+         * Cache of discovery results with TTL management.
+         */
+        this.cache = new Map();
+        /**
+         * Cache of peer Bloom filters.
+         */
+        this.bloomFilterCache = new Map();
+    }
+    /**
+     * Discover locations for a block across the network.
+     *
+     * @param blockId - The block ID to discover
+     * @returns Promise resolving to discovery result with locations
+     * @see Requirements 5.1, 5.2, 5.3, 5.4, 5.5
+     */
+    async discoverBlock(blockId) {
+        const startTime = Date.now();
+        // Check cache first
+        const cachedLocations = this.getCachedLocations(blockId);
+        if (cachedLocations !== null) {
+            return {
+                blockId,
+                found: cachedLocations.length > 0,
+                locations: cachedLocations,
+                queriedPeers: 0,
+                duration: Date.now() - startTime,
+            };
+        }
+        // Get connected peers
+        const connectedPeers = this.networkProvider.getConnectedPeerIds();
+        if (connectedPeers.length === 0) {
+            return {
+                blockId,
+                found: false,
+                locations: [],
+                queriedPeers: 0,
+                duration: Date.now() - startTime,
+            };
+        }
+        // Filter peers using Bloom filters
+        const peersToQuery = await this.filterPeersWithBloomFilters(connectedPeers, blockId);
+        // Query peers with concurrency limiting
+        const queryResults = await this.queryPeersWithConcurrencyLimit(peersToQuery, blockId);
+        // Build location records from successful queries
+        const locations = this.buildLocationRecords(queryResults);
+        // Sort by latency (lowest first)
+        locations.sort((a, b) => (a.latencyMs ?? Infinity) - (b.latencyMs ?? Infinity));
+        // Cache the results
+        this.cacheResults(blockId, locations);
+        return {
+            blockId,
+            found: locations.length > 0,
+            locations,
+            queriedPeers: queryResults.length,
+            duration: Date.now() - startTime,
+        };
+    }
+    /**
+     * Query a specific peer for a block.
+     *
+     * @param peerId - The peer to query
+     * @param blockId - The block ID to query for
+     * @returns Promise resolving to the query result
+     * @see Requirements 5.3
+     */
+    async queryPeer(peerId, blockId) {
+        const startTime = Date.now();
+        try {
+            const hasBlock = await this.networkProvider.queryPeerForBlock(peerId, blockId, this.config.queryTimeoutMs);
+            return {
+                peerId,
+                hasBlock,
+                latencyMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            return {
+                peerId,
+                hasBlock: false,
+                latencyMs: Date.now() - startTime,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    /**
+     * Get cached discovery results for a block.
+     *
+     * @param blockId - The block ID to get cached locations for
+     * @returns Cached location records or null if not cached or expired
+     * @see Requirements 5.8
+     */
+    getCachedLocations(blockId) {
+        const entry = this.cache.get(blockId);
+        if (!entry) {
+            return null;
+        }
+        // Check if cache has expired
+        const age = Date.now() - entry.cachedAt;
+        if (age > this.config.cacheTtlMs) {
+            this.cache.delete(blockId);
+            return null;
+        }
+        return [...entry.locations];
+    }
+    /**
+     * Clear the discovery cache for a specific block.
+     *
+     * @param blockId - The block ID to clear from cache
+     */
+    clearCache(blockId) {
+        this.cache.delete(blockId);
+    }
+    /**
+     * Clear the entire discovery cache.
+     */
+    clearAllCache() {
+        this.cache.clear();
+    }
+    /**
+     * Get the Bloom filter from a peer.
+     *
+     * @param peerId - The peer to get the Bloom filter from
+     * @returns Promise resolving to the peer's Bloom filter
+     * @see Requirements 4.2, 5.2
+     */
+    async getPeerBloomFilter(peerId) {
+        // Check cache first
+        const cached = this.bloomFilterCache.get(peerId);
+        if (cached) {
+            return cached;
+        }
+        // Fetch from network
+        const filter = await this.networkProvider.getPeerBloomFilter(peerId);
+        // Cache the filter
+        this.bloomFilterCache.set(peerId, filter);
+        return filter;
+    }
+    /**
+     * Get the current configuration.
+     *
+     * @returns The discovery configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Clear the Bloom filter cache for a specific peer.
+     *
+     * @param peerId - The peer to clear from cache
+     */
+    clearBloomFilterCache(peerId) {
+        this.bloomFilterCache.delete(peerId);
+    }
+    /**
+     * Clear all Bloom filter caches.
+     */
+    clearAllBloomFilterCache() {
+        this.bloomFilterCache.clear();
+    }
+    /**
+     * Filter peers using their Bloom filters.
+     * Only returns peers whose Bloom filters indicate they might have the block.
+     *
+     * @param peerIds - Peers to filter
+     * @param blockId - Block ID to check
+     * @returns Peers that might have the block
+     * @see Requirements 4.3, 4.4, 4.5, 5.2
+     */
+    async filterPeersWithBloomFilters(peerIds, blockId) {
+        const peersToQuery = [];
+        // Check each peer's Bloom filter
+        const filterPromises = peerIds.map(async (peerId) => {
+            try {
+                const filter = await this.getPeerBloomFilter(peerId);
+                // If Bloom filter says block might exist, include peer
+                if (filter.mightContain(blockId)) {
+                    return peerId;
+                }
+                // Bloom filter says block definitely doesn't exist, skip peer
+                return null;
+            }
+            catch {
+                // If we can't get the Bloom filter, include peer to be safe
+                return peerId;
+            }
+        });
+        const results = await Promise.all(filterPromises);
+        for (const peerId of results) {
+            if (peerId !== null) {
+                peersToQuery.push(peerId);
+            }
+        }
+        return peersToQuery;
+    }
+    /**
+     * Query peers with concurrency limiting.
+     *
+     * @param peerIds - Peers to query
+     * @param blockId - Block ID to query for
+     * @returns Query results from all peers
+     * @see Requirements 5.3, 13.2
+     */
+    async queryPeersWithConcurrencyLimit(peerIds, blockId) {
+        const results = [];
+        const pending = [];
+        let index = 0;
+        const queryNext = async () => {
+            while (index < peerIds.length) {
+                const currentIndex = index++;
+                const peerId = peerIds[currentIndex];
+                const result = await this.queryPeer(peerId, blockId);
+                results.push(result);
+            }
+        };
+        // Start up to maxConcurrentQueries parallel query chains
+        const concurrency = Math.min(this.config.maxConcurrentQueries, peerIds.length);
+        for (let i = 0; i < concurrency; i++) {
+            pending.push(queryNext());
+        }
+        await Promise.all(pending);
+        return results;
+    }
+    /**
+     * Build location records from query results.
+     *
+     * @param queryResults - Results from peer queries
+     * @returns Location records for peers that have the block
+     * @see Requirements 5.4
+     */
+    buildLocationRecords(queryResults) {
+        const locations = [];
+        for (const result of queryResults) {
+            if (result.hasBlock && !result.error) {
+                locations.push({
+                    nodeId: result.peerId,
+                    lastSeen: new Date(),
+                    isAuthoritative: false, // Remote copies are not authoritative
+                    latencyMs: result.latencyMs,
+                });
+            }
+        }
+        return locations;
+    }
+    /**
+     * Cache discovery results.
+     *
+     * @param blockId - Block ID to cache
+     * @param locations - Location records to cache
+     */
+    cacheResults(blockId, locations) {
+        this.cache.set(blockId, {
+            locations: [...locations],
+            cachedAt: Date.now(),
+        });
+    }
+}
+exports.DiscoveryProtocol = DiscoveryProtocol;
+//# sourceMappingURL=discoveryProtocol.js.map

package/src/lib/availability/discoveryProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discoveryProtocol.js","sourceRoot":"","sources":["../../../../../brightchain-api-lib/src/lib/availability/discoveryProtocol.ts"],"names":[],"mappings":"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"}

package/src/lib/availability/gossipService.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Gossip Service Implementation
+ *
+ * Implements gossip-based block announcements across the network.
+ * Supports announcement batching, TTL decrement on forwarding,
+ * and fanout to random peers.
+ *
+ * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 6.6
+ */
+import { AnnouncementHandler, BlockAnnouncement, GossipConfig, IGossipService } from '@brightchain/brightchain-lib';
+export { DEFAULT_GOSSIP_CONFIG } from '@brightchain/brightchain-lib';
+/**
+ * Interface for peer management operations.
+ * Abstracts peer selection for gossip forwarding.
+ */
+export interface IPeerProvider {
+    /**
+     * Get the local node ID.
+     */
+    getLocalNodeId(): string;
+    /**
+     * Get all connected peer IDs.
+     */
+    getConnectedPeerIds(): string[];
+    /**
+     * Send an announcement batch to a specific peer.
+     *
+     * @param peerId - The peer to send to
+     * @param announcements - The announcements to send
+     */
+    sendAnnouncementBatch(peerId: string, announcements: BlockAnnouncement[]): Promise<void>;
+}
+/**
+ * Gossip Service Implementation
+ *
+ * Handles gossip-based block announcements across the network.
+ * Implements batching, TTL management, and random peer selection.
+ *
+ * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 6.6
+ */
+export declare class GossipService implements IGossipService {
+    private readonly peerProvider;
+    private readonly config;
+    /**
+     * Pending announcements waiting to be batched and sent.
+     */
+    private pendingAnnouncements;
+    /**
+     * Registered announcement handlers.
+     */
+    private handlers;
+    /**
+     * Batch timer handle.
+     */
+    private batchTimer;
+    /**
+     * Whether the service is running.
+     */
+    private running;
+    /**
+     * Create a new GossipService.
+     *
+     * @param peerProvider - Provider for peer management operations
+     * @param config - Gossip configuration (uses defaults if not provided)
+     */
+    constructor(peerProvider: IPeerProvider, config?: GossipConfig);
+    /**
+     * Announce a new block to the network.
+     *
+     * @param blockId - The block ID to announce
+     * @see Requirements 6.1
+     */
+    announceBlock(blockId: string): Promise<void>;
+    /**
+     * Announce block removal to the network.
+     *
+     * @param blockId - The block ID being removed
+     * @see Requirements 6.5
+     */
+    announceRemoval(blockId: string): Promise<void>;
+    /**
+     * Handle an incoming block announcement from a peer.
+     * Notifies handlers and optionally forwards with decremented TTL.
+     *
+     * @param announcement - The received announcement
+     * @see Requirements 6.2, 6.4
+     */
+    handleAnnouncement(announcement: BlockAnnouncement): Promise<void>;
+    /**
+     * Subscribe to announcement events.
+     *
+     * @param handler - Function to call when an announcement is received
+     * @see Requirements 6.2
+     */
+    onAnnouncement(handler: AnnouncementHandler): void;
+    /**
+     * Remove an announcement handler.
+     *
+     * @param handler - The handler to remove
+     */
+    offAnnouncement(handler: AnnouncementHandler): void;
+    /**
+     * Get pending announcements that have not yet been sent.
+     *
+     * @returns Array of pending announcements
+     * @see Requirements 6.6
+     */
+    getPendingAnnouncements(): BlockAnnouncement[];
+    /**
+     * Immediately flush all pending announcements.
+     *
+     * @see Requirements 6.6
+     */
+    flushAnnouncements(): Promise<void>;
+    /**
+     * Start the gossip service.
+     */
+    start(): void;
+    /**
+     * Stop the gossip service.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the current configuration.
+     *
+     * @returns The gossip configuration
+     */
+    getConfig(): GossipConfig;
+    /**
+     * Queue an announcement for batching.
+     *
+     * @param announcement - The announcement to queue
+     */
+    private queueAnnouncement;
+    /**
+     * Select random peers from the available peers.
+     *
+     * @param peers - Available peer IDs
+     * @param count - Number of peers to select
+     * @returns Selected peer IDs
+     * @see Requirements 6.3
+     */
+    private selectRandomPeers;
+    /**
+     * Split announcements into batches of maximum size.
+     *
+     * @param announcements - Announcements to split
+     * @param maxSize - Maximum batch size
+     * @returns Array of batches
+     * @see Requirements 6.6
+     */
+    private splitIntoBatches;
+    /**
+     * Clear all pending announcements (for testing).
+     */
+    clearPending(): void;
+}
+//# sourceMappingURL=gossipService.d.ts.map

package/src/lib/availability/gossipService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gossipService.d.ts","sourceRoot":"","sources":["../../../../../brightchain-api-lib/src/lib/availability/gossipService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACf,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAYrE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,cAAc,IAAI,MAAM,CAAC;IAEzB;;OAEG;IACH,mBAAmB,IAAI,MAAM,EAAE,CAAC;IAEhC;;;;;OAKG;IACH,qBAAqB,CACnB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,iBAAiB,EAAE,GACjC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,qBAAa,aAAc,YAAW,cAAc;IA4BhD,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IA5BzB;;OAEG;IACH,OAAO,CAAC,oBAAoB,CAA2B;IAEvD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAuC;IAEvD;;OAEG;IACH,OAAO,CAAC,UAAU,CAA+C;IAEjE;;OAEG;IACH,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;OAKG;gBAEgB,YAAY,EAAE,aAAa,EAC3B,MAAM,GAAE,YAAkC;IAG7D;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnD;;;;;OAKG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYrD;;;;;;OAMG;IACG,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBxE;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAIlD;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAInD;;;;;OAKG;IACH,uBAAuB,IAAI,iBAAiB,EAAE;IAI9C;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IA2CzC;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB3B;;;;OAIG;IACH,SAAS,IAAI,YAAY;IAIzB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACH,YAAY,IAAI,IAAI;CAGrB"}