haraka-plugin-amqp_reporting 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0 - 2026-05-09
+
+- Initial release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Haraka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# haraka-plugin-amqp_reporting
+
+[![npm version](https://img.shields.io/npm/v/haraka-plugin-amqp_reporting.svg)](https://www.npmjs.com/package/haraka-plugin-amqp_reporting)
+[![CI](https://github.com/brassnode/haraka-plugin-amqp_reporting/actions/workflows/ci.yml/badge.svg)](https://github.com/brassnode/haraka-plugin-amqp_reporting/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Haraka plugin that publishes outbound delivery outcome events to a RabbitMQ topic exchange.
+
+Reports `delivered`, `bounced`, and `deferred` outcomes after each delivery attempt so downstream services can update job status without polling Haraka directly.
+
+## Features
+
+- Three delivery outcome events (`delivered`, `bounced`, `deferred`) published to a RabbitMQ topic exchange
+- Per-message routing keys (`outcome.delivered`, `outcome.bounced`, `outcome.deferred`) for selective consumer binding
+- Confirm-channel publishing — the broker acknowledges each message before the plugin considers it sent
+- 5-second per-publish timeout prevents a stalled broker from blocking Haraka's delivery pipeline
+- One AMQP connection per worker process; connections are isolated and re-established automatically on worker restart
+- Stashes `X-Job-Id` and `X-Ip-Id` headers at queue time and strips them from the outbound message
+- Compatible with any AMQP 0-9-1 broker via `amqp://` or `amqps://` URLs (RabbitMQ, AWS MQ, CloudAMQP, etc.)
+
+## Requirements
+
+- Node.js >= 22
+- Haraka SMTP server
+- RabbitMQ broker reachable from each Haraka worker
+
+## Install
+
+Navigate to your Haraka installation directory:
+
+```sh
+cd /path/to/local/haraka
+```
+
+Install the plugin:
+
+```sh
+npm install haraka-plugin-amqp_reporting
+```
+
+Register the plugin:
+
+```sh
+echo "amqp_reporting" >> config/plugins
+```
+
+Restart Haraka:
+
+```sh
+service haraka restart
+```
+
+## Configuration
+
+Copy the default config into your Haraka config directory:
+
+```sh
+cp node_modules/haraka-plugin-amqp_reporting/config/amqp_reporting.ini config/amqp_reporting.ini
+```
+
+### amqp_reporting.ini
+
+```ini
+[main]
+; Set to false to disable the plugin entirely
+enabled = true
+
+; AMQP broker URL — supports amqp:// and amqps://
+amqp_url = amqp://guest:guest@localhost:5672
+
+; Topic exchange to publish delivery outcome events to
+exchange = mailing.delivery.outcomes
+```
+
+The plugin declares the exchange as `topic, durable` on startup. The exchange must not already exist with different options.
+
+## How it works
+
+The plugin uses two inbound hooks and three outbound delivery hooks:
+
+| Hook         | Action                                                             |
+| ------------ | ------------------------------------------------------------------ |
+| `init_child` | Opens one AMQP connection + confirm channel per worker process     |
+| `queue`      | Stashes `X-Job-Id`/`X-Ip-Id` into `hmail.todo.notes`; strips both  |
+| `delivered`  | Publishes `outcome.delivered` after a 2xx acceptance               |
+| `bounce`     | Publishes `outcome.bounced` after a permanent 5xx or exhausted 4xx |
+| `deferred`   | Publishes `outcome.deferred` on each temporary 4xx deferral        |
+
+## Event schema
+
+Every message published to RabbitMQ has the following JSON body:
+
+| Field              | Type   | Description                                           |
+| ------------------ | ------ | ----------------------------------------------------- |
+| `jobId`            | string | Value of `X-Job-Id` header stashed at queue time      |
+| `ipId`             | string | Value of `X-Ip-Id` header stashed at queue time       |
+| `status`           | string | `"delivered"`, `"bounced"`, or `"deferred"`           |
+| `smtpCode`         | number | Numeric SMTP response code (e.g. `250`, `550`, `421`) |
+| `smtpMessage`      | string | Full SMTP response text                               |
+| `recipientAddress` | string | Recipient email address from `RCPT TO`                |
+| `domain`           | string | Destination domain                                    |
+| `attemptedAt`      | string | ISO 8601 timestamp of the delivery attempt            |
+
+## Routing keys
+
+| Routing key         | Fires when                                             |
+| ------------------- | ------------------------------------------------------ |
+| `outcome.delivered` | Destination server accepted the message (2xx)          |
+| `outcome.bounced`   | Permanent rejection (5xx) or exhausted 4xx retry queue |
+| `outcome.deferred`  | Temporary deferral (4xx), Haraka will retry            |
+
+Bind all three routing keys to the same queue if a single consumer handles all outcomes:
+
+```sh
+rabbitmqadmin declare queue name=mailing.delivery.outcomes.q durable=true
+rabbitmqadmin declare binding source=mailing.delivery.outcomes \
+  destination=mailing.delivery.outcomes.q routing_key="outcome.*"
+```
+
+## Reliability notes
+
+- One AMQP connection per worker process; no connection is shared across workers.
+- Publishes use confirm channels — the broker acknowledges each message before the plugin considers it sent.
+- A 5-second per-publish timeout prevents a stalled broker from blocking Haraka's delivery pipeline. If a publish times out or is nack'd, the error is logged and delivery continues unaffected.
+- If the AMQP connection drops, the plugin logs the error and stops publishing. Worker restart re-establishes the connection via `hook_init_child`.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## Contributing
+
+Pull requests are welcome. Please open an issue first to discuss significant changes.
+
+Run tests:
+
+```sh
+npm test
+```
+
+Check code style:
+
+```sh
+npm run lint
+```
+
+Auto-fix style:
+
+```sh
+npm run format
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/config/amqp_reporting.ini

@@ -0,0 +1,10 @@
+
+[main]
+; Set to false to disable the plugin entirely
+enabled = true
+
+; AMQP broker URL — supports amqp:// and amqps://
+amqp_url = amqp://guest:guest@localhost:5672
+
+; Topic exchange to publish delivery outcome events to (must be pre-declared or declared here)
+exchange = mailing.delivery.outcomes

package/index.js

@@ -0,0 +1,168 @@
+'use strict'
+
+const amqplib = require('amqplib/callback_api')
+
+const plugin = exports
+
+plugin.register = function () {
+  this.load_amqp_reporting_ini()
+
+  if (!this.cfg.main.enabled) {
+    this.loginfo('disabled via config')
+    return
+  }
+
+  this.register_hook('init_child', 'hook_init_child')
+  this.register_hook('queue',      'hook_queue')
+  this.register_hook('delivered',  'hook_delivered')
+  this.register_hook('bounce',     'hook_bounce')
+  this.register_hook('deferred',   'hook_deferred')
+}
+
+plugin.load_amqp_reporting_ini = function () {
+  this.cfg = this.config.get(
+    'amqp_reporting.ini',
+    { booleans: ['+enabled'] },
+    () => { this.load_amqp_reporting_ini() },
+  )
+}
+
+plugin.hook_init_child = function (next) {
+  const url = this.cfg.main.amqp_url
+  this._connect(url, (err, conn) => {
+    if (err) {
+      this.logerror(`AMQP connect failed: ${err.message}`)
+      return next()
+    }
+    conn.on('error', (e) => {
+      this.logerror(`AMQP connection error: ${e.message}`)
+      this.amqp = null
+    })
+    conn.createConfirmChannel((assertErr, ch) => this._setup_channel(next, conn, assertErr, ch))
+  })
+}
+
+plugin._connect = function (url, cb) {
+  amqplib.connect(url, cb)
+}
+
+plugin._setup_channel = function (next, conn, err, ch) {
+  if (err) {
+    this.logerror(`AMQP channel failed: ${err.message}`)
+    return next()
+  }
+  const exchange = this.cfg.main.exchange
+  ch.assertExchange(exchange, 'topic', { durable: true }, (assertErr) => {
+    if (assertErr) {
+      this.logerror(`AMQP assertExchange failed: ${assertErr.message}`)
+      return next()
+    }
+    this.amqp = { conn, ch, exchange }
+    this.loginfo(`AMQP ready - exchange: ${exchange}`)
+    next()
+  })
+}
+
+plugin.hook_queue = function (next, connection) {
+  const txn = connection.transaction
+  if (!txn) return next()
+
+  const jobId = txn.header.get('X-Job-Id') || ''
+  const ipId  = txn.header.get('X-Ip-Id')  || ''
+
+  txn.notes.amqp_job_id = jobId.trim()
+  txn.notes.amqp_ip_id  = ipId.trim()
+
+  txn.remove_header('X-Job-Id')
+  txn.remove_header('X-Ip-Id')
+
+  next()
+}
+
+plugin.hook_delivered = function (next, hmail, connection, params) {
+  const notes  = (hmail && hmail.todo && hmail.todo.notes) || {}
+  const rcpt   = params && params[0] ? params[0].address() : ''
+  const msg    = (params && params[1]) || ''
+  const domain = (params && params[2]) || ''
+
+  this._publish('outcome.delivered', {
+    jobId:            notes.amqp_job_id || '',
+    ipId:             notes.amqp_ip_id  || '',
+    status:           'delivered',
+    smtpCode:         this._parse_smtp_code(msg, 250),
+    smtpMessage:      msg,
+    recipientAddress: rcpt,
+    domain,
+    attemptedAt:      new Date().toISOString(),
+  })
+
+  next()
+}
+
+plugin.hook_bounce = function (next, hmail, error) {
+  const notes = (hmail && hmail.todo && hmail.todo.notes) || {}
+  const rcpts = (hmail && hmail.todo && hmail.todo.rcpt_to) || []
+  const code  = (error && error.code) || 0
+  const msg   = (error && error.message) || ''
+
+  this._publish('outcome.bounced', {
+    jobId:            notes.amqp_job_id || '',
+    ipId:             notes.amqp_ip_id  || '',
+    status:           'bounced',
+    smtpCode:         code,
+    smtpMessage:      msg,
+    recipientAddress: rcpts.length ? rcpts[0].address() : '',
+    domain:           (hmail && hmail.todo && hmail.todo.domain) || '',
+    attemptedAt:      new Date().toISOString(),
+  })
+
+  next()
+}
+
+plugin.hook_deferred = function (next, hmail, params) {
+  const notes  = (hmail && hmail.todo && hmail.todo.notes) || {}
+  const domain = (params && params[0]) || ''
+  const msg    = (params && params[1]) || ''
+  const rcpt   = params && params[2] ? params[2].address() : ''
+
+  this._publish('outcome.deferred', {
+    jobId:            notes.amqp_job_id || '',
+    ipId:             notes.amqp_ip_id  || '',
+    status:           'deferred',
+    smtpCode:         this._parse_smtp_code(msg, 421),
+    smtpMessage:      msg,
+    recipientAddress: rcpt,
+    domain,
+    attemptedAt:      new Date().toISOString(),
+  })
+
+  next()
+}
+
+plugin._publish = function (routingKey, event) {
+  if (!this.amqp) return
+
+  const { ch, exchange } = this.amqp
+  const body    = Buffer.from(JSON.stringify(event))
+  const options = { persistent: true, mandatory: true }
+  const timeout = this.PUBLISH_TIMEOUT !== undefined ? this.PUBLISH_TIMEOUT : 5000
+
+  let settled = false
+
+  const timer = setTimeout(() => {
+    settled = true
+    this.logerror(`AMQP publish timeout - routingKey: ${routingKey}, jobId: ${event.jobId}`)
+  }, timeout)
+
+  ch.publish(exchange, routingKey, body, options, (err) => {
+    if (settled) return
+    settled = true
+    clearTimeout(timer)
+    if (err) this.logerror(`AMQP publish nack - routingKey: ${routingKey}: ${err.message}`)
+  })
+}
+
+plugin._parse_smtp_code = function (msg, fallback) {
+  const m = /^(\d{3})/.exec(msg || '')
+  return m ? parseInt(m[1], 10) : fallback
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "haraka-plugin-amqp_reporting",
+  "version": "1.1.1",
+  "description": "Haraka plugin that publishes outbound delivery outcome events to a RabbitMQ topic exchange",
+  "main": "index.js",
+  "files": [
+    "CHANGELOG.md",
+    "config"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "format": "npm run prettier:fix && npm run lint:fix",
+    "lint": "npx eslint *.js test",
+    "lint:fix": "npx eslint *.js test --fix",
+    "prettier": "npx prettier . --check",
+    "prettier:fix": "npx prettier . --write --log-level=warn",
+    "test": "node --test",
+    "test:coverage": "HARAKA_COVERAGE=1 npx c8 npm test",
+    "versions": "npx dependency-version-checker check",
+    "versions:fix": "npx dependency-version-checker update"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haraka/haraka-plugin-amqp_reporting.git"
+  },
+  "keywords": [
+    "haraka-plugin",
+    "amqp_reporting"
+  ],
+  "author": "Abdulmatin Sanni <abdulmatin@brassnode.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/haraka/haraka-plugin-amqp_reporting/issues"
+  },
+  "homepage": "https://github.com/haraka/haraka-plugin-amqp_reporting#readme",
+  "dependencies": {
+    "amqplib": "^0.10.4"
+  },
+  "devDependencies": {
+    "@haraka/eslint-config": "^2.0.2",
+    "haraka-test-fixtures": "^1.3.8"
+  },
+  "prettier": {
+    "printWidth": 100,
+    "singleQuote": true,
+    "semi": false
+  }
+}