dcrouter/ts/mail/delivery/smtp/interfaces.ts

/**
 * SMTP Server Module Interfaces
 * This file contains all interfaces for the refactored SMTP server implementation
 */

import * as plugins from '../../../plugins.js';
import type { Email } from '../../core/classes.email.js';
import type { UnifiedEmailServer } from '../../routing/classes.unified.email.server.js';
import { SmtpState, EmailProcessingMode, IEnvelopeRecipient, ISmtpEnvelope, ISmtpSession, ISmtpAuth, ISmtpServerOptions, ISmtpTransactionResult } from '../interfaces.js';

// Re-export the basic interfaces from the main interfaces file
export {
  SmtpState,
  EmailProcessingMode,
  IEnvelopeRecipient,
  ISmtpEnvelope,
  ISmtpSession,
  ISmtpAuth,
  ISmtpServerOptions,
  ISmtpTransactionResult
};

/**
 * Interface for SMTP session events
 * These events are emitted by the session manager
 */
export interface ISessionEvents {
  created: (session: ISmtpSession, socket: plugins.net.Socket | plugins.tls.TLSSocket) => void;
  stateChanged: (session: ISmtpSession, previousState: SmtpState, newState: SmtpState) => void;
  timeout: (session: ISmtpSession, socket: plugins.net.Socket | plugins.tls.TLSSocket) => void;
  completed: (session: ISmtpSession, socket: plugins.net.Socket | plugins.tls.TLSSocket) => void;
  error: (session: ISmtpSession, error: Error) => void;
}

/**
 * Interface for the session manager component
 */
export interface ISessionManager {
  /**
   * Creates a new session for a socket connection
   */
  createSession(socket: plugins.net.Socket | plugins.tls.TLSSocket, secure: boolean): ISmtpSession;
  
  /**
   * Updates the session state
   */
  updateSessionState(session: ISmtpSession, newState: SmtpState): void;
  
  /**
   * Updates the session's last activity timestamp
   */
  updateSessionActivity(session: ISmtpSession): void;
  
  /**
   * Removes a session
   */
  removeSession(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
  
  /**
   * Gets a session for a socket
   */
  getSession(socket: plugins.net.Socket | plugins.tls.TLSSocket): ISmtpSession | undefined;
  
  /**
   * Cleans up idle sessions
   */
  cleanupIdleSessions(): void;
  
  /**
   * Gets the current number of active sessions
   */
  getSessionCount(): number;
  
  /**
   * Clears all sessions (used when shutting down)
   */
  clearAllSessions(): void;
  
  /**
   * Register an event listener
   */
  on<K extends keyof ISessionEvents>(event: K, listener: ISessionEvents[K]): void;
  
  /**
   * Remove an event listener
   */
  off<K extends keyof ISessionEvents>(event: K, listener: ISessionEvents[K]): void;
}

/**
 * Interface for the connection manager component
 */
export interface IConnectionManager {
  /**
   * Handle a new connection
   */
  handleNewConnection(socket: plugins.net.Socket): void;
  
  /**
   * Handle a new secure TLS connection
   */
  handleNewSecureConnection(socket: plugins.tls.TLSSocket): void;
  
  /**
   * Set up event handlers for a socket
   */
  setupSocketEventHandlers(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
  
  /**
   * Get the current connection count
   */
  getConnectionCount(): number;
  
  /**
   * Check if the server has reached the maximum number of connections
   */
  hasReachedMaxConnections(): boolean;
  
  /**
   * Close all active connections
   */
  closeAllConnections(): void;
}

/**
 * Interface for the command handler component
 */
export interface ICommandHandler {
  /**
   * Process a command from the client
   */
  processCommand(socket: plugins.net.Socket | plugins.tls.TLSSocket, commandLine: string): void;
  
  /**
   * Send a response to the client
   */
  sendResponse(socket: plugins.net.Socket | plugins.tls.TLSSocket, response: string): void;
  
  /**
   * Handle EHLO command
   */
  handleEhlo(socket: plugins.net.Socket | plugins.tls.TLSSocket, clientHostname: string): void;
  
  /**
   * Handle MAIL FROM command
   */
  handleMailFrom(socket: plugins.net.Socket | plugins.tls.TLSSocket, args: string): void;
  
  /**
   * Handle RCPT TO command
   */
  handleRcptTo(socket: plugins.net.Socket | plugins.tls.TLSSocket, args: string): void;
  
  /**
   * Handle DATA command
   */
  handleData(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
  
  /**
   * Handle RSET command
   */
  handleRset(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
  
  /**
   * Handle NOOP command
   */
  handleNoop(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
  
  /**
   * Handle QUIT command
   */
  handleQuit(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
}

/**
 * Interface for the data handler component
 */
export interface IDataHandler {
  /**
   * Process incoming email data
   */
  processEmailData(socket: plugins.net.Socket | plugins.tls.TLSSocket, data: string): Promise<void>;
  
  /**
   * Process a complete email
   */
  processEmail(session: ISmtpSession): Promise<ISmtpTransactionResult>;
  
  /**
   * Save an email to disk
   */
  saveEmail(session: ISmtpSession): void;
  
  /**
   * Parse an email into an Email object
   */
  parseEmail(session: ISmtpSession): Promise<Email>;
}

/**
 * Interface for the TLS handler component
 */
export interface ITlsHandler {
  /**
   * Handle STARTTLS command
   */
  handleStartTls(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
  
  /**
   * Upgrade a connection to TLS
   */
  startTLS(socket: plugins.net.Socket): void;
  
  /**
   * Create a secure server
   */
  createSecureServer(): plugins.tls.Server | undefined;
  
  /**
   * Check if TLS is enabled
   */
  isTlsEnabled(): boolean;
}

/**
 * Interface for the security handler component
 */
export interface ISecurityHandler {
  /**
   * Check IP reputation for a connection
   */
  checkIpReputation(socket: plugins.net.Socket | plugins.tls.TLSSocket): Promise<boolean>;
  
  /**
   * Validate an email address
   */
  isValidEmail(email: string): boolean;
  
  /**
   * Validate authentication credentials
   */
  authenticate(session: ISmtpSession, username: string, password: string, method: string): Promise<boolean>;
  
  /**
   * Log a security event
   */
  logSecurityEvent(event: string, level: string, details: Record<string, any>): void;
}

/**
 * Interface for the SMTP server component
 */
export interface ISmtpServer {
  /**
   * Start the SMTP server
   */
  listen(): Promise<void>;
  
  /**
   * Stop the SMTP server
   */
  close(): Promise<void>;
  
  /**
   * Get the session manager
   */
  getSessionManager(): ISessionManager;
  
  /**
   * Get the connection manager
   */
  getConnectionManager(): IConnectionManager;
  
  /**
   * Get the command handler
   */
  getCommandHandler(): ICommandHandler;
  
  /**
   * Get the data handler
   */
  getDataHandler(): IDataHandler;
  
  /**
   * Get the TLS handler
   */
  getTlsHandler(): ITlsHandler;
  
  /**
   * Get the security handler
   */
  getSecurityHandler(): ISecurityHandler;
  
  /**
   * Get the server options
   */
  getOptions(): ISmtpServerOptions;
  
  /**
   * Get the email server reference
   */
  getEmailServer(): UnifiedEmailServer;
}

/**
 * Configuration for creating an SMTP server
 */
export interface ISmtpServerConfig {
  /**
   * Email server reference
   */
  emailServer: UnifiedEmailServer;
  
  /**
   * SMTP server options
   */
  options: ISmtpServerOptions;
  
  /**
   * Optional session manager
   */
  sessionManager?: ISessionManager;
  
  /**
   * Optional connection manager
   */
  connectionManager?: IConnectionManager;
  
  /**
   * Optional command handler
   */
  commandHandler?: ICommandHandler;
  
  /**
   * Optional data handler
   */
  dataHandler?: IDataHandler;
  
  /**
   * Optional TLS handler
   */
  tlsHandler?: ITlsHandler;
  
  /**
   * Optional security handler
   */
  securityHandler?: ISecurityHandler;
}