@webimpian/zonemta-log-central 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webimpian
+
+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,81 @@
+# ZoneMTA → Log Central
+
+[![npm version](https://img.shields.io/npm/v/@webimpian/zonemta-log-central.svg)](https://www.npmjs.com/package/@webimpian/zonemta-log-central)
+[![License](https://img.shields.io/npm/l/@webimpian/zonemta-log-central.svg)](LICENSE.md)
+
+[ZoneMTA](https://github.com/zone-eu/zone-mta) plugin that ships mail delivery logs to a [Log Central](https://log.dev-aplikasiniaga.com) server: every queued, delivered, deferred, and bounced message becomes a searchable log entry with message-id, recipient, sending zone, and the remote MX response.
+
+Built on [`@webimpian/log-central-node`](https://www.npmjs.com/package/@webimpian/log-central-node) — batched background delivery, capped backoff, and bounded memory, so a Log Central outage can never disrupt mail flow. Hook handlers swallow their own failures and always advance ZoneMTA's plugin chain.
+
+## Installation
+
+Inside your ZoneMTA application directory:
+
+```bash
+npm install @webimpian/zonemta-log-central
+```
+
+Enable the plugin in the ZoneMTA config:
+
+```toml
+# config/plugins/log-central.toml
+["modules/@webimpian/zonemta-log-central"]
+enabled=["receiver", "main", "sender"]
+url="https://logs.example.com/api"
+token="your-project-key"
+app="your-mta-slug"
+environment="production"
+channel="zonemta"
+```
+
+Alternatively, if you keep local plugins in a `plugins/` folder, drop in a one-line shim as `plugins/log-central.js`:
+
+```js
+module.exports = require('@webimpian/zonemta-log-central');
+```
+
+and enable it as `["log-central"]` with the same options.
+
+## What gets logged
+
+| ZoneMTA hook | Level | Entry |
+|---|---|---|
+| `message:queue` | info | Message accepted into the queue (id, from, recipients, interface) |
+| `sender:delivered` | info | MX accepted the message (recipient, zone, MX response) |
+| `sender:responseError` | warning | Delivery deferred/failed (recipient, zone, error response) |
+| `queue:bounce` | error | Message bounced permanently (recipient, response, category) |
+| `log:entry` | debug | Raw ZoneMTA message-event feed — **off by default** |
+
+Toggle any of them in the config:
+
+```toml
+["modules/@webimpian/zonemta-log-central".events]
+queued=false
+raw=true
+```
+
+## Options
+
+| Option | Default | Purpose |
+|---|---|---|
+| `url` | *(required)* | Log Central ingest base URL, e.g. `https://logs.example.com/api` |
+| `token` | *(required)* | The app's project key (bearer token) |
+| `app` | *(required)* | The app's slug, must match the token's app |
+| `environment` | `production` | Environment tag on every entry |
+| `channel` | `zonemta` | Log channel shown in the Log Central viewer |
+| `hostname` | `os.hostname()` | Hostname tag on every entry |
+| `batchSize` / `flushInterval` / `maxQueue` | see client | Passed through to [`@webimpian/log-central-node`](https://www.npmjs.com/package/@webimpian/log-central-node) |
+| `events` | all on, `raw` off | Toggle individual hooks (see above) |
+
+If `url`, `token`, or `app` is missing, the plugin logs a warning through ZoneMTA's logger and disables itself — it never prevents ZoneMTA from starting.
+
+## Testing
+
+```bash
+npm install
+npm test
+```
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

package/index.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const { LogCentralClient } = require('@webimpian/log-central-node');
+
+const DEFAULT_EVENTS = {
+    queued: true,
+    delivered: true,
+    deferred: true,
+    bounced: true,
+    raw: false,
+};
+
+module.exports.title = 'Log Central';
+
+module.exports.init = function (app, done) {
+    const config = app.config || {};
+
+    let client;
+
+    try {
+        client = new LogCentralClient({
+            url: config.url,
+            token: config.token,
+            app: config.app,
+            environment: config.environment || 'production',
+            channel: config.channel || 'zonemta',
+            hostname: config.hostname,
+            batchSize: config.batchSize,
+            flushInterval: config.flushInterval,
+            maxQueue: config.maxQueue,
+            fetch: config.fetch,
+        });
+    } catch (err) {
+        if (app.logger && typeof app.logger.error === 'function') {
+            app.logger.error('LogCentral', 'plugin disabled: %s', err.message);
+        }
+
+        return done();
+    }
+
+    app.logCentral = client;
+
+    const events = Object.assign({}, DEFAULT_EVENTS, config.events);
+
+    // A hook that throws breaks ZoneMTA's plugin chain and with it the mail
+    // flow, so every handler swallows its own errors and always calls next.
+    const safely = handler => (...args) => {
+        const next = typeof args[args.length - 1] === 'function' ? args.pop() : null;
+
+        try {
+            handler(...args);
+        } catch {
+            // never disrupt mail flow because of logging
+        }
+
+        if (next) {
+            next();
+        }
+    };
+
+    if (events.queued) {
+        app.addHook('message:queue', safely((envelope, messageInfo) => {
+            const recipients = Array.isArray(envelope.to) ? envelope.to : [];
+
+            client.info(
+                `Queued ${envelope.id} from ${envelope.from || '<>'} to ${recipients.length} recipient${recipients.length === 1 ? '' : 's'}`,
+                {
+                    id: envelope.id,
+                    from: envelope.from,
+                    to: recipients,
+                    interface: envelope.interface,
+                    origin: envelope.origin,
+                    transtype: envelope.transtype,
+                    subject: messageInfo && messageInfo.subject,
+                },
+            );
+        }));
+    }
+
+    if (events.delivered) {
+        app.addHook('sender:delivered', safely((delivery, info) => {
+            client.info(`Delivered ${delivery.id}.${delivery.seq} to ${delivery.recipient}`, {
+                id: delivery.id,
+                seq: delivery.seq,
+                recipient: delivery.recipient,
+                domain: delivery.domain,
+                zone: delivery.sendingZone,
+                mx: info && (info.mx || info.host),
+                response: info && info.response,
+            });
+        }));
+    }
+
+    if (events.deferred) {
+        app.addHook('sender:responseError', safely((delivery, connection, err) => {
+            const reason = (err && (err.response || err.message)) || 'unknown error';
+
+            client.warning(`Delivery failed for ${delivery.id}.${delivery.seq} to ${delivery.recipient}: ${reason}`, {
+                id: delivery.id,
+                seq: delivery.seq,
+                recipient: delivery.recipient,
+                domain: delivery.domain,
+                zone: delivery.sendingZone,
+                response: err && err.response,
+                category: err && err.category,
+            });
+        }));
+    }
+
+    if (events.bounced) {
+        app.addHook('queue:bounce', safely(bounce => {
+            const recipient = bounce.to || bounce.recipient || 'unknown recipient';
+
+            client.error(`Bounced ${bounce.id}${bounce.seq ? `.${bounce.seq}` : ''} to ${recipient}: ${bounce.response || ''}`, {
+                id: bounce.id,
+                seq: bounce.seq,
+                from: bounce.from,
+                to: recipient,
+                response: bounce.response,
+                category: bounce.category,
+                zone: bounce.sendingZone,
+            });
+        }));
+    }
+
+    if (events.raw) {
+        app.addHook('log:entry', safely(entry => {
+            const message = (entry && (entry.short_message || entry.action)) || 'zonemta log entry';
+
+            client.debug(message, entry || {});
+        }));
+    }
+
+    done();
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@webimpian/zonemta-log-central",
+    "version": "1.0.0",
+    "description": "ZoneMTA plugin that ships mail delivery logs (queued, delivered, deferred, bounced) to a Log Central server.",
+    "keywords": [
+        "zonemta",
+        "zone-mta",
+        "logging",
+        "log-central"
+    ],
+    "license": "MIT",
+    "author": "Khairul Imran <infrastructure@webimpian.com>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/webimpian-os/zonemta-log-central.git"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "main": "index.js",
+    "files": [
+        "index.js",
+        "LICENSE.md",
+        "README.md"
+    ],
+    "dependencies": {
+        "@webimpian/log-central-node": "^1.0.0"
+    },
+    "scripts": {
+        "test": "node --test"
+    }
+}