serve.zone/mailer
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat(storage): add comprehensive tests for StorageManager with memory, filesystem, and custom function backends
Some checks failed
CI / Type Check & Lint (push) Failing after 3s
Details
CI / Build Test (Current Platform) (push) Failing after 3s
Details
CI / Build All Platforms (push) Failing after 3s
Details

Browse Source 
feat(email): implement EmailSendJob class for robust email delivery with retry logic and MX record resolution

feat(mail): restructure mail module exports for simplified access to core and delivery functionalities
This commit is contained in:
Jürgen Kunz
2025-10-28 19:46:17 +00:00
parent 6523c55516
commit 17f5661636
271 changed files with 61736 additions and 6222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

894
test/readme.md
View File

@@ -1,503 +1,443 @@
# Mailer SMTP Test Suite (Deno)
Comprehensive SMTP server and client test suite ported from dcrouter to Deno-native testing.
## Test Framework
- **Framework**: Deno native testing (`Deno.test`)
- **Assertions**: `@std/assert` from Deno standard library
- **Run Command**: `deno test --allow-all --no-check test/`
- **Run Single Test**: `deno test --allow-all --no-check test/suite/smtpserver_commands/test.cmd-01.ehlo-command.test.ts`
## Test Infrastructure
### Helpers (`test/helpers/`)
- **`server.loader.ts`** - Test SMTP server lifecycle management
- Start/stop test servers with configurable options
- TLS certificate handling
- Mock email processing
- Port management utilities
- **`utils.ts`** - SMTP protocol test utilities
- TCP connection management (Deno-native)
- SMTP command sending/receiving
- Protocol handshake helpers
- MIME message creation
- Retry and timing utilities
- **`smtp.client.ts`** - SMTP client test utilities
- Test client creation with various configurations
- Email sending helpers
- Connection pooling testing
- Throughput measurement
### Fixtures (`test/fixtures/`)
- **`test-cert.pem`** - Self-signed certificate for TLS testing
- **`test-key.pem`** - Private key for TLS testing
## Test Suite Organization
All tests follow the naming convention: `test.<category-id>.<description>.test.ts`
### Test Categories
#### 1. Connection Management (CM) - `smtpserver_connection/`
Tests for SMTP connection handling, TLS support, and connection lifecycle.
| ID | Test | Priority | Status |
|----|------|----------|--------|
| **CM-01** | **TLS Connection** | **High** | **✅ PORTED** |
| CM-02 | Multiple Simultaneous Connections | High | Planned |
| CM-03 | Connection Timeout | High | Planned |
| CM-06 | STARTTLS Upgrade | High | Planned |
| CM-10 | Plain Connection | Low | Planned |
#### 2. SMTP Commands (CMD) - `smtpserver_commands/`
Tests for SMTP protocol command implementation.
| ID | Test | Priority | Status |
|----|------|----------|--------|
| **CMD-01** | **EHLO Command** | **High** | **✅ PORTED** |
| **CMD-02** | **MAIL FROM Command** | **High** | **✅ PORTED** |
| **CMD-03** | **RCPT TO Command** | **High** | **✅ PORTED** |
| **CMD-04** | **DATA Command** | **High** | **✅ PORTED** |
| **CMD-06** | **RSET Command** | **Medium** | **✅ PORTED** |
| **CMD-13** | **QUIT Command** | **High** | **✅ PORTED** |
#### 3. Email Processing (EP) - `smtpserver_email-processing/`
Tests for email content handling, parsing, and delivery.
| ID | Test | Priority | Status |
|----|------|----------|--------|
| **EP-01** | **Basic Email Sending** | **High** | **✅ PORTED** |
| EP-02 | Invalid Email Address Handling | High | Planned |
| EP-04 | Large Email Handling | High | Planned |
| EP-05 | MIME Handling | High | Planned |
#### 4. Security (SEC) - `smtpserver_security/`
Tests for security features and protections.
| ID | Test | Priority | Status |
|----|------|----------|--------|
| **SEC-01** | **Authentication** | **High** | **✅ PORTED** |
| SEC-03 | DKIM Processing | High | Planned |
| SEC-04 | SPF Checking | High | Planned |
| **SEC-06** | **IP Reputation Checking** | **High** | **✅ PORTED** |
| SEC-08 | Rate Limiting | High | Planned |
| SEC-10 | Header Injection Prevention | High | Planned |
#### 5. Error Handling (ERR) - `smtpserver_error-handling/`
Tests for proper error handling and recovery.
| ID | Test | Priority | Status |
|----|------|----------|--------|
| **ERR-01** | **Syntax Error Handling** | **High** | **✅ PORTED** |
| **ERR-02** | **Invalid Sequence Handling** | **High** | **✅ PORTED** |
| ERR-05 | Resource Exhaustion | High | Planned |
| ERR-07 | Exception Handling | High | Planned |
## Currently Ported Tests
### ✅ CMD-01: EHLO Command (`test.cmd-01.ehlo-command.test.ts`)
**Tests**: 5 total (5 passing)
- Server startup/shutdown
- EHLO response with proper capabilities
- Invalid hostname handling
- Command pipelining (multiple EHLO)
**Key validations**:
- ✓ Server advertises SIZE capability
- ✓ Server advertises 8BITMIME capability
- ✓ Last capability line uses "250 " (space, not hyphen)
- ✓ Server handles invalid hostnames gracefully
- ✓ Second EHLO resets session state
### ✅ CMD-02: MAIL FROM Command (`test.cmd-02.mail-from.test.ts`)
**Tests**: 6 total (6 passing)
- Valid sender address acceptance
- Invalid sender address rejection
- SIZE parameter support
- Command sequence enforcement
**Key validations**:
- ✓ Accepts valid email formats
- ✓ Accepts IP literals (user@[192.168.1.1])
- ✓ Rejects malformed addresses
- ✓ Supports SIZE parameter
- ✓ Enforces EHLO before MAIL FROM
### ✅ CMD-03: RCPT TO Command (`test.cmd-03.rcpt-to.test.ts`)
**Tests**: 7 total (7 passing)
- Valid recipient address acceptance
- Multiple recipients support
- Invalid recipient address rejection
- Command sequence enforcement
- RSET clears recipients
**Key validations**:
- ✓ Accepts valid recipient formats
- ✓ Accepts IP literals and subdomains
- ✓ Supports multiple recipients per transaction
- ✓ Rejects invalid email addresses
- ✓ Enforces RCPT TO after MAIL FROM
- ✓ RSET properly clears recipient list
### ✅ CMD-04: DATA Command (`test.cmd-04.data-command.test.ts`)
**Tests**: 7 total (7 passing)
- Email data transmission after RCPT TO
- Rejection without RCPT TO
- Dot-stuffing handling
- Large message support
- Command sequence enforcement
**Key validations**:
- ✓ Accepts email data with proper terminator
- ✓ Returns 354 to start data input
- ✓ Returns 250 after successful email acceptance
- ✓ Rejects DATA without MAIL FROM
- ✓ Handles dot-stuffed content correctly
- ✓ Supports large messages (10KB+)
### ✅ CMD-06: RSET Command (`test.cmd-06.rset-command.test.ts`)
**Tests**: 8 total (8 passing)
- RSET after MAIL FROM
- RSET after RCPT TO
- Multiple consecutive RSET commands
- RSET without active transaction
- RSET clears all recipients
- RSET with parameters (ignored)
**Key validations**:
- ✓ Responds with 250 OK
- ✓ Resets transaction state after MAIL FROM
- ✓ Clears recipients requiring new MAIL FROM
- ✓ Idempotent (multiple RSETs work)
- ✓ Works without active transaction
- ✓ Clears all recipients from transaction
- ✓ Ignores parameters as per RFC
### ✅ CMD-13: QUIT Command (`test.cmd-13.quit-command.test.ts`)
**Tests**: 7 total (7 passing)
- Graceful connection termination
- QUIT after MAIL FROM
- QUIT after complete transaction
- Idempotent QUIT handling
- Immediate QUIT without EHLO
**Key validations**:
- ✓ Returns 221 Service closing
- ✓ Works at any point in SMTP session
- ✓ Properly closes connection
- ✓ Handles multiple QUIT commands gracefully
- ✓ Allows immediate QUIT after greeting
### ✅ CM-01: TLS Connection (`test.cm-01.tls-connection.test.ts`)
**Tests**: 8 total (8 passing)
- Server advertises STARTTLS capability
- STARTTLS command initiates upgrade
- Direct TLS connection support
- STARTTLS not available after already started
- STARTTLS requires EHLO first
- Connection accepts commands after TLS
- Server lifecycle management
**Key validations**:
- ✓ STARTTLS advertised in EHLO capabilities
- ✓ STARTTLS command responds with 220 Ready
- ✓ Direct TLS connections work (with self-signed certs)
- ✓ Second STARTTLS properly rejected
- ✓ STARTTLS before EHLO handled correctly
- ✓ TLS upgrade process validated
### ✅ EP-01: Basic Email Sending (`test.ep-01.basic-email-sending.test.ts`)
**Tests**: 7 total (7 passing)
- Complete SMTP transaction flow (CONNECT → EHLO → MAIL FROM → RCPT TO → DATA → CONTENT → QUIT)
- Email with MIME attachment (multipart/mixed)
- HTML email (multipart/alternative)
- Email with custom headers (X-Custom-Header, X-Priority, Reply-To, etc.)
- Minimal email (body only, no headers)
- Server lifecycle management
**Key validations**:
- ✓ Complete email lifecycle from greeting to QUIT
- ✓ MIME multipart messages with attachments
- ✓ HTML email with plain text fallback
- ✓ Custom header support (X-*, Reply-To, Organization)
- ✓ Minimal email content accepted
- ✓ Email queuing and processing confirmed
### ✅ SEC-06: IP Reputation Checking (`test.sec-06.ip-reputation.test.ts`)
**Tests**: 7 total (7 passing)
- IP reputation check accepts localhost connections
- Known good senders accepted
- Multiple connections from same IP handled
- Complete SMTP flow with reputation check
- Infrastructure placeholder test
- Server lifecycle management
**Key validations**:
- ✓ IP reputation infrastructure in place
- ✓ Localhost connections accepted after reputation check
- ✓ Legitimate senders and recipients accepted
- ✓ Multiple concurrent connections handled properly
- ✓ Complete email transaction works with IP checks
- ✓ IPReputationChecker class exists (placeholder implementation)
**Note**: Current implementation uses placeholder IP reputation checker that accepts all legitimate traffic. Infrastructure is ready for future implementation of real IP reputation databases, blacklist checking, and suspicious pattern detection.
### ✅ ERR-01: Syntax Error Handling (`test.err-01.syntax-errors.test.ts`)
**Tests**: 10 total (10 passing)
- Rejects invalid commands
- Rejects MAIL FROM without brackets
- Rejects RCPT TO without brackets
- Rejects EHLO without hostname
- Handles commands with extra parameters
- Rejects malformed email addresses
- Rejects commands in wrong sequence
- Handles excessively long commands
- Server lifecycle management
**Key validations**:
- ✓ Invalid commands rejected with 500/502 error codes
- ✓ MAIL FROM requires angle brackets (501 error if missing)
- ✓ RCPT TO requires angle brackets (501 error if missing)
- ✓ EHLO requires hostname parameter (501 error if missing)
- ✓ Extra parameters on QUIT handled (501 syntax error)
- ✓ Malformed email addresses rejected (501 error)
- ✓ Commands in wrong sequence rejected (503 error)
- ✓ Excessively long commands handled gracefully
### ✅ ERR-02: Invalid Sequence Handling (`test.err-02.invalid-sequence.test.ts`)
**Tests**: 10 total (10 passing)
- Rejects MAIL FROM before EHLO
- Rejects RCPT TO before MAIL FROM
- Rejects DATA before RCPT TO (RFC 5321 compliance)
- Allows multiple EHLO commands
- Handles second MAIL FROM without RSET
- Rejects DATA without MAIL FROM
- Handles commands after QUIT
- Recovers from syntax errors in sequence
- Server lifecycle management
**Key validations**:
- ✓ MAIL FROM requires EHLO first (503 error if missing)
- ✓ RCPT TO requires MAIL FROM first (503 error if missing)
- ✓ DATA requires RCPT TO with at least one recipient (503 error if missing)
- ✓ Multiple EHLO commands allowed (resets session state)
- ✓ Commands after QUIT handled correctly (connection closed)
- ✓ Session recovers from syntax errors without terminating
- ✓ RFC 5321 compliance: strict command sequence enforcement
## Running Tests
### Run All Tests
# DCRouter SMTP Test Suite
```
test/
├── readme.md # This file
├── helpers/
│ ├── server.loader.ts # SMTP server lifecycle management
│ ├── utils.ts # Common test utilities
│ └── smtp.client.ts # Test SMTP client utilities
└── suite/
├── smtpserver_commands/ # SMTP command tests (CMD)
├── smtpserver_connection/ # Connection management tests (CM)
├── smtpserver_edge-cases/ # Edge case tests (EDGE)
├── smtpserver_email-processing/ # Email processing tests (EP)
├── smtpserver_error-handling/ # Error handling tests (ERR)
├── smtpserver_performance/ # Performance tests (PERF)
├── smtpserver_reliability/ # Reliability tests (REL)
├── smtpserver_rfc-compliance/ # RFC compliance tests (RFC)
└── smtpserver_security/ # Security tests (SEC)
```
## Test ID Convention
All test files follow a strict naming convention: `test.<category-id>.<description>.ts`
Examples:
- `test.cmd-01.ehlo-command.ts` - EHLO command test
- `test.cm-01.tls-connection.ts` - TLS connection test
- `test.sec-01.authentication.ts` - Authentication test
## Test Categories
### 1. Connection Management (CM)
Tests for validating SMTP connection handling, TLS support, and connection lifecycle management.
| ID | Test Description | Priority | Implementation |
|-------|-------------------------------------------|----------|----------------|
| CM-01 | TLS Connection Test | High | `suite/smtpserver_connection/test.cm-01.tls-connection.ts` |
| CM-02 | Multiple Simultaneous Connections | High | `suite/smtpserver_connection/test.cm-02.multiple-connections.ts` |
| CM-03 | Connection Timeout | High | `suite/smtpserver_connection/test.cm-03.connection-timeout.ts` |
| CM-04 | Connection Limits | Medium | `suite/smtpserver_connection/test.cm-04.connection-limits.ts` |
| CM-05 | Connection Rejection | Medium | `suite/smtpserver_connection/test.cm-05.connection-rejection.ts` |
| CM-06 | STARTTLS Connection Upgrade | High | `suite/smtpserver_connection/test.cm-06.starttls-upgrade.ts` |
| CM-07 | Abrupt Client Disconnection | Medium | `suite/smtpserver_connection/test.cm-07.abrupt-disconnection.ts` |
| CM-08 | TLS Version Compatibility | Medium | `suite/smtpserver_connection/test.cm-08.tls-versions.ts` |
| CM-09 | TLS Cipher Configuration | Medium | `suite/smtpserver_connection/test.cm-09.tls-ciphers.ts` |
| CM-10 | Plain Connection Test | Low | `suite/smtpserver_connection/test.cm-10.plain-connection.ts` |
| CM-11 | TCP Keep-Alive Test | Low | `suite/smtpserver_connection/test.cm-11.keepalive.ts` |
### 2. SMTP Commands (CMD)
Tests for validating proper SMTP protocol command implementation.
| ID | Test Description | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| CMD-01 | EHLO Command | High | `suite/smtpserver_commands/test.cmd-01.ehlo-command.ts` |
| CMD-02 | MAIL FROM Command | High | `suite/smtpserver_commands/test.cmd-02.mail-from.ts` |
| CMD-03 | RCPT TO Command | High | `suite/smtpserver_commands/test.cmd-03.rcpt-to.ts` |
| CMD-04 | DATA Command | High | `suite/smtpserver_commands/test.cmd-04.data-command.ts` |
| CMD-05 | NOOP Command | Medium | `suite/smtpserver_commands/test.cmd-05.noop-command.ts` |
| CMD-06 | RSET Command | Medium | `suite/smtpserver_commands/test.cmd-06.rset-command.ts` |
| CMD-07 | VRFY Command | Low | `suite/smtpserver_commands/test.cmd-07.vrfy-command.ts` |
| CMD-08 | EXPN Command | Low | `suite/smtpserver_commands/test.cmd-08.expn-command.ts` |
| CMD-09 | SIZE Extension | Medium | `suite/smtpserver_commands/test.cmd-09.size-extension.ts` |
| CMD-10 | HELP Command | Low | `suite/smtpserver_commands/test.cmd-10.help-command.ts` |
| CMD-11 | Command Pipelining | Medium | `suite/smtpserver_commands/test.cmd-11.command-pipelining.ts` |
| CMD-12 | HELO Command | Low | `suite/smtpserver_commands/test.cmd-12.helo-command.ts` |
| CMD-13 | QUIT Command | High | `suite/smtpserver_commands/test.cmd-13.quit-command.ts` |
### 3. Email Processing (EP)
Tests for validating email content handling, parsing, and delivery.
| ID | Test Description | Priority | Implementation |
|-------|-------------------------------------------|----------|----------------|
| EP-01 | Basic Email Sending | High | `suite/smtpserver_email-processing/test.ep-01.basic-email-sending.ts` |
| EP-02 | Invalid Email Address Handling | High | `suite/smtpserver_email-processing/test.ep-02.invalid-email-addresses.ts` |
| EP-03 | Multiple Recipients | Medium | `suite/smtpserver_email-processing/test.ep-03.multiple-recipients.ts` |
| EP-04 | Large Email Handling | High | `suite/smtpserver_email-processing/test.ep-04.large-email.ts` |
| EP-05 | MIME Handling | High | `suite/smtpserver_email-processing/test.ep-05.mime-handling.ts` |
| EP-06 | Attachment Handling | Medium | `suite/smtpserver_email-processing/test.ep-06.attachment-handling.ts` |
| EP-07 | Special Character Handling | Medium | `suite/smtpserver_email-processing/test.ep-07.special-character-handling.ts` |
| EP-08 | Email Routing | High | `suite/smtpserver_email-processing/test.ep-08.email-routing.ts` |
| EP-09 | Delivery Status Notifications | Medium | `suite/smtpserver_email-processing/test.ep-09.delivery-status-notifications.ts` |
### 4. Security (SEC)
Tests for validating security features and protections.
| ID | Test Description | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| SEC-01 | Authentication | High | `suite/smtpserver_security/test.sec-01.authentication.ts` |
| SEC-02 | Authorization | High | `suite/smtpserver_security/test.sec-02.authorization.ts` |
| SEC-03 | DKIM Processing | High | `suite/smtpserver_security/test.sec-03.dkim-processing.ts` |
| SEC-04 | SPF Checking | High | `suite/smtpserver_security/test.sec-04.spf-checking.ts` |
| SEC-05 | DMARC Policy Enforcement | Medium | `suite/smtpserver_security/test.sec-05.dmarc-policy.ts` |
| SEC-06 | IP Reputation Checking | High | `suite/smtpserver_security/test.sec-06.ip-reputation.ts` |
| SEC-07 | Content Scanning | Medium | `suite/smtpserver_security/test.sec-07.content-scanning.ts` |
| SEC-08 | Rate Limiting | High | `suite/smtpserver_security/test.sec-08.rate-limiting.ts` |
| SEC-09 | TLS Certificate Validation | High | `suite/smtpserver_security/test.sec-09.tls-certificate-validation.ts` |
| SEC-10 | Header Injection Prevention | High | `suite/smtpserver_security/test.sec-10.header-injection-prevention.ts` |
| SEC-11 | Bounce Management | Medium | `suite/smtpserver_security/test.sec-11.bounce-management.ts` |
### 5. Error Handling (ERR)
Tests for validating proper error handling and recovery.
| ID | Test Description | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| ERR-01 | Syntax Error Handling | High | `suite/smtpserver_error-handling/test.err-01.syntax-errors.ts` |
| ERR-02 | Invalid Sequence Handling | High | `suite/smtpserver_error-handling/test.err-02.invalid-sequence.ts` |
| ERR-03 | Temporary Failure Handling | Medium | `suite/smtpserver_error-handling/test.err-03.temporary-failures.ts` |
| ERR-04 | Permanent Failure Handling | Medium | `suite/smtpserver_error-handling/test.err-04.permanent-failures.ts` |
| ERR-05 | Resource Exhaustion Handling | High | `suite/smtpserver_error-handling/test.err-05.resource-exhaustion.ts` |
| ERR-06 | Malformed MIME Handling | Medium | `suite/smtpserver_error-handling/test.err-06.malformed-mime.ts` |
| ERR-07 | Exception Handling | High | `suite/smtpserver_error-handling/test.err-07.exception-handling.ts` |
| ERR-08 | Error Logging | Medium | `suite/smtpserver_error-handling/test.err-08.error-logging.ts` |
### 6. Performance (PERF)
Tests for validating performance characteristics and benchmarks.
| ID | Test Description | Priority | Implementation |
|---------|------------------------------------------|----------|----------------|
| PERF-01 | Throughput Testing | Medium | `suite/smtpserver_performance/test.perf-01.throughput.ts` |
| PERF-02 | Concurrency Testing | High | `suite/smtpserver_performance/test.perf-02.concurrency.ts` |
| PERF-03 | CPU Utilization | Medium | `suite/smtpserver_performance/test.perf-03.cpu-utilization.ts` |
| PERF-04 | Memory Usage | Medium | `suite/smtpserver_performance/test.perf-04.memory-usage.ts` |
| PERF-05 | Connection Processing Time | Medium | `suite/smtpserver_performance/test.perf-05.connection-processing-time.ts` |
| PERF-06 | Message Processing Time | Medium | `suite/smtpserver_performance/test.perf-06.message-processing-time.ts` |
| PERF-07 | Resource Cleanup | High | `suite/smtpserver_performance/test.perf-07.resource-cleanup.ts` |
### 7. Reliability (REL)
Tests for validating system reliability and stability.
| ID | Test Description | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| REL-01 | Long-Running Operation | High | `suite/smtpserver_reliability/test.rel-01.long-running-operation.ts` |
| REL-02 | Restart Recovery | High | `suite/smtpserver_reliability/test.rel-02.restart-recovery.ts` |
| REL-03 | Resource Leak Detection | High | `suite/smtpserver_reliability/test.rel-03.resource-leak-detection.ts` |
| REL-04 | Error Recovery | High | `suite/smtpserver_reliability/test.rel-04.error-recovery.ts` |
| REL-05 | DNS Resolution Failure Handling | Medium | `suite/smtpserver_reliability/test.rel-05.dns-resolution-failure.ts` |
| REL-06 | Network Interruption Handling | Medium | `suite/smtpserver_reliability/test.rel-06.network-interruption.ts` |
### 8. Edge Cases (EDGE)
Tests for validating handling of unusual or extreme scenarios.
| ID | Test Description | Priority | Implementation |
|---------|-------------------------------------------|----------|----------------|
| EDGE-01 | Very Large Email | Low | `suite/smtpserver_edge-cases/test.edge-01.very-large-email.ts` |
| EDGE-02 | Very Small Email | Low | `suite/smtpserver_edge-cases/test.edge-02.very-small-email.ts` |
| EDGE-03 | Invalid Character Handling | Medium | `suite/smtpserver_edge-cases/test.edge-03.invalid-character-handling.ts` |
| EDGE-04 | Empty Commands | Low | `suite/smtpserver_edge-cases/test.edge-04.empty-commands.ts` |
| EDGE-05 | Extremely Long Lines | Medium | `suite/smtpserver_edge-cases/test.edge-05.extremely-long-lines.ts` |
| EDGE-06 | Extremely Long Headers | Medium | `suite/smtpserver_edge-cases/test.edge-06.extremely-long-headers.ts` |
| EDGE-07 | Unusual MIME Types | Low | `suite/smtpserver_edge-cases/test.edge-07.unusual-mime-types.ts` |
| EDGE-08 | Nested MIME Structures | Low | `suite/smtpserver_edge-cases/test.edge-08.nested-mime-structures.ts` |
### 9. RFC Compliance (RFC)
Tests for validating compliance with SMTP-related RFCs.
| ID | Test Description | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| RFC-01 | RFC 5321 Compliance | High | `suite/smtpserver_rfc-compliance/test.rfc-01.rfc5321-compliance.ts` |
| RFC-02 | RFC 5322 Compliance | High | `suite/smtpserver_rfc-compliance/test.rfc-02.rfc5322-compliance.ts` |
| RFC-03 | RFC 7208 SPF Compliance | Medium | `suite/smtpserver_rfc-compliance/test.rfc-03.rfc7208-spf-compliance.ts` |
| RFC-04 | RFC 6376 DKIM Compliance | Medium | `suite/smtpserver_rfc-compliance/test.rfc-04.rfc6376-dkim-compliance.ts` |
| RFC-05 | RFC 7489 DMARC Compliance | Medium | `suite/smtpserver_rfc-compliance/test.rfc-05.rfc7489-dmarc-compliance.ts` |
| RFC-06 | RFC 8314 TLS Compliance | Medium | `suite/smtpserver_rfc-compliance/test.rfc-06.rfc8314-tls-compliance.ts` |
| RFC-07 | RFC 3461 DSN Compliance | Low | `suite/smtpserver_rfc-compliance/test.rfc-07.rfc3461-dsn-compliance.ts` |
## SMTP Client Test Suite
The following test categories ensure our SMTP client is production-ready, RFC-compliant, and handles all real-world scenarios properly.
### Client Test Organization
```
test/
└── suite/
├── smtpclient_connection/ # Client connection management tests (CCM)
├── smtpclient_commands/ # Client command execution tests (CCMD)
├── smtpclient_email-composition/ # Email composition tests (CEP)
├── smtpclient_security/ # Client security tests (CSEC)
├── smtpclient_error-handling/ # Client error handling tests (CERR)
├── smtpclient_performance/ # Client performance tests (CPERF)
├── smtpclient_reliability/ # Client reliability tests (CREL)
├── smtpclient_edge-cases/ # Client edge case tests (CEDGE)
└── smtpclient_rfc-compliance/ # Client RFC compliance tests (CRFC)
```
### 10. Client Connection Management (CCM)
Tests for validating how the SMTP client establishes and manages connections to servers.
| ID | Test Description | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| CCM-01 | Basic TCP Connection | High | `suite/smtpclient_connection/test.ccm-01.basic-tcp-connection.ts` |
| CCM-02 | TLS Connection Establishment | High | `suite/smtpclient_connection/test.ccm-02.tls-connection.ts` |
| CCM-03 | STARTTLS Upgrade | High | `suite/smtpclient_connection/test.ccm-03.starttls-upgrade.ts` |
| CCM-04 | Connection Pooling | High | `suite/smtpclient_connection/test.ccm-04.connection-pooling.ts` |
| CCM-05 | Connection Reuse | Medium | `suite/smtpclient_connection/test.ccm-05.connection-reuse.ts` |
| CCM-06 | Connection Timeout Handling | High | `suite/smtpclient_connection/test.ccm-06.connection-timeout.ts` |
| CCM-07 | Automatic Reconnection | High | `suite/smtpclient_connection/test.ccm-07.automatic-reconnection.ts` |
| CCM-08 | DNS Resolution & MX Records | High | `suite/smtpclient_connection/test.ccm-08.dns-mx-resolution.ts` |
| CCM-09 | IPv4/IPv6 Dual Stack Support | Medium | `suite/smtpclient_connection/test.ccm-09.dual-stack-support.ts` |
| CCM-10 | Proxy Support (SOCKS/HTTP) | Low | `suite/smtpclient_connection/test.ccm-10.proxy-support.ts` |
| CCM-11 | Keep-Alive Management | Medium | `suite/smtpclient_connection/test.ccm-11.keepalive-management.ts` |
### 11. Client Command Execution (CCMD)
Tests for validating how the client sends SMTP commands and processes responses.
| ID | Test Description | Priority | Implementation |
|---------|-------------------------------------------|----------|----------------|
| CCMD-01 | EHLO/HELO Command Sending | High | `suite/smtpclient_commands/test.ccmd-01.ehlo-helo-sending.ts` |
| CCMD-02 | MAIL FROM Command with Parameters | High | `suite/smtpclient_commands/test.ccmd-02.mail-from-parameters.ts` |
| CCMD-03 | RCPT TO Command with Multiple Recipients | High | `suite/smtpclient_commands/test.ccmd-03.rcpt-to-multiple.ts` |
| CCMD-04 | DATA Command and Content Transmission | High | `suite/smtpclient_commands/test.ccmd-04.data-transmission.ts` |
| CCMD-05 | AUTH Command (LOGIN, PLAIN, CRAM-MD5) | High | `suite/smtpclient_commands/test.ccmd-05.auth-mechanisms.ts` |
| CCMD-06 | Command Pipelining | Medium | `suite/smtpclient_commands/test.ccmd-06.command-pipelining.ts` |
| CCMD-07 | Response Code Parsing | High | `suite/smtpclient_commands/test.ccmd-07.response-parsing.ts` |
| CCMD-08 | Extended Response Handling | Medium | `suite/smtpclient_commands/test.ccmd-08.extended-responses.ts` |
| CCMD-09 | QUIT Command and Graceful Disconnect | High | `suite/smtpclient_commands/test.ccmd-09.quit-disconnect.ts` |
| CCMD-10 | RSET Command Usage | Medium | `suite/smtpclient_commands/test.ccmd-10.rset-usage.ts` |
| CCMD-11 | NOOP Keep-Alive | Low | `suite/smtpclient_commands/test.ccmd-11.noop-keepalive.ts` |
### 12. Client Email Composition (CEP)
Tests for validating email composition, formatting, and encoding.
| ID | Test Description | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| CEP-01 | Basic Email Headers | High | `suite/smtpclient_email-composition/test.cep-01.basic-headers.ts` |
| CEP-02 | MIME Multipart Messages | High | `suite/smtpclient_email-composition/test.cep-02.mime-multipart.ts` |
| CEP-03 | Attachment Encoding | High | `suite/smtpclient_email-composition/test.cep-03.attachment-encoding.ts` |
| CEP-04 | UTF-8 and International Characters | High | `suite/smtpclient_email-composition/test.cep-04.utf8-international.ts` |
| CEP-05 | Base64 and Quoted-Printable Encoding | Medium | `suite/smtpclient_email-composition/test.cep-05.content-encoding.ts` |
| CEP-06 | HTML Email with Inline Images | Medium | `suite/smtpclient_email-composition/test.cep-06.html-inline-images.ts` |
| CEP-07 | Custom Headers | Low | `suite/smtpclient_email-composition/test.cep-07.custom-headers.ts` |
| CEP-08 | Message-ID Generation | Medium | `suite/smtpclient_email-composition/test.cep-08.message-id.ts` |
| CEP-09 | Date Header Formatting | Medium | `suite/smtpclient_email-composition/test.cep-09.date-formatting.ts` |
| CEP-10 | Line Length Limits (RFC 5322) | High | `suite/smtpclient_email-composition/test.cep-10.line-length-limits.ts` |
### 13. Client Security (CSEC)
Tests for client-side security features and protections.
| ID | Test Description | Priority | Implementation |
|---------|-------------------------------------------|----------|----------------|
| CSEC-01 | TLS Certificate Verification | High | `suite/smtpclient_security/test.csec-01.tls-verification.ts` |
| CSEC-02 | Authentication Mechanisms | High | `suite/smtpclient_security/test.csec-02.auth-mechanisms.ts` |
| CSEC-03 | OAuth2 Support | Medium | `suite/smtpclient_security/test.csec-03.oauth2-support.ts` |
| CSEC-04 | Password Security (No Plaintext) | High | `suite/smtpclient_security/test.csec-04.password-security.ts` |
| CSEC-05 | DKIM Signing | High | `suite/smtpclient_security/test.csec-05.dkim-signing.ts` |
| CSEC-06 | SPF Record Compliance | Medium | `suite/smtpclient_security/test.csec-06.spf-compliance.ts` |
| CSEC-07 | Secure Credential Storage | High | `suite/smtpclient_security/test.csec-07.credential-storage.ts` |
| CSEC-08 | TLS Version Enforcement | High | `suite/smtpclient_security/test.csec-08.tls-version-enforcement.ts` |
| CSEC-09 | Certificate Pinning | Low | `suite/smtpclient_security/test.csec-09.certificate-pinning.ts` |
| CSEC-10 | Injection Attack Prevention | High | `suite/smtpclient_security/test.csec-10.injection-prevention.ts` |
### 14. Client Error Handling (CERR)
Tests for how the client handles various error conditions.
| ID | Test Description | Priority | Implementation |
|---------|-------------------------------------------|----------|----------------|
| CERR-01 | 4xx Error Response Handling | High | `suite/smtpclient_error-handling/test.cerr-01.4xx-errors.ts` |
| CERR-02 | 5xx Error Response Handling | High | `suite/smtpclient_error-handling/test.cerr-02.5xx-errors.ts` |
| CERR-03 | Network Failure Recovery | High | `suite/smtpclient_error-handling/test.cerr-03.network-failures.ts` |
| CERR-04 | Timeout Recovery | High | `suite/smtpclient_error-handling/test.cerr-04.timeout-recovery.ts` |
| CERR-05 | Retry Logic with Backoff | High | `suite/smtpclient_error-handling/test.cerr-05.retry-backoff.ts` |
| CERR-06 | Greylisting Handling | Medium | `suite/smtpclient_error-handling/test.cerr-06.greylisting.ts` |
| CERR-07 | Rate Limit Response Handling | High | `suite/smtpclient_error-handling/test.cerr-07.rate-limits.ts` |
| CERR-08 | Malformed Server Response | Medium | `suite/smtpclient_error-handling/test.cerr-08.malformed-responses.ts` |
| CERR-09 | Connection Drop During Transfer | High | `suite/smtpclient_error-handling/test.cerr-09.connection-drops.ts` |
| CERR-10 | Authentication Failure Handling | High | `suite/smtpclient_error-handling/test.cerr-10.auth-failures.ts` |
### 15. Client Performance (CPERF)
Tests for client performance characteristics and optimization.
| ID | Test Description | Priority | Implementation |
|----------|-------------------------------------------|----------|----------------|
| CPERF-01 | Bulk Email Sending | High | `suite/smtpclient_performance/test.cperf-01.bulk-sending.ts` |
| CPERF-02 | Connection Pool Efficiency | High | `suite/smtpclient_performance/test.cperf-02.pool-efficiency.ts` |
| CPERF-03 | Memory Usage Under Load | High | `suite/smtpclient_performance/test.cperf-03.memory-usage.ts` |
| CPERF-04 | CPU Usage Optimization | Medium | `suite/smtpclient_performance/test.cperf-04.cpu-optimization.ts` |
| CPERF-05 | Parallel Sending Performance | High | `suite/smtpclient_performance/test.cperf-05.parallel-sending.ts` |
| CPERF-06 | Large Attachment Handling | Medium | `suite/smtpclient_performance/test.cperf-06.large-attachments.ts` |
| CPERF-07 | Queue Management | High | `suite/smtpclient_performance/test.cperf-07.queue-management.ts` |
| CPERF-08 | DNS Caching Efficiency | Medium | `suite/smtpclient_performance/test.cperf-08.dns-caching.ts` |
### 16. Client Reliability (CREL)
Tests for client reliability and resilience.
| ID | Test Description | Priority | Implementation |
|---------|-------------------------------------------|----------|----------------|
| CREL-01 | Long Running Stability | High | `suite/smtpclient_reliability/test.crel-01.long-running.ts` |
| CREL-02 | Failover to Backup MX | High | `suite/smtpclient_reliability/test.crel-02.mx-failover.ts` |
| CREL-03 | Queue Persistence | High | `suite/smtpclient_reliability/test.crel-03.queue-persistence.ts` |
| CREL-04 | Crash Recovery | High | `suite/smtpclient_reliability/test.crel-04.crash-recovery.ts` |
| CREL-05 | Memory Leak Prevention | High | `suite/smtpclient_reliability/test.crel-05.memory-leaks.ts` |
| CREL-06 | Concurrent Operation Safety | High | `suite/smtpclient_reliability/test.crel-06.concurrency-safety.ts` |
| CREL-07 | Resource Cleanup | Medium | `suite/smtpclient_reliability/test.crel-07.resource-cleanup.ts` |
### 17. Client Edge Cases (CEDGE)
Tests for unusual scenarios and edge cases.
| ID | Test Description | Priority | Implementation |
|----------|-------------------------------------------|----------|----------------|
| CEDGE-01 | Extremely Slow Server Response | Medium | `suite/smtpclient_edge-cases/test.cedge-01.slow-server.ts` |
| CEDGE-02 | Server Sending Invalid UTF-8 | Low | `suite/smtpclient_edge-cases/test.cedge-02.invalid-utf8.ts` |
| CEDGE-03 | Extremely Large Recipients List | Medium | `suite/smtpclient_edge-cases/test.cedge-03.large-recipient-list.ts` |
| CEDGE-04 | Zero-Byte Attachments | Low | `suite/smtpclient_edge-cases/test.cedge-04.zero-byte-attachments.ts` |
| CEDGE-05 | Server Disconnect Mid-Command | High | `suite/smtpclient_edge-cases/test.cedge-05.mid-command-disconnect.ts` |
| CEDGE-06 | Unusual Server Banners | Low | `suite/smtpclient_edge-cases/test.cedge-06.unusual-banners.ts` |
| CEDGE-07 | Non-Standard Port Connections | Medium | `suite/smtpclient_edge-cases/test.cedge-07.non-standard-ports.ts` |
### 18. Client RFC Compliance (CRFC)
Tests for RFC compliance from the client perspective.
| ID | Test Description | Priority | Implementation |
|---------|-------------------------------------------|----------|----------------|
| CRFC-01 | RFC 5321 Client Requirements | High | `suite/smtpclient_rfc-compliance/test.crfc-01.rfc5321-client.ts` |
| CRFC-02 | RFC 5322 Message Format | High | `suite/smtpclient_rfc-compliance/test.crfc-02.rfc5322-format.ts` |
| CRFC-03 | RFC 2045-2049 MIME Compliance | High | `suite/smtpclient_rfc-compliance/test.crfc-03.mime-compliance.ts` |
| CRFC-04 | RFC 4954 AUTH Extension | High | `suite/smtpclient_rfc-compliance/test.crfc-04.auth-extension.ts` |
| CRFC-05 | RFC 3207 STARTTLS | High | `suite/smtpclient_rfc-compliance/test.crfc-05.starttls.ts` |
| CRFC-06 | RFC 1870 SIZE Extension | Medium | `suite/smtpclient_rfc-compliance/test.crfc-06.size-extension.ts` |
| CRFC-07 | RFC 6152 8BITMIME Extension | Medium | `suite/smtpclient_rfc-compliance/test.crfc-07.8bitmime.ts` |
| CRFC-08 | RFC 2920 Command Pipelining | Medium | `suite/smtpclient_rfc-compliance/test.crfc-08.pipelining.ts` |
## Running SMTP Client Tests
### Run All Client Tests
```bash
deno test --allow-all --no-check test/
cd dcrouter
pnpm test test/suite/smtpclient_*
```
### Run Specific Category
### Run Specific Client Test Category
```bash
# SMTP commands tests
deno test --allow-all --no-check test/suite/smtpserver_commands/
# Run all client connection tests
pnpm test test/suite/smtpclient_connection
# Connection tests
deno test --allow-all --no-check test/suite/smtpserver_connection/
# Run all client security tests
pnpm test test/suite/smtpclient_security
```
### Run Single Test File
### Run Single Client Test File
```bash
deno test --allow-all --no-check test/suite/smtpserver_commands/test.cmd-01.ehlo-command.test.ts
# Run basic TCP connection test
tsx test/suite/smtpclient_connection/test.ccm-01.basic-tcp-connection.ts
# Run AUTH mechanisms test
tsx test/suite/smtpclient_commands/test.ccmd-05.auth-mechanisms.ts
```
### Run with Verbose Output
```bash
deno test --allow-all --no-check --trace-leaks test/
```
## Client Performance Benchmarks
## Test Development Guidelines
Expected performance metrics for production-ready SMTP client:
- **Sending Rate**: >100 emails per second (with connection pooling)
- **Connection Pool Size**: 10-50 concurrent connections efficiently managed
- **Memory Usage**: <500MB for 1000 concurrent email operations
- **DNS Cache Hit Rate**: >90% for repeated domains
- **Retry Success Rate**: >95% for temporary failures
- **Large Attachment Support**: Files up to 25MB without performance degradation
- **Queue Processing**: >1000 emails/minute with persistent queue
### Writing New Tests
## Client Security Requirements
1. **Use Deno.test() format**:
```typescript
Deno.test({
name: 'CMD-XX: Description of test',
async fn() {
// Test implementation
},
sanitizeResources: false, // Required for network tests
sanitizeOps: false, // Required for network tests
});
```
All client security tests must pass for production deployment:
- **TLS Support**: TLS 1.2+ required, TLS 1.3 preferred
- **Authentication**: Support for LOGIN, PLAIN, CRAM-MD5, OAuth2
- **Certificate Validation**: Proper certificate chain validation
- **DKIM Signing**: Automatic DKIM signature generation
- **Credential Security**: No plaintext password storage
- **Injection Prevention**: Protection against header/command injection
2. **Import assertions from @std/assert**:
```typescript
import { assert, assertEquals, assertMatch } from '@std/assert';
```
## Client Production Readiness Criteria
3. **Use test helpers**:
```typescript
import { startTestServer, stopTestServer } from '../../helpers/server.loader.ts';
import { connectToSmtp, sendSmtpCommand } from '../../helpers/utils.ts';
```
### Production Gate 1: Core Functionality (>95% tests passing)
- Basic connection establishment
- Command execution and response parsing
- Email composition and sending
- Error handling and recovery
4. **Always cleanup**:
- Close connections with `closeSmtpConnection()` or `conn.close()`
- Stop test servers with `stopTestServer()`
- Use try/finally blocks for guaranteed cleanup
5. **Test isolation**:
- Each test file uses its own port (e.g., CMD-01 uses 25251, CMD-02 uses 25252)
- Setup and cleanup tests ensure clean state
## Key Differences from dcrouter Tests
### Framework
- **Before**: `@git.zone/tstest/tapbundle` (Node.js)
- **After**: Deno.test (native)
### Assertions
- **Before**: `expect(x).toBeTruthy()`, `expect(x).toEqual(y)`
- **After**: `assert(x)`, `assertEquals(x, y)`, `assertMatch(x, regex)`
### Network I/O
- **Before**: Node.js `net` module
- **After**: Deno `Deno.connect()` / `Deno.listen()`
### Imports
- **Before**: `.js` extensions, Node-style imports
- **After**: `.ts` extensions, Deno-style imports
## Test Priorities
### Phase 1: Core SMTP Functionality (High Priority) ✅ **COMPLETE**
- ✅ CMD-01: EHLO Command
- ✅ CMD-02: MAIL FROM Command
- ✅ CMD-03: RCPT TO Command
- ✅ CMD-04: DATA Command
- ✅ CMD-13: QUIT Command
- ✅ CM-01: TLS Connection
- ✅ EP-01: Basic Email Sending
### Phase 2: Security & Validation (High Priority)
- 🔄 SEC-01: Authentication
- ✅ SEC-06: IP Reputation
- 🔄 SEC-08: Rate Limiting
- 🔄 SEC-10: Header Injection Prevention
- ✅ ERR-01: Syntax Error Handling
- ✅ ERR-02: Invalid Sequence Handling
### Phase 3: Advanced Features (Medium Priority)
- 🔄 SEC-03: DKIM Processing
- 🔄 SEC-04: SPF Checking
- 🔄 EP-04: Large Email Handling
- 🔄 EP-05: MIME Handling
- 🔄 CM-02: Multiple Connections
- 🔄 CM-06: STARTTLS Upgrade
### Phase 4: Complete Coverage (All Remaining)
- All performance tests
- All reliability tests
- All edge case tests
- All RFC compliance tests
- SMTP client tests
## Current Status
**Infrastructure**: ✅ Complete
- Deno-native test helpers (utils.ts, server.loader.ts, smtp.client.ts)
- Server lifecycle management
- SMTP protocol utilities with readSmtpResponse helper
- Test certificates (self-signed RSA)
**Tests Ported**: 11/100+ test files (82 total tests passing)
- ✅ CMD-01: EHLO Command (5 tests passing)
- ✅ CMD-02: MAIL FROM Command (6 tests passing)
- ✅ CMD-03: RCPT TO Command (7 tests passing)
- ✅ CMD-04: DATA Command (7 tests passing)
- ✅ CMD-06: RSET Command (8 tests passing)
- ✅ CMD-13: QUIT Command (7 tests passing)
- ✅ CM-01: TLS Connection (8 tests passing)
- ✅ EP-01: Basic Email Sending (7 tests passing)
- ✅ SEC-06: IP Reputation Checking (7 tests passing)
- ✅ ERR-01: Syntax Error Handling (10 tests passing)
- ✅ ERR-02: Invalid Sequence Handling (10 tests passing)
**Coverage**: Complete essential SMTP transaction flow
- EHLO → MAIL FROM → RCPT TO → DATA → QUIT ✅
- TLS/STARTTLS support ✅
- Complete email lifecycle (MIME, HTML, custom headers) ✅
**Phase 1 Status**: ✅ **COMPLETE** (7/7 tests, 100%)
**Phase 2 Status**: 🔄 **IN PROGRESS** (3/6 tests, 50%)
- ✅ SEC-06: IP Reputation
- ✅ ERR-01: Syntax Errors
- ✅ ERR-02: Invalid Sequence
- 🔄 SEC-01: Authentication
- 🔄 SEC-08: Rate Limiting
- 🔄 SEC-10: Header Injection
**Next Steps**:
1. Port SEC-01: Authentication test
2. Port SEC-08: Rate Limiting test
3. Port SEC-10: Header Injection Prevention test
4. Continue with Phase 3 (Advanced Features)
## Production Readiness Criteria
### Gate 1: Core Functionality (>90% tests passing)
- Basic SMTP command handling
- Connection management
- Email delivery
- Error handling
### Gate 2: Security (>95% tests passing)
### Production Gate 2: Advanced Features (>90% tests passing)
- Connection pooling and reuse
- Authentication mechanisms
- TLS/STARTTLS support
- Rate limiting
- Injection prevention
- Retry logic and resilience
### Gate 3: Enterprise Ready (>85% tests passing)
### Production Gate 3: Enterprise Ready (>85% tests passing)
- High-volume sending capabilities
- Advanced security features
- Full RFC compliance
- Performance under load
- Advanced security features
- Complete edge case handling
## Contributing
## Key Differences: Server vs Client Tests
When porting tests from dcrouter:
| Aspect | Server Tests | Client Tests |
|--------|--------------|--------------|
| **Focus** | Accepting connections, processing commands | Making connections, sending commands |
| **Security** | Validating incoming data, enforcing policies | Protecting credentials, validating servers |
| **Performance** | Handling many clients concurrently | Efficient bulk sending, connection reuse |
| **Reliability** | Staying up under attack/load | Retrying failures, handling timeouts |
| **RFC Compliance** | Server MUST requirements | Client MUST requirements |
1. Maintain test IDs and organization
2. Convert to Deno.test() format
3. Use @std/assert for assertions
4. Update imports to .ts extensions
5. Use Deno-native TCP connections
6. Preserve test logic and validations
7. Add `sanitizeResources: false, sanitizeOps: false` for network tests
8. Update this README with ported tests
## Test Implementation Priority
## Resources
1. **Critical** (implement first):
- Basic connection and command sending
- Authentication mechanisms
- Error handling and retry logic
- TLS/Security features
2. **High Priority** (implement second):
- Connection pooling
- Email composition and MIME
- Performance optimization
- RFC compliance
3. **Medium Priority** (implement third):
- Advanced features (OAuth2, etc.)
- Edge case handling
- Extended performance tests
- Additional RFC extensions
4. **Low Priority** (implement last):
- Proxy support
- Certificate pinning
- Unusual scenarios
- Optional RFC features
- [Deno Testing](https://deno.land/manual/basics/testing)
- [Deno Standard Library - Assert](https://deno.land/std/assert)
- [RFC 5321 - SMTP](https://tools.ietf.org/html/rfc5321)
- [RFC 5322 - Internet Message Format](https://tools.ietf.org/html/rfc5322)