claude-flow-novice 1.6.3 → 1.6.5

package/.claude-flow-novice/dist/src/coordination/archives/v2-sdk-typescript/v2/core/message-broker.js

@@ -0,0 +1,920 @@
+/**
+ * Agent Coordination V2 - Message Broker Implementation
+ *
+ * EventEmitter-based message broker supporting:
+ * - Pub/sub pattern with topic-based routing
+ * - Request/reply pattern with timeout handling
+ * - Broadcast pattern to all subscribers
+ * - Priority queue ordering
+ * - At-least-once delivery semantics
+ *
+ * @module coordination/v2/core/message-broker
+ */ import { EventEmitter } from 'events';
+import { RateLimiter } from 'limiter';
+import { MessagePriority, MessageUtils, DeliverySemantics } from './message.js';
+import { PayloadValidator } from '../security/payload-validator.js';
+/**
+ * Message broker error.
+ */ export class MessageBrokerError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'MessageBrokerError';
+    }
+}
+/**
+ * Priority queue for message ordering.
+ */ let PriorityQueue = class PriorityQueue {
+    items = [];
+    enqueue(item) {
+        this.items.push(item);
+        this.items.sort((a, b)=>b.priority - a.priority); // Higher priority first
+    }
+    dequeue() {
+        return this.items.shift();
+    }
+    peek() {
+        return this.items[0];
+    }
+    get length() {
+        return this.items.length;
+    }
+    size() {
+        return this.items.length;
+    }
+    clear() {
+        this.items = [];
+    }
+};
+/**
+ * Message Broker Implementation.
+ *
+ * Core message bus for inter-agent communication with support for:
+ * - Topic-based pub/sub pattern
+ * - Request/reply pattern with correlation
+ * - Broadcast to all subscribers
+ * - Priority-based message ordering
+ * - At-least-once delivery semantics
+ * - Subscription management
+ * - Message statistics and monitoring
+ *
+ * @example
+ * ```typescript
+ * const broker = new MessageBroker();
+ *
+ * // Subscribe to topic
+ * const sub = await broker.subscribe({
+ *   topic: 'task.completed',
+ *   handler: async (msg) => {
+ *     console.log('Task completed:', msg.payload);
+ *   }
+ * });
+ *
+ * // Publish message
+ * await broker.publish({
+ *   topic: 'task.completed',
+ *   payload: { taskId: 'task-1', result: 'success' },
+ *   priority: MessagePriority.HIGH
+ * });
+ *
+ * // Request/reply pattern
+ * const reply = await broker.request('task.execute', { taskId: 'task-2' });
+ * console.log('Reply:', reply.payload);
+ *
+ * // Unsubscribe
+ * sub.unsubscribe();
+ * ```
+ */ export class MessageBroker {
+    emitter;
+    subscriptions;
+    pendingRequests;
+    messageQueue;
+    config;
+    stats;
+    processing;
+    subscriptionCounter;
+    // SEC-DOS-001: Per-sender queue tracking and dead letter queue
+    senderQueueSizes;
+    deadLetterQueue;
+    // SEC-DOS-002: Rate limiting
+    rateLimiters;
+    rateLimiterCleanupInterval;
+    // SEC-INJ-001: Payload validation
+    payloadValidator;
+    // SEC-MEM-001: Subscription tracking and limits
+    agentSubscriptions;
+    subscriptionCleanupInterval;
+    /**
+   * Creates a new message broker instance.
+   *
+   * @param config - Broker configuration options
+   */ constructor(config){
+        this.emitter = new EventEmitter();
+        this.emitter.setMaxListeners(0); // Unlimited listeners
+        this.subscriptions = new Map();
+        this.pendingRequests = new Map();
+        this.messageQueue = new PriorityQueue();
+        this.subscriptionCounter = 0;
+        this.processing = false;
+        // SEC-DOS-001: Initialize per-sender queue tracking
+        this.senderQueueSizes = new Map();
+        this.deadLetterQueue = new PriorityQueue();
+        // SEC-DOS-002: Initialize rate limiters
+        this.rateLimiters = new Map();
+        // SEC-MEM-001: Initialize subscription tracking
+        this.agentSubscriptions = new Map();
+        this.config = {
+            maxQueueSize: config?.maxQueueSize ?? 10000,
+            maxQueueSizePerSender: config?.maxQueueSizePerSender ?? 100,
+            enableDeadLetterQueue: config?.enableDeadLetterQueue ?? true,
+            priorityEvictionThreshold: config?.priorityEvictionThreshold ?? 0.9,
+            defaultRequestTimeout: config?.defaultRequestTimeout ?? 30000,
+            enableStats: config?.enableStats ?? true,
+            maxConcurrency: config?.maxConcurrency ?? 100,
+            maxSubscriptions: config?.maxSubscriptions ?? 10000,
+            maxSubscriptionsPerAgent: config?.maxSubscriptionsPerAgent ?? 100,
+            subscriptionTTL: config?.subscriptionTTL ?? 3600000,
+            cleanupIntervalMs: config?.cleanupIntervalMs ?? 60000,
+            authorizationProvider: config?.authorizationProvider,
+            rateLimit: config?.rateLimit ? {
+                maxMessagesPerSecond: config.rateLimit.maxMessagesPerSecond ?? 100,
+                maxBurstSize: config.rateLimit.maxBurstSize ?? 10,
+                strategy: config.rateLimit.strategy ?? 'token-bucket'
+            } : undefined,
+            payloadValidation: config?.payloadValidation
+        };
+        // SEC-INJ-001: Initialize payload validator
+        this.payloadValidator = new PayloadValidator(this.config.payloadValidation);
+        this.stats = {
+            totalPublished: 0,
+            totalDelivered: 0,
+            totalFailed: 0,
+            totalSubscriptions: 0,
+            messagesByTopic: {},
+            messagesByPriority: {},
+            avgDeliveryTime: 0
+        };
+        // SEC-DOS-002: Start rate limiter cleanup if rate limiting is enabled
+        if (this.config.rateLimit) {
+            this.startRateLimiterCleanup();
+        }
+        // SEC-MEM-001: Start subscription cleanup for TTL expiration
+        this.startSubscriptionCleanup();
+    }
+    // ============================================
+    // Pub/Sub Pattern
+    // ============================================
+    /**
+   * Subscribes to a topic with a message handler.
+   *
+   * @param config - Subscription configuration
+   * @returns Subscription handle for management
+   * @throws {MessageBrokerError} If configuration is invalid
+   *
+   * @example
+   * ```typescript
+   * const sub = await broker.subscribe({
+   *   topic: 'task.*',
+   *   handler: async (msg) => {
+   *     console.log('Received:', msg.payload);
+   *   },
+   *   priority: 10
+   * });
+   * ```
+   */ async subscribe(config) {
+        if (!config.topic || typeof config.topic !== 'string') {
+            throw new MessageBrokerError('Subscription topic must be a non-empty string');
+        }
+        // SEC-007: Validate topic name to prevent injection
+        this.validateTopicName(config.topic);
+        if (typeof config.handler !== 'function') {
+            throw new MessageBrokerError('Subscription handler must be a function');
+        }
+        // SEC-MEM-001: Check global subscription limit
+        if (this.stats.totalSubscriptions >= this.config.maxSubscriptions) {
+            throw new MessageBrokerError(`Maximum subscriptions reached (max: ${this.config.maxSubscriptions})`);
+        }
+        // SEC-MEM-001: Check per-agent subscription limit
+        const subscriberId = config.subscriberId || 'anonymous';
+        const agentSubs = this.agentSubscriptions.get(subscriberId) || new Set();
+        if (agentSubs.size >= this.config.maxSubscriptionsPerAgent) {
+            throw new MessageBrokerError(`Subscriber ${subscriberId} exceeded subscription limit (max: ${this.config.maxSubscriptionsPerAgent})`);
+        }
+        // SEC-012: Check subscription authorization
+        if (this.config.authorizationProvider && config.subscriberId) {
+            const authorized = await this.config.authorizationProvider.canSubscribe(config.subscriberId, config.topic);
+            if (!authorized) {
+                throw new MessageBrokerError(`Subscriber ${config.subscriberId} not authorized to subscribe to topic ${config.topic}`);
+            }
+        }
+        const subscriptionId = `sub-${++this.subscriptionCounter}-${Date.now()}`;
+        // SEC-MEM-001: Create subscription with TTL expiration
+        const internalSub = {
+            id: subscriptionId,
+            topic: config.topic,
+            handler: config.handler,
+            priority: config.priority ?? 0,
+            createdAt: Date.now(),
+            filter: config.filter,
+            expiresAt: Date.now() + this.config.subscriptionTTL,
+            subscriberId
+        };
+        // Add to subscriptions map
+        if (!this.subscriptions.has(config.topic)) {
+            this.subscriptions.set(config.topic, []);
+        }
+        const topicSubs = this.subscriptions.get(config.topic);
+        topicSubs.push(internalSub);
+        // Sort by priority (higher priority first)
+        topicSubs.sort((a, b)=>b.priority - a.priority);
+        // SEC-MEM-001: Track subscription by agent
+        agentSubs.add(subscriptionId);
+        this.agentSubscriptions.set(subscriberId, agentSubs);
+        this.stats.totalSubscriptions++;
+        return {
+            id: subscriptionId,
+            topic: config.topic,
+            createdAt: internalSub.createdAt,
+            unsubscribe: ()=>this.unsubscribe(subscriptionId)
+        };
+    }
+    /**
+   * Unsubscribes a subscription by ID.
+   *
+   * @param subscriptionId - Subscription ID to remove
+   * @returns True if subscription was removed, false if not found
+   */ unsubscribe(subscriptionId) {
+        for (const topic of Array.from(this.subscriptions.keys())){
+            const subs = this.subscriptions.get(topic);
+            const index = subs.findIndex((sub)=>sub.id === subscriptionId);
+            if (index !== -1) {
+                const sub = subs[index];
+                subs.splice(index, 1);
+                this.stats.totalSubscriptions--;
+                // SEC-MEM-001: Clean up agent subscription tracking
+                if (sub.subscriberId) {
+                    const agentSubs = this.agentSubscriptions.get(sub.subscriberId);
+                    if (agentSubs) {
+                        agentSubs.delete(subscriptionId);
+                        if (agentSubs.size === 0) {
+                            this.agentSubscriptions.delete(sub.subscriberId);
+                        }
+                    }
+                }
+                // Clean up empty topic entries
+                if (subs.length === 0) {
+                    this.subscriptions.delete(topic);
+                }
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+   * Publishes a message to a topic.
+   *
+   * @param config - Message configuration
+   * @returns Promise resolving to the published message
+   * @throws {MessageBrokerError} If message validation fails or queue is full
+   *
+   * @example
+   * ```typescript
+   * await broker.publish({
+   *   topic: 'task.completed',
+   *   payload: { taskId: 'task-1' },
+   *   priority: MessagePriority.HIGH
+   * });
+   * ```
+   */ async publish(config) {
+        MessageUtils.validateConfig(config);
+        // SEC-007: Validate topic name to prevent injection
+        this.validateTopicName(config.topic);
+        // SEC-INJ-001: Validate and sanitize payload BEFORE processing
+        const validationResult = this.payloadValidator.validate(config.payload);
+        if (!validationResult.valid) {
+            this.emitter.emit('validation:failed', {
+                errors: validationResult.errors,
+                senderId: config.senderId,
+                topic: config.topic
+            });
+            throw new MessageBrokerError(`Payload validation failed: ${validationResult.errors.join(', ')}`);
+        }
+        // SEC-INJ-001: Sanitize payload to prevent injection attacks
+        const sanitizedPayload = this.payloadValidator.sanitize(config.payload);
+        const senderId = config.senderId || 'anonymous';
+        // SEC-DOS-002: Rate limiting - Check FIRST before any processing
+        if (this.config.rateLimit) {
+            const allowed = await this.checkRateLimit(senderId);
+            if (!allowed) {
+                this.emitter.emit('rate-limit:exceeded', {
+                    senderId,
+                    topic: config.topic
+                });
+                throw new MessageBrokerError(`Rate limit exceeded for sender ${senderId}`);
+            }
+        }
+        // SEC-DOS-001: Per-sender queue limit - Check BEFORE global limit
+        // CRITICAL: Read and increment atomically to prevent race condition
+        const currentSenderSize = this.senderQueueSizes.get(senderId) || 0;
+        // Debug logging for per-sender queue tracking
+        if (process.env.DEBUG_MESSAGE_BROKER) {
+            console.log(`[MessageBroker PUBLISH] Sender ${senderId}: ${currentSenderSize} messages (limit: ${this.config.maxQueueSizePerSender}), queue processing: ${this.processing}`);
+        }
+        if (currentSenderSize >= this.config.maxQueueSizePerSender) {
+            throw new MessageBrokerError(`Sender ${senderId} exceeded queue limit (${currentSenderSize}/${this.config.maxQueueSizePerSender})`);
+        }
+        // SEC-DOS-001: Increment IMMEDIATELY after check to reserve slot (before async processing)
+        this.senderQueueSizes.set(senderId, currentSenderSize + 1);
+        if (process.env.DEBUG_MESSAGE_BROKER) {
+            console.log(`[MessageBroker PUBLISH] After increment: ${this.senderQueueSizes.get(senderId)}`);
+        }
+        // SEC-DOS-001: Global queue limit with priority eviction
+        if (this.messageQueue.length >= this.config.maxQueueSize) {
+            // If queue is at priority eviction threshold, evict low-priority messages
+            const evictionThreshold = Math.floor(this.config.maxQueueSize * this.config.priorityEvictionThreshold);
+            if (this.messageQueue.length >= evictionThreshold) {
+                const messagePriority = MessageUtils.normalizePriority(config.priority);
+                const evicted = this.evictLowPriorityMessages(messagePriority);
+                if (evicted.length === 0) {
+                    throw new MessageBrokerError(`Message queue full (max: ${this.config.maxQueueSize}, no evictable messages)`);
+                }
+                this.emitter.emit('queue:high-pressure', {
+                    queueSize: this.messageQueue.length,
+                    evicted: evicted.length,
+                    evictedMessages: evicted,
+                    threshold: evictionThreshold
+                });
+            } else {
+                throw new MessageBrokerError(`Message queue full (max: ${this.config.maxQueueSize})`);
+            }
+        }
+        // SEC-INJ-001: Use sanitized payload in message
+        const message = {
+            id: MessageUtils.generateMessageId(),
+            topic: config.topic,
+            payload: sanitizedPayload,
+            priority: MessageUtils.normalizePriority(config.priority),
+            timestamp: Date.now(),
+            replyTo: config.replyTo,
+            correlationId: config.correlationId,
+            senderId: config.senderId,
+            recipientId: config.recipientId,
+            deliverySemantics: config.deliverySemantics ?? DeliverySemantics.AT_LEAST_ONCE,
+            metadata: config.metadata
+        };
+        this.messageQueue.enqueue(message);
+        // SEC-DOS-001: Sender queue size already incremented at line 517 (atomic check-and-increment)
+        if (this.config.enableStats) {
+            this.stats.totalPublished++;
+            this.stats.messagesByTopic[message.topic] = (this.stats.messagesByTopic[message.topic] || 0) + 1;
+            this.stats.messagesByPriority[message.priority] = (this.stats.messagesByPriority[message.priority] || 0) + 1;
+        }
+        // Start processing if not already processing
+        this.processQueue().catch((error)=>{
+            console.error('Message queue processing error:', error);
+        });
+        return message;
+    }
+    /**
+   * Broadcasts a message to all subscribers matching the topic pattern.
+   *
+   * @param config - Message configuration
+   * @returns Promise resolving to array of delivery results
+   */ async broadcast(config) {
+        await this.publish({
+            ...config,
+            metadata: {
+                ...config.metadata,
+                broadcast: true
+            }
+        });
+    }
+    // ============================================
+    // Request/Reply Pattern
+    // ============================================
+    /**
+   * Sends a request message and waits for a reply.
+   *
+   * @param topic - Request topic
+   * @param payload - Request payload
+   * @param options - Request options (timeout, correlation ID)
+   * @returns Promise resolving to reply message
+   * @throws {MessageBrokerError} If request times out or fails
+   *
+   * @example
+   * ```typescript
+   * const reply = await broker.request('task.execute', { taskId: 'task-1' }, {
+   *   timeout: 5000
+   * });
+   * console.log('Reply:', reply.payload);
+   * ```
+   */ async request(topic, payload, options) {
+        const correlationId = options?.correlationId ?? MessageUtils.generateCorrelationId();
+        const timeout = options?.timeout ?? this.config.defaultRequestTimeout;
+        const priority = options?.priority ?? MessagePriority.NORMAL;
+        const replyTopic = `${topic}.reply.${correlationId}`;
+        return new Promise((resolve, reject)=>{
+            // Set timeout
+            const timeoutId = setTimeout(()=>{
+                this.pendingRequests.delete(correlationId);
+                reject(new MessageBrokerError(`Request timeout after ${timeout}ms (correlationId: ${correlationId})`));
+            }, timeout);
+            // Store pending request
+            this.pendingRequests.set(correlationId, {
+                correlationId,
+                resolve: resolve,
+                reject,
+                timeoutId,
+                createdAt: Date.now(),
+                expectedSender: options?.senderId,
+                resolved: false
+            });
+            // Publish request message
+            this.publish({
+                topic,
+                payload,
+                priority,
+                replyTo: replyTopic,
+                correlationId
+            }).catch((error)=>{
+                clearTimeout(timeoutId);
+                this.pendingRequests.delete(correlationId);
+                reject(error);
+            });
+        });
+    }
+    /**
+   * Sends a reply to a request message.
+   *
+   * @param request - Original request message
+   * @param payload - Reply payload
+   * @param success - Success status (default: true)
+   * @param error - Error message if failed
+   * @returns Promise resolving when reply is sent
+   *
+   * @example
+   * ```typescript
+   * await broker.subscribe({
+   *   topic: 'task.execute',
+   *   handler: async (msg) => {
+   *     const result = await executeTask(msg.payload);
+   *     await broker.reply(msg, result);
+   *   }
+   * });
+   * ```
+   */ async reply(request, payload, success = true, error) {
+        if (!request.replyTo) {
+            throw new MessageBrokerError('Cannot reply: request has no replyTo topic');
+        }
+        if (!request.correlationId) {
+            throw new MessageBrokerError('Cannot reply: request has no correlationId');
+        }
+        const reply = MessageUtils.createReply(request, payload, success, error);
+        await this.publish({
+            topic: request.replyTo,
+            payload: reply,
+            priority: request.priority,
+            correlationId: request.correlationId,
+            senderId: request.recipientId // SEC-006: Propagate responder ID for validation
+        });
+    }
+    // ============================================
+    // Message Processing
+    // ============================================
+    /**
+   * Processes the message queue (internal).
+   * Handles priority ordering and at-least-once delivery.
+   */ async processQueue() {
+        if (this.processing) {
+            return; // Already processing
+        }
+        this.processing = true;
+        try {
+            while(this.messageQueue.length > 0){
+                // SEC-DOS-001-RACE: Peek at message first to check for matching handlers
+                const message = this.messageQueue.peek();
+                if (!message) break;
+                // Check if there are any matching handlers BEFORE dequeuing
+                const hasHandlers = this.hasMatchingHandlers(message);
+                // SEC-DOS-001-RACE: Only dequeue if handlers exist to prevent race condition
+                if (!hasHandlers) {
+                    break;
+                }
+                // Now dequeue the message
+                this.messageQueue.dequeue();
+                // SEC-DOS-001: Deliver first, then decrement (counter represents "in-flight" messages)
+                await this.deliverMessage(message);
+                // SEC-DOS-001: Decrement AFTER successful delivery (message no longer in-flight)
+                const senderId = message.senderId || 'anonymous';
+                const senderSize = this.senderQueueSizes.get(senderId) || 0;
+                if (senderSize > 0) {
+                    this.senderQueueSizes.set(senderId, senderSize - 1);
+                    if (process.env.DEBUG_MESSAGE_BROKER) {
+                        console.log(`[MessageBroker DELIVER] Decremented ${senderId}: ${senderSize} -> ${this.senderQueueSizes.get(senderId)}`);
+                    }
+                }
+            }
+        } finally{
+            this.processing = false;
+        }
+    }
+    /**
+   * Checks if there are any matching handlers for a message (without delivering).
+   * Used to prevent dequeuing messages when no subscribers exist.
+   */ hasMatchingHandlers(message) {
+        // Check for pending request/reply handlers
+        if (message.correlationId && this.pendingRequests.has(message.correlationId)) {
+            return true;
+        }
+        // Check for topic subscribers
+        for (const topicPattern of Array.from(this.subscriptions.keys())){
+            if (MessageUtils.matchesTopic(message.topic, topicPattern)) {
+                const subs = this.subscriptions.get(topicPattern);
+                if (subs.length > 0) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+   * Delivers a message to all matching subscribers.
+   * Returns true if message was delivered to any handler, false otherwise.
+   */ async deliverMessage(message) {
+        const startTime = Date.now();
+        const matchingHandlers = [];
+        // SEC-MEM-001: Clean up expired subscriptions before delivery
+        this.cleanupExpiredSubscriptions();
+        // Find matching subscriptions
+        for (const topicPattern of Array.from(this.subscriptions.keys())){
+            const subs = this.subscriptions.get(topicPattern);
+            if (MessageUtils.matchesTopic(message.topic, topicPattern)) {
+                matchingHandlers.push(...subs);
+            }
+        }
+        // Handle reply messages (special case)
+        if (message.correlationId && this.pendingRequests.has(message.correlationId)) {
+            const pendingRequest = this.pendingRequests.get(message.correlationId);
+            // SEC-006: Validate sender authorization for reply
+            if (pendingRequest.expectedSender && message.senderId !== pendingRequest.expectedSender) {
+                console.warn(`[MessageBroker] Unauthorized reply sender: expected ${pendingRequest.expectedSender}, got ${message.senderId}`);
+                return; // Drop unauthorized reply
+            }
+            // SEC-006: Check duplicate reply detection
+            if (pendingRequest.resolved) {
+                console.warn(`[MessageBroker] Duplicate reply detected for correlationId ${message.correlationId}`);
+                return; // Drop duplicate reply
+            }
+            // Mark resolved and cleanup
+            pendingRequest.resolved = true;
+            clearTimeout(pendingRequest.timeoutId);
+            this.pendingRequests.delete(message.correlationId);
+            pendingRequest.resolve(message.payload);
+        }
+        // Sort handlers by priority
+        matchingHandlers.sort((a, b)=>b.priority - a.priority);
+        // Deliver to handlers
+        for (const sub of matchingHandlers){
+            try {
+                // Apply filter if present
+                if (sub.filter && !sub.filter(message)) {
+                    continue;
+                }
+                await sub.handler(message);
+                if (this.config.enableStats) {
+                    this.stats.totalDelivered++;
+                }
+            } catch (error) {
+                if (this.config.enableStats) {
+                    this.stats.totalFailed++;
+                }
+                // Emit error event but don't throw (at-least-once delivery)
+                this.emitter.emit('error', {
+                    error,
+                    message,
+                    subscription: sub
+                });
+            }
+        }
+        // SEC-DOS-001: Sender queue size already decremented in processQueue() after dequeue (line 729-734)
+        // Update delivery time statistics
+        if (this.config.enableStats && matchingHandlers.length > 0) {
+            const deliveryTime = Date.now() - startTime;
+            this.stats.avgDeliveryTime = (this.stats.avgDeliveryTime * (this.stats.totalDelivered - 1) + deliveryTime) / this.stats.totalDelivered;
+        }
+        // Return true if message was delivered to any handler
+        return matchingHandlers.length > 0;
+    }
+    // ============================================
+    // Statistics and Monitoring
+    // ============================================
+    /**
+   * Gets current message broker statistics.
+   *
+   * @returns Statistics object
+   */ getStats() {
+        return {
+            ...this.stats,
+            messagesByTopic: {
+                ...this.stats.messagesByTopic
+            },
+            messagesByPriority: {
+                ...this.stats.messagesByPriority
+            }
+        };
+    }
+    /**
+   * Resets all statistics counters.
+   */ resetStats() {
+        this.stats = {
+            totalPublished: 0,
+            totalDelivered: 0,
+            totalFailed: 0,
+            totalSubscriptions: this.stats.totalSubscriptions,
+            messagesByTopic: {},
+            messagesByPriority: {},
+            avgDeliveryTime: 0
+        };
+    }
+    /**
+   * Gets all active subscriptions.
+   *
+   * @returns Array of subscription information
+   */ getSubscriptions() {
+        const result = [];
+        for (const subs of Array.from(this.subscriptions.values())){
+            for (const sub of subs){
+                result.push({
+                    id: sub.id,
+                    topic: sub.topic,
+                    priority: sub.priority,
+                    createdAt: sub.createdAt
+                });
+            }
+        }
+        return result;
+    }
+    /**
+   * Gets the current queue size.
+   *
+   * @returns Number of messages in queue
+   */ getQueueSize() {
+        return this.messageQueue.length;
+    }
+    /**
+   * Gets the number of pending requests.
+   *
+   * @returns Number of pending request/reply operations
+   */ getPendingRequestCount() {
+        return this.pendingRequests.size;
+    }
+    // ============================================
+    // Security Validation
+    // ============================================
+    /**
+   * Validates topic name to prevent injection attacks (SEC-007).
+   *
+   * @param topic - Topic name to validate
+   * @throws {MessageBrokerError} If topic name is invalid
+   */ validateTopicName(topic) {
+        // SEC-007: Prevent path traversal FIRST (before pattern check)
+        if (topic.includes('..') || topic.includes('//')) {
+            throw new MessageBrokerError('Path traversal detected in topic name');
+        }
+        // SEC-007: Prevent excessively long topics
+        if (topic.length > 256) {
+            throw new MessageBrokerError('Topic name exceeds 256 characters');
+        }
+        // SEC-007: Validate topic pattern (alphanumeric, dots, dashes, underscores, wildcards)
+        const validTopicPattern = /^[a-zA-Z0-9._-]+(\.[a-zA-Z0-9._*-]+)*$/;
+        if (!validTopicPattern.test(topic)) {
+            throw new MessageBrokerError(`Invalid topic name: ${topic}`);
+        }
+    }
+    // ============================================
+    // SEC-DOS-001 & SEC-DOS-002: DoS Protection Methods
+    // ============================================
+    /**
+   * SEC-DOS-002: Checks rate limit for a sender using token bucket algorithm.
+   *
+   * @param senderId - Sender identifier
+   * @returns True if request is allowed, false if rate limit exceeded
+   */ async checkRateLimit(senderId) {
+        if (!this.config.rateLimit) {
+            return true; // Rate limiting disabled
+        }
+        let limiter = this.rateLimiters.get(senderId);
+        if (!limiter) {
+            // Create new rate limiter for this sender
+            limiter = new RateLimiter({
+                tokensPerInterval: this.config.rateLimit.maxMessagesPerSecond,
+                interval: 'second',
+                fireImmediately: true
+            });
+            this.rateLimiters.set(senderId, limiter);
+        }
+        try {
+            const remainingTokens = await limiter.removeTokens(1);
+            return remainingTokens >= 0;
+        } catch (error) {
+            // Rate limit exceeded
+            return false;
+        }
+    }
+    /**
+   * SEC-DOS-002: Periodically cleanup idle rate limiters to prevent memory leaks.
+   */ startRateLimiterCleanup() {
+        this.rateLimiterCleanupInterval = setInterval(()=>{
+            // Remove rate limiters that haven't been used recently
+            // In production, you would track last access time
+            // For now, we clear limiters periodically to prevent unbounded growth
+            if (this.rateLimiters.size > 1000) {
+                // Keep only the most recent 500 limiters (simple cleanup strategy)
+                const entries = Array.from(this.rateLimiters.entries());
+                const toKeep = entries.slice(-500);
+                this.rateLimiters.clear();
+                toKeep.forEach(([key, value])=>this.rateLimiters.set(key, value));
+            }
+        }, 60000); // Cleanup every 60 seconds
+    }
+    /**
+   * SEC-DOS-001: Evicts low-priority messages when queue is full.
+   * Only evicts enough messages to make room for 1 new message.
+   *
+   * @param incomingPriority - Priority of the incoming message
+   * @returns Array of evicted messages
+   */ evictLowPriorityMessages(incomingPriority) {
+        const evicted = [];
+        // SEC-DOS-001-RACE: Only evict 1 message to make room for the incoming message
+        // Don't evict ALL lower-priority messages
+        const items = this.messageQueue.items;
+        if (!items || items.length === 0) {
+            return evicted;
+        }
+        // Find lowest priority message
+        let lowestIndex = 0;
+        let lowestPriority = items[0].priority;
+        for(let i = 1; i < items.length; i++){
+            if (items[i].priority < lowestPriority) {
+                lowestPriority = items[i].priority;
+                lowestIndex = i;
+            }
+        }
+        // Only evict if priority is lower than incoming
+        if (lowestPriority < incomingPriority) {
+            const candidate = items[lowestIndex];
+            items.splice(lowestIndex, 1);
+            // Move to dead letter queue if enabled
+            if (this.config.enableDeadLetterQueue) {
+                this.deadLetterQueue.enqueue(candidate);
+            }
+            // Decrement sender queue size
+            const senderId = candidate.senderId || 'anonymous';
+            const senderSize = this.senderQueueSizes.get(senderId) || 0;
+            if (senderSize > 0) {
+                this.senderQueueSizes.set(senderId, senderSize - 1);
+            }
+            evicted.push(candidate);
+        }
+        return evicted;
+    }
+    /**
+   * Gets the current size of the dead letter queue.
+   *
+   * @returns Number of messages in dead letter queue
+   */ getDeadLetterQueueSize() {
+        return this.deadLetterQueue.length;
+    }
+    /**
+   * SEC-DOS-002: Returns the number of active rate limiters.
+   */ getRateLimiterCount() {
+        return this.rateLimiters.size;
+    }
+    /**
+   * Retrieves messages from the dead letter queue.
+   *
+   * @param count - Number of messages to retrieve (default: all)
+   * @returns Array of dead letter messages
+   */ getDeadLetterMessages(count) {
+        const items = this.deadLetterQueue.items;
+        if (!items) return [];
+        if (count === undefined) {
+            return [
+                ...items
+            ];
+        }
+        return items.slice(0, count);
+    }
+    /**
+   * Clears the dead letter queue.
+   */ clearDeadLetterQueue() {
+        this.deadLetterQueue.clear();
+    }
+    // ============================================
+    // SEC-MEM-001: Subscription Cleanup
+    // ============================================
+    /**
+   * Starts periodic subscription cleanup to expire old subscriptions (SEC-MEM-001).
+   * Runs periodically to remove expired subscriptions based on TTL.
+   */ startSubscriptionCleanup() {
+        const cleanupInterval = this.config.cleanupIntervalMs ?? 60000;
+        this.subscriptionCleanupInterval = setInterval(()=>{
+            this.cleanupExpiredSubscriptions();
+        }, cleanupInterval);
+    }
+    /**
+   * Synchronously removes expired subscriptions (SEC-MEM-001).
+   * Called by background timer and immediately before publishing.
+   *
+   * @returns Number of subscriptions removed
+   */ cleanupExpiredSubscriptions() {
+        const now = Date.now();
+        let expiredCount = 0;
+        for (const topic of Array.from(this.subscriptions.keys())){
+            const subs = this.subscriptions.get(topic);
+            const validSubs = subs.filter((sub)=>{
+                if (sub.expiresAt && now >= sub.expiresAt) {
+                    // Expired subscription
+                    expiredCount++;
+                    // Clean up agent tracking
+                    if (sub.subscriberId) {
+                        const agentSubs = this.agentSubscriptions.get(sub.subscriberId);
+                        if (agentSubs) {
+                            agentSubs.delete(sub.id);
+                            if (agentSubs.size === 0) {
+                                this.agentSubscriptions.delete(sub.subscriberId);
+                            }
+                        }
+                    }
+                    this.stats.totalSubscriptions--;
+                    return false; // Remove expired subscription
+                }
+                return true; // Keep valid subscription
+            });
+            if (validSubs.length === 0) {
+                this.subscriptions.delete(topic);
+            } else if (validSubs.length !== subs.length) {
+                this.subscriptions.set(topic, validSubs);
+            }
+        }
+        if (expiredCount > 0) {
+            this.emitter.emit('subscriptions:expired', {
+                count: expiredCount
+            });
+        }
+        return expiredCount;
+    }
+    // ============================================
+    // Lifecycle Management
+    // ============================================
+    /**
+   * Clears all subscriptions and pending messages.
+   */ clear() {
+        this.subscriptions.clear();
+        this.messageQueue.clear();
+        // Cancel all pending requests
+        for (const correlationId of Array.from(this.pendingRequests.keys())){
+            const pending = this.pendingRequests.get(correlationId);
+            clearTimeout(pending.timeoutId);
+            pending.reject(new MessageBrokerError('Broker cleared'));
+        }
+        this.pendingRequests.clear();
+        // SEC-MEM-001: Clear subscription tracking
+        this.agentSubscriptions.clear();
+        // SEC-DOS-002: Clear rate limiters
+        this.rateLimiters.clear();
+        if (this.rateLimiterCleanupInterval) {
+            clearInterval(this.rateLimiterCleanupInterval);
+            this.rateLimiterCleanupInterval = undefined;
+        }
+        // SEC-MEM-001: Clear subscription cleanup interval
+        if (this.subscriptionCleanupInterval) {
+            clearInterval(this.subscriptionCleanupInterval);
+            this.subscriptionCleanupInterval = undefined;
+        }
+        this.stats.totalSubscriptions = 0;
+        this.emitter.removeAllListeners();
+    }
+    /**
+   * Shuts down the message broker gracefully.
+   * Waits for pending messages to be processed.
+   *
+   * @param timeout - Maximum wait time in milliseconds (default: 5000)
+   * @returns Promise resolving when shutdown complete
+   */ async shutdown(timeout = 5000) {
+        const startTime = Date.now();
+        // Wait for queue to drain
+        while(this.messageQueue.length > 0 && Date.now() - startTime < timeout){
+            await new Promise((resolve)=>setTimeout(resolve, 100));
+        }
+        this.clear();
+    }
+    /**
+   * Registers an error handler for message processing errors.
+   *
+   * @param handler - Error handler function
+   */ onError(handler) {
+        this.emitter.on('error', handler);
+    }
+}
+
+//# sourceMappingURL=message-broker.js.map