v5.2.3

changelog.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 2026-02-26 - 5.2.3 - fix(delivery)
+prevent throttle reset timer from firing after stop and avoid scheduling duplicate timers
+
+- add throttleResetTimer property to track scheduled throttle-reset timeout
+- clear throttleResetTimer when stopping to prevent it firing after shutdown
+- clear existing throttleResetTimer before scheduling a new one and null it when fired to avoid duplicate timers and potential leaks
+
+## 2026-02-12 - 5.2.2 - fix(deps)
+bump dependencies: @push.rocks/smartrust to ^1.2.1, lru-cache to ^11.2.6
+
+- Bumped @push.rocks/smartrust from ^1.2.0 to ^1.2.1
+- Bumped lru-cache from ^11.2.5 to ^11.2.6
+
+## 2026-02-11 - 5.2.1 - fix(rust-bridge)
+map Node.js platform/arch to tsrust-style suffix and add platform-specific and dev localPaths for RustBridge
+
+- Add getPlatformSuffix() to map process.platform/process.arch to tsrust-style suffixes (e.g. linux_amd64)
+- Include dist_rust/mailer-bin_{suffix} when available to prefer cross-compiled binaries
+- Consolidate localPaths and add local dev build paths (rust/target/release and rust/target/debug)
+- Pass the computed localPaths array into plugins.smartrust.RustBridge (searchSystemPath remains disabled)
+
+## 2026-02-11 - 5.2.0 - feat(packaging)
+add package exports entry, include ts/dist_ts in package files, and add TS barrel index re-exports
+
+- package.json: add "exports" mapping "." -> "./dist_ts/index.js" to provide a module entry point
+- package.json: add "ts/**/*" and "dist_ts/**/*" to "files" so TypeScript sources and built output are published
+- ts/index.ts: new barrel that re-exports './00_commitinfo_data.js', './mail/index.js', and './security/index.js'
+
+## 2026-02-11 - 5.1.3 - fix(docs)
+clarify sendEmail default behavior and document automatic MX discovery and delivery modes
+
+- Updated README to describe automatic MX record discovery and grouping behavior when using sendEmail() (MTA mode)
+- Added a Delivery Modes section and API signature for sendEmail(mode) describing mta, forward, and process options
+- Expanded examples to show multi-recipient delivery, explicit mode usage, and retained low-level sendOutboundEmail example
+
+## 2026-02-11 - 5.1.2 - fix(readme)
+adjust ASCII architecture diagram alignment in README
+
+- Whitespace and alignment tweaks to the ASCII architecture diagram in readme.md
+- No code or behavior changes; documentation-only edit
+
+## 2026-02-11 - 5.1.1 - fix(release)
+no changes
+
+- No files changed in this commit.
+- Current package version remains 5.1.0 (from package.json).
+
 ## 2026-02-11 - 5.1.0 - feat(mailer-smtp)
 add SCRAM-SHA-256 auth, Ed25519 DKIM, opportunistic TLS, SNI cert selection, pipelining and delivery/bridge improvements
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartmta",
-  "version": "5.1.0",
+  "version": "5.2.3",
   "description": "A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with Rust acceleration.",
   "keywords": [
     "mta",
@@ -27,6 +27,9 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "type": "module",
+  "exports": {
+    ".": "./dist_ts/index.js"
+  },
   "bin": {
     "mailer": "./bin/mailer-wrapper.js"
   },
@@ -49,13 +52,15 @@
     "@push.rocks/smartlog": "^3.1.8",
     "@push.rocks/smartmail": "^2.2.0",
     "@push.rocks/smartpath": "^6.0.0",
-    "@push.rocks/smartrust": "^1.2.0",
+    "@push.rocks/smartrust": "^1.2.1",
     "@tsclass/tsclass": "^9.2.0",
-    "lru-cache": "^11.2.5",
+    "lru-cache": "^11.2.6",
     "mailparser": "^3.9.3",
     "uuid": "^13.0.0"
   },
   "files": [
+    "ts/**/*",
+    "dist_ts/**/*",
     "bin/",
     "scripts/install-binary.js",
     "dist_rust/**/*",

pnpm-lock.yaml

@@ -24,14 +24,14 @@ importers:
         specifier: ^6.0.0
         version: 6.0.0
       '@push.rocks/smartrust':
-        specifier: ^1.2.0
-        version: 1.2.0
+        specifier: ^1.2.1
+        version: 1.2.1
       '@tsclass/tsclass':
         specifier: ^9.2.0
         version: 9.3.0
       lru-cache:
-        specifier: ^11.2.5
-        version: 11.2.5
+        specifier: ^11.2.6
+        version: 11.2.6
       mailparser:
         specifier: ^3.9.3
         version: 3.9.3
@@ -69,6 +69,9 @@ packages:
   '@api.global/typedrequest@3.2.5':
     resolution: {integrity: sha512-LM/sUTuYnU5xY4gNZrN6ERMiKr+SpDZuSxJkAZz1YazC7ymGfo6uQ8sCnN8eNNQNFqIOkC+BtfYRayfbGwYLLg==}
 
+  '@api.global/typedrequest@3.2.6':
+    resolution: {integrity: sha512-CnvbjYjnGGw3rwL+7bTHSgRHEpDujzhs3cv7l1xgCXMPQe3DcPg74+9ep1Y5cu21T/w0pxNnDCJpbb0SHqHzAw==}
+
   '@api.global/typedserver@3.0.80':
     resolution: {integrity: sha512-dcp0oXsjBL+XdFg1wUUP08uJQid5bQ0Yv3V3Y3lnI2QCbat0FU+Tsb0TZRnZ4+P150Vj/ITBqJUgDzFsF34grA==}
 
@@ -830,8 +833,8 @@ packages:
   '@push.rocks/smartrouter@1.3.3':
     resolution: {integrity: sha512-1+xZEnWlhzqLWAaJ1zFNhQ0zgbfCWQl1DBT72LygLxTs+P0K8AwJKgqo/IX6CT55kGCFnPAZIYSbVJlGsgrB0w==}
 
-  '@push.rocks/smartrust@1.2.0':
-    resolution: {integrity: sha512-JlaALselIHoP6C3ceQbrvz424G21cND/QsH/KI3E/JrO4XphJiGZwM6f4yJWrijdPYR/YYMoaIiYN7ybZp0C4w==}
+  '@push.rocks/smartrust@1.2.1':
+    resolution: {integrity: sha512-ANwXXibUwoHNWF1hhXhXVVrfzYlhgHYRa2205Jkd/s/wXzcWHftYZthilJj+52B7nkzSB76umfxKfK5eBYY2Ug==}
 
   '@push.rocks/smartrx@3.0.10':
     resolution: {integrity: sha512-USjIYcsSfzn14cwOsxgq/bBmWDTTzy3ouWAnW5NdMyRRzEbmeNrvmy6TRqNeDlJ2PsYNTt1rr/zGUqvIy72ITg==}
@@ -2491,8 +2494,8 @@ packages:
     resolution: {integrity: sha512-ozCC6gdQ+glXOQsveKD0YsDy8DSQFjDTz4zyzEHNV5+JP5D62LmfDZ6o1cycFx9ouG940M5dE8C8CTewdj2YWQ==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
 
-  lru-cache@11.2.5:
-    resolution: {integrity: sha512-vFrFJkWtJvJnD5hg+hJvVE8Lh/TcMzKnTgCWmtBipwI5yLX/iX+5UB2tfuyODF5E7k9xEzMdYgGqaSb1c0c5Yw==}
+  lru-cache@11.2.6:
+    resolution: {integrity: sha512-ESL2CrkS/2wTPfuend7Zhkzo2u0daGJ/A2VucJOgQ/C48S/zB8MMeMHSGKYpXhIjbPxfuezITkaBH1wqv00DDQ==}
     engines: {node: 20 || >=22}
 
   lru-cache@7.18.3:
@@ -3594,6 +3597,19 @@ snapshots:
       '@push.rocks/webrequest': 3.0.37
       '@push.rocks/webstream': 1.0.10
 
+  '@api.global/typedrequest@3.2.6':
+    dependencies:
+      '@api.global/typedrequest-interfaces': 3.0.19
+      '@push.rocks/isounique': 1.0.5
+      '@push.rocks/lik': 6.2.2
+      '@push.rocks/smartbuffer': 3.0.5
+      '@push.rocks/smartdelay': 3.0.5
+      '@push.rocks/smartguard': 3.1.0
+      '@push.rocks/smartpromise': 4.2.3
+      '@push.rocks/webrequest': 4.0.1
+      '@push.rocks/webstream': 1.0.10
+    optional: true
+
   '@api.global/typedserver@3.0.80(@push.rocks/smartserve@2.0.1)':
     dependencies:
       '@api.global/typedrequest': 3.2.5
@@ -5326,7 +5342,7 @@ snapshots:
       '@push.rocks/smartrx': 3.0.10
       path-to-regexp: 8.3.0
 
-  '@push.rocks/smartrust@1.2.0':
+  '@push.rocks/smartrust@1.2.1':
     dependencies:
       '@push.rocks/smartpath': 6.0.0
 
@@ -5347,7 +5363,7 @@ snapshots:
 
   '@push.rocks/smartserve@2.0.1':
     dependencies:
-      '@api.global/typedrequest': 3.2.5
+      '@api.global/typedrequest': 3.2.6
       '@cfworker/json-schema': 4.1.1
       '@push.rocks/lik': 6.2.2
       '@push.rocks/smartenv': 6.0.0
@@ -7313,7 +7329,7 @@ snapshots:
 
   lowercase-keys@3.0.0: {}
 
-  lru-cache@11.2.5: {}
+  lru-cache@11.2.6: {}
 
   lru-cache@7.18.3: {}
 
@@ -7920,7 +7936,7 @@ snapshots:
 
   path-scurry@2.0.1:
     dependencies:
-      lru-cache: 11.2.5
+      lru-cache: 11.2.6
       minipass: 7.1.2
 
   path-to-regexp@8.3.0: {}

readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartmta
 
-A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with a Rust-powered SMTP engine — no nodemailer, no shortcuts. 🚀
+A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with a Rust-powered SMTP engine — no nodemailer, no shortcuts. Automatic MX record discovery means you just call `sendEmail()` and smartmta figures out where to deliver. 🚀
 
 ## Issue Reporting and Security
 
@@ -43,28 +43,28 @@ After installation, run `pnpm build` to compile the Rust binary (`mailer-bin`).
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
-│                    UnifiedEmailServer                         │
-│     (orchestrates all components, emits events)               │
+│                    UnifiedEmailServer                        │
+│     (orchestrates all components, emits events)              │
 ├───────────┬───────────┬──────────────┬───────────────────────┤
 │   Email   │  Security │  Delivery    │  Configuration        │
 │   Router  │  Stack    │  System      │                       │
-│  ┌──────┐ │ ┌───────┐ │ ┌──────────┐ │  ┌────────────────┐  │
-│  │Match │ │ │ DKIM  │ │ │ Queue    │ │  │ DomainRegistry │  │
-│  │Route │ │ │ SPF   │ │ │ Rate Lim │ │  │ DnsManager     │  │
-│  │ Act  │ │ │ DMARC │ │ │ Retry    │ │  │ DKIMCreator    │  │
-│  └──────┘ │ │ IPRep │ │ └──────────┘ │  │ Templates      │  │
-│           │ │ Scan  │ │              │  └────────────────┘  │
+│  ┌──────┐ │ ┌───────┐ │ ┌──────────┐ │  ┌────────────────┐   │
+│  │Match │ │ │ DKIM  │ │ │ Queue    │ │  │ DomainRegistry │   │
+│  │Route │ │ │ SPF   │ │ │ Rate Lim │ │  │ DnsManager     │   │
+│  │ Act  │ │ │ DMARC │ │ │ Retry    │ │  │ DKIMCreator    │   │
+│  └──────┘ │ │ IPRep │ │ └──────────┘ │  │ Templates      │   │
+│           │ │ Scan  │ │              │  └────────────────┘   │
 │           │ └───────┘ │              │                       │
 ├───────────┴───────────┴──────────────┴───────────────────────┤
-│              Rust Security Bridge (smartrust IPC)             │
+│              Rust Security Bridge (smartrust IPC)            │
 ├──────────────────────────────────────────────────────────────┤
-│                   Rust Acceleration Layer                      │
-│  ┌──────────────┐  ┌───────────────┐  ┌──────────────────┐  │
-│  │ mailer-smtp  │  │mailer-security│  │   mailer-core    │  │
-│  │ SMTP Server  │  │DKIM/SPF/DMARC │  │ Types/Validation │  │
-│  │ SMTP Client  │  │IP Rep/Content │  │ MIME/Bounce      │  │
-│  │ TLS/AUTH     │  │   Scanning    │  │   Detection      │  │
-│  └──────────────┘  └───────────────┘  └──────────────────┘  │
+│                   Rust Acceleration Layer                    │
+│  ┌──────────────┐  ┌───────────────┐  ┌──────────────────┐   │
+│  │ mailer-smtp  │  │mailer-security│  │   mailer-core    │   │
+│  │ SMTP Server  │  │DKIM/SPF/DMARC │  │ Types/Validation │   │
+│  │ SMTP Client  │  │IP Rep/Content │  │ MIME/Bounce      │   │
+│  │ TLS/AUTH     │  │   Scanning    │  │   Detection      │   │
+│  └──────────────┘  └───────────────┘  └──────────────────┘   │
 └──────────────────────────────────────────────────────────────┘
 ```
 
@@ -78,9 +78,10 @@ After installation, run `pnpm build` to compile the Rust binary (`mailer-bin`).
 
 **Data flow for outbound mail:**
 
-1. 📝 TypeScript constructs the email and resolves DKIM keys for the sender domain
-2. 🦀 Sends to Rust via IPC — Rust builds the RFC 2822 message, signs with DKIM, and delivers via its SMTP client with connection pooling
-3. 📬 Result (accepted/rejected recipients, server response) returned to TypeScript
+1. 📝 TypeScript constructs the email and calls `sendEmail()` (defaults to MTA mode)
+2. 🔍 MTA mode automatically resolves MX records for each recipient domain, sorts by priority, and groups recipients for efficient delivery
+3. 🦀 Sends to Rust via IPC — Rust builds the RFC 2822 message, signs with DKIM, and delivers via its SMTP client with connection pooling
+4. 📬 Result (accepted/rejected recipients, server response) returned to TypeScript
 
 ## Usage
 
@@ -169,9 +170,9 @@ await emailServer.start();
 
 > 🔒 **Note:** `start()` will throw if the Rust binary is not compiled. Run `pnpm build` first.
 
-### 📧 Sending Outbound Emails
+### 📧 Sending Emails (Automatic MX Discovery)
 
-All outbound email delivery goes through the Rust SMTP client, accessed via `UnifiedEmailServer.sendOutboundEmail()`. The Rust client handles connection pooling, TLS negotiation, and DKIM signing automatically:
+The recommended way to send email is `sendEmail()`. It defaults to **MTA mode**, which automatically resolves MX records for each recipient domain via DNS — you don't need to know the destination mail server:
 
 ```typescript
 import { Email, UnifiedEmailServer } from '@push.rocks/smartmta';
@@ -179,8 +180,7 @@ import { Email, UnifiedEmailServer } from '@push.rocks/smartmta';
 // Build an email
 const email = new Email({
   from: 'sender@example.com',
-  to: ['recipient@example.com'],
-  cc: ['cc@example.com'],
+  to: ['alice@gmail.com', 'bob@company.org'],
   subject: 'Hello from smartmta! 🚀',
   text: 'Plain text body',
   html: '<h1>Hello!</h1><p>HTML body with <strong>formatting</strong></p>',
@@ -194,7 +194,50 @@ const email = new Email({
   ],
 });
 
-// Send via the Rust SMTP client (connection pooling, TLS, DKIM signing)
+// Send — MTA mode auto-discovers MX servers for gmail.com and company.org
+const emailId = await emailServer.sendEmail(email);
+
+// Optionally specify a delivery mode explicitly
+const emailId2 = await emailServer.sendEmail(email, 'mta');
+```
+
+In MTA mode, smartmta:
+- 🔍 Resolves MX records for each recipient domain (e.g. `gmail.com`, `company.org`)
+- 📊 Sorts MX hosts by priority (lowest = highest priority per RFC 5321)
+- 🔄 Tries each MX host in order until delivery succeeds
+- 🌐 Falls back to the domain's A record if no MX records exist
+- 📦 Groups recipients by domain for efficient batch delivery
+- 🔑 Signs outbound mail with DKIM automatically
+
+### 📮 Delivery Modes
+
+`sendEmail()` accepts a mode parameter that controls how the email is delivered:
+
+```typescript
+public async sendEmail(
+  email: Email,
+  mode: EmailProcessingMode = 'mta',  // 'mta' | 'forward' | 'process'
+  route?: IEmailRoute,
+  options?: {
+    skipSuppressionCheck?: boolean;
+    ipAddress?: string;
+    isTransactional?: boolean;
+  }
+): Promise<string>
+```
+
+| Mode | Description |
+|---|---|
+| `mta` (default) | **Auto MX discovery** — resolves MX records via DNS, delivers directly to the recipient's mail server. No relay configuration needed. |
+| `forward` | **Relay delivery** — forwards the email to a configured SMTP host (e.g. an internal mail gateway or third-party relay). |
+| `process` | **Scan + deliver** — runs the content scanning / security pipeline first, then delivers via auto MX resolution. |
+
+### 📬 Direct SMTP Delivery (Low-Level)
+
+For cases where you know the exact target SMTP server (e.g. relaying to a specific host), use the lower-level `sendOutboundEmail()`:
+
+```typescript
+// Send directly to a known SMTP server (bypasses MX resolution)
 const result = await emailServer.sendOutboundEmail('smtp.example.com', 587, email, {
   auth: { user: 'sender@example.com', pass: 'your-password' },
   dkimDomain: 'example.com',

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartmta',
-  version: '5.1.0',
+  version: '5.2.3',
   description: 'A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with Rust acceleration.'
 }

ts/index.ts

@@ -0,0 +1,3 @@
+export * from './00_commitinfo_data.js';
+export * from './mail/index.js';
+export * from './security/index.js';

ts/mail/delivery/classes.delivery.system.ts

@@ -108,6 +108,7 @@ export class MultiModeDeliverySystem extends EventEmitter {
   private activeDeliveries: Set<string> = new Set();
   private running: boolean = false;
   private throttled: boolean = false;
+  private throttleResetTimer: ReturnType<typeof setTimeout> | null = null;
   private rateLimitLastCheck: number = Date.now();
   private rateLimitCounter: number = 0;
   private emailServer?: UnifiedEmailServer;
@@ -212,6 +213,12 @@ export class MultiModeDeliverySystem extends EventEmitter {
     
     this.running = false;
 
+    // Clear throttle reset timer to prevent it firing after stop
+    if (this.throttleResetTimer) {
+      clearTimeout(this.throttleResetTimer);
+      this.throttleResetTimer = null;
+    }
+
     // Wait for active deliveries to complete
     if (this.activeDeliveries.size > 0) {
       logger.log('info', `Waiting for ${this.activeDeliveries.size} active deliveries to complete`);
@@ -776,7 +783,11 @@ export class MultiModeDeliverySystem extends EventEmitter {
       
       // Schedule throttle reset
       const resetDelay = 60000 - elapsed;
-      setTimeout(() => {
+      if (this.throttleResetTimer) {
+        clearTimeout(this.throttleResetTimer);
+      }
+      this.throttleResetTimer = setTimeout(() => {
+        this.throttleResetTimer = null;
         this.throttled = false;
         this.rateLimitLastCheck = Date.now();
         this.rateLimitCounter = 0;

ts/security/classes.rustsecuritybridge.ts

@@ -375,18 +375,39 @@ export class RustSecurityBridge extends EventEmitter {
   private _deliberateStop = false;
   private _smtpServerConfig: ISmtpServerConfig | null = null;
 
+  /**
+   * Map Node.js process.platform / process.arch to the tsrust-style suffix
+   * used for cross-compiled binaries, e.g. mailer-bin_linux_amd64.
+   */
+  private static getPlatformSuffix(): string | null {
+    const archMap: Record<string, string> = { x64: 'amd64', arm64: 'arm64' };
+    const os = process.platform;   // 'linux', 'darwin', 'win32', …
+    const arch = archMap[process.arch];
+    if (!arch) return null;
+    return `${os}_${arch}`;
+  }
+
   private constructor() {
     super();
+
+    const suffix = RustSecurityBridge.getPlatformSuffix();
+    const localPaths: string[] = [];
+
+    // dist_rust/ candidates (tsrust cross-compiled output)
+    if (suffix) {
+      localPaths.push(plugins.path.join(paths.packageDir, 'dist_rust', `mailer-bin_${suffix}`));
+    }
+    localPaths.push(plugins.path.join(paths.packageDir, 'dist_rust', 'mailer-bin'));
+    // Local dev build paths
+    localPaths.push(plugins.path.join(paths.packageDir, 'rust', 'target', 'release', 'mailer-bin'));
+    localPaths.push(plugins.path.join(paths.packageDir, 'rust', 'target', 'debug', 'mailer-bin'));
+
     this.bridge = new plugins.smartrust.RustBridge<TMailerCommands>({
       binaryName: 'mailer-bin',
       cliArgs: ['--management'],
       requestTimeoutMs: 30_000,
       readyTimeoutMs: 10_000,
-      localPaths: [
-        plugins.path.join(paths.packageDir, 'dist_rust', 'mailer-bin'),
-        plugins.path.join(paths.packageDir, 'rust', 'target', 'release', 'mailer-bin'),
-        plugins.path.join(paths.packageDir, 'rust', 'target', 'debug', 'mailer-bin'),
-      ],
+      localPaths,
       searchSystemPath: false,
     });