How haraka/haraka-plugin-bounce works
Project type and purpose
• This is a Node.js plugin (“haraka-plugin-bounce”) for the Haraka SMTP server.
• Its purpose is to hook into Haraka’s SMTP request pipeline and apply multiple configurable strategies to detect, validate, and process bounce messages.
File structure
• Top level:
• index.js – the plugin entry point
• config/ – contains bounce.ini and auxiliary JSON files (whitelist, bad_rcpt)
• test/ – unit and integration tests
• .github/workflows – CI, linting (Prettier), security (CodeQL), publish automation
• package.json – dependencies and plugin metadata
• No frontend; it lives entirely in the Haraka backend plugin architecture.
• Configuration and test artifacts are file-based; no external database.
README insights
• Describes features: hash-based validation, SPF checks, return-path rules, whitelist/bad-recipient lists.
• Specifies config parameters in config/bounce.ini and JSON whitelist.
• Integration point: append "bounce" to Haraka’s config/plugins file.
Main components
a. Haraka SMTP Server (core)
b. Plugin Engine (Haraka’s hook dispatcher)
c. bounce plugin module (index.js + sub-modules)
d. Configuration store (config/bounce.ini, bounce_whitelist.json, bounce_bad_rcpt)
e. Node.js crypto module (HMAC generation/validation)
f. DNS resolver (for SPF checks)
g. Downstream plugins or delivery subsystem
h. Client endpoints (SMTP clients sending mail; recipients)
Relationships and data flows
1. SMTP Client → Haraka SMTP listener
2. Haraka → sequential plugin hooks (e.g. hook_data, hook_queue)
3. bounce plugin loads config and JSON lists at startup
4. On bounce detection hook:
• Extract headers
• Call crypto to validate hash (if enabled)
• Query DNS for SPF validation (if enabled)
• Check return-path, recipient count, bad_rcpt list, whitelist
• Decide: accept & forward to downstream plugins/delivery or reject with SMTP error
5. Haraka → downstream plugins → final delivery or bounce back to sender
6. Plugin logs events, errors, metrics
Architectural patterns and principles
• Plugin architecture (inversion of control): Haraka calls plugin hooks
• Single responsibility: each check (hash, SPF, return-path) is a separate function
• Configuration-driven behavior: all rules toggled via INI/JSON
• No global state; config loaded once, then immutable during runtime
• Extensibility: adding new checks is adding new hook handlers or config sections
Relevant technologies
• Node.js runtime (v14+)
• Haraka SMTP server
• Node.js crypto (HMAC, hashing algorithms)
• DNS resolver library (for SPF record lookups)
• INI parser (for bounce.ini)
• JSON parser (for whitelists)
• Mocha or similar for test/index.js
• GitHub Actions for CI, Prettier for formatting, CodeQL for security scanning
Detailed capture of essential elements
• Config loading on plugin init.
• Decision diamond: “Bounce checks pass?” → Yes forwards, No rejects.
• File watchers or reloads if config changes at runtime (if applicable).
• Example config toggles beside each subcomponent.