dcrouter/readme.plan.md

# DcRouter Socket-Handler Integration Plan

First line: Remember to reread CLAUDE.md file for guidelines.

## Overview
Integrate socket-handler support for both DNS and Mail services in DcRouter, allowing smartproxy to pass sockets directly instead of servers listening on ports.

## Core Logic
- **DNS**: If dnsDomain is set, DnsServer is instantiated with socket-handler for HTTPS/DoH
- **Mail**: If useSocketHandler is enabled in emailConfig, mail servers accept sockets from smartproxy
- **Automatic Routing**: Setting these options automatically configures smartproxy routes

## Architecture

### DNS Architecture
- **HTTPS/DoH Traffic**: smartproxy → socket-handler → smartdns (no port listening)
- **UDP Traffic**: Direct to smartdns DnsServer on VM IP:53 (bypasses smartproxy)
- **Automatic Setup**: Setting dnsDomain triggers all DNS infrastructure

### Mail Architecture  
- **Socket-Handler Mode**: smartproxy → socket-handler → mail server (no port listening)
- **Traditional Mode**: smartproxy → forward → mail server (listening on ports)
- **Configurable**: useSocketHandler flag determines the mode

## Implementation Steps

### 1. Analyze Current Architecture
- [x] Examine how DcRouter currently integrates services
- [x] Study email server socket handling in SmtpServer
- [x] Check existing smartproxy socket-handler patterns
- [x] Review UnifiedEmailServer connection handling

### 2. DNS Socket-Handler Implementation

#### 2.1 Create DNS Socket Handler
- [x] Create a custom socket handler that processes DNS-over-HTTPS requests
- [x] Handler should use smartdns without port binding
- [x] Use built-in handleHttpsSocket method from smartdns
- [x] Set manualHttpsMode: true in DnsServer options

#### 2.2 Configure smartdns DnsServer
- [x] Create DnsServer instance with UDP only on VM IP interface
- [x] Set manualHttpsMode: true to disable HTTPS port binding
- [x] Configure to listen on port 53 for UDP traffic only
- [x] Use handleHttpsSocket method for DoH sockets

### 3. Mail Socket-Handler Implementation

#### 3.1 Modify SmtpServer
- [x] ConnectionManager already has handleConnection method
- [x] Connection handling already works with provided sockets
- [x] Session management works with socket-handler mode
- [x] Backward compatibility maintained

#### 3.2 Update UnifiedEmailServer
- [x] Add useSocketHandler flag to IUnifiedEmailServerOptions
- [x] Modify start() to skip server creation when useSocketHandler is true
- [x] Add handleSocket method to accept sockets from smartproxy
- [x] All email processing works in socket-handler mode

#### 3.3 Create Mail Socket Handler
- [x] Create socket handler for SMTP/submission/SMTPS
- [x] Handle TLS for port 465 (immediate TLS wrapping)
- [x] Pass sockets to UnifiedEmailServer.handleSocket

### 4. DcRouter Integration

#### 4.1 Configuration Updates
- [x] Add `dnsDomain` property to DcRouter config
- [x] Add `useSocketHandler` to email config options
- [x] Update interface definitions

#### 4.2 Route Generation Updates
- [x] Modify generateEmailRoutes to create socket-handler actions when enabled
- [x] Create DNS routes with socket-handler actions
- [x] Ensure proper domain and path matching

#### 4.3 Service Lifecycle
- [x] Update setupSmartProxy to handle socket-handler routes
- [x] Services start correctly without port binding
- [x] Socket cleanup handled by connection managers

### 5. SmartProxy Route Configuration
- [x] DNS routes: match dnsDomain with paths /dns-query and /resolve
- [x] Mail routes: match ports 25, 587, 465 with socket-handler actions
- [x] Configure TLS handling for each protocol appropriately
- [x] Automatic Let's Encrypt via smartproxy certificate: 'auto'

### 6. Testing (To be done)

#### 6.1 DNS Testing
- [ ] Test that DNS server is NOT instantiated when dnsDomain is not set
- [ ] Test that DNS server IS instantiated when dnsDomain is set
- [ ] Test UDP DNS queries on port 53
- [ ] Test DoH queries through smartproxy socket-handler
- [ ] Verify HTTP/2 support for DoH

#### 6.2 Mail Testing
- [ ] Test traditional port-based mail delivery
- [ ] Test socket-handler mail delivery
- [ ] Verify STARTTLS works in socket-handler mode
- [ ] Test SMTPS (port 465) with socket-handler
- [ ] Ensure connection pooling works correctly

#### 6.3 Integration Testing
- [ ] Test both DNS and Mail with socket-handlers simultaneously
- [ ] Verify no port conflicts
- [ ] Test automatic startup/shutdown
- [ ] Load test socket-handler performance

## Technical Details

### DcRouter Configuration
```typescript
// DcRouter config with socket-handler support
const dcRouterConfig = {
  // ... other config
  dnsDomain: 'example.com', // Optional - if set, DNS server is enabled
  emailConfig: {
    ports: [25, 587, 465],
    domains: ['mail.example.com'],
    useSocketHandler: true, // Enable socket-handler mode for mail
    routes: [/* email routing rules */]
  }
}
```

### DNS Implementation

#### Conditional DNS Instantiation
```typescript
// In DcRouter startup logic
if (config.dnsDomain) {
  // Create DNS server instance
  this.dnsServer = new DnsServer({
    udpPort: 53,
    udpBindAddress: vmIpAddress,
    httpsPort: undefined, // No HTTPS listening
    dnssecZone: config.dnsDomain
  });
  
  // Create smartproxy route for DoH
  const dnsRoute = {
    match: {
      domain: config.dnsDomain,
      path: ['/dns-query', '/resolve']
    },
    action: {
      type: 'socket-handler',
      handler: this.createDnsSocketHandler()
    }
  };
}
```

#### DNS Socket Handler
```typescript
const createDnsSocketHandler = () => {
  return async (socket: net.Socket) => {
    // Handle HTTP/2 for DoH
    const session = http2.createSession(socket);
    
    session.on('stream', async (stream, headers) => {
      if (headers[':path'] === '/dns-query') {
        const dnsQuery = await parseDnsQuery(stream);
        const response = await dnsServer.resolveQuery(dnsQuery);
        stream.respond({ ':status': 200, 'content-type': 'application/dns-message' });
        stream.end(response);
      }
    });
  };
}
```

### Mail Implementation

#### Email Route Generation with Socket-Handler
```typescript
private generateEmailRoutes(emailConfig: IUnifiedEmailServerOptions): IRouteConfig[] {
  const routes: IRouteConfig[] = [];
  
  for (const port of emailConfig.ports) {
    const action = emailConfig.useSocketHandler
      ? {
          type: 'socket-handler',
          handler: this.createMailSocketHandler(port)
        }
      : {
          type: 'forward',
          target: { host: 'localhost', port: mapPort(port) }
        };
    
    routes.push({
      match: { ports: [port] },
      action
    });
  }
  
  return routes;
}
```

#### Mail Socket Handler
```typescript
const createMailSocketHandler = (port: number) => {
  return async (socket: net.Socket) => {
    // Determine protocol based on port
    const isSecure = port === 465;
    
    if (isSecure) {
      // For SMTPS, handle TLS immediately
      const tlsSocket = new tls.TLSSocket(socket, {
        isServer: true,
        cert: tlsCert,
        key: tlsKey
      });
      await this.emailServer.handleSocket(tlsSocket, port);
    } else {
      // For SMTP/Submission, pass raw socket
      await this.emailServer.handleSocket(socket, port);
    }
  };
}
```

#### UnifiedEmailServer Socket Handling
```typescript
// In UnifiedEmailServer class
public async handleSocket(socket: net.Socket, port: number): Promise<void> {
  // Create session for this socket
  const session = this.sessionManager.createSession(socket);
  
  // Handle connection based on port
  switch (port) {
    case 25:  // SMTP
    case 587: // Submission (STARTTLS)
      await this.connectionManager.handleConnection(socket, session);
      break;
    case 465: // SMTPS (already TLS)
      await this.connectionManager.handleSecureConnection(socket, session);
      break;
  }
}

## Dependencies
- @push.rocks/smartproxy (already integrated)
- @push.rocks/smartdns (to be added)

## Implementation Phases

### Phase 1: DNS Socket-Handler (Priority)
1. Add smartdns dependency
2. Implement DNS socket-handler
3. Add dnsDomain configuration
4. Test DoH functionality

### Phase 2: Mail Socket-Handler  
1. Refactor SmtpServer for socket handling
2. Update UnifiedEmailServer
3. Implement mail socket-handlers
4. Add useSocketHandler configuration
5. Test all mail protocols

### Phase 3: Integration & Testing
1. Full integration testing
2. Performance benchmarking
3. Documentation updates
4. Migration guide for existing users

## Notes

### DNS Notes
- UDP traffic bypasses proxy entirely (kernel-level routing)
- DoH provides encrypted DNS over HTTPS through proxy
- Socket handler allows DNS processing without port binding
- DNS functionality is entirely optional - only enabled when dnsDomain is configured
- Setting dnsDomain triggers automatic setup of all DNS infrastructure
- Automatic Let's Encrypt certificate provisioning for configured dnsDomain

### Mail Notes
- Socket-handler mode eliminates internal port binding for mail services
- Traditional port forwarding mode remains available for compatibility
- STARTTLS negotiation handled within socket-handler for ports 25/587
- Port 465 (SMTPS) requires immediate TLS handshake in socket-handler
- Connection pooling and session management work in both modes
- Socket-handler reduces latency by eliminating internal forwarding

### General Benefits
- Reduced resource usage (no internal port binding)
- Better performance (direct socket passing)
- Simplified configuration (automatic route creation)
- Enhanced security (no exposed internal ports)
- Unified approach for all services through smartproxy