Haraka 3.1.7 → 3.2.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Unreleased
 
+### [3.2.0] - 2026-05-NN
+
+- fix(status): merge worker status into summary #3574
+- dep: replace address-rfc282{1,2} with @haraka/email-address #3566
+- change(BREAKING for some plugins), see https://github.com/haraka/Haraka/issues/3564
+
 ### [3.1.7] - 2026-05-19
 
 - feat(smtp_forward,smtp_proxy): honor `tls.ini` `[main]` and plugin `[tls]`
@@ -1862,3 +1868,4 @@ config files.
 [3.1.5]: https://github.com/haraka/Haraka/releases/tag/v3.1.5
 [3.1.6]: https://github.com/haraka/Haraka/releases/tag/v3.1.6
 [3.1.7]: https://github.com/haraka/Haraka/releases/tag/v3.1.7
+[3.2.0]: https://github.com/haraka/Haraka/releases/tag/v3.2.0

package/address.js

@@ -0,0 +1,53 @@
+'use strict'
+
+// SUNSET 2027: Haraka core constructs envelope addresses with
+// @haraka/email-address, whose `.address` / `.host` are string
+// properties. Core itself — and a large body of bundled and
+// third-party plugins — still use the historical address-rfc2821 /
+// address-rfc2822 *method* contract (`addr.address()`, `addr.host()`).
+//
+// `asLegacy()` wraps each instance so both the new string-property API
+// and the legacy callable form work during the transition. The wrap is
+// idempotent, and `unwrapLegacy()` recovers the raw instance so the
+// outbound queue's JSON re-hydration copies primitive string fields
+// rather than the callable accessors.
+//
+// Once the ecosystem has migrated, delete this module, require
+// `Address` straight from '@haraka/email-address', and drop the wrapper
+// (see @haraka/email-address lib/legacy.js).
+
+const { Address: BaseAddress, asLegacy, unwrapLegacy } = require('@haraka/email-address')
+
+class Address extends BaseAddress {
+    constructor(...args) {
+        // never re-hydrate from a wrapped instance — copy raw strings
+        if (args.length) args[0] = unwrapLegacy(args[0])
+        // `new Address(user, host)` where `host` is another wrapped
+        // address's `.host` — the SUNSET-2027 callable accessor is
+        // `typeof 'function'`, which BaseAddress would mistake for an
+        // options object. Coerce it back to the primitive string.
+        if (args.length >= 2 && typeof args[1] === 'function') {
+            args[1] = String(args[1])
+        }
+        super(...args)
+        return asLegacy(this)
+    }
+
+    // Preserve the address-rfc2821 wire shape so existing on-disk queue
+    // files stay byte-compatible across the upgrade and re-hydrate
+    // unchanged. @haraka/email-address additionally carries
+    // phrase/comment/group/opts, which are irrelevant to envelope
+    // addresses and must not leak into the persisted todo. SUNSET 2027.
+    toJSON() {
+        const out = {
+            original: this.original,
+            original_host: this.original_host,
+            host: this.host,
+            user: this.user,
+        }
+        if (this.is_utf8) out.is_utf8 = true
+        return out
+    }
+}
+
+module.exports = { Address }

package/bin/haraka

@@ -406,7 +406,7 @@ if (parsed.version) {
   plugins.load_plugins(parsed.test && parsed.test[0] !== 'all' ? parsed.test : null)
   const Connection = require(path.join(base, 'connection'))
   // var Transaction = require(path.join(base, "transaction"));
-  const Address = require('address-rfc2821').Address
+  const Address = require('../address').Address
   const Notes = require('haraka-notes')
   const constants = require('haraka-constants')
   const client = {

package/connection.js

@@ -12,7 +12,7 @@ const constants = require('haraka-constants')
 const net_utils = require('haraka-net-utils')
 const Notes = require('haraka-notes')
 const utils = require('haraka-utils')
-const { Address } = require('address-rfc2821')
+const { Address } = require('./address')
 const ResultStore = require('haraka-results')
 
 // Haraka libs
@@ -1039,7 +1039,7 @@ class Connection {
         this.lognotice(dmsg, {
             code: constants.translate(retval === constants.cont ? constants.ok : retval),
             msg: msg || '',
-            sender: this.transaction.mail_from.address(),
+            sender: this.transaction.mail_from.address,
         })
         switch (retval) {
             case constants.deny:
@@ -1089,7 +1089,7 @@ class Connection {
             this.lognotice(dmsg, {
                 code: constants.translate(retval === constants.cont ? constants.ok : retval),
                 msg: msg || '',
-                sender: this.transaction.mail_from.address(),
+                sender: this.transaction.mail_from.address,
             })
         }
         switch (retval) {

package/docs/Outbound.md

@@ -203,7 +203,7 @@ Options accepted by `send_email(from, to, contents, next, options)`:
 
 To send an already-built `Transaction` directly, use `outbound.send_trans_email(transaction, next)`. This is what `send_email()` calls internally and fires the `pre_send_trans_email` hook.
 
-<a name="fn1">1</a>: `Address` objects are [address-rfc2821](https://github.com/haraka/node-address-rfc2821) objects.
+<a name="fn1">1</a>: `Address` objects are [@haraka/email-address](https://github.com/haraka/email-address) objects.
 
 [url-tls]: plugins/tls.md
 [url-harakamx]: https://github.com/haraka/haraka-net-utils?tab=readme-ov-file#harakamx

package/docs/Transaction.md

@@ -132,4 +132,4 @@ Append a banner to the end of the message. If `html` is omitted, each newline in
 
 Register a filter applied to body parts. `ct_match` is either a regex matched against the content-type line, or a string matched as a prefix (e.g. `/^text\/html/` or `'text/plain'`). `filter` receives `(content_type, encoding, buffer)` and must return a `Buffer` with the replacement body (in the same encoding).
 
-[address]: https://github.com/haraka/node-address-rfc2821
+[address]: https://github.com/haraka/email-address

package/docs/plugins/status.md

@@ -11,15 +11,31 @@ This plugin allows to get internal status of queues and pools with SMTP commands
 
 ```
 < 220 example.com ESMTP Haraka ready
-> STATUS QUEUE LIST
+> STATUS QUEUE INSPECT
 < 211 {"delivery_queue":[],"temp_fail_queue":[]}
 ```
 
 ## Available commands list
 
-- `STATUS POOL LIST` - list of active pools
-- `STATUS QUEUE STATS` - queue statistics in format "<in_progress>/<delivery_queue length>/<temp_fail_queue length>"
-- `STATUS QUEUE LIST` - list of parsed queue files with _uuid, domain, mail_from, rcpt_to_ attributes
-- `STATUS QUEUE INSPECT` - returns content of _outbound.delivery_queue_ and _outbound.temp_fail_queue_
+- `STATUS POOL LIST` - map of active outbound connection pools, keyed by `host:port`
+- `STATUS QUEUE STATS` - queue statistics in format `"<in_progress>/<delivery_queue length>/<temp_fail_queue length>"`
+- `STATUS QUEUE LIST` - list of queue files on disk with _uuid, domain, mail_from, rcpt_to_ attributes
+- `STATUS QUEUE INSPECT` - returns merged content of `outbound.delivery_queue` and `outbound.temp_fail_queue` across all workers
 - `STATUS QUEUE DISCARD file` - stop delivering email file
 - `STATUS QUEUE PUSH file` - try to re-deliver email immediately
+
+## Notes
+
+### Live data only
+
+`POOL LIST`, `QUEUE STATS`, and `QUEUE INSPECT` reflect live in-memory state. They show only messages currently being processed or waiting in the retry queue. `QUEUE LIST` reads queue files from disk and may show messages that have already been delivered if they haven't been cleaned up yet.
+
+### Cluster mode
+
+In cluster mode, `POOL LIST`, `QUEUE STATS`, and `QUEUE INSPECT` aggregate results from all worker processes into a single response:
+
+- `POOL LIST` — pool maps from all workers are merged into one object
+- `QUEUE STATS` — counters from all workers are summed into a single `"N/N/N"` string
+- `QUEUE INSPECT` — `delivery_queue` and `temp_fail_queue` arrays from all workers are concatenated
+
+`QUEUE LIST` always runs on the master process since it reads shared queue files from disk.

package/outbound/hmail.js

@@ -7,7 +7,7 @@ const dns = require('node:dns')
 const net = require('node:net')
 const path = require('node:path')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../address')
 const config = require('haraka-config')
 const constants = require('haraka-constants')
 const DSN = require('haraka-dsn')
@@ -1148,7 +1148,7 @@ class HMailItem extends events.EventEmitter {
         }
         for (const rcpt_to of this.todo.rcpt_to) {
             bounce_body.push(CRLF)
-            bounce_body.push(`Final-Recipient: rfc822;${rcpt_to.address()}${CRLF}`)
+            bounce_body.push(`Final-Recipient: rfc822;${rcpt_to.address}${CRLF}`)
             let dsn_action = null
             if (rcpt_to.dsn_action) {
                 dsn_action = rcpt_to.dsn_action

package/outbound/index.js

@@ -3,7 +3,7 @@
 const fs = require('node:fs/promises')
 const path = require('node:path')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../address')
 const config = require('haraka-config')
 const constants = require('haraka-constants')
 const net_utils = require('haraka-net-utils')

package/outbound/queue.js

@@ -4,7 +4,7 @@ const child_process = require('node:child_process')
 const fs = require('node:fs/promises')
 const path = require('node:path')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../address')
 const config = require('haraka-config')
 
 const logger = require('../logger')

package/package.json

@@ -9,7 +9,7 @@
     "server",
     "email"
   ],
-  "version": "3.1.7",
+  "version": "3.2.0",
   "homepage": "http://haraka.github.io",
   "repository": {
     "type": "git",
@@ -20,8 +20,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "address-rfc2821": "~2.2.0",
-    "address-rfc2822": "~2.2.3",
+    "@haraka/email-address": "~3.1.3",
     "haraka-config": "~1.6.0",
     "haraka-constants": "~1.0.7",
     "haraka-dsn": "~1.2.0",

package/plugins/block_me.js

@@ -25,12 +25,12 @@ exports.hook_data_post = function (next, connection) {
     }
 
     // Check recipient is the right one
-    if (connection.transaction.rcpt_to[0].address().toLowerCase() != recip) {
+    if (connection.transaction.rcpt_to[0].address.toLowerCase() != recip) {
         return next()
     }
 
     // Check sender is in list
-    const sender = connection.transaction.mail_from.address()
+    const sender = connection.transaction.mail_from.address
     if (!utils.in_array(sender, senders)) {
         return next(DENY, `You are not allowed to block mail, ${sender}`)
     }

package/plugins/queue/smtp_forward.js

@@ -69,7 +69,7 @@ exports.get_config = function (conn) {
     if (this.cfg.main.domain_selector === 'mail_from') {
         if (!conn.transaction.mail_from) return this.cfg.main
         dom = conn.transaction.mail_from.host
-        address = conn.transaction.mail_from.address()
+        address = conn.transaction.mail_from.address
     } else {
         if (!conn.transaction.rcpt_to[0]) return this.cfg.main
         dom = conn.transaction.rcpt_to[0].host
@@ -92,7 +92,7 @@ exports.check_sender = function (next, connection, params) {
     const txn = connection?.transaction
     if (!txn) return
 
-    const email = params[0].address()
+    const email = params[0].address
     if (!email) {
         txn.results.add(this, { skip: 'mail_from.null', emit: true })
         return next()

package/plugins/rcpt_to.host_list_base.js

@@ -26,7 +26,7 @@ exports.hook_mail = function (next, connection, params) {
     const txn = connection?.transaction
     if (!txn) return
 
-    const email = params[0].address()
+    const email = params[0].address
     if (!email) {
         txn.results.add(this, { skip: 'mail_from.null', emit: true })
         return next()

package/plugins/record_envelope_addresses.js

@@ -4,14 +4,14 @@
 
 exports.hook_rcpt = (next, connection, params) => {
     if (connection?.transaction) {
-        connection.transaction.add_header('X-Envelope-To', params[0].address())
+        connection.transaction.add_header('X-Envelope-To', params[0].address)
     }
     next()
 }
 
 exports.hook_mail = (next, connection, params) => {
     if (connection?.transaction) {
-        connection.transaction.add_header('X-Envelope-From', params[0].address())
+        connection.transaction.add_header('X-Envelope-From', params[0].address)
     }
     next()
 }

package/plugins/status.js

@@ -171,7 +171,8 @@ exports.hook_init_master = function (next) {
         if (msg.event !== 'status.request') return
 
         plugin.call_workers(msg, (response) => {
-            msg.result = response.filter((el) => el != null)
+            const valid = response.filter((el) => el != null)
+            msg.result = plugin.merge_worker_responses(msg.params, valid)
             msg.event = 'status.result'
             sender.send(msg)
         })
@@ -212,13 +213,41 @@ exports.call_master = (cmd, cb) => {
 
 exports.call_workers = function (cmd, cb) {
     Promise.allSettled(Object.values(server.cluster.workers).map((w) => this.call_worker(w, cmd))).then((r) => {
-        cb(
-            // r.filter(s => s.status === 'rejected').flatMap(s => s.reason),
-            r.filter((s) => s.status === 'fulfilled').flatMap((s) => s.value),
-        )
+        cb(r.filter((s) => s.status === 'fulfilled').map((s) => s.value))
     })
 }
 
+// Merge per-worker responses into a single result matching non-cluster output shape.
+exports.merge_worker_responses = (params, results) => {
+    const cmd = params.trim().split(/\s+/).slice(0, 2).join(' ').toUpperCase()
+
+    switch (cmd) {
+        case 'POOL LIST': {
+            return Object.assign({}, ...results)
+        }
+        case 'QUEUE INSPECT': {
+            const merged = { delivery_queue: [], temp_fail_queue: [] }
+            for (const r of results) {
+                if (!r) continue
+                if (Array.isArray(r.delivery_queue)) merged.delivery_queue.push(...r.delivery_queue)
+                if (Array.isArray(r.temp_fail_queue)) merged.temp_fail_queue.push(...r.temp_fail_queue)
+            }
+            return merged
+        }
+        case 'QUEUE STATS': {
+            const totals = [0, 0, 0]
+            for (const r of results) {
+                if (!r) continue
+                const parts = String(r).split('/')
+                for (let i = 0; i < 3; i++) totals[i] += parseInt(parts[i] ?? 0, 10)
+            }
+            return totals.join('/')
+        }
+        default:
+            return results
+    }
+}
+
 // sends command to worker and then wait for response or timeout
 exports.call_worker = (worker, cmd) => {
     return new Promise((resolve) => {

package/test/connection.js

@@ -5,7 +5,7 @@ const assert = require('node:assert/strict')
 
 const constants = require('haraka-constants')
 const DSN = require('haraka-dsn')
-const { Address } = require('address-rfc2821')
+const { Address } = require('../address')
 
 const connection = require('../connection')
 const Server = require('../server')

package/test/fixtures/util_hmailitem.js

@@ -2,7 +2,7 @@
 
 const assert = require('node:assert')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../../address')
 const fixtures = require('haraka-test-fixtures')
 
 /**

package/test/outbound/index.js

@@ -211,7 +211,7 @@ describe('outbound', () => {
         it('yields to setImmediate before opening process_delivery pipes', async () => {
             const stream = require('node:stream')
             const Transaction = require('../../transaction')
-            const Address = require('address-rfc2821').Address
+            const Address = require('../../address').Address
             const outbound = require('../../outbound')
             const plugins = require('../../plugins')
 
@@ -271,7 +271,7 @@ describe('outbound', () => {
 
         it('adds missing Message-Id/Date and prepends Received before queueing', async () => {
             process.env.HARAKA_TEST_DIR = path.resolve('test')
-            const Address = require('address-rfc2821').Address
+            const Address = require('../../address').Address
             const outbound = require('../../outbound')
             const plugins = require('../../plugins')
 

package/test/plugins/auth/auth_base.js

@@ -2,7 +2,7 @@
 const assert = require('node:assert')
 const { describe, it, beforeEach } = require('node:test')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../../../address')
 const fixtures = require('haraka-test-fixtures')
 const utils = require('haraka-utils')
 

package/test/plugins/block_me.js

@@ -6,7 +6,7 @@ const assert = require('node:assert/strict')
 const { describe, it, beforeEach, after } = require('node:test')
 
 const fixtures = require('haraka-test-fixtures')
-const { Address } = require('address-rfc2821')
+const { Address } = require('@haraka/email-address')
 require('haraka-constants').import(global)
 
 // block_me appends to <config>/mail_from.blocklist when a sender is blocked;

package/test/plugins/queue/smtp_forward.js

@@ -5,7 +5,7 @@ const assert = require('node:assert/strict')
 const { EventEmitter } = require('node:events')
 const path = require('node:path')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../../../address')
 const fixtures = require('haraka-test-fixtures')
 const Notes = require('haraka-notes')
 

package/test/plugins/rcpt_to.host_list_base.js

@@ -2,7 +2,7 @@
 const assert = require('node:assert/strict')
 const { describe, it, beforeEach } = require('node:test')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../../address')
 const fixtures = require('haraka-test-fixtures')
 
 const _set_up = () => {

package/test/plugins/rcpt_to.in_host_list.js

@@ -2,7 +2,7 @@
 const assert = require('node:assert/strict')
 const { describe, it, beforeEach } = require('node:test')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../../address')
 const fixtures = require('haraka-test-fixtures')
 require('haraka-constants').import(global)
 

package/test/plugins/record_envelope_addresses.js

@@ -1,9 +1,9 @@
 'use strict'
 
-const assert = require('node:assert/strict')
+const assert = require('node:assert')
 const { describe, it, beforeEach } = require('node:test')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../../address')
 const fixtures = require('haraka-test-fixtures')
 
 const _set_up = () => {

package/test/plugins/status.js

@@ -134,4 +134,75 @@ describe('status', () => {
             this.plugin.hook_unrecognized_command(() => {}, this.connection, ['STATUS', 'QUEUE PUSH file'])
         })
     })
+
+    describe('merge_worker_responses', () => {
+        beforeEach(_set_up)
+
+        it('POOL LIST merges objects from all workers', () => {
+            const result = JSON.parse(
+                JSON.stringify(
+                    this.plugin.merge_worker_responses('POOL LIST', [
+                        { 'host1:25': { inUse: 1, size: 3 } },
+                        { 'host2:25': { inUse: 0, size: 2 } },
+                        {},
+                    ]),
+                ),
+            )
+            assert.deepEqual(result, {
+                'host1:25': { inUse: 1, size: 3 },
+                'host2:25': { inUse: 0, size: 2 },
+            })
+        })
+
+        it('POOL LIST with all empty workers returns empty object', () => {
+            const result = JSON.parse(JSON.stringify(this.plugin.merge_worker_responses('POOL LIST', [{}, {}, {}])))
+            assert.deepEqual(result, {})
+        })
+
+        it('QUEUE INSPECT merges queues from all workers', () => {
+            const result = JSON.parse(
+                JSON.stringify(
+                    this.plugin.merge_worker_responses('QUEUE INSPECT', [
+                        { delivery_queue: [{ id: 'a' }], temp_fail_queue: [{ id: 'x', fire_time: 1 }] },
+                        { delivery_queue: [{ id: 'b' }], temp_fail_queue: [] },
+                        { delivery_queue: [], temp_fail_queue: [{ id: 'y', fire_time: 2 }] },
+                    ]),
+                ),
+            )
+            assert.deepEqual(result, {
+                delivery_queue: [{ id: 'a' }, { id: 'b' }],
+                temp_fail_queue: [
+                    { id: 'x', fire_time: 1 },
+                    { id: 'y', fire_time: 2 },
+                ],
+            })
+        })
+
+        it('QUEUE INSPECT with all empty queues returns empty lists', () => {
+            const result = JSON.parse(
+                JSON.stringify(
+                    this.plugin.merge_worker_responses('QUEUE INSPECT', [
+                        { delivery_queue: [], temp_fail_queue: [] },
+                        { delivery_queue: [], temp_fail_queue: [] },
+                    ]),
+                ),
+            )
+            assert.deepEqual(result, { delivery_queue: [], temp_fail_queue: [] })
+        })
+
+        it('QUEUE STATS sums across workers', () => {
+            const result = this.plugin.merge_worker_responses('QUEUE STATS', ['1/2/3', '0/1/0', '2/0/1'])
+            assert.equal(result, '3/3/4')
+        })
+
+        it('QUEUE STATS with all zeros', () => {
+            const result = this.plugin.merge_worker_responses('QUEUE STATS', ['0/0/0', '0/0/0', '0/0/0'])
+            assert.equal(result, '0/0/0')
+        })
+
+        it('unknown command returns results array unchanged', () => {
+            const result = this.plugin.merge_worker_responses('POOL UNKNOWN', [{ foo: 1 }, { foo: 2 }])
+            assert.equal(result.length, 2)
+        })
+    })
 })

package/test/smtp_client.js

@@ -5,7 +5,7 @@ const assert = require('node:assert/strict')
 const { PassThrough } = require('node:stream')
 const path = require('node:path')
 
-const { Address } = require('address-rfc2821')
+const { Address } = require('../address')
 const fixtures = require('haraka-test-fixtures')
 const net_utils = require('haraka-net-utils')
 const message = require('haraka-email-message')