dcrouter/readme.plan.md

# SMTP Server Refactoring Plan

## Problem Statement

The SMTP server implementation in `classes.smtpserver.ts` has grown to be too large and complex, with over 1300 lines of code. This makes it difficult to maintain, test, and extend. We need to refactor it into multiple smaller, focused files to improve maintainability and adhere to the single responsibility principle.

## Refactoring Goals

1. Improve code organization by splitting the SMTPServer class into multiple focused modules
2. Enhance testability by making components more isolated and easier to mock
3. Improve maintainability by reducing file sizes and complexity
4. Preserve existing functionality and behavior while improving the architecture

## Proposed File Structure

```
mail/
  └── delivery/
      ├── smtp/
      │   ├── index.ts                     - Main export file
      │   ├── interfaces.ts                - All SMTP-related interfaces
      │   ├── constants.ts                 - Constants and enums
      │   ├── smtp-server.ts               - Main server class (core functionality)
      │   ├── session-manager.ts           - Session creation and management
      │   ├── command-handler.ts           - SMTP command processing
      │   ├── data-handler.ts              - Email data processing
      │   ├── tls-handler.ts               - TLS and STARTTLS functionality
      │   ├── security-handler.ts          - Security checks and validations
      │   ├── connection-manager.ts        - Connection management and cleanup
      │   └── utils/
      │       ├── validation.ts            - Validation utilities
      │       ├── logging.ts               - Logging utilities
      │       └── helpers.ts               - Other helper functions
      ├── classes.smtpserver.ts            - Legacy file (will be deprecated)
      └── interfaces.ts                    - Main delivery interfaces
```

## Module Responsibilities

### 1. smtp-server.ts (150-200 lines)
- Core server initialization and lifecycle management
- Server startup and shutdown
- Port binding and socket creation
- Delegates to other modules for specific functionality

### 2. session-manager.ts (100-150 lines)
- Session creation and tracking
- Session timeout management
- Session cleanup
- Session state management

### 3. command-handler.ts (200-250 lines)
- SMTP command parsing and routing
- Command validation
- Command implementation (EHLO, MAIL FROM, RCPT TO, etc.)
- Response formatting

### 4. data-handler.ts (150-200 lines)
- Email data collection and processing
- DATA command handling
- MIME parsing
- Email creation and forwarding
- Email storage

### 5. tls-handler.ts (100-150 lines)
- TLS connection handling
- STARTTLS implementation
- Certificate management
- Secure socket creation

### 6. security-handler.ts (100-150 lines)
- IP reputation checking
- Access control
- Rate limiting
- Security logging
- SPAM detection

### 7. connection-manager.ts (100-150 lines)
- Connection tracking and limits
- Idle connection cleanup
- Connection error handling
- Socket event handling

### 8. interfaces.ts (100-150 lines)
- All interface definitions
- Type aliases
- Type guards
- Enum definitions

## Implementation Strategy

### Phase 1: Initial Structure and Scaffolding (Days 1-2)

1. Create the folder structure and empty files
   - Create `mail/delivery/smtp` directory
   - Create all module files with basic exports
   - Set up barrel file (index.ts)

2. Move interfaces to the new interfaces.ts file
   - Extract all interfaces from current implementation
   - Add proper documentation
   - Add any missing interface properties

3. Extract constants and enums to constants.ts
   - Move all constants and enums to dedicated file
   - Ensure proper typing and documentation
   - Replace magic numbers with named constants

4. Set up the basic structure for each module
   - Define basic class skeletons
   - Set up dependency injection structure
   - Document interfaces for each module

### Phase 2: Gradual Implementation Transfer (Days 3-7)

1. Start with utility modules
   - Implement validation.ts with email validation functions
   - Create logging.ts with structured logging utilities
   - Build helpers.ts with common helper functions

2. Implement session-manager.ts
   - Extract session creation and management logic
   - Implement timeout handling
   - Add session state management functions

3. Implement connection-manager.ts
   - Extract connection tracking code
   - Implement connection limits
   - Add socket event handling logic

4. Implement command-handler.ts
   - Extract command parsing and processing
   - Split command handlers into separate methods
   - Implement command validation and routing

5. Implement data-handler.ts
   - Extract email data processing logic
   - Implement DATA command handling
   - Add email storage and forwarding

6. Implement tls-handler.ts
   - Extract TLS connection handling
   - Implement STARTTLS functionality
   - Add certificate management

7. Implement security-handler.ts
   - Extract IP reputation checking
   - Implement security logging
   - Add access control functionality

### Phase 3: Core Server Refactoring (Days 8-10)

1. Refactor the main SMTPServer class
   - Update constructor to create and initialize components
   - Implement dependency injection for all modules
   - Delegate functionality to appropriate modules
   - Reduce core class to server lifecycle management

2. Update event handling
   - Ensure proper event propagation between modules
   - Implement event delegation pattern
   - Add missing event handlers

3. Implement cross-module communication
   - Define clear interfaces for module interaction
   - Ensure proper data flow between components
   - Avoid circular dependencies

4. Verify functionality preservation
   - Ensure all methods have equivalent implementations
   - Add logging to trace execution flow
   - Create test cases for edge conditions

### Phase 4: Legacy Compatibility (Days 11-12)

1. Create facade in classes.smtpserver.ts
   - Keep original class signature
   - Delegate to new implementation internally
   - Ensure backward compatibility

2. Add deprecation notices
   - Mark legacy file with deprecation comments
   - Add migration guide in comments
   - Document breaking changes if any

3. Update documentation
   - Create detailed documentation for new architecture
   - Add examples of how to use the new modules
   - Document extension points

4. Create comprehensive tests
   - Ensure all modules have proper unit tests
   - Add integration tests between modules
   - Verify backward compatibility with existing code

## Testing Strategy

1. Unit Testing
   - Create unit tests for each module in isolation
   - Mock dependencies for pure unit testing
   - Test edge cases and error handling

2. Integration Testing
   - Test interactions between modules
   - Verify correct event propagation
   - Test full SMTP communication flow

3. Regression Testing
   - Ensure all existing tests pass
   - Verify no functionality is lost
   - Compare performance metrics

4. Compatibility Testing
   - Test with existing code that uses the legacy class
   - Verify backward compatibility
   - Document any necessary migration steps

## Timeline Estimate

- Phase 1: 1-2 days
- Phase 2: 3-5 days
- Phase 3: 2-3 days
- Phase 4: 1-2 days

Total: 7-12 days of development time

## Success Criteria

1. All existing tests pass with the new implementation
2. No regression in functionality or performance
3. Each file is less than 300 lines of code
4. Improved code organization and documentation
5. Better separation of concerns between modules
6. Easier maintenance and extension of SMTP functionality

## Risks and Mitigations

### Risk: Breaking existing functionality
**Mitigation**: Comprehensive test coverage and backward compatibility facade

### Risk: Performance degradation due to additional indirection
**Mitigation**: Performance benchmarking before and after refactoring

### Risk: Increased complexity due to distributed code
**Mitigation**: Clear documentation and proper module interfaces

### Risk: Time overrun due to unforeseen dependencies
**Mitigation**: Incremental approach with working checkpoints after each phase

## Future Extensions

Once this refactoring is complete, we can more easily:

1. Add support for additional SMTP extensions
2. Implement pluggable authentication mechanisms
3. Add more sophisticated security features
4. Improve performance with targeted optimizations
5. Create specialized versions for different use cases