siwatsystem-public/mxrelay-consumer
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mxrelay-consumer/README.md

602 lines
No EOL
17 KiB
Markdown
Raw Blame History

# @siwats/mxrelay-consumer
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
A production-ready TypeScript client library for SMTP over WebSocket protocol with **session-based queue management**, automatic reconnection, and comprehensive error handling. Features proper SMTP session protocol implementation with mutex-based session locking.
## 🚀 Key Features
### **Session-Based SMTP Protocol**
- **Proper SMTP Sessions**: One session = EHLO → AUTH → Multiple Emails → QUIT
- **Session Mutex**: Only one SMTP session active at a time (protocol compliant)
- **Email Batching**: Send multiple emails efficiently within a single session
- **Resource Optimization**: Connect only when needed, disconnect when idle
### **Intelligent Queue Management**
- **Session Queuing**: Queues complete email sessions, not individual commands
- **Priority-Based Processing**: CRITICAL > HIGH > NORMAL > LOW priority levels
- **Configurable Batching**: Control emails per session with `maxEmailsPerSession`
- **Smart Resource Usage**: Auto-connect/disconnect based on queue state
### **Production-Ready Reliability**
- **Comprehensive Error Handling**: Structured error classification and meaningful messages
- **Automatic Reconnection**: Exponential backoff with configurable retry limits
- **Timeout Management**: Session, email, and connection-level timeouts
- **Connection State Management**: Full lifecycle state tracking
### **Nodemailer Integration**
- **Full Nodemailer Compatibility**: Drop-in replacement for existing transports
- **Standard API**: Use familiar Nodemailer methods and options
- **Advanced Features**: Attachments, HTML, multipart messages, custom headers
## 📊 Architecture Overview
```mermaid
graph TB
subgraph "Client Application"
App[Your Application]
NM[Nodemailer]
Transport[SMTPWSTransport]
end
subgraph "Session Management"
Client[SMTPOverWSClient]
Queue[Session Queue]
SM[Session Manager]
end
subgraph "Protocol Layer"
WS[WebSocket Connection]
Auth[Authentication]
Channel[SMTP Channel]
end
subgraph "Remote Server"
Relay[SMTP WebSocket Relay]
SMTP[SMTP Server]
end
App --> NM
NM --> Transport
Transport --> Client
Client --> Queue
Queue --> SM
SM --> WS
WS --> Auth
Auth --> Channel
Channel --> Relay
Relay --> SMTP
style Client fill:#e1f5fe
style Queue fill:#f3e5f5
style SM fill:#fff3e0
style Channel fill:#e8f5e8
```
## 🔄 Session Processing Flow
```mermaid
sequenceDiagram
participant App as Application
participant Client as SMTPOverWSClient
participant Queue as Session Queue
participant WS as WebSocket
participant Server as SMTP Server
Note over App,Server: Email Submission
App->>Client: queueEmail(from, to[], data)
Client->>Queue: Add to session or create new
Note over App,Server: Session Processing (Mutex)
Queue->>Client: Process next session
Client->>WS: Connect (if needed)
WS->>Server: WebSocket connection
Server-->>WS: Connection established
Client->>Server: AUTHENTICATE
Server-->>Client: AUTH_SUCCESS
Client->>Server: SMTP_CHANNEL_OPEN
Server-->>Client: SMTP_CHANNEL_READY
Server-->>Client: 220 SMTP ready
Client->>Server: EHLO client
Server-->>Client: 250 EHLO OK
Client->>Server: AUTH PLAIN <credentials>
Server-->>Client: 235 AUTH OK
loop For each email in session
Client->>Server: MAIL FROM:<sender>
Server-->>Client: 250 Sender OK
Client->>Server: RCPT TO:<recipient>
Server-->>Client: 250 Recipient OK
Client->>Server: DATA
Server-->>Client: 354 Start data
Client->>Server: <email content>\r\n.
Server-->>Client: 250 Message accepted
Client->>App: Email resolved
end
Client->>Server: QUIT
Server-->>Client: 221 Goodbye
Client->>Server: SMTP_CHANNEL_CLOSE
WS->>WS: Disconnect (if queue empty)
Client->>App: Session completed
```
## 📦 Installation
```bash
npm install @siwats/mxrelay-consumer
# or
bun add @siwats/mxrelay-consumer
```
## 🚀 Quick Start
### Direct Client Usage (New Session-Based API)
```typescript
import { SMTPOverWSClient } from '@siwats/mxrelay-consumer';
const client = new SMTPOverWSClient({
url: 'wss://api.siwatsystem.com/smtp',
apiKey: 'your-api-key',
debug: true,
maxEmailsPerSession: 5, // Batch up to 5 emails per session
sessionTimeout: 300000 // 5 minute session timeout
});
// Queue individual emails - they'll be batched into sessions automatically
try {
// These emails will be sent in the same SMTP session
const emailId1 = await client.queueEmail(
'sender@example.com',
['recipient1@example.com'],
'Subject: Email 1\r\n\r\nFirst email content'
);
const emailId2 = await client.queueEmail(
'sender@example.com',
['recipient2@example.com'],
'Subject: Email 2\r\n\r\nSecond email content'
);
console.log('Emails queued:', emailId1, emailId2);
} catch (error) {
console.error('Email error:', error.message);
} finally {
await client.shutdown();
}
```
### Nodemailer Transport (Recommended)
```typescript
import nodemailer from 'nodemailer';
import { createTransport } from '@siwats/mxrelay-consumer';
// Create transport with session batching
const transport = createTransport('your-api-key', {
host: 'api.siwatsystem.com',
port: 443,
secure: true,
debug: true,
maxEmailsPerSession: 10, // Batch up to 10 emails per session
sessionBatchTimeout: 2000 // Wait 2 seconds to batch emails
});
const transporter = nodemailer.createTransporter(transport);
// Send multiple emails - automatically batched into sessions
const emails = [
{
from: 'sender@example.com',
to: 'user1@example.com',
subject: 'Welcome Email',
html: '<h1>Welcome to our service!</h1>'
},
{
from: 'sender@example.com',
to: 'user2@example.com',
subject: 'Newsletter',
html: '<h1>Monthly Newsletter</h1>',
attachments: [{ filename: 'report.pdf', path: './report.pdf' }]
}
];
// Send all emails - they'll be efficiently batched into SMTP sessions
for (const email of emails) {
try {
const info = await transporter.sendMail(email);
console.log('Email sent:', info.messageId);
} catch (error) {
console.error('Failed to send email:', error.message);
}
}
await transport.close();
```
## ⚙️ Configuration
### Client Configuration
```typescript
interface SMTPClientConfig {
url: string; // WebSocket server URL
apiKey: string; // Authentication API key
// Session Management
sessionTimeout?: number; // Session timeout (default: 300000ms)
maxEmailsPerSession?: number; // Emails per session (default: 10)
sessionBatchTimeout?: number; // Batch wait time (default: 1000ms)
// Connection Management
debug?: boolean; // Enable debug logging (default: false)
maxQueueSize?: number; // Session queue limit (default: 100)
reconnectInterval?: number; // Reconnect delay (default: 5000ms)
maxReconnectAttempts?: number; // Max retry attempts (default: 10)
authTimeout?: number; // Auth timeout (default: 30000ms)
channelTimeout?: number; // Channel timeout (default: 10000ms)
messageTimeout?: number; // SMTP command timeout (default: 60000ms)
heartbeatInterval?: number; // Heartbeat interval (default: 30000ms)
}
```
### Transport Configuration
```typescript
interface TransportOptions extends Omit<SMTPClientConfig, 'url' | 'apiKey'> {
host?: string; // Server host (default: 'api.siwatsystem.com')
port?: number; // Server port (default: 443)
secure?: boolean; // Use wss:// (default: true)
apiKey?: string; // API key for authentication
}
```
## 🎯 Advanced Usage
### Session Priority and Options
```typescript
import { MessagePriority, SessionSendOptions } from '@siwats/mxrelay-consumer';
// High priority email (processed first)
await client.queueEmail(
'urgent@company.com',
['admin@company.com'],
'Subject: URGENT ALERT\r\n\r\nSystem down!',
{
priority: MessagePriority.HIGH,
timeout: 30000,
retries: 5
}
);
// Critical priority email (highest priority)
await client.queueEmail(
'security@company.com',
['security-team@company.com'],
'Subject: SECURITY BREACH\r\n\r\nImmediate action required!',
{
priority: MessagePriority.CRITICAL,
immediate: true // Skip batching, send immediately
}
);
```
### Session Event Monitoring
```typescript
// Session-level events
client.on('sessionQueued', (sessionId, queueSize) => {
console.log(`Session ${sessionId} queued. Queue size: ${queueSize}`);
});
client.on('sessionStarted', (sessionId, emailCount) => {
console.log(`Processing session ${sessionId} with ${emailCount} emails`);
});
client.on('sessionCompleted', (sessionId, results) => {
console.log(`Session ${sessionId} completed with ${results.length} emails`);
});
// Email-level events within sessions
client.on('emailProcessed', (sessionId, emailId, responseTime) => {
console.log(`Email ${emailId} in session ${sessionId} processed in ${responseTime}ms`);
});
client.on('emailFailed', (sessionId, emailId, error) => {
console.error(`Email ${emailId} in session ${sessionId} failed:`, error.message);
});
// Connection events
client.on('connected', () => console.log('WebSocket connected'));
client.on('authenticated', () => console.log('Authentication successful'));
client.on('disconnected', () => console.log('Connection lost'));
```
### Session Statistics
```typescript
const stats = client.getStats();
console.log('Session Statistics:', {
sessionsQueued: stats.sessionsQueued,
sessionsProcessed: stats.sessionsProcessed,
sessionsFailed: stats.sessionsFailed,
emailsProcessed: stats.emailsProcessed,
emailsFailed: stats.emailsFailed,
averageSessionTime: stats.averageSessionTime,
averageEmailTime: stats.averageEmailTime,
queueSize: stats.queueSize
});
console.log('Session State:', client.getSessionState()); // IDLE, PROCESSING, FAILED
console.log('Connection State:', client.getConnectionState()); // DISCONNECTED, CONNECTED, etc.
```
## 🛡️ Error Handling
### SMTP Session Errors
```typescript
try {
await client.queueEmail(
'invalid-sender@domain.com',
['recipient@example.com'],
'Subject: Test\r\n\r\nTest message'
);
} catch (error) {
if (error instanceof MessageError) {
console.error('SMTP Error:', error.message);
console.log('Email ID:', error.messageId);
console.log('Retry Count:', error.retryCount);
}
}
```
### Session State Management
The client manages session states automatically:
```mermaid
stateDiagram-v2
[*] --> IDLE
IDLE --> PROCESSING: Session queued
PROCESSING --> IDLE: Session completed
PROCESSING --> FAILED: Session error
FAILED --> PROCESSING: Retry session
FAILED --> IDLE: Max retries reached
IDLE --> [*]: Client shutdown
```
- `IDLE` - No active session, ready to process
- `PROCESSING` - Session currently being processed (mutex locked)
- `FAILED` - Session failed, will retry or reject
- `COMPLETED` - Session successfully completed
### Connection States
```mermaid
stateDiagram-v2
[*] --> DISCONNECTED
DISCONNECTED --> CONNECTING: Connect requested
CONNECTING --> CONNECTED: WebSocket established
CONNECTED --> AUTHENTICATING: Send credentials
AUTHENTICATING --> AUTHENTICATED: Auth successful
AUTHENTICATED --> CHANNEL_OPENING: Open SMTP channel
CHANNEL_OPENING --> CHANNEL_READY: Channel established
CHANNEL_READY --> CHANNEL_CLOSED: Session complete
CHANNEL_CLOSED --> AUTHENTICATED: Ready for next session
AUTHENTICATED --> DISCONNECTED: Queue empty
CONNECTING --> RECONNECTING: Connection failed
AUTHENTICATING --> RECONNECTING: Auth failed
CHANNEL_OPENING --> RECONNECTING: Channel failed
RECONNECTING --> CONNECTING: Retry attempt
RECONNECTING --> FAILED: Max retries reached
FAILED --> [*]: Shutdown
DISCONNECTED --> [*]: Shutdown
```
## 🔧 Session Queue Architecture
```mermaid
flowchart TD
subgraph Emails ["📧 Email Submission"]
E1[Email 1 - HIGH]
E2[Email 2 - NORMAL]
E3[Email 3 - HIGH]
E4[Email 4 - CRITICAL]
end
subgraph Queue ["📋 Session Creation"]
SQ[Session Queue]
S1[Session 1 - CRITICAL]
S2[Session 2 - HIGH]
S3[Session 3 - NORMAL]
end
subgraph Processing ["⚡ Session Processing"]
SP[Session Processor]
SC[SMTP Connection]
SM[Session Manager]
end
E1 --> SQ
E2 --> SQ
E3 --> SQ
E4 --> SQ
SQ --> S1
SQ --> S2
SQ --> S3
S1 --> SP
S2 --> SP
S3 --> SP
SP --> SC
SC --> SM
style S1 fill:#ffcdd2
style S2 fill:#fff3e0
style S3 fill:#e8f5e8
style SP fill:#e1f5fe
style SC fill:#f3e5f5
```
## 🏭 Production Configuration
### Optimal Settings
```typescript
const client = new SMTPOverWSClient({
url: 'wss://api.siwatsystem.com/smtp',
apiKey: process.env.MXRELAY_API_KEY,
// Production optimizations
debug: false,
maxEmailsPerSession: 20, // Batch more emails per session
sessionBatchTimeout: 5000, // Wait longer to accumulate emails
sessionTimeout: 600000, // 10 minute session timeout
maxQueueSize: 1000, // Higher queue capacity
reconnectInterval: 15000, // Longer reconnect delay
maxReconnectAttempts: 3, // Fewer retries in production
messageTimeout: 120000 // 2 minute SMTP timeout
});
```
### Graceful Shutdown
```typescript
process.on('SIGTERM', async () => {
console.log('Shutting down SMTP client...');
try {
// Wait for current sessions to complete
await client.shutdown(60000); // 60 second timeout
console.log('SMTP client shutdown complete');
} catch (error) {
console.error('Forced SMTP client shutdown');
}
process.exit(0);
});
```
## 📚 API Reference
### SMTPOverWSClient
#### Methods
- `queueEmail(from, to[], data, options?)` - Queue email for session processing
- `getStats()` - Get session and email statistics
- `getConnectionState()` - Get current connection state
- `getSessionState()` - Get current session processing state
- `getQueueSize()` - Get session queue size
- `shutdown(timeout?)` - Graceful shutdown with session completion
#### Events
- **Session Events**: `sessionQueued`, `sessionStarted`, `sessionCompleted`, `sessionFailed`
- **Email Events**: `emailProcessed`, `emailFailed`
- **Connection Events**: `connecting`, `connected`, `authenticated`, `disconnected`, `reconnecting`
- **Queue Events**: `queueProcessingStarted`, `queueProcessingCompleted`
- **State Events**: `stateChanged`, `error`
### createTransport(apiKey, options?)
Creates a Nodemailer-compatible transport with session batching.
- `apiKey` - Your API key for authentication
- `options` - Optional transport and session configuration
## 🔍 Debugging
### Enable Debug Logging
```typescript
const client = new SMTPOverWSClient({
url: 'wss://api.siwatsystem.com/smtp',
apiKey: 'your-api-key',
debug: true // Enable comprehensive logging
});
// Debug output includes:
// - Session creation and batching
// - SMTP protocol commands and responses
// - Connection state transitions
// - Queue processing details
// - Error stack traces
```
### Monitor Session Processing
```typescript
client.on('sessionStarted', (sessionId, emailCount) => {
console.log(`🚀 Starting session ${sessionId} with ${emailCount} emails`);
});
client.on('emailProcessed', (sessionId, emailId, responseTime) => {
console.log(`✅ Email ${emailId} processed in ${responseTime}ms`);
});
client.on('sessionCompleted', (sessionId, results) => {
const successful = results.filter(r => r.success).length;
const failed = results.filter(r => !r.success).length;
console.log(`🎉 Session ${sessionId} complete: ${successful} sent, ${failed} failed`);
});
```
## 🧪 Development
### Setup
```bash
# Clone repository
git clone https://git.siwatsystem.com/siwatsystem-public/mxrelay-consumer.git
cd mxrelay-consumer
# Install dependencies
bun install
# Run examples directly (TypeScript)
bun run examples/nodemailer-transport.ts
```
### Build & Test
```bash
# Build all formats
bun run build
# Run tests
bun test
# Run linting
bun run lint
# Format code
bun run format
```
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Issues**: [Git Repository Issues](https://git.siwatsystem.com/siwatsystem-public/mxrelay-consumer/issues)
- **Documentation**: [Project Repository](https://git.siwatsystem.com/siwatsystem-public/mxrelay-consumer)
---
**Built by SiwatSystem** | *Session-based SMTP over WebSocket*
Reference in a new issue View git blame Copy permalink