@brightchain/brightchain-api-lib 0.0.1

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

@@ -0,0 +1,250 @@
+/**
+ * @fileoverview Availability Service Implementation
+ *
+ * Main service for coordinating block availability tracking across the distributed
+ * storage system. Integrates BlockRegistry, DiscoveryProtocol, GossipService,
+ * ReconciliationService, and HeartbeatMonitor.
+ *
+ * @see Requirements 1.7, 7.2, 7.3, 7.4, 7.5, 7.7, 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+ */
+import { AvailabilityEventHandler, AvailabilityServiceConfig, AvailabilityState, AvailabilityStatistics, EventFilter, IAvailabilityService, IBlockRegistry, IDiscoveryProtocol, IGossipService, IHeartbeatMonitor, ILocationRecord, IReconciliationService, LocationQueryResult, ReconciliationResult } from '@brightchain/brightchain-lib';
+/**
+ * Internal structure for tracking block metadata with location.
+ */
+interface BlockLocationData {
+    /**
+     * Current availability state
+     */
+    state: AvailabilityState;
+    /**
+     * Known locations for this block
+     */
+    locations: ILocationRecord[];
+    /**
+     * When the location data was last updated
+     */
+    lastUpdated: Date;
+}
+/**
+ * Availability Service Implementation
+ *
+ * Coordinates block availability tracking, discovery, partition handling,
+ * and event emission across the distributed storage system.
+ *
+ * @see Requirements 1.7, 7.2, 7.3, 7.4, 7.5, 7.7, 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+ */
+export declare class AvailabilityService implements IAvailabilityService {
+    private readonly registry;
+    private readonly discoveryProtocol;
+    private readonly gossipService;
+    private readonly reconciliationService;
+    private readonly heartbeatMonitor;
+    private readonly config;
+    /**
+     * Block location data indexed by block ID.
+     */
+    private readonly blockData;
+    /**
+     * Registered event handlers with filters.
+     */
+    private readonly handlers;
+    /**
+     * Whether the service is currently in partition mode.
+     */
+    private partitionMode;
+    /**
+     * Peers that were disconnected when entering partition mode.
+     */
+    private disconnectedPeers;
+    /**
+     * Whether the service is running.
+     */
+    private running;
+    /**
+     * Create a new AvailabilityService.
+     *
+     * @param registry - Block registry for local block tracking
+     * @param discoveryProtocol - Protocol for discovering blocks on the network
+     * @param gossipService - Service for announcing blocks
+     * @param reconciliationService - Service for state reconciliation
+     * @param heartbeatMonitor - Monitor for peer connectivity
+     * @param config - Service configuration
+     */
+    constructor(registry: IBlockRegistry, discoveryProtocol: IDiscoveryProtocol, gossipService: IGossipService, reconciliationService: IReconciliationService, heartbeatMonitor: IHeartbeatMonitor, config?: AvailabilityServiceConfig);
+    /**
+     * Get the availability state for a block.
+     *
+     * @param blockId - The block ID to query
+     * @returns Promise resolving to the block's availability state
+     * @see Requirements 1.7, 11.1
+     */
+    getAvailabilityState(blockId: string): Promise<AvailabilityState>;
+    /**
+     * Get all known locations for a block.
+     *
+     * @param blockId - The block ID to query
+     * @returns Promise resolving to array of location records
+     * @see Requirements 11.2
+     */
+    getBlockLocations(blockId: string): Promise<ILocationRecord[]>;
+    /**
+     * Get detailed location query result with staleness indication.
+     *
+     * @param blockId - The block ID to query
+     * @returns Promise resolving to location query result
+     * @see Requirements 11.5, 11.6
+     */
+    queryBlockLocation(blockId: string): Promise<LocationQueryResult>;
+    /**
+     * List all blocks in a specific availability state.
+     *
+     * @param state - The availability state to filter by
+     * @returns Promise resolving to array of block IDs
+     * @see Requirements 11.3
+     */
+    listBlocksByState(state: AvailabilityState): Promise<string[]>;
+    /**
+     * Get statistics about block availability distribution.
+     *
+     * @returns Promise resolving to availability statistics
+     * @see Requirements 11.4
+     */
+    getStatistics(): Promise<AvailabilityStatistics>;
+    /**
+     * Update or add a location record for a block.
+     *
+     * @param blockId - The block ID to update
+     * @param location - The location record to add or update
+     * @see Requirements 2.4, 14.2
+     */
+    updateLocation(blockId: string, location: ILocationRecord): Promise<void>;
+    /**
+     * Remove a location record for a block.
+     *
+     * @param blockId - The block ID to update
+     * @param nodeId - The node ID to remove from locations
+     * @see Requirements 2.5, 14.3
+     */
+    removeLocation(blockId: string, nodeId: string): Promise<void>;
+    /**
+     * Set the availability state for a block.
+     *
+     * @param blockId - The block ID to update
+     * @param state - The new availability state
+     * @see Requirements 14.1
+     */
+    setAvailabilityState(blockId: string, state: AvailabilityState): Promise<void>;
+    /**
+     * Check if the service is currently in partition mode.
+     *
+     * @returns True if in partition mode
+     * @see Requirements 7.2
+     */
+    isInPartitionMode(): boolean;
+    /**
+     * Enter partition mode.
+     *
+     * @see Requirements 7.2, 7.3, 7.7, 14.4
+     */
+    enterPartitionMode(): void;
+    /**
+     * Exit partition mode and initiate reconciliation.
+     *
+     * @returns Promise resolving to reconciliation result
+     * @see Requirements 7.5, 9.1, 14.4, 14.5
+     */
+    exitPartitionMode(): Promise<ReconciliationResult>;
+    /**
+     * Get the list of peers that were disconnected when entering partition mode.
+     *
+     * @returns Array of disconnected peer IDs
+     */
+    getDisconnectedPeers(): string[];
+    /**
+     * Subscribe to availability events.
+     *
+     * @param handler - Function to call when events occur
+     * @param filter - Optional filter to receive only specific events
+     * @see Requirements 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+     */
+    onEvent(handler: AvailabilityEventHandler, filter?: EventFilter): void;
+    /**
+     * Remove an event handler.
+     *
+     * @param handler - The handler to remove
+     */
+    offEvent(handler: AvailabilityEventHandler): void;
+    /**
+     * Start the availability service.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the availability service.
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the service is running.
+     *
+     * @returns True if the service is active
+     */
+    isRunning(): boolean;
+    /**
+     * Get the current configuration.
+     *
+     * @returns The availability service configuration
+     */
+    getConfig(): AvailabilityServiceConfig;
+    /**
+     * Get the local node ID.
+     *
+     * @returns The local node's unique identifier
+     */
+    getLocalNodeId(): string;
+    /**
+     * Handle connectivity change events from heartbeat monitor.
+     */
+    private handleConnectivityChange;
+    /**
+     * Mark all Remote blocks as Orphaned when entering partition mode.
+     *
+     * @see Requirements 7.3
+     */
+    private markRemoteBlocksAsOrphaned;
+    /**
+     * Emit an event to all matching handlers.
+     *
+     * @param event - The event to emit
+     */
+    private emitEvent;
+    /**
+     * Check if an event matches a filter.
+     *
+     * @param event - The event to check
+     * @param filter - The filter to match against
+     * @returns True if the event matches the filter
+     * @see Requirements 14.6
+     */
+    private eventMatchesFilter;
+    /**
+     * Extract block ID from an event if present.
+     */
+    private getBlockIdFromEvent;
+    /**
+     * Simple glob pattern matching (supports * wildcard).
+     */
+    private matchesGlobPattern;
+    /**
+     * Clear all block data (for testing).
+     */
+    clear(): void;
+    /**
+     * Get block data directly (for testing).
+     */
+    getBlockData(blockId: string): BlockLocationData | undefined;
+    /**
+     * Set block data directly (for testing).
+     */
+    setBlockData(blockId: string, data: BlockLocationData): void;
+}
+export {};
+//# sourceMappingURL=availabilityService.d.ts.map

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

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