@brightchain/brightchain-api-lib 0.14.0 → 0.15.0

package/src/lib/blockFetch/blockFetcher.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * @fileoverview BlockFetcher Implementation
+ *
+ * Retrieves block data from remote nodes with:
+ * - Checksum verification
+ * - Retry logic with exponential backoff
+ * - Node health tracking (cooldown)
+ * - Pool-scoped storage via putInPool
+ * - Pool metadata validation (PoolMismatchError on mismatch)
+ *
+ * @see cross-node-eventual-consistency design, Section 9
+ * @see pool-scoped-whitening requirements 7.1, 7.2, 7.3, 7.4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockFetcher = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+/**
+ * BlockFetcher retrieves blocks from remote nodes, verifies checksums,
+ * stores them in the correct pool, and validates pool metadata.
+ *
+ * Pool-scoped fetch behavior (Requirements 7.1–7.4):
+ * - When poolId is provided, fetched blocks are stored via putInPool(poolId, data)
+ * - The fetcher verifies that the block's metadata poolId matches the requested poolId
+ * - PoolMismatchError is thrown when metadata doesn't match
+ * - Tuple reconstruction callers pass the same poolId for all blocks
+ */
+class BlockFetcher {
+    constructor(transport, availabilityService, store, config = brightchain_lib_1.DEFAULT_BLOCK_FETCHER_CONFIG, gossipService, fetchQueue) {
+        this.transport = transport;
+        this.availabilityService = availabilityService;
+        this.store = store;
+        this.config = config;
+        this.gossipService = gossipService;
+        this.fetchQueue = fetchQueue;
+        this.nodeCooldowns = new Map();
+        this.checksumService = new brightchain_lib_1.ChecksumService();
+        this.running = false;
+        /**
+         * Bound handler for gossip announcements, stored so we can unsubscribe in stop().
+         * Only set when proactiveFetchEnabled is true and gossipService is provided.
+         */
+        this.announcementHandler = null;
+    }
+    /**
+     * Fetch a block from remote nodes and store it locally.
+     *
+     * The entire operation is bounded by `fetchTimeoutMs` (Req 1.6).
+     *
+     * When poolId is provided:
+     * 1. The block is stored in the specified pool via putInPool (Req 7.1)
+     * 2. After storage, the block's metadata poolId is verified against the requested poolId (Req 7.2)
+     * 3. If metadata doesn't match, the block is rejected with PoolMismatchError (Req 7.3)
+     *
+     * For tuple reconstruction, callers pass the same poolId for all blocks (Req 7.4).
+     */
+    async fetchBlock(blockId, poolId) {
+        return this.withTimeout(blockId, () => this.doFetchBlock(blockId, poolId));
+    }
+    /**
+     * Core fetch logic: query locations, filter cooldowns, try nodes in order.
+     */
+    async doFetchBlock(blockId, poolId) {
+        const locations = await this.availabilityService.getBlockLocations(blockId);
+        const candidateNodes = locations
+            .map((loc) => loc.nodeId)
+            .filter((nodeId) => this.isNodeAvailable(nodeId));
+        if (candidateNodes.length === 0) {
+            return {
+                success: false,
+                error: `No available nodes for block ${blockId}`,
+                attemptedNodes: [],
+            };
+        }
+        const attemptedNodes = [];
+        for (const nodeId of candidateNodes) {
+            const result = await this.tryFetchFromNode(nodeId, blockId, poolId, attemptedNodes);
+            if (result) {
+                return result;
+            }
+        }
+        return {
+            success: false,
+            error: `All ${candidateNodes.length} candidate nodes failed for block ${blockId}`,
+            attemptedNodes,
+        };
+    }
+    /**
+     * Try fetching a block from a single node with retries.
+     * Returns a successful BlockFetchResult or null if all retries failed.
+     */
+    async tryFetchFromNode(nodeId, blockId, poolId, attemptedNodes) {
+        for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+            try {
+                if (attempt > 0) {
+                    const delay = this.config.retryBaseDelayMs * Math.pow(2, attempt - 1);
+                    await this.sleep(delay);
+                }
+                const data = await this.transport.fetchBlockFromNode(nodeId, blockId, poolId);
+                // Verify checksum matches blockId
+                const computedChecksum = this.checksumService
+                    .calculateChecksum(data)
+                    .toHex();
+                if (computedChecksum !== blockId) {
+                    const msg = `Checksum mismatch: expected ${blockId}, got ${computedChecksum}`;
+                    attemptedNodes.push({ nodeId, error: msg });
+                    this.markNodeUnavailable(nodeId);
+                    return null;
+                }
+                // Store the block in the correct pool
+                await this.storeBlock(blockId, data, poolId);
+                // Validate pool metadata if poolId was specified (Req 7.2, 7.3)
+                if (poolId) {
+                    await this.validatePoolMetadata(blockId, poolId);
+                }
+                attemptedNodes.push({ nodeId });
+                return {
+                    success: true,
+                    data,
+                    attemptedNodes,
+                };
+            }
+            catch (error) {
+                // Re-throw PoolMismatchError immediately — don't retry pool violations
+                if (error instanceof brightchain_lib_1.PoolMismatchError) {
+                    attemptedNodes.push({ nodeId, error: error.message });
+                    throw error;
+                }
+                if (error instanceof brightchain_lib_1.BlockFetchError) {
+                    attemptedNodes.push({ nodeId, error: error.message });
+                    throw error;
+                }
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                // Only record the final attempt failure
+                if (attempt === this.config.maxRetries) {
+                    attemptedNodes.push({ nodeId, error: errorMsg });
+                    this.markNodeUnavailable(nodeId);
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Store a fetched block. When poolId is provided and the store supports pools,
+     * the block is stored in the specified pool via putInPool (Req 7.1).
+     * Otherwise falls back to the standard put method.
+     */
+    async storeBlock(blockId, data, poolId) {
+        if (poolId && (0, brightchain_lib_1.isPooledBlockStore)(this.store)) {
+            await this.store.putInPool(poolId, data);
+        }
+        else {
+            await this.store.put(blockId, data);
+        }
+    }
+    /**
+     * Validate that the stored block's metadata poolId matches the requested poolId.
+     * Throws PoolMismatchError if there's a mismatch (Req 7.2, 7.3).
+     */
+    async validatePoolMetadata(blockId, expectedPoolId) {
+        const metadata = await this.store.getMetadata(blockId);
+        if (metadata?.poolId && metadata.poolId !== expectedPoolId) {
+            throw new brightchain_lib_1.PoolMismatchError(blockId, expectedPoolId, metadata.poolId);
+        }
+    }
+    /** Check if a node is currently available (not in cooldown) */
+    isNodeAvailable(nodeId) {
+        const cooldownUntil = this.nodeCooldowns.get(nodeId);
+        if (cooldownUntil === undefined) {
+            return true;
+        }
+        if (Date.now() >= cooldownUntil) {
+            this.nodeCooldowns.delete(nodeId);
+            return true;
+        }
+        return false;
+    }
+    /** Mark a node as unavailable for the configured cooldown period */
+    markNodeUnavailable(nodeId) {
+        this.nodeCooldowns.set(nodeId, Date.now() + this.config.nodeCooldownMs);
+    }
+    /** Get the current configuration */
+    getConfig() {
+        return { ...this.config };
+    }
+    /** Start the fetcher and subscribe to gossip announcements if proactive fetching is enabled */
+    start() {
+        this.running = true;
+        if (this.config.proactiveFetchEnabled &&
+            this.gossipService &&
+            this.fetchQueue) {
+            this.announcementHandler = (announcement) => {
+                void this.handleProactiveAnnouncement(announcement);
+            };
+            this.gossipService.onAnnouncement(this.announcementHandler);
+        }
+    }
+    /** Stop the fetcher, unsubscribe from gossip, and clean up */
+    stop() {
+        if (this.announcementHandler && this.gossipService) {
+            this.gossipService.offAnnouncement(this.announcementHandler);
+            this.announcementHandler = null;
+        }
+        this.running = false;
+        this.nodeCooldowns.clear();
+    }
+    /** Whether the fetcher is currently running */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Handle a gossip announcement for proactive fetching.
+     * Checks if the block is already local; if not, enqueues a low-priority fetch.
+     *
+     * @see Requirements 6.1, 6.2
+     */
+    async handleProactiveAnnouncement(announcement) {
+        // Only proactively fetch for 'add' announcements
+        if (announcement.type !== 'add') {
+            return;
+        }
+        const { blockId } = announcement;
+        try {
+            const state = await this.availabilityService.getAvailabilityState(blockId);
+            // Block is already locally accessible — no need to fetch
+            if ((0, brightchain_lib_1.isLocallyAccessible)(state)) {
+                return;
+            }
+            // Enqueue a low-priority fetch via the fetch queue
+            if (this.fetchQueue) {
+                // Fire-and-forget: we don't need to await the result for proactive fetches
+                void this.fetchQueue.enqueue(blockId);
+            }
+        }
+        catch {
+            // Proactive fetch is best-effort; swallow errors silently
+        }
+    }
+    /**
+     * Race the fetch operation against fetchTimeoutMs (Req 1.6).
+     * Returns a FetchTimeoutError result if the timeout fires first.
+     */
+    withTimeout(blockId, operation) {
+        const { fetchTimeoutMs } = this.config;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve({
+                    success: false,
+                    error: `Fetch for block ${blockId} timed out after ${fetchTimeoutMs}ms`,
+                    attemptedNodes: [],
+                });
+            }, fetchTimeoutMs);
+            operation()
+                .then((result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(result);
+            })
+                .catch((err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.BlockFetcher = BlockFetcher;
+//# sourceMappingURL=blockFetcher.js.map

package/src/lib/blockFetch/blockFetcher.js.map

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

package/src/lib/blockFetch/fetchQueue.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview FetchQueue Implementation
+ *
+ * Priority queue with deduplication for remote block fetch requests.
+ * - Coalesces concurrent requests for the same blockId into a single fetch
+ * - Bounds concurrency to maxConcurrency simultaneous fetches
+ * - Orders pending fetches by waiter count (more waiters = higher priority)
+ * - Enforces per-request timeout with cancellation for all waiters
+ *
+ * The queue delegates actual fetch execution to an injected executor function,
+ * which allows the BlockFetcher to handle node selection, retries, and
+ * checksum verification while the queue handles scheduling concerns.
+ *
+ * @see cross-node-eventual-consistency design, Section 10
+ * @see Requirements 4.1, 4.2, 4.3, 4.4
+ */
+import { BlockFetchResult, FetchQueueConfig, IFetchQueue, PoolId } from '@brightchain/brightchain-lib';
+/**
+ * Function type for the fetch executor.
+ * The queue calls this to perform the actual block retrieval.
+ * The executor is responsible for node selection, retries, and verification.
+ */
+export type FetchExecutor = (blockId: string, poolId?: PoolId) => Promise<BlockFetchResult>;
+/**
+ * FetchQueue manages block fetch requests with deduplication, priority ordering,
+ * and bounded concurrency.
+ *
+ * Deduplication (Req 4.1): If blockId is already pending or active, new callers
+ * are appended to the existing waiters list — only one fetch executes.
+ *
+ * Concurrency (Req 4.2): At most `maxConcurrency` fetches run in parallel.
+ *
+ * Priority (Req 4.3): When a slot opens, the pending entry with the most waiters
+ * is dispatched next.
+ *
+ * Timeout (Req 4.4): Each active fetch is bounded by `fetchTimeoutMs`. On timeout,
+ * all waiters for that blockId receive a FetchTimeoutError.
+ */
+export declare class FetchQueue implements IFetchQueue {
+    private readonly executor;
+    /** Queued blockIds not yet dispatched — keyed by blockId */
+    private readonly pending;
+    /**
+     * Currently executing blockIds.
+     * Maps blockId to its waiters list and the timeout handle for cancellation.
+     */
+    private readonly active;
+    private readonly config;
+    /**
+     * @param executor - Function that performs the actual block fetch.
+     *   The queue calls this when dispatching; the executor handles node
+     *   selection, retries, and checksum verification.
+     * @param config - Optional partial config; merged with defaults.
+     */
+    constructor(executor: FetchExecutor, config?: Partial<FetchQueueConfig>);
+    /**
+     * Enqueue a block fetch request.
+     * If the blockId is already pending or active, the caller's promise is
+     * coalesced with the existing request (Req 4.1).
+     */
+    enqueue(blockId: string, poolId?: PoolId): Promise<BlockFetchResult>;
+    /** Number of requests waiting to be dispatched */
+    getPendingCount(): number;
+    /** Number of fetches currently in progress */
+    getActiveCount(): number;
+    /**
+     * Cancel all pending and active fetch requests.
+     * Every waiter receives a rejection with the given reason.
+     */
+    cancelAll(reason: string): void;
+    /** Current queue configuration */
+    getConfig(): FetchQueueConfig;
+    /**
+     * Dispatch pending entries up to the concurrency limit.
+     * Selects the entry with the most waiters first (Req 4.3).
+     */
+    private drain;
+    /**
+     * Pick and remove the pending entry with the most waiters.
+     */
+    private pickHighestPriority;
+    /**
+     * Dispatch a single fetch: move entry to active, start the executor,
+     * and arm the timeout (Req 4.4).
+     */
+    private dispatch;
+}
+//# sourceMappingURL=fetchQueue.d.ts.map

package/src/lib/blockFetch/fetchQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchQueue.d.ts","sourceRoot":"","sources":["../../../../../brightchain-api-lib/src/lib/blockFetch/fetchQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,gBAAgB,EAEhB,gBAAgB,EAEhB,WAAW,EACX,MAAM,EACP,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,KACZ,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAe/B;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAW,YAAW,WAAW;IAsB1C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IArB3B,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAEhE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGT;IAEd,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAE1C;;;;;OAKG;gBAEgB,QAAQ,EAAE,aAAa,EACxC,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAKpC;;;;OAIG;IACI,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8B3E,kDAAkD;IAC3C,eAAe,IAAI,MAAM;IAIhC,8CAA8C;IACvC,cAAc,IAAI,MAAM;IAI/B;;;OAGG;IACI,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAmBtC,kCAAkC;IAC3B,SAAS,IAAI,gBAAgB;IAMpC;;;OAGG;IACH,OAAO,CAAC,KAAK;IAWb;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAmEjB"}

package/src/lib/blockFetch/fetchQueue.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * @fileoverview FetchQueue Implementation
+ *
+ * Priority queue with deduplication for remote block fetch requests.
+ * - Coalesces concurrent requests for the same blockId into a single fetch
+ * - Bounds concurrency to maxConcurrency simultaneous fetches
+ * - Orders pending fetches by waiter count (more waiters = higher priority)
+ * - Enforces per-request timeout with cancellation for all waiters
+ *
+ * The queue delegates actual fetch execution to an injected executor function,
+ * which allows the BlockFetcher to handle node selection, retries, and
+ * checksum verification while the queue handles scheduling concerns.
+ *
+ * @see cross-node-eventual-consistency design, Section 10
+ * @see Requirements 4.1, 4.2, 4.3, 4.4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchQueue = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+/**
+ * FetchQueue manages block fetch requests with deduplication, priority ordering,
+ * and bounded concurrency.
+ *
+ * Deduplication (Req 4.1): If blockId is already pending or active, new callers
+ * are appended to the existing waiters list — only one fetch executes.
+ *
+ * Concurrency (Req 4.2): At most `maxConcurrency` fetches run in parallel.
+ *
+ * Priority (Req 4.3): When a slot opens, the pending entry with the most waiters
+ * is dispatched next.
+ *
+ * Timeout (Req 4.4): Each active fetch is bounded by `fetchTimeoutMs`. On timeout,
+ * all waiters for that blockId receive a FetchTimeoutError.
+ */
+class FetchQueue {
+    /**
+     * @param executor - Function that performs the actual block fetch.
+     *   The queue calls this when dispatching; the executor handles node
+     *   selection, retries, and checksum verification.
+     * @param config - Optional partial config; merged with defaults.
+     */
+    constructor(executor, config) {
+        this.executor = executor;
+        /** Queued blockIds not yet dispatched — keyed by blockId */
+        this.pending = new Map();
+        /**
+         * Currently executing blockIds.
+         * Maps blockId to its waiters list and the timeout handle for cancellation.
+         */
+        this.active = new Map();
+        this.config = { ...brightchain_lib_1.DEFAULT_FETCH_QUEUE_CONFIG, ...config };
+    }
+    /**
+     * Enqueue a block fetch request.
+     * If the blockId is already pending or active, the caller's promise is
+     * coalesced with the existing request (Req 4.1).
+     */
+    enqueue(blockId, poolId) {
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject };
+            // Coalesce with an already-active fetch
+            const activeEntry = this.active.get(blockId);
+            if (activeEntry) {
+                activeEntry.waiters.push(waiter);
+                return;
+            }
+            // Coalesce with a pending entry
+            const pendingEntry = this.pending.get(blockId);
+            if (pendingEntry) {
+                pendingEntry.waiters.push(waiter);
+                return;
+            }
+            // Create a new pending entry
+            this.pending.set(blockId, {
+                blockId,
+                poolId,
+                waiters: [waiter],
+            });
+            // Try to dispatch immediately if there's capacity
+            this.drain();
+        });
+    }
+    /** Number of requests waiting to be dispatched */
+    getPendingCount() {
+        return this.pending.size;
+    }
+    /** Number of fetches currently in progress */
+    getActiveCount() {
+        return this.active.size;
+    }
+    /**
+     * Cancel all pending and active fetch requests.
+     * Every waiter receives a rejection with the given reason.
+     */
+    cancelAll(reason) {
+        const error = new Error(reason);
+        for (const [, entry] of this.pending) {
+            for (const waiter of entry.waiters) {
+                waiter.reject(error);
+            }
+        }
+        this.pending.clear();
+        for (const [, entry] of this.active) {
+            clearTimeout(entry.timeoutHandle);
+            for (const waiter of entry.waiters) {
+                waiter.reject(error);
+            }
+        }
+        this.active.clear();
+    }
+    /** Current queue configuration */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ── Private helpers ──────────────────────────────────────────────────
+    /**
+     * Dispatch pending entries up to the concurrency limit.
+     * Selects the entry with the most waiters first (Req 4.3).
+     */
+    drain() {
+        while (this.active.size < this.config.maxConcurrency &&
+            this.pending.size > 0) {
+            const next = this.pickHighestPriority();
+            if (!next)
+                break;
+            this.dispatch(next);
+        }
+    }
+    /**
+     * Pick and remove the pending entry with the most waiters.
+     */
+    pickHighestPriority() {
+        let best;
+        for (const [, entry] of this.pending) {
+            if (!best || entry.waiters.length > best.waiters.length) {
+                best = entry;
+            }
+        }
+        if (best) {
+            this.pending.delete(best.blockId);
+        }
+        return best;
+    }
+    /**
+     * Dispatch a single fetch: move entry to active, start the executor,
+     * and arm the timeout (Req 4.4).
+     */
+    dispatch(entry) {
+        const { blockId, poolId, waiters } = entry;
+        let settled = false;
+        const timeoutHandle = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            const current = this.active.get(blockId);
+            this.active.delete(blockId);
+            const timeoutError = new brightchain_lib_1.FetchTimeoutError(blockId, this.config.fetchTimeoutMs);
+            if (current) {
+                for (const w of current.waiters) {
+                    w.reject(timeoutError);
+                }
+            }
+            this.drain();
+        }, this.config.fetchTimeoutMs);
+        this.active.set(blockId, { waiters, timeoutHandle });
+        this.executor(blockId, poolId)
+            .then((result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutHandle);
+            const current = this.active.get(blockId);
+            this.active.delete(blockId);
+            if (current) {
+                for (const w of current.waiters) {
+                    w.resolve(result);
+                }
+            }
+            this.drain();
+        })
+            .catch((err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutHandle);
+            const current = this.active.get(blockId);
+            this.active.delete(blockId);
+            const failResult = {
+                success: false,
+                error: err.message,
+                attemptedNodes: [],
+            };
+            if (current) {
+                for (const w of current.waiters) {
+                    w.resolve(failResult);
+                }
+            }
+            this.drain();
+        });
+    }
+}
+exports.FetchQueue = FetchQueue;
+//# sourceMappingURL=fetchQueue.js.map

package/src/lib/blockFetch/fetchQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchQueue.js","sourceRoot":"","sources":["../../../../../brightchain-api-lib/src/lib/blockFetch/fetchQueue.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,kEAOsC;AAyBtC;;;;;;;;;;;;;;GAcG;AACH,MAAa,UAAU;IAerB;;;;;OAKG;IACH,YACmB,QAAuB,EACxC,MAAkC;QADjB,aAAQ,GAAR,QAAQ,CAAe;QArB1C,4DAA4D;QAC3C,YAAO,GAA8B,IAAI,GAAG,EAAE,CAAC;QAEhE;;;WAGG;QACc,WAAM,GAGnB,IAAI,GAAG,EAAE,CAAC;QAcZ,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,4CAA0B,EAAE,GAAG,MAAM,EAAE,CAAC;IAC7D,CAAC;IAED;;;;OAIG;IACI,OAAO,CAAC,OAAe,EAAE,MAAe;QAC7C,OAAO,IAAI,OAAO,CAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACvD,MAAM,MAAM,GAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;YAE3C,wCAAwC;YACxC,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC7C,IAAI,WAAW,EAAE,CAAC;gBAChB,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACjC,OAAO;YACT,CAAC;YAED,gCAAgC;YAChC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC/C,IAAI,YAAY,EAAE,CAAC;gBACjB,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAClC,OAAO;YACT,CAAC;YAED,6BAA6B;YAC7B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE;gBACxB,OAAO;gBACP,MAAM;gBACN,OAAO,EAAE,CAAC,MAAM,CAAC;aAClB,CAAC,CAAC;YAEH,kDAAkD;YAClD,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED,kDAAkD;IAC3C,eAAe;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,8CAA8C;IACvC,cAAc;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,MAAc;QAC7B,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;QAEhC,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBACnC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAErB,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACpC,YAAY,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;YAClC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBACnC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,kCAAkC;IAC3B,SAAS;QACd,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED,wEAAwE;IAExE;;;OAGG;IACK,KAAK;QACX,OACE,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc;YAC7C,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,EACrB,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACxC,IAAI,CAAC,IAAI;gBAAE,MAAM;YACjB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED;;OAEG;IACK,mBAAmB;QACzB,IAAI,IAA8B,CAAC;QACnC,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBACxD,IAAI,GAAG,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACK,QAAQ,CAAC,KAAmB;QAClC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;QAC3C,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;YACpC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YAEf,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAE5B,MAAM,YAAY,GAAG,IAAI,mCAAiB,CACxC,OAAO,EACP,IAAI,CAAC,MAAM,CAAC,cAAc,CAC3B,CAAC;YAEF,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;oBAChC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;YAED,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAE/B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;QAErD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;aAC3B,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YACf,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,aAAa,CAAC,CAAC;YAE5B,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAE5B,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;oBAChC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACpB,CAAC;YACH,CAAC;YAED,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAU,EAAE,EAAE;YACpB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,aAAa,CAAC,CAAC;YAE5B,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAE5B,MAAM,UAAU,GAAqB;gBACnC,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG,CAAC,OAAO;gBAClB,cAAc,EAAE,EAAE;aACnB,CAAC;YAEF,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;oBAChC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC;YAED,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;IACP,CAAC;CACF;AA7MD,gCA6MC"}

package/src/lib/blockFetch/httpBlockFetchTransport.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview HTTP Block Fetch Transport
+ *
+ * Implements IBlockFetchTransport using HTTP GET requests to remote nodes'
+ * SyncController `/api/sync/blocks/:blockId` endpoint.
+ *
+ * Node.js specific (uses fetch API available in Node 18+).
+ *
+ * @see cross-node-eventual-consistency design, Section 2
+ * @see Requirements 1.1, 5.2
+ */
+import { IBlockFetchTransport, PoolId } from '@brightchain/brightchain-lib';
+/**
+ * Resolves a node ID to its base URL (e.g., `http://node-address:port`).
+ * Implementations may use a static registry, DNS, or discovery service.
+ */
+export interface INodeAddressResolver {
+    /**
+     * Get the base URL for a given node.
+     * @param nodeId - The node identifier
+     * @returns The base URL (without trailing slash), or undefined if unknown
+     */
+    getNodeBaseUrl(nodeId: string): string | undefined;
+}
+/**
+ * Simple map-based node address resolver.
+ * Maps node IDs to their base URLs.
+ */
+export declare class MapNodeAddressResolver implements INodeAddressResolver {
+    private readonly nodeAddresses;
+    constructor(nodeAddresses: Map<string, string>);
+    getNodeBaseUrl(nodeId: string): string | undefined;
+}
+/**
+ * HTTP-based implementation of IBlockFetchTransport.
+ *
+ * Fetches block data from remote nodes via their SyncController endpoint:
+ *   GET /api/sync/blocks/:blockId[?poolId=<poolId>]
+ *
+ * The response is JSON with `{ message, blockId, data }` where `data` is
+ * base64-encoded. This transport decodes the base64 data and returns raw bytes.
+ *
+ * @see Requirements 1.1 — Block fetching protocol
+ * @see Requirements 5.2 — Pool ID included in fetch request
+ */
+export declare class HttpBlockFetchTransport implements IBlockFetchTransport {
+    private readonly addressResolver;
+    constructor(addressResolver: INodeAddressResolver);
+    /**
+     * Fetch raw block data from a specific remote node via HTTP GET.
+     *
+     * @param nodeId - The target node identifier (resolved to URL via addressResolver)
+     * @param blockId - The block checksum/ID to fetch
+     * @param poolId - Optional pool scope; appended as query parameter
+     * @returns The raw block bytes decoded from the base64 response
+     * @throws BlockFetchError if the node address is unknown, HTTP request fails, or response is invalid
+     */
+    fetchBlockFromNode(nodeId: string, blockId: string, poolId?: PoolId): Promise<Uint8Array>;
+    /**
+     * Build the full URL for the block fetch request.
+     * Format: {baseUrl}/api/sync/blocks/{blockId}[?poolId={poolId}]
+     */
+    private buildUrl;
+}
+//# sourceMappingURL=httpBlockFetchTransport.d.ts.map

package/src/lib/blockFetch/httpBlockFetchTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpBlockFetchTransport.d.ts","sourceRoot":"","sources":["../../../../../brightchain-api-lib/src/lib/blockFetch/httpBlockFetchTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAGL,oBAAoB,EACpB,MAAM,EACP,MAAM,8BAA8B,CAAC;AAEtC;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACpD;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAExD,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG1D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,uBAAwB,YAAW,oBAAoB;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe;gBAAf,eAAe,EAAE,oBAAoB;IAElE;;;;;;;;OAQG;IACU,kBAAkB,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,CAAC;IA+DtB;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAUjB"}