@brightchain/brightchain-api-lib 0.0.1

package/src/lib/availability/configValidation.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * @fileoverview Configuration Validation
+ *
+ * Provides validation functions for availability system configurations.
+ * Ensures all configuration values are valid and returns descriptive error messages.
+ *
+ * @see Requirements 13.1, 13.2, 13.3, 13.4, 13.5, 13.6
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigValidationError = void 0;
+exports.validateDiscoveryConfig = validateDiscoveryConfig;
+exports.validateGossipConfig = validateGossipConfig;
+exports.validateHeartbeatConfig = validateHeartbeatConfig;
+exports.createValidatedDiscoveryConfig = createValidatedDiscoveryConfig;
+exports.createValidatedGossipConfig = createValidatedGossipConfig;
+exports.createValidatedHeartbeatConfig = createValidatedHeartbeatConfig;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+/**
+ * Configuration validation error.
+ * Contains a descriptive error message about what is invalid.
+ */
+class ConfigValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigValidationError';
+    }
+}
+exports.ConfigValidationError = ConfigValidationError;
+/**
+ * Validate DiscoveryConfig.
+ * Ensures all values are positive and within reasonable ranges.
+ *
+ * @param config - The discovery configuration to validate
+ * @throws {ConfigValidationError} If configuration is invalid
+ * @see Requirements 13.1, 13.2, 13.3, 13.6
+ */
+function validateDiscoveryConfig(config) {
+    // Validate queryTimeoutMs
+    if (config.queryTimeoutMs !== undefined) {
+        if (!Number.isFinite(config.queryTimeoutMs)) {
+            throw new ConfigValidationError('queryTimeoutMs must be a finite number');
+        }
+        if (config.queryTimeoutMs <= 0) {
+            throw new ConfigValidationError('queryTimeoutMs must be positive');
+        }
+        if (config.queryTimeoutMs > 300000) {
+            // 5 minutes max
+            throw new ConfigValidationError('queryTimeoutMs must not exceed 300000ms (5 minutes)');
+        }
+    }
+    // Validate maxConcurrentQueries
+    if (config.maxConcurrentQueries !== undefined) {
+        if (!Number.isInteger(config.maxConcurrentQueries)) {
+            throw new ConfigValidationError('maxConcurrentQueries must be an integer');
+        }
+        if (config.maxConcurrentQueries < 1) {
+            throw new ConfigValidationError('maxConcurrentQueries must be at least 1');
+        }
+        if (config.maxConcurrentQueries > 1000) {
+            throw new ConfigValidationError('maxConcurrentQueries must not exceed 1000');
+        }
+    }
+    // Validate cacheTtlMs
+    if (config.cacheTtlMs !== undefined) {
+        if (!Number.isFinite(config.cacheTtlMs)) {
+            throw new ConfigValidationError('cacheTtlMs must be a finite number');
+        }
+        if (config.cacheTtlMs < 0) {
+            throw new ConfigValidationError('cacheTtlMs must be non-negative');
+        }
+        if (config.cacheTtlMs > 86400000) {
+            // 24 hours max
+            throw new ConfigValidationError('cacheTtlMs must not exceed 86400000ms (24 hours)');
+        }
+    }
+    // Validate bloomFilterFalsePositiveRate
+    if (config.bloomFilterFalsePositiveRate !== undefined) {
+        if (!Number.isFinite(config.bloomFilterFalsePositiveRate)) {
+            throw new ConfigValidationError('bloomFilterFalsePositiveRate must be a finite number');
+        }
+        if (config.bloomFilterFalsePositiveRate <= 0 ||
+            config.bloomFilterFalsePositiveRate >= 1) {
+            throw new ConfigValidationError('bloomFilterFalsePositiveRate must be between 0 and 1 (exclusive)');
+        }
+    }
+    // Validate bloomFilterHashCount
+    if (config.bloomFilterHashCount !== undefined) {
+        if (!Number.isInteger(config.bloomFilterHashCount)) {
+            throw new ConfigValidationError('bloomFilterHashCount must be an integer');
+        }
+        if (config.bloomFilterHashCount < 1) {
+            throw new ConfigValidationError('bloomFilterHashCount must be at least 1');
+        }
+        if (config.bloomFilterHashCount > 20) {
+            throw new ConfigValidationError('bloomFilterHashCount must not exceed 20');
+        }
+    }
+}
+/**
+ * Validate GossipConfig.
+ * Ensures all values are positive and within reasonable ranges.
+ *
+ * @param config - The gossip configuration to validate
+ * @throws {ConfigValidationError} If configuration is invalid
+ * @see Requirements 13.4, 13.6
+ */
+function validateGossipConfig(config) {
+    // Validate fanout
+    if (config.fanout !== undefined) {
+        if (!Number.isInteger(config.fanout)) {
+            throw new ConfigValidationError('fanout must be an integer');
+        }
+        if (config.fanout < 1) {
+            throw new ConfigValidationError('fanout must be at least 1');
+        }
+        if (config.fanout > 100) {
+            throw new ConfigValidationError('fanout must not exceed 100');
+        }
+    }
+    // Validate defaultTtl
+    if (config.defaultTtl !== undefined) {
+        if (!Number.isInteger(config.defaultTtl)) {
+            throw new ConfigValidationError('defaultTtl must be an integer');
+        }
+        if (config.defaultTtl < 0) {
+            throw new ConfigValidationError('defaultTtl must be non-negative');
+        }
+        if (config.defaultTtl > 10) {
+            throw new ConfigValidationError('defaultTtl must not exceed 10');
+        }
+    }
+    // Validate batchIntervalMs
+    if (config.batchIntervalMs !== undefined) {
+        if (!Number.isFinite(config.batchIntervalMs)) {
+            throw new ConfigValidationError('batchIntervalMs must be a finite number');
+        }
+        if (config.batchIntervalMs < 0) {
+            throw new ConfigValidationError('batchIntervalMs must be non-negative');
+        }
+        if (config.batchIntervalMs > 60000) {
+            // 1 minute max
+            throw new ConfigValidationError('batchIntervalMs must not exceed 60000ms (1 minute)');
+        }
+    }
+    // Validate maxBatchSize
+    if (config.maxBatchSize !== undefined) {
+        if (!Number.isInteger(config.maxBatchSize)) {
+            throw new ConfigValidationError('maxBatchSize must be an integer');
+        }
+        if (config.maxBatchSize < 1) {
+            throw new ConfigValidationError('maxBatchSize must be at least 1');
+        }
+        if (config.maxBatchSize > 10000) {
+            throw new ConfigValidationError('maxBatchSize must not exceed 10000');
+        }
+    }
+}
+/**
+ * Validate HeartbeatConfig.
+ * Ensures all values are positive and within reasonable ranges.
+ * Also validates that timeoutMs < intervalMs for proper operation.
+ *
+ * @param config - The heartbeat configuration to validate
+ * @throws {ConfigValidationError} If configuration is invalid
+ * @see Requirements 13.5, 13.6
+ */
+function validateHeartbeatConfig(config) {
+    // Validate intervalMs
+    if (config.intervalMs !== undefined) {
+        if (!Number.isFinite(config.intervalMs)) {
+            throw new ConfigValidationError('intervalMs must be a finite number');
+        }
+        if (config.intervalMs <= 0) {
+            throw new ConfigValidationError('intervalMs must be positive');
+        }
+        if (config.intervalMs > 300000) {
+            // 5 minutes max
+            throw new ConfigValidationError('intervalMs must not exceed 300000ms (5 minutes)');
+        }
+    }
+    // Validate timeoutMs
+    if (config.timeoutMs !== undefined) {
+        if (!Number.isFinite(config.timeoutMs)) {
+            throw new ConfigValidationError('timeoutMs must be a finite number');
+        }
+        if (config.timeoutMs <= 0) {
+            throw new ConfigValidationError('timeoutMs must be positive');
+        }
+        if (config.timeoutMs > 60000) {
+            // 1 minute max
+            throw new ConfigValidationError('timeoutMs must not exceed 60000ms (1 minute)');
+        }
+    }
+    // Validate missedThreshold
+    if (config.missedThreshold !== undefined) {
+        if (!Number.isInteger(config.missedThreshold)) {
+            throw new ConfigValidationError('missedThreshold must be an integer');
+        }
+        if (config.missedThreshold < 1) {
+            throw new ConfigValidationError('missedThreshold must be at least 1');
+        }
+        if (config.missedThreshold > 100) {
+            throw new ConfigValidationError('missedThreshold must not exceed 100');
+        }
+    }
+    // Cross-field validation: timeoutMs should be less than intervalMs
+    if (config.timeoutMs !== undefined &&
+        config.intervalMs !== undefined &&
+        config.timeoutMs >= config.intervalMs) {
+        throw new ConfigValidationError('timeoutMs must be less than intervalMs for proper heartbeat operation');
+    }
+}
+/**
+ * Create a validated DiscoveryConfig by merging partial config with defaults.
+ * Validates the merged configuration before returning.
+ *
+ * @param config - Partial configuration to merge with defaults
+ * @returns Complete validated configuration
+ * @throws {ConfigValidationError} If configuration is invalid
+ */
+function createValidatedDiscoveryConfig(config = {}) {
+    validateDiscoveryConfig(config);
+    return {
+        ...brightchain_lib_1.DEFAULT_DISCOVERY_CONFIG,
+        ...config,
+    };
+}
+/**
+ * Create a validated GossipConfig by merging partial config with defaults.
+ * Validates the merged configuration before returning.
+ *
+ * @param config - Partial configuration to merge with defaults
+ * @returns Complete validated configuration
+ * @throws {ConfigValidationError} If configuration is invalid
+ */
+function createValidatedGossipConfig(config = {}) {
+    validateGossipConfig(config);
+    return {
+        ...brightchain_lib_1.DEFAULT_GOSSIP_CONFIG,
+        ...config,
+    };
+}
+/**
+ * Create a validated HeartbeatConfig by merging partial config with defaults.
+ * Validates the merged configuration before returning.
+ *
+ * @param config - Partial configuration to merge with defaults
+ * @returns Complete validated configuration
+ * @throws {ConfigValidationError} If configuration is invalid
+ */
+function createValidatedHeartbeatConfig(config = {}) {
+    const merged = {
+        ...brightchain_lib_1.DEFAULT_HEARTBEAT_CONFIG,
+        ...config,
+    };
+    // Validate the merged config to catch cross-field issues
+    validateHeartbeatConfig(merged);
+    return merged;
+}
+//# sourceMappingURL=configValidation.js.map

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

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

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

@@ -0,0 +1,160 @@
+/**
+ * @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
+ */
+import { BloomFilter, DiscoveryConfig, DiscoveryResult, IDiscoveryProtocol, ILocationRecord, PeerQueryResult } from '@brightchain/brightchain-lib';
+export { DEFAULT_DISCOVERY_CONFIG } from '@brightchain/brightchain-lib';
+/**
+ * Interface for peer network operations.
+ * Abstracts network communication for discovery queries.
+ */
+export interface IPeerNetworkProvider {
+    /**
+     * Get all connected peer IDs.
+     */
+    getConnectedPeerIds(): string[];
+    /**
+     * 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
+     */
+    getPeerBloomFilter(peerId: string): Promise<BloomFilter>;
+    /**
+     * Query a peer for a specific block.
+     *
+     * @param peerId - The peer to query
+     * @param blockId - The block ID to query for
+     * @param timeoutMs - Query timeout in milliseconds
+     * @returns Promise resolving to whether the peer has the block
+     */
+    queryPeerForBlock(peerId: string, blockId: string, timeoutMs: number): Promise<boolean>;
+}
+/**
+ * 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
+ */
+export declare class DiscoveryProtocol implements IDiscoveryProtocol {
+    private readonly networkProvider;
+    private readonly config;
+    /**
+     * Cache of discovery results with TTL management.
+     */
+    private readonly cache;
+    /**
+     * Cache of peer Bloom filters.
+     */
+    private readonly bloomFilterCache;
+    /**
+     * Create a new DiscoveryProtocol.
+     *
+     * @param networkProvider - Provider for peer network operations
+     * @param config - Discovery configuration (uses defaults if not provided)
+     */
+    constructor(networkProvider: IPeerNetworkProvider, config?: DiscoveryConfig);
+    /**
+     * 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
+     */
+    discoverBlock(blockId: string): Promise<DiscoveryResult>;
+    /**
+     * 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
+     */
+    queryPeer(peerId: string, blockId: string): Promise<PeerQueryResult>;
+    /**
+     * 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: string): ILocationRecord[] | null;
+    /**
+     * Clear the discovery cache for a specific block.
+     *
+     * @param blockId - The block ID to clear from cache
+     */
+    clearCache(blockId: string): void;
+    /**
+     * Clear the entire discovery cache.
+     */
+    clearAllCache(): void;
+    /**
+     * 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
+     */
+    getPeerBloomFilter(peerId: string): Promise<BloomFilter>;
+    /**
+     * Get the current configuration.
+     *
+     * @returns The discovery configuration
+     */
+    getConfig(): DiscoveryConfig;
+    /**
+     * Clear the Bloom filter cache for a specific peer.
+     *
+     * @param peerId - The peer to clear from cache
+     */
+    clearBloomFilterCache(peerId: string): void;
+    /**
+     * Clear all Bloom filter caches.
+     */
+    clearAllBloomFilterCache(): void;
+    /**
+     * 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
+     */
+    private filterPeersWithBloomFilters;
+    /**
+     * 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
+     */
+    private queryPeersWithConcurrencyLimit;
+    /**
+     * 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
+     */
+    private buildLocationRecords;
+    /**
+     * Cache discovery results.
+     *
+     * @param blockId - Block ID to cache
+     * @param locations - Location records to cache
+     */
+    private cacheResults;
+}
+//# sourceMappingURL=discoveryProtocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discoveryProtocol.d.ts","sourceRoot":"","sources":["../../../../../brightchain-api-lib/src/lib/availability/discoveryProtocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,WAAW,EACX,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAqBxE;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,mBAAmB,IAAI,MAAM,EAAE,CAAC;IAEhC;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,iBAAiB,CACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAkBxD,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAlBzB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAE5D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;IAExE;;;;;OAKG;gBAEgB,eAAe,EAAE,oBAAoB,EACrC,MAAM,GAAE,eAAwC;IAGnE;;;;;;OAMG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA2D9D;;;;;;;OAOG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAyB1E;;;;;;OAMG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,GAAG,IAAI;IAgB7D;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,aAAa,IAAI,IAAI;IAIrB;;;;;;OAMG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAgB9D;;;;OAIG;IACH,SAAS,IAAI,eAAe;IAI5B;;;;OAIG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3C;;OAEG;IACH,wBAAwB,IAAI,IAAI;IAIhC;;;;;;;;OAQG;YACW,2BAA2B;IAgCzC;;;;;;;OAOG;YACW,8BAA8B;IAgC5C;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CAMrB"}