runmq 1.3.0 → 1.4.0

package/README.md

@@ -23,8 +23,9 @@ Whether you’re running <b>background jobs</b>, designing an <b>event-driven ar
 - **Isolated Queues per Processor**: Each processor gets its own dedicated queue and DLQ, ensuring full isolation and predictable behavior across services.
 - **Schema Validation**: Optional JSON Schema validation powered by AJV for safer message handling and data integrity.
 - **Concurrent Consumers**: Scale either horizontally (multiple instances) or vertically (multiple consumers per queue, leveraging RabbitMQ prefetch) to maximize throughput and efficiency.
-- **RabbitMQ Durability & Acknowledgements**: Leverages RabbitMQ’s persistent storage and acknowledgment model to guarantee at-least-once delivery, even across restarts and failures.
+- **RabbitMQ Durability & Acknowledgements**: Leverages RabbitMQ's persistent storage and acknowledgment model to guarantee at-least-once delivery, even across restarts and failures.
 - **Custom Logging**: Plug in your own logger or use the default console logger for full control over message visibility.
+- **Management Dashboard**: A web-based dashboard for real-time monitoring and management of queues, DLQs, and message processing. [Check it out!](https://github.com/runmq/pulse)
 
 ## Installation
 
@@ -212,7 +213,24 @@ RunMQ can leverage RabbitMQ policies to manage the delay between attempts, it's
 #### Benefits
 - Flexible and easy management of retry delays
 - Reduces operational overhead
-- Fully compatible with RunMQ’s retry and DLQ mechanisms
+- Fully compatible with RunMQ's retry and DLQ mechanisms
+
+### Queue Metadata Storage
+
+RunMQ automatically stores queue metadata (such as max retries and creation timestamp) using RabbitMQ's parameters API. This enables external tools and dashboards to discover RunMQ-managed queues and understand their configuration without direct access to the application code.
+
+When a processor is configured, RunMQ creates a metadata parameter that stores:
+- **Version**: Schema version for future-proof migrations.
+- **Max Retries**: The configured retry limit for the queue.
+- **Created At**: ISO 8601 timestamp when the queue was first configured.
+- **Updated At**: ISO 8601 timestamp when the configuration was last changed (if applicable).
+
+#### Benefits
+- **Dashboard Integration**: External monitoring tools and dashboards can query RabbitMQ's management API to retrieve queue metadata and display topology information (e.g., "10 retries with 5s delay, then to DLQ").
+- **Self-Documenting Queues**: Queue configurations are discoverable directly from RabbitMQ, without needing access to application source code.
+- **Automatic Updates**: When processor configuration changes, metadata is automatically updated while preserving the original creation timestamp.
+
+> **Note**: This feature requires RabbitMQ Management Plugin to be enabled for external tools to query the metadata parameters and for the parameters to be set.
 
 ### Custom Logger
 

package/dist/index.cjs

@@ -244,10 +244,39 @@ var RabbitMQClientChannel = class {
   }
 };
 
+// src/core/logging/RunMQConsoleLogger.ts
+var RunMQConsoleLogger = class {
+  constructor() {
+    this.prefix = "[RunMQ] - ";
+  }
+  log(message) {
+    console.log(this.formatMessage(message));
+  }
+  error(message, ...optionalParams) {
+    console.error(this.formatMessage(message), ...optionalParams);
+  }
+  warn(message, ...optionalParams) {
+    console.warn(this.formatMessage(message), ...optionalParams);
+  }
+  info(message, ...optionalParams) {
+    console.info(this.formatMessage(message), ...optionalParams);
+  }
+  debug(message, ...optionalParams) {
+    console.debug(this.formatMessage(message), ...optionalParams);
+  }
+  verbose(message, ...optionalParams) {
+    console.debug(this.formatMessage(message), ...optionalParams);
+  }
+  formatMessage(message) {
+    return `${this.prefix} ${message}`;
+  }
+};
+
 // src/core/clients/RabbitMQClientAdapter.ts
 var RabbitMQClientAdapter = class {
-  constructor(config) {
+  constructor(config, logger = new RunMQConsoleLogger()) {
     this.config = config;
+    this.logger = logger;
     this.isConnected = false;
     this.acquiredChannels = [];
   }
@@ -271,17 +300,17 @@ var RabbitMQClientAdapter = class {
         connectionTimeout: 5e3
       });
       this.connection.on("error", (err) => {
-        console.error("RabbitMQ connection error:", err);
+        this.logger.error("RabbitMQ connection error:", { error: err });
         this.isConnected = false;
       });
       this.connection.on("connection", () => {
         this.isConnected = true;
       });
       this.connection.on("connection.blocked", (reason) => {
-        console.warn("RabbitMQ connection blocked:", reason);
+        this.logger.warn("RabbitMQ connection blocked:", { reason });
       });
       this.connection.on("connection.unblocked", () => {
-        console.info("RabbitMQ connection unblocked");
+        this.logger.info("RabbitMQ connection unblocked");
       });
       await this.connection.onConnect(5e3, true);
       this.isConnected = true;
@@ -368,7 +397,8 @@ var Constants = {
   DEAD_LETTER_ROUTER_EXCHANGE_NAME: RUNMQ_PREFIX + "dead_letter_router",
   RETRY_DELAY_QUEUE_PREFIX: RUNMQ_PREFIX + "retry_delay_",
   DLQ_QUEUE_PREFIX: RUNMQ_PREFIX + "dlq_",
-  MESSAGE_TTL_OPERATOR_POLICY_PREFIX: RUNMQ_PREFIX + "message_ttl_operator_policy"
+  MESSAGE_TTL_OPERATOR_POLICY_PREFIX: RUNMQ_PREFIX + "message_ttl_operator_policy",
+  METADATA_STORE_PREFIX: RUNMQ_PREFIX + "metadata_"
 };
 var DEFAULTS = {
   RECONNECT_DELAY: 5e3,
@@ -446,6 +476,27 @@ var RunMQFailedMessageRejecterProcessor = class {
   }
 };
 
+// src/core/message/RunMQMessage.ts
+var RunMQMessage = class {
+  static isValid(obj) {
+    if (typeof obj === "object" && obj !== null) {
+      return "message" in obj && "meta" in obj && typeof obj.message === "object" && obj.message !== null && Array.isArray(obj.message) === false && typeof obj.meta === "object" && obj.meta !== null && "id" in obj.meta && "correlationId" in obj.meta && "publishedAt" in obj.meta && typeof obj.meta.id === "string" && typeof obj.meta.correlationId === "string" && typeof obj.meta.publishedAt === "number";
+    }
+    return false;
+  }
+  constructor(message, meta) {
+    this.message = message;
+    this.meta = meta;
+  }
+};
+var RunMQMessageMeta = class {
+  constructor(id, publishedAt, correlationId) {
+    this.id = id;
+    this.correlationId = correlationId;
+    this.publishedAt = publishedAt;
+  }
+};
+
 // src/core/consumer/ConsumerCreatorUtils.ts
 var ConsumerCreatorUtils = class {
   static getDLQTopicName(topic) {
@@ -497,7 +548,28 @@ var RunMQRetriesCheckerProcessor = class {
     );
   }
   moveToFinalDeadLetter(message) {
-    this.DLQPublisher.publish(ConsumerCreatorUtils.getDLQTopicName(this.config.name), message);
+    const originalPayload = this.extractOriginalPayload(message);
+    const dlqMessage = new RabbitMQMessage(
+      originalPayload,
+      message.id,
+      message.correlationId,
+      message.channel,
+      message.amqpMessage,
+      message.headers
+    );
+    this.DLQPublisher.publish(ConsumerCreatorUtils.getDLQTopicName(this.config.name), dlqMessage);
+  }
+  extractOriginalPayload(message) {
+    if (typeof message.message === "string") {
+      try {
+        const parsed = JSON.parse(message.message);
+        if (RunMQMessage.isValid(parsed)) {
+          return parsed.message;
+        }
+      } catch (e) {
+      }
+    }
+    return message.message;
   }
   acknowledgeMessage(message) {
     try {
@@ -575,27 +647,6 @@ var RunMQExceptionLoggerProcessor = class {
   }
 };
 
-// src/core/message/RunMQMessage.ts
-var RunMQMessage = class {
-  static isValid(obj) {
-    if (typeof obj === "object" && obj !== null) {
-      return "message" in obj && "meta" in obj && typeof obj.message === "object" && obj.message !== null && Array.isArray(obj.message) === false && typeof obj.meta === "object" && obj.meta !== null && "id" in obj.meta && "correlationId" in obj.meta && "publishedAt" in obj.meta && typeof obj.meta.id === "string" && typeof obj.meta.correlationId === "string" && typeof obj.meta.publishedAt === "number";
-    }
-    return false;
-  }
-  constructor(message, meta) {
-    this.message = message;
-    this.meta = meta;
-  }
-};
-var RunMQMessageMeta = class {
-  constructor(id, publishedAt, correlationId) {
-    this.id = id;
-    this.correlationId = correlationId;
-    this.publishedAt = publishedAt;
-  }
-};
-
 // src/core/serializers/deserializer/validation/AjvSchemaValidator.ts
 var import_ajv = __toESM(require("ajv"), 1);
 var AjvSchemaValidator = class {
@@ -870,6 +921,91 @@ var RabbitMQManagementClient = class {
       return false;
     }
   }
+  /**
+   * Creates or updates a RabbitMQ parameter.
+   * Parameters are custom key-value stores that can hold any JSON data.
+   *
+   * @param name - The parameter name
+   * @param value - The parameter value (any JSON-serializable object)
+   */
+  async setParameter(name, value) {
+    try {
+      const url = `${this.config.url}/api/global-parameters/${encodeURIComponent(name)}`;
+      const response = await fetch(url, {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": this.getAuthHeader()
+        },
+        body: JSON.stringify({ value })
+      });
+      if (!response.ok) {
+        const error = await response.text();
+        this.logger.error(`Failed to set parameter ${name}: ${response.status} - ${error}`);
+        return false;
+      }
+      this.logger.info(`Successfully set parameter: ${name}`);
+      return true;
+    } catch (error) {
+      this.logger.error(`Error setting parameter: ${error}`);
+      return false;
+    }
+  }
+  /**
+   * Gets a RabbitMQ parameter.
+   *
+   * @param name - The parameter name
+   */
+  async getParameter(name) {
+    try {
+      const url = `${this.config.url}/api/global-parameters/${encodeURIComponent(name)}`;
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Authorization": this.getAuthHeader()
+        }
+      });
+      if (!response.ok) {
+        if (response.status === 404) {
+          return null;
+        }
+        const error = await response.text();
+        this.logger.error(`Failed to get parameter ${name}: ${response.status} - ${error}`);
+        return null;
+      }
+      const data = await response.json();
+      return data.value;
+    } catch (error) {
+      this.logger.error(`Error getting parameter: ${error}`);
+      return null;
+    }
+  }
+  /**
+   * Deletes a RabbitMQ parameter.
+   *
+   * @param name - The parameter name
+   */
+  async deleteParameter(name) {
+    try {
+      const url = `${this.config.url}/api/global-parameters/${encodeURIComponent(name)}`;
+      const response = await fetch(url, {
+        method: "DELETE",
+        headers: {
+          "Authorization": this.getAuthHeader()
+        }
+      });
+      if (!response.ok && response.status !== 404) {
+        const error = await response.text();
+        this.logger.error(`Failed to delete parameter ${name}: ${response.status} - ${error}`);
+        return false;
+      }
+      this.logger.info(`Successfully deleted parameter: ${name}`);
+      return true;
+    } catch (error) {
+      this.logger.error(`Error deleting parameter: ${error}`);
+      return false;
+    }
+  }
 };
 
 // src/core/management/Policies/RabbitMQMessageTTLPolicy.ts
@@ -899,6 +1035,9 @@ var RunMQTTLPolicyManager = class {
     }
   }
   async initialize() {
+    if (this.isManagementPluginEnabled) {
+      return;
+    }
     if (!this.managementClient) {
       this.logger.warn("Management client not configured");
       return;
@@ -931,21 +1070,166 @@ var RunMQTTLPolicyManager = class {
   }
 };
 
+// src/core/management/Policies/RunMQQueueMetadata.ts
+var METADATA_SCHEMA_VERSION = 0;
+
+// src/core/management/Policies/RabbitMQMetadata.ts
+var RabbitMQMetadata = class {
+  /**
+   * Creates metadata for a queue.
+   * @param maxRetries - Maximum retry attempts configured for the queue
+   * @param existingMetadata - Optional existing metadata to preserve createdAt
+   * @returns RunMQQueueMetadata object
+   */
+  static createMetadataFor(maxRetries, existingMetadata) {
+    var _a2;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return __spreadValues({
+      version: METADATA_SCHEMA_VERSION,
+      maxRetries,
+      createdAt: (_a2 = existingMetadata == null ? void 0 : existingMetadata.createdAt) != null ? _a2 : now
+    }, existingMetadata ? { updatedAt: now } : {});
+  }
+  /**
+   * Gets the parameter name for a given queue.
+   */
+  static getParameterName(queueName) {
+    return Constants.METADATA_STORE_PREFIX + queueName;
+  }
+};
+
+// src/core/management/Policies/RunMQMetadataManager.ts
+var RunMQMetadataManager = class {
+  constructor(logger, managementConfig) {
+    this.logger = logger;
+    this.managementConfig = managementConfig;
+    this.managementClient = null;
+    this.isManagementPluginEnabled = false;
+    if (this.managementConfig) {
+      this.managementClient = new RabbitMQManagementClient(this.managementConfig, this.logger);
+    }
+  }
+  /**
+   * Initialize the manager by checking if management plugin is available.
+   */
+  async initialize() {
+    if (this.isManagementPluginEnabled) {
+      return;
+    }
+    if (!this.managementClient) {
+      this.logger.warn("Management client not configured - metadata storage disabled");
+      return;
+    }
+    this.isManagementPluginEnabled = await this.managementClient.checkManagementPluginEnabled();
+    if (!this.isManagementPluginEnabled) {
+      this.logger.warn("RabbitMQ management plugin is not enabled - metadata storage disabled");
+    } else {
+      this.logger.info("RunMQ metadata storage initialized");
+    }
+  }
+  /**
+   * Store or update metadata for a queue.
+   * If metadata already exists, preserves createdAt and sets updatedAt.
+   *
+   * @param queueName - The name of the queue
+   * @param maxRetries - Maximum retry attempts
+   * @returns true if metadata was stored successfully, false otherwise
+   */
+  async apply(queueName, maxRetries) {
+    if (!this.isManagementPluginEnabled || !this.managementClient) {
+      this.logger.warn(`Cannot store metadata for queue '${queueName}' - management plugin not available`);
+      return false;
+    }
+    try {
+      const existingMetadata = await this.getMetadata(queueName);
+      const metadata = RabbitMQMetadata.createMetadataFor(
+        maxRetries,
+        existingMetadata != null ? existingMetadata : void 0
+      );
+      const paramName = RabbitMQMetadata.getParameterName(queueName);
+      const success = await this.managementClient.setParameter(
+        paramName,
+        metadata
+      );
+      if (success) {
+        const action = existingMetadata ? "Updated" : "Created";
+        this.logger.info(`${action} metadata for queue: ${queueName}`);
+        return true;
+      }
+      this.logger.error(`Failed to store metadata for queue: ${queueName}`);
+      return false;
+    } catch (error) {
+      this.logger.error(`Error storing metadata for queue ${queueName}: ${error}`);
+      return false;
+    }
+  }
+  /**
+   * Get metadata for a queue.
+   *
+   * @param queueName - The name of the queue
+   * @returns The queue metadata or null if not found
+   */
+  async getMetadata(queueName) {
+    if (!this.isManagementPluginEnabled || !this.managementClient) {
+      return null;
+    }
+    try {
+      const paramName = RabbitMQMetadata.getParameterName(queueName);
+      return await this.managementClient.getParameter(
+        paramName
+      );
+    } catch (error) {
+      this.logger.warn(`Failed to get metadata for queue ${queueName}: ${error}`);
+      return null;
+    }
+  }
+  /**
+   * Delete metadata for a queue.
+   *
+   * @param queueName - The name of the queue
+   */
+  async cleanup(queueName) {
+    if (!this.isManagementPluginEnabled || !this.managementClient) {
+      return;
+    }
+    const paramName = RabbitMQMetadata.getParameterName(queueName);
+    await this.managementClient.deleteParameter(paramName);
+    this.logger.info(`Deleted metadata for queue: ${queueName}`);
+  }
+  /**
+   * Check if management plugin is enabled and metadata storage is available.
+   */
+  isEnabled() {
+    return this.isManagementPluginEnabled;
+  }
+};
+
 // src/core/consumer/RunMQConsumerCreator.ts
 var RunMQConsumerCreator = class {
   constructor(client, logger, managementConfig) {
     this.client = client;
     this.logger = logger;
     this.ttlPolicyManager = new RunMQTTLPolicyManager(logger, managementConfig);
+    this.metadataManager = new RunMQMetadataManager(logger, managementConfig);
   }
   async createConsumer(consumerConfiguration) {
     await this.ttlPolicyManager.initialize();
+    await this.metadataManager.initialize();
     await this.assertQueues(consumerConfiguration);
     await this.bindQueues(consumerConfiguration);
+    await this.storeMetadata(consumerConfiguration);
     for (let i = 0; i < consumerConfiguration.processorConfig.consumersCount; i++) {
       await this.runProcessor(consumerConfiguration);
     }
   }
+  async storeMetadata(consumerConfiguration) {
+    var _a2;
+    const maxRetries = (_a2 = consumerConfiguration.processorConfig.attempts) != null ? _a2 : DEFAULTS.PROCESSING_ATTEMPTS;
+    await this.metadataManager.apply(
+      consumerConfiguration.processorConfig.name,
+      maxRetries
+    );
+  }
   async runProcessor(consumerConfiguration) {
     const consumerChannel = await this.getProcessorChannel();
     const DLQPublisher = new RunMQPublisherCreator(this.logger).createPublisher(Constants.DEAD_LETTER_ROUTER_EXCHANGE_NAME);
@@ -1062,34 +1346,6 @@ var ConsumerConfiguration = class {
   }
 };
 
-// src/core/logging/RunMQConsoleLogger.ts
-var RunMQConsoleLogger = class {
-  constructor() {
-    this.prefix = "[RunMQ] - ";
-  }
-  log(message) {
-    console.log(this.formatMessage(message));
-  }
-  error(message, ...optionalParams) {
-    console.error(this.formatMessage(message), ...optionalParams);
-  }
-  warn(message, ...optionalParams) {
-    console.warn(this.formatMessage(message), ...optionalParams);
-  }
-  info(message, ...optionalParams) {
-    console.info(this.formatMessage(message), ...optionalParams);
-  }
-  debug(message, ...optionalParams) {
-    console.debug(this.formatMessage(message), ...optionalParams);
-  }
-  verbose(message, ...optionalParams) {
-    console.debug(this.formatMessage(message), ...optionalParams);
-  }
-  formatMessage(message) {
-    return `${this.prefix} ${message}`;
-  }
-};
-
 // src/core/message/RabbitMQMessageProperties.ts
 var RabbitMQMessageProperties = class {
   constructor(id, correlationId) {
@@ -1108,7 +1364,8 @@ var RunMQ = class _RunMQ {
       reconnectDelay: (_a2 = config.reconnectDelay) != null ? _a2 : DEFAULTS.RECONNECT_DELAY,
       maxReconnectAttempts: (_b = config.maxReconnectAttempts) != null ? _b : DEFAULTS.MAX_RECONNECT_ATTEMPTS
     });
-    this.client = new RabbitMQClientAdapter(this.config);
+    this.client = new RabbitMQClientAdapter(this.config, this.logger);
+    this.consumer = new RunMQConsumerCreator(this.client, this.logger, this.config.management);
   }
   /**
    * Starts the RunMQ instance by establishing a connection to RabbitMQ and initializing necessary components.
@@ -1129,8 +1386,7 @@ var RunMQ = class _RunMQ {
    * @param processor The function that will process the incoming messages
    */
   async process(topic, config, processor) {
-    const consumer = new RunMQConsumerCreator(this.client, this.logger, this.config.management);
-    await consumer.createConsumer(new ConsumerConfiguration(topic, config, processor));
+    await this.consumer.createConsumer(new ConsumerConfiguration(topic, config, processor));
   }
   /**
    * Publishes a message to the specified topic with an optional correlation ID
@@ -1189,7 +1445,6 @@ var RunMQ = class _RunMQ {
         return;
       } catch (error) {
         this.retryAttempts++;
-        console.log(this.logger);
         this.logger.error(`Connection attempt ${this.retryAttempts}/${maxAttempts} failed:`, error);
         if (this.retryAttempts >= maxAttempts) {
           throw new RunMQException(