@brightchain/brightchain-api-lib 0.0.1

package/src/lib/stores/diskBlockAsyncStore.js

@@ -0,0 +1,803 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiskBlockAsyncStore = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const stream_1 = require("stream");
+const checksumTransform_1 = require("../transforms/checksumTransform");
+const memoryWritableStream_1 = require("../transforms/memoryWritableStream");
+const xorMultipleTransform_1 = require("../transforms/xorMultipleTransform");
+const diskBlockMetadataStore_1 = require("./diskBlockMetadataStore");
+const diskBlockStore_1 = require("./diskBlockStore");
+/**
+ * Parity block file extension pattern: {blockId}.p{index}
+ */
+const PARITY_FILE_EXTENSION_PREFIX = '.p';
+/**
+ * DiskBlockAsyncStore provides asynchronous operations for storing and retrieving blocks from disk.
+ * It supports raw block storage and XOR operations with stream-based data handling.
+ * Blocks are stored as raw data without metadata - their meaning is derived from CBLs.
+ *
+ * This implementation supports:
+ * - Core block operations (store, retrieve, delete)
+ * - Metadata management for tracking block lifecycle and access patterns
+ * - FEC (Forward Error Correction) operations using Reed-Solomon encoding
+ * - Replication tracking for distributed storage
+ */
+class DiskBlockAsyncStore extends diskBlockStore_1.DiskBlockStore {
+    constructor(config) {
+        super(config);
+        /**
+         * Optional FEC service for parity generation and recovery.
+         * If not provided, FEC operations will return errors or no-ops.
+         */
+        this.fecService = null;
+        this.metadataStore = new diskBlockMetadataStore_1.DiskBlockMetadataStore(config.storePath, config.blockSize);
+    }
+    /**
+     * Set the FEC service for parity generation and recovery.
+     * @param fecService - The FEC service to use
+     */
+    setFecService(fecService) {
+        this.fecService = fecService;
+    }
+    /**
+     * Get the FEC service if available.
+     * @returns The FEC service or null if not available
+     */
+    getFecService() {
+        return this.fecService;
+    }
+    /**
+     * Get the metadata store.
+     * @returns The metadata store
+     */
+    getMetadataStore() {
+        return this.metadataStore;
+    }
+    /**
+     * Convert a key to hex string format.
+     * @param key - The key as Checksum or string
+     * @returns The key as hex string
+     */
+    keyToHex(key) {
+        return typeof key === 'string' ? key : key.toHex();
+    }
+    /**
+     * Convert a hex string to Checksum.
+     * @param hex - The hex string
+     * @returns The Checksum
+     */
+    hexToChecksum(hex) {
+        return brightchain_lib_1.Checksum.fromHex(hex);
+    }
+    /**
+     * Get the file path for a parity block.
+     * Parity files are stored alongside block files with .p{index} extension.
+     * @param blockId - The data block's checksum
+     * @param parityIndex - The parity block index (0-based)
+     * @returns The parity file path
+     */
+    parityPath(blockId, parityIndex) {
+        return this.blockPath(blockId) + PARITY_FILE_EXTENSION_PREFIX + parityIndex;
+    }
+    /**
+     * Check if a block exists
+     */
+    async has(key) {
+        const keyChecksum = typeof key === 'string' ? brightchain_lib_1.Checksum.fromHex(key) : key;
+        const blockPath = this.blockPath(keyChecksum);
+        return (0, fs_1.existsSync)(blockPath);
+    }
+    /**
+     * Get a handle to a block
+     */
+    get(key) {
+        const keyChecksum = typeof key === 'string' ? brightchain_lib_1.Checksum.fromHex(key) : key;
+        const blockPath = this.blockPath(keyChecksum);
+        // Read the block data synchronously to create the handle
+        // This matches the synchronous signature expected by IBlockStore.get
+        if (!(0, fs_1.existsSync)(blockPath)) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyChecksum.toHex(),
+            });
+        }
+        const data = (0, fs_1.readFileSync)(blockPath);
+        return (0, brightchain_lib_1.createBlockHandle)(brightchain_lib_1.RawDataBlock, this._blockSize, data, keyChecksum, true, // canRead
+        true);
+    }
+    /**
+     * Get a block's data
+     */
+    async getData(key) {
+        const keyHex = this.keyToHex(key);
+        const blockPath = this.blockPath(key);
+        if (!(0, fs_1.existsSync)(blockPath)) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        let data;
+        try {
+            data = await (0, promises_1.readFile)(blockPath);
+        }
+        catch {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        if (data.length > this._blockSize) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockFileSizeMismatch);
+        }
+        // Use file creation time as block creation time
+        const stats = await (0, promises_1.stat)(blockPath);
+        const dateCreated = stats.birthtime;
+        // Record access in metadata
+        if (this.metadataStore.has(keyHex)) {
+            await this.metadataStore.recordAccess(keyHex);
+        }
+        return new brightchain_lib_1.RawDataBlock(this._blockSize, data, dateCreated, key, brightchain_lib_1.BlockType.RawData, brightchain_lib_1.BlockDataType.EphemeralStructuredData, // Use EphemeralStructuredData as default
+        true, // canRead
+        true);
+    }
+    /**
+     * Delete a block's data (and associated parity blocks and metadata)
+     * @param key - The block's checksum
+     */
+    async deleteData(key) {
+        const keyHex = this.keyToHex(key);
+        const blockPath = this.blockPath(key);
+        if (!(0, fs_1.existsSync)(blockPath)) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound);
+        }
+        // Get metadata to find parity blocks
+        const metadata = await this.metadataStore.get(keyHex);
+        // Delete parity blocks first
+        if (metadata && metadata.parityBlockIds.length > 0) {
+            for (let i = 0; i < metadata.parityBlockIds.length; i++) {
+                const parityFilePath = this.parityPath(key, i);
+                if ((0, fs_1.existsSync)(parityFilePath)) {
+                    try {
+                        await (0, promises_1.unlink)(parityFilePath);
+                    }
+                    catch {
+                        // Ignore errors deleting parity files
+                    }
+                }
+            }
+        }
+        // Delete the block data
+        try {
+            await (0, promises_1.unlink)(blockPath);
+        }
+        catch (error) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockDeletionFailed, undefined, {
+                ERROR: error instanceof Error ? error.message : String(error),
+            });
+        }
+        // Delete metadata (if exists)
+        if (this.metadataStore.has(keyHex)) {
+            try {
+                await this.metadataStore.delete(keyHex);
+            }
+            catch {
+                // Ignore errors deleting metadata
+            }
+        }
+    }
+    /**
+     * Store a block's data with optional durability settings
+     */
+    async setData(block, options) {
+        if (block.blockSize !== this._blockSize) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockSizeMismatch);
+        }
+        const keyHex = this.keyToHex(block.idChecksum);
+        const blockPath = this.blockPath(block.idChecksum);
+        if ((0, fs_1.existsSync)(blockPath)) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockPathAlreadyExists);
+        }
+        try {
+            block.validate();
+        }
+        catch {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockValidationFailed);
+        }
+        // Ensure block directory exists before writing
+        this.ensureBlockPath(block.idChecksum);
+        try {
+            await (0, promises_1.writeFile)(blockPath, Buffer.from(block.data));
+        }
+        catch (error) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockDirectoryCreationFailed, undefined, {
+                ERROR: error instanceof Error ? error.message : String(error),
+            });
+        }
+        // Create metadata for the block
+        const metadata = (0, brightchain_lib_1.createDefaultBlockMetadata)(keyHex, block.data.length, keyHex, options);
+        await this.metadataStore.create(metadata);
+        // Generate parity blocks based on durability level
+        const durabilityLevel = options?.durabilityLevel ?? brightchain_lib_1.DurabilityLevel.Standard;
+        const parityCount = (0, brightchain_lib_1.getParityCountForDurability)(durabilityLevel);
+        if (parityCount > 0 && this.fecService) {
+            try {
+                await this.generateParityBlocks(block.idChecksum, parityCount);
+            }
+            catch {
+                // If parity generation fails, we still keep the block but log the issue
+                // The block will have no parity protection
+            }
+        }
+    }
+    /**
+     * XOR multiple blocks together
+     */
+    async xor(blocks, destBlockMetadata) {
+        if (!blocks.length) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.NoBlocksProvided);
+        }
+        return new Promise((resolve, reject) => {
+            // Create read streams from the full block data
+            const readStreams = blocks.map((block) => {
+                const data = block.fullData; // Use fullData to get padded content
+                const stream = new stream_1.Readable();
+                stream.push(Buffer.from(data));
+                stream.push(null);
+                return stream;
+            });
+            const xorStream = new xorMultipleTransform_1.XorMultipleTransformStream(readStreams);
+            const checksumStream = new checksumTransform_1.ChecksumTransform();
+            const writeStream = new memoryWritableStream_1.MemoryWritableStream();
+            // Set up pipeline
+            xorStream.pipe(checksumStream).pipe(writeStream);
+            // Handle stream ends
+            this.handleReadStreamEnds(readStreams, xorStream);
+            // Handle checksum calculation
+            checksumStream.on('checksum', (checksumBuffer) => {
+                try {
+                    const block = new brightchain_lib_1.RawDataBlock(this._blockSize, writeStream.data, new Date(destBlockMetadata.dateCreated), checksumBuffer, brightchain_lib_1.BlockType.RawData, destBlockMetadata.dataType, // Use the metadata's dataType
+                    true, // canRead
+                    true);
+                    resolve(block);
+                }
+                catch (error) {
+                    reject(error);
+                }
+                finally {
+                    this.cleanupStreams([
+                        ...readStreams,
+                        xorStream,
+                        checksumStream,
+                        writeStream,
+                    ]);
+                }
+            });
+            // Handle errors
+            const handleError = (error) => {
+                this.cleanupStreams([
+                    ...readStreams,
+                    xorStream,
+                    checksumStream,
+                    writeStream,
+                ]);
+                reject(error);
+            };
+            readStreams.forEach((stream) => stream.on('error', handleError));
+            xorStream.on('error', handleError);
+            checksumStream.on('error', handleError);
+            writeStream.on('error', handleError);
+        });
+    }
+    /**
+     * Handle read stream ends
+     */
+    handleReadStreamEnds(readStreams, xorStream) {
+        let endedStreams = 0;
+        readStreams.forEach((readStream) => {
+            readStream.on('end', () => {
+                if (++endedStreams === readStreams.length) {
+                    xorStream.end();
+                }
+            });
+        });
+    }
+    /**
+     * Clean up streams
+     */
+    cleanupStreams(streams) {
+        streams.forEach((stream) => {
+            try {
+                stream.destroy();
+            }
+            catch {
+                // Ignore errors during cleanup
+            }
+        });
+    }
+    /**
+     * Get random block checksums from the store
+     * @param count - Maximum number of blocks to return
+     * @returns Array of random block checksums
+     */
+    async getRandomBlocks(count) {
+        const blockSizeString = (0, brightchain_lib_1.blockSizeToSizeString)(this._blockSize);
+        const basePath = (0, path_1.join)(this._storePath, blockSizeString);
+        if (!(0, fs_1.existsSync)(basePath)) {
+            return [];
+        }
+        const blocks = [];
+        const firstLevelDirs = await (0, promises_1.readdir)(basePath);
+        // Randomly select first level directories until we have enough blocks
+        while (blocks.length < count && firstLevelDirs.length > 0) {
+            // Pick a random first level directory
+            const randomFirstIndex = Math.floor(Math.random() * firstLevelDirs.length);
+            const firstDir = firstLevelDirs[randomFirstIndex];
+            const firstLevelPath = (0, path_1.join)(basePath, firstDir);
+            if (!(0, fs_1.existsSync)(firstLevelPath)) {
+                // Remove invalid directory and continue
+                firstLevelDirs.splice(randomFirstIndex, 1);
+                continue;
+            }
+            // Get second level directories
+            const secondLevelDirs = await (0, promises_1.readdir)(firstLevelPath);
+            if (secondLevelDirs.length === 0) {
+                // Remove empty directory and continue
+                firstLevelDirs.splice(randomFirstIndex, 1);
+                continue;
+            }
+            // Pick a random second level directory
+            const randomSecondIndex = Math.floor(Math.random() * secondLevelDirs.length);
+            const secondDir = secondLevelDirs[randomSecondIndex];
+            const secondLevelPath = (0, path_1.join)(firstLevelPath, secondDir);
+            if (!(0, fs_1.existsSync)(secondLevelPath)) {
+                continue;
+            }
+            // Get block files (exclude metadata and parity files)
+            const blockFiles = (await (0, promises_1.readdir)(secondLevelPath)).filter((file) => !file.endsWith('.m.json') &&
+                !file.includes(PARITY_FILE_EXTENSION_PREFIX));
+            if (blockFiles.length === 0) {
+                continue;
+            }
+            // Pick a random block
+            const randomBlockIndex = Math.floor(Math.random() * blockFiles.length);
+            const blockFile = blockFiles[randomBlockIndex];
+            blocks.push(brightchain_lib_1.Checksum.fromHex(blockFile));
+            // Remove used directory if we still need more blocks
+            if (blocks.length < count) {
+                firstLevelDirs.splice(randomFirstIndex, 1);
+            }
+        }
+        return blocks;
+    }
+    /**
+     * Store raw data with a key (convenience method)
+     * Creates a RawDataBlock and stores it
+     */
+    async put(key, data, options) {
+        const keyChecksum = typeof key === 'string' ? brightchain_lib_1.Checksum.fromHex(key) : key;
+        const block = new brightchain_lib_1.RawDataBlock(this._blockSize, data, new Date(), keyChecksum);
+        await this.setData(block, options);
+    }
+    /**
+     * Delete a block (convenience method, alias for deleteData)
+     */
+    async delete(key) {
+        const keyChecksum = typeof key === 'string' ? brightchain_lib_1.Checksum.fromHex(key) : key;
+        await this.deleteData(keyChecksum);
+    }
+    // === Metadata Operations ===
+    /**
+     * Get metadata for a block
+     * @param key - The block's checksum or ID
+     * @returns The block's metadata, or null if not found
+     */
+    async getMetadata(key) {
+        const keyHex = this.keyToHex(key);
+        return this.metadataStore.get(keyHex);
+    }
+    /**
+     * Update metadata for a block
+     * @param key - The block's checksum or ID
+     * @param updates - Partial metadata updates to apply
+     */
+    async updateMetadata(key, updates) {
+        const keyHex = this.keyToHex(key);
+        if (!this.metadataStore.has(keyHex)) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        await this.metadataStore.update(keyHex, updates);
+    }
+    // === FEC/Durability Operations ===
+    /**
+     * Generate parity blocks for a data block using Reed-Solomon encoding.
+     * Parity blocks are stored as separate files: {blockId}.p0, {blockId}.p1, etc.
+     * @param key - The data block's checksum
+     * @param parityCount - Number of parity blocks to generate
+     * @returns Array of parity block checksums (as synthetic IDs)
+     * @throws FecError if FEC service is not available or encoding fails
+     */
+    async generateParityBlocks(key, parityCount) {
+        const keyHex = this.keyToHex(key);
+        const keyChecksum = typeof key === 'string' ? brightchain_lib_1.Checksum.fromHex(key) : key;
+        // Check if FEC service is available
+        if (!this.fecService) {
+            throw new brightchain_lib_1.FecError(brightchain_lib_1.FecErrorType.FecEncodingFailed, undefined, {
+                ERROR: 'FEC service is not available',
+            });
+        }
+        // Check if block exists
+        const blockPath = this.blockPath(keyChecksum);
+        if (!(0, fs_1.existsSync)(blockPath)) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        // Check if FEC service is available in the environment
+        const isAvailable = await this.fecService.isAvailable();
+        if (!isAvailable) {
+            throw new brightchain_lib_1.FecError(brightchain_lib_1.FecErrorType.FecEncodingFailed, undefined, {
+                ERROR: 'FEC service is not available in this environment',
+            });
+        }
+        // Read block data
+        const blockData = await (0, promises_1.readFile)(blockPath);
+        // Generate parity data
+        const parityData = await this.fecService.createParityData(blockData, parityCount);
+        // Store parity blocks as separate files
+        const parityBlockIds = [];
+        for (let i = 0; i < parityData.length; i++) {
+            const parityFilePath = this.parityPath(keyChecksum, i);
+            await (0, promises_1.writeFile)(parityFilePath, Buffer.from(parityData[i].data));
+            parityBlockIds.push(`${keyHex}.p${i}`);
+        }
+        // Update metadata with parity block IDs
+        if (this.metadataStore.has(keyHex)) {
+            await this.metadataStore.update(keyHex, { parityBlockIds });
+        }
+        // Return parity block IDs as Checksum (using hex encoding for synthetic IDs)
+        return parityBlockIds.map((id) => {
+            // For parity block IDs, we create a checksum from the hex-encoded ID string
+            // This is a synthetic ID, not a real checksum of data
+            const paddedHex = id.padEnd(64, '0').slice(0, 64);
+            return brightchain_lib_1.Checksum.fromHex(paddedHex);
+        });
+    }
+    /**
+     * Get parity block checksums for a data block.
+     * @param key - The data block's checksum or ID
+     * @returns Array of parity block checksums
+     */
+    async getParityBlocks(key) {
+        const keyHex = this.keyToHex(key);
+        // Get metadata to find parity block IDs
+        const metadata = await this.metadataStore.get(keyHex);
+        if (!metadata) {
+            return [];
+        }
+        // Return parity block IDs as Checksum
+        // Pad to 128 hex characters (64 bytes) for SHA3-512
+        return metadata.parityBlockIds.map((id) => {
+            const paddedHex = id.padEnd(128, '0').slice(0, 128);
+            return brightchain_lib_1.Checksum.fromHex(paddedHex);
+        });
+    }
+    /**
+     * Load parity data from disk for a block.
+     * @param key - The data block's checksum
+     * @returns Array of parity data objects
+     */
+    async loadParityData(key) {
+        const keyHex = this.keyToHex(key);
+        const metadata = await this.metadataStore.get(keyHex);
+        if (!metadata || metadata.parityBlockIds.length === 0) {
+            return [];
+        }
+        const parityData = [];
+        for (let i = 0; i < metadata.parityBlockIds.length; i++) {
+            const parityFilePath = this.parityPath(key, i);
+            if ((0, fs_1.existsSync)(parityFilePath)) {
+                const data = await (0, promises_1.readFile)(parityFilePath);
+                parityData.push({ data, index: i });
+            }
+        }
+        return parityData;
+    }
+    /**
+     * Attempt to recover a corrupted or missing block using parity data.
+     * @param key - The block's checksum or ID
+     * @returns Recovery result with the recovered block or error
+     */
+    async recoverBlock(key) {
+        const keyHex = this.keyToHex(key);
+        const keyChecksum = typeof key === 'string' ? brightchain_lib_1.Checksum.fromHex(key) : key;
+        // Check if FEC service is available
+        if (!this.fecService) {
+            return {
+                success: false,
+                error: 'FEC service is not available',
+            };
+        }
+        // Check if FEC service is available in the environment
+        const isAvailable = await this.fecService.isAvailable();
+        if (!isAvailable) {
+            return {
+                success: false,
+                error: 'FEC service is not available in this environment',
+            };
+        }
+        // Get parity data from disk
+        const parityData = await this.loadParityData(keyChecksum);
+        if (parityData.length === 0) {
+            return {
+                success: false,
+                error: 'No parity data available for recovery',
+            };
+        }
+        // Get metadata for original size
+        const metadata = await this.metadataStore.get(keyHex);
+        if (!metadata) {
+            return {
+                success: false,
+                error: 'Block metadata not found',
+            };
+        }
+        try {
+            // Get corrupted data if block still exists
+            const blockPath = this.blockPath(keyChecksum);
+            let corruptedData = null;
+            if ((0, fs_1.existsSync)(blockPath)) {
+                corruptedData = await (0, promises_1.readFile)(blockPath);
+            }
+            // Attempt recovery
+            const result = await this.fecService.recoverFileData(corruptedData, parityData, metadata.size);
+            if (result.recovered) {
+                // Create a new block with recovered data
+                const recoveredBlock = new brightchain_lib_1.RawDataBlock(this._blockSize, new Uint8Array(result.data));
+                // Update the stored block on disk
+                await (0, promises_1.writeFile)(blockPath, Buffer.from(result.data));
+                return {
+                    success: true,
+                    recoveredBlock,
+                };
+            }
+            return {
+                success: false,
+                error: 'Recovery failed - insufficient parity data',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown recovery error',
+            };
+        }
+    }
+    /**
+     * Verify block integrity against its parity data.
+     * @param key - The block's checksum or ID
+     * @returns True if the block data matches its parity data
+     */
+    async verifyBlockIntegrity(key) {
+        const _keyHex = this.keyToHex(key);
+        const keyChecksum = typeof key === 'string' ? brightchain_lib_1.Checksum.fromHex(key) : key;
+        // Check if FEC service is available
+        if (!this.fecService) {
+            // Without FEC service, we can only verify the block exists
+            return this.has(key);
+        }
+        // Check if FEC service is available in the environment
+        const isAvailable = await this.fecService.isAvailable();
+        if (!isAvailable) {
+            // Without FEC service, we can only verify the block exists
+            return this.has(key);
+        }
+        // Check if block exists
+        const blockPath = this.blockPath(keyChecksum);
+        if (!(0, fs_1.existsSync)(blockPath)) {
+            return false;
+        }
+        // Get parity data from disk
+        const parityData = await this.loadParityData(keyChecksum);
+        if (parityData.length === 0) {
+            // No parity data - can only verify block exists
+            return true;
+        }
+        try {
+            const blockData = await (0, promises_1.readFile)(blockPath);
+            return await this.fecService.verifyFileIntegrity(blockData, parityData);
+        }
+        catch {
+            return false;
+        }
+    }
+    // === Replication Operations ===
+    /**
+     * Get blocks that are pending replication (status = Pending).
+     * @returns Array of block checksums pending replication
+     */
+    async getBlocksPendingReplication() {
+        const pendingBlocks = await this.metadataStore.findByReplicationStatus(brightchain_lib_1.ReplicationStatus.Pending);
+        return pendingBlocks
+            .filter((meta) => meta.targetReplicationFactor > 0)
+            .map((meta) => this.hexToChecksum(meta.blockId));
+    }
+    /**
+     * Get blocks that are under-replicated (status = UnderReplicated).
+     * @returns Array of block checksums that need additional replicas
+     */
+    async getUnderReplicatedBlocks() {
+        const underReplicatedBlocks = await this.metadataStore.findByReplicationStatus(brightchain_lib_1.ReplicationStatus.UnderReplicated);
+        return underReplicatedBlocks.map((meta) => this.hexToChecksum(meta.blockId));
+    }
+    /**
+     * Record that a block has been replicated to a node.
+     * @param key - The block's checksum or ID
+     * @param nodeId - The ID of the node that now holds a replica
+     */
+    async recordReplication(key, nodeId) {
+        const keyHex = this.keyToHex(key);
+        const metadata = await this.metadataStore.get(keyHex);
+        if (!metadata) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        // Add node to replica list if not already present
+        const replicaNodeIds = [...metadata.replicaNodeIds];
+        if (!replicaNodeIds.includes(nodeId)) {
+            replicaNodeIds.push(nodeId);
+        }
+        // Update replication status based on target factor
+        let replicationStatus = metadata.replicationStatus;
+        if (replicaNodeIds.length >= metadata.targetReplicationFactor) {
+            replicationStatus = brightchain_lib_1.ReplicationStatus.Replicated;
+        }
+        else if (replicaNodeIds.length > 0) {
+            replicationStatus = brightchain_lib_1.ReplicationStatus.UnderReplicated;
+        }
+        await this.metadataStore.update(keyHex, {
+            replicaNodeIds,
+            replicationStatus,
+        });
+    }
+    /**
+     * Record that a replica node is no longer available.
+     * @param key - The block's checksum or ID
+     * @param nodeId - The ID of the node that lost the replica
+     */
+    async recordReplicaLoss(key, nodeId) {
+        const keyHex = this.keyToHex(key);
+        const metadata = await this.metadataStore.get(keyHex);
+        if (!metadata) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        // Remove node from replica list
+        const replicaNodeIds = metadata.replicaNodeIds.filter((id) => id !== nodeId);
+        // Update replication status based on remaining replicas
+        let replicationStatus = metadata.replicationStatus;
+        if (metadata.targetReplicationFactor > 0) {
+            if (replicaNodeIds.length >= metadata.targetReplicationFactor) {
+                replicationStatus = brightchain_lib_1.ReplicationStatus.Replicated;
+            }
+            else if (replicaNodeIds.length > 0) {
+                replicationStatus = brightchain_lib_1.ReplicationStatus.UnderReplicated;
+            }
+            else {
+                replicationStatus = brightchain_lib_1.ReplicationStatus.Pending;
+            }
+        }
+        await this.metadataStore.update(keyHex, {
+            replicaNodeIds,
+            replicationStatus,
+        });
+    }
+    // === Block Expiration and Cleanup ===
+    /**
+     * Find all blocks that have expired (expiresAt is in the past).
+     * @returns Array of metadata for expired blocks
+     */
+    async findExpired() {
+        return this.metadataStore.findExpired();
+    }
+    /**
+     * Clean up expired blocks.
+     * This method identifies expired blocks and deletes them along with their
+     * parity blocks and metadata.
+     *
+     * @param cblChecker - Optional function to check if a block is referenced by a CBL.
+     *                     If provided, blocks referenced by active CBLs will not be deleted.
+     * @returns Object containing deleted block IDs and any errors encountered
+     */
+    async cleanupExpiredBlocks(cblChecker) {
+        const expiredBlocks = await this.findExpired();
+        const deletedBlockIds = [];
+        const errors = [];
+        for (const metadata of expiredBlocks) {
+            try {
+                // Check if block is referenced by a CBL
+                if (cblChecker) {
+                    const isReferenced = await cblChecker(metadata.blockId);
+                    if (isReferenced) {
+                        // Skip deletion - block is still referenced
+                        continue;
+                    }
+                }
+                // Delete the block (this also deletes parity blocks and metadata)
+                const keyBuffer = this.hexToChecksum(metadata.blockId);
+                await this.deleteData(keyBuffer);
+                deletedBlockIds.push(metadata.blockId);
+            }
+            catch (error) {
+                errors.push({
+                    blockId: metadata.blockId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return { deletedBlockIds, errors };
+    }
+    // === XOR Brightening Operations ===
+    /**
+     * Brighten a block by XORing it with random blocks from the store.
+     * This is used to implement Owner-Free storage patterns where the
+     * original data cannot be reconstructed without all the random blocks.
+     *
+     * @param key - The source block's checksum or ID
+     * @param randomBlockCount - Number of random blocks to XOR with
+     * @returns Result containing the brightened block ID and the random block IDs used
+     * @throws StoreError if the source block is not found or insufficient random blocks are available
+     */
+    async brightenBlock(key, randomBlockCount) {
+        const keyHex = this.keyToHex(key);
+        const keyChecksum = typeof key === 'string' ? brightchain_lib_1.Checksum.fromHex(key) : key;
+        // Verify source block exists
+        const blockPath = this.blockPath(keyChecksum);
+        if (!(0, fs_1.existsSync)(blockPath)) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        // Get random blocks for XOR operation
+        const randomBlockChecksums = await this.getRandomBlocks(randomBlockCount);
+        // Check if we have enough random blocks
+        if (randomBlockChecksums.length < randomBlockCount) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.InsufficientRandomBlocks, undefined, {
+                REQUESTED: randomBlockCount.toString(),
+                AVAILABLE: randomBlockChecksums.length.toString(),
+            });
+        }
+        // Get the source block handle
+        const sourceBlockHandle = this.get(keyChecksum);
+        // Get handles for all random blocks
+        const randomBlockHandles = randomBlockChecksums.map((checksum) => this.get(checksum));
+        // Combine source block with random blocks for XOR operation
+        const allBlockHandles = [sourceBlockHandle, ...randomBlockHandles];
+        // Create metadata for the brightened block
+        const destBlockMetadata = new brightchain_lib_1.BlockMetadata(this._blockSize, brightchain_lib_1.BlockType.RawData, brightchain_lib_1.BlockDataType.EphemeralStructuredData, this._blockSize, // lengthWithoutPadding - use full block size for XOR result
+        new Date());
+        // Perform XOR operation using the existing xor method
+        const brightenedBlock = await this.xor(allBlockHandles, destBlockMetadata);
+        const brightenedBlockId = brightenedBlock.idChecksum.toHex();
+        // Store the brightened block if it doesn't already exist
+        const brightenedBlockExists = await this.has(brightenedBlockId);
+        if (!brightenedBlockExists) {
+            await this.setData(brightenedBlock);
+        }
+        // Get the random block IDs as hex strings
+        const randomBlockIds = randomBlockChecksums.map((checksum) => checksum.toHex());
+        return {
+            brightenedBlockId,
+            randomBlockIds,
+            originalBlockId: keyHex,
+        };
+    }
+}
+exports.DiskBlockAsyncStore = DiskBlockAsyncStore;
+//# sourceMappingURL=diskBlockAsyncStore.js.map