@serve.zone/dcrouter 2.12.4

package/ts/mail/delivery/smtpclient/constants.ts

@@ -0,0 +1,145 @@
+/**
+ * SMTP Client Constants and Error Codes
+ * All constants, error codes, and enums for SMTP client operations
+ */
+
+/**
+ * SMTP response codes
+ */
+export const SMTP_CODES = {
+  // Positive completion replies
+  SERVICE_READY: 220,
+  SERVICE_CLOSING: 221,
+  AUTHENTICATION_SUCCESSFUL: 235,
+  REQUESTED_ACTION_OK: 250,
+  USER_NOT_LOCAL: 251,
+  CANNOT_VERIFY_USER: 252,
+  
+  // Positive intermediate replies
+  START_MAIL_INPUT: 354,
+  
+  // Transient negative completion replies
+  SERVICE_NOT_AVAILABLE: 421,
+  MAILBOX_BUSY: 450,
+  LOCAL_ERROR: 451,
+  INSUFFICIENT_STORAGE: 452,
+  UNABLE_TO_ACCOMMODATE: 455,
+  
+  // Permanent negative completion replies
+  SYNTAX_ERROR: 500,
+  SYNTAX_ERROR_PARAMETERS: 501,
+  COMMAND_NOT_IMPLEMENTED: 502,
+  BAD_SEQUENCE: 503,
+  PARAMETER_NOT_IMPLEMENTED: 504,
+  MAILBOX_UNAVAILABLE: 550,
+  USER_NOT_LOCAL_TRY_FORWARD: 551,
+  EXCEEDED_STORAGE: 552,
+  MAILBOX_NAME_NOT_ALLOWED: 553,
+  TRANSACTION_FAILED: 554
+} as const;
+
+/**
+ * SMTP command names
+ */
+export const SMTP_COMMANDS = {
+  HELO: 'HELO',
+  EHLO: 'EHLO',
+  MAIL_FROM: 'MAIL FROM',
+  RCPT_TO: 'RCPT TO',
+  DATA: 'DATA',
+  RSET: 'RSET',
+  NOOP: 'NOOP',
+  QUIT: 'QUIT',
+  STARTTLS: 'STARTTLS',
+  AUTH: 'AUTH'
+} as const;
+
+/**
+ * Authentication methods
+ */
+export const AUTH_METHODS = {
+  PLAIN: 'PLAIN',
+  LOGIN: 'LOGIN',
+  OAUTH2: 'XOAUTH2',
+  CRAM_MD5: 'CRAM-MD5'
+} as const;
+
+/**
+ * Common SMTP extensions
+ */
+export const SMTP_EXTENSIONS = {
+  PIPELINING: 'PIPELINING',
+  SIZE: 'SIZE',
+  STARTTLS: 'STARTTLS',
+  AUTH: 'AUTH',
+  EIGHT_BIT_MIME: '8BITMIME',
+  CHUNKING: 'CHUNKING',
+  ENHANCED_STATUS_CODES: 'ENHANCEDSTATUSCODES',
+  DSN: 'DSN'
+} as const;
+
+/**
+ * Default configuration values
+ */
+export const DEFAULTS = {
+  CONNECTION_TIMEOUT: 60000, // 60 seconds
+  SOCKET_TIMEOUT: 300000,    // 5 minutes
+  COMMAND_TIMEOUT: 30000,    // 30 seconds
+  MAX_CONNECTIONS: 5,
+  MAX_MESSAGES: 100,
+  PORT_SMTP: 25,
+  PORT_SUBMISSION: 587,
+  PORT_SMTPS: 465,
+  RETRY_ATTEMPTS: 3,
+  RETRY_DELAY: 1000,
+  POOL_IDLE_TIMEOUT: 30000   // 30 seconds
+} as const;
+
+/**
+ * Error types for classification
+ */
+export enum SmtpErrorType {
+  CONNECTION_ERROR = 'CONNECTION_ERROR',
+  AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR',
+  PROTOCOL_ERROR = 'PROTOCOL_ERROR',
+  TIMEOUT_ERROR = 'TIMEOUT_ERROR',
+  TLS_ERROR = 'TLS_ERROR',
+  SYNTAX_ERROR = 'SYNTAX_ERROR',
+  MAILBOX_ERROR = 'MAILBOX_ERROR',
+  QUOTA_ERROR = 'QUOTA_ERROR',
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR'
+}
+
+/**
+ * Regular expressions for parsing
+ */
+export const REGEX_PATTERNS = {
+  EMAIL_ADDRESS: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+  RESPONSE_CODE: /^(\d{3})([ -])(.*)/,
+  ENHANCED_STATUS: /^(\d\.\d\.\d)\s/,
+  AUTH_CAPABILITIES: /AUTH\s+(.+)/i,
+  SIZE_EXTENSION: /SIZE\s+(\d+)/i
+} as const;
+
+/**
+ * Line endings and separators
+ */
+export const LINE_ENDINGS = {
+  CRLF: '\r\n',
+  LF: '\n',
+  CR: '\r'
+} as const;
+
+/**
+ * Connection states for internal use
+ */
+export const CONNECTION_STATES = {
+  DISCONNECTED: 'disconnected',
+  CONNECTING: 'connecting',
+  CONNECTED: 'connected',
+  AUTHENTICATED: 'authenticated',
+  READY: 'ready',
+  BUSY: 'busy',
+  CLOSING: 'closing',
+  ERROR: 'error'
+} as const;

package/ts/mail/delivery/smtpclient/create-client.ts

@@ -0,0 +1,94 @@
+/**
+ * SMTP Client Factory
+ * Factory function for client creation and dependency injection
+ */
+
+import { SmtpClient } from './smtp-client.js';
+import { ConnectionManager } from './connection-manager.js';
+import { CommandHandler } from './command-handler.js';
+import { AuthHandler } from './auth-handler.js';
+import { TlsHandler } from './tls-handler.js';
+import { SmtpErrorHandler } from './error-handler.js';
+import type { ISmtpClientOptions } from './interfaces.js';
+import { validateClientOptions } from './utils/validation.js';
+import { DEFAULTS } from './constants.js';
+
+/**
+ * Create a complete SMTP client with all components
+ */
+export function createSmtpClient(options: ISmtpClientOptions): SmtpClient {
+  // Validate options
+  const errors = validateClientOptions(options);
+  if (errors.length > 0) {
+    throw new Error(`Invalid client options: ${errors.join(', ')}`);
+  }
+  
+  // Apply defaults
+  const clientOptions: ISmtpClientOptions = {
+    connectionTimeout: DEFAULTS.CONNECTION_TIMEOUT,
+    socketTimeout: DEFAULTS.SOCKET_TIMEOUT,
+    maxConnections: DEFAULTS.MAX_CONNECTIONS,
+    maxMessages: DEFAULTS.MAX_MESSAGES,
+    pool: false,
+    secure: false,
+    debug: false,
+    ...options
+  };
+  
+  // Create handlers
+  const errorHandler = new SmtpErrorHandler(clientOptions);
+  const connectionManager = new ConnectionManager(clientOptions);
+  const commandHandler = new CommandHandler(clientOptions);
+  const authHandler = new AuthHandler(clientOptions, commandHandler);
+  const tlsHandler = new TlsHandler(clientOptions, commandHandler);
+  
+  // Create and return SMTP client
+  return new SmtpClient({
+    options: clientOptions,
+    connectionManager,
+    commandHandler,
+    authHandler,
+    tlsHandler,
+    errorHandler
+  });
+}
+
+/**
+ * Create SMTP client with connection pooling enabled
+ */
+export function createPooledSmtpClient(options: ISmtpClientOptions): SmtpClient {
+  return createSmtpClient({
+    ...options,
+    pool: true,
+    maxConnections: options.maxConnections || DEFAULTS.MAX_CONNECTIONS,
+    maxMessages: options.maxMessages || DEFAULTS.MAX_MESSAGES
+  });
+}
+
+/**
+ * Create SMTP client for high-volume sending
+ */
+export function createBulkSmtpClient(options: ISmtpClientOptions): SmtpClient {
+  return createSmtpClient({
+    ...options,
+    pool: true,
+    maxConnections: Math.max(options.maxConnections || 10, 10),
+    maxMessages: Math.max(options.maxMessages || 1000, 1000),
+    connectionTimeout: options.connectionTimeout || 30000,
+    socketTimeout: options.socketTimeout || 120000
+  });
+}
+
+/**
+ * Create SMTP client for transactional emails
+ */
+export function createTransactionalSmtpClient(options: ISmtpClientOptions): SmtpClient {
+  return createSmtpClient({
+    ...options,
+    pool: false, // Use fresh connections for transactional emails
+    maxConnections: 1,
+    maxMessages: 1,
+    connectionTimeout: options.connectionTimeout || 10000,
+    socketTimeout: options.socketTimeout || 30000
+  });
+}

package/ts/mail/delivery/smtpclient/error-handler.ts

@@ -0,0 +1,141 @@
+/**
+ * SMTP Client Error Handler
+ * Error classification and recovery strategies
+ */
+
+import { SmtpErrorType } from './constants.js';
+import type { ISmtpResponse, ISmtpErrorContext, ISmtpClientOptions } from './interfaces.js';
+import { logDebug } from './utils/logging.js';
+
+export class SmtpErrorHandler {
+  private options: ISmtpClientOptions;
+  
+  constructor(options: ISmtpClientOptions) {
+    this.options = options;
+  }
+  
+  /**
+   * Classify error type based on response or error
+   */
+  public classifyError(error: Error | ISmtpResponse, context?: ISmtpErrorContext): SmtpErrorType {
+    logDebug('Classifying error', this.options, { errorMessage: error instanceof Error ? error.message : String(error), context });
+    
+    // Handle Error objects
+    if (error instanceof Error) {
+      return this.classifyErrorByMessage(error);
+    }
+    
+    // Handle SMTP response codes
+    if (typeof error === 'object' && 'code' in error) {
+      return this.classifyErrorByCode(error.code);
+    }
+    
+    return SmtpErrorType.UNKNOWN_ERROR;
+  }
+  
+  /**
+   * Determine if error is retryable
+   */
+  public isRetryable(errorType: SmtpErrorType, response?: ISmtpResponse): boolean {
+    switch (errorType) {
+      case SmtpErrorType.CONNECTION_ERROR:
+      case SmtpErrorType.TIMEOUT_ERROR:
+        return true;
+      
+      case SmtpErrorType.PROTOCOL_ERROR:
+        // Only retry on temporary failures (4xx codes)
+        return response ? response.code >= 400 && response.code < 500 : false;
+      
+      case SmtpErrorType.AUTHENTICATION_ERROR:
+      case SmtpErrorType.TLS_ERROR:
+      case SmtpErrorType.SYNTAX_ERROR:
+      case SmtpErrorType.MAILBOX_ERROR:
+      case SmtpErrorType.QUOTA_ERROR:
+        return false;
+      
+      default:
+        return false;
+    }
+  }
+  
+  /**
+   * Get retry delay for error type
+   */
+  public getRetryDelay(attempt: number, errorType: SmtpErrorType): number {
+    const baseDelay = 1000; // 1 second
+    const maxDelay = 30000;  // 30 seconds
+    
+    // Exponential backoff with jitter
+    const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
+    const jitter = Math.random() * 0.1 * delay; // 10% jitter
+    
+    return Math.floor(delay + jitter);
+  }
+  
+  /**
+   * Create enhanced error with context
+   */
+  public createError(
+    message: string,
+    errorType: SmtpErrorType,
+    context?: ISmtpErrorContext,
+    originalError?: Error
+  ): Error {
+    const error = new Error(message);
+    (error as any).type = errorType;
+    (error as any).context = context;
+    (error as any).originalError = originalError;
+    
+    return error;
+  }
+  
+  private classifyErrorByMessage(error: Error): SmtpErrorType {
+    const message = error.message.toLowerCase();
+    
+    if (message.includes('timeout') || message.includes('etimedout')) {
+      return SmtpErrorType.TIMEOUT_ERROR;
+    }
+    
+    if (message.includes('connect') || message.includes('econnrefused') || 
+        message.includes('enotfound') || message.includes('enetunreach')) {
+      return SmtpErrorType.CONNECTION_ERROR;
+    }
+    
+    if (message.includes('tls') || message.includes('ssl') || 
+        message.includes('certificate') || message.includes('handshake')) {
+      return SmtpErrorType.TLS_ERROR;
+    }
+    
+    if (message.includes('auth')) {
+      return SmtpErrorType.AUTHENTICATION_ERROR;
+    }
+    
+    return SmtpErrorType.UNKNOWN_ERROR;
+  }
+  
+  private classifyErrorByCode(code: number): SmtpErrorType {
+    if (code >= 500) {
+      // Permanent failures
+      if (code === 550 || code === 551 || code === 553) {
+        return SmtpErrorType.MAILBOX_ERROR;
+      }
+      if (code === 552) {
+        return SmtpErrorType.QUOTA_ERROR;
+      }
+      if (code === 500 || code === 501 || code === 502 || code === 504) {
+        return SmtpErrorType.SYNTAX_ERROR;
+      }
+      return SmtpErrorType.PROTOCOL_ERROR;
+    }
+    
+    if (code >= 400) {
+      // Temporary failures
+      if (code === 450 || code === 451 || code === 452) {
+        return SmtpErrorType.QUOTA_ERROR;
+      }
+      return SmtpErrorType.PROTOCOL_ERROR;
+    }
+    
+    return SmtpErrorType.UNKNOWN_ERROR;
+  }
+}

package/ts/mail/delivery/smtpclient/index.ts

@@ -0,0 +1,24 @@
+/**
+ * SMTP Client Module Exports
+ * Modular SMTP client implementation for robust email delivery
+ */
+
+// Main client class and factory
+export * from './smtp-client.js';
+export * from './create-client.js';
+
+// Core handlers
+export * from './connection-manager.js';
+export * from './command-handler.js';
+export * from './auth-handler.js';
+export * from './tls-handler.js';
+export * from './error-handler.js';
+
+// Interfaces and types
+export * from './interfaces.js';
+export * from './constants.js';
+
+// Utilities
+export * from './utils/validation.js';
+export * from './utils/logging.js';
+export * from './utils/helpers.js';

package/ts/mail/delivery/smtpclient/interfaces.ts

@@ -0,0 +1,242 @@
+/**
+ * SMTP Client Interfaces and Types
+ * All interface definitions for the modular SMTP client
+ */
+
+import type * as tls from 'node:tls';
+import type * as net from 'node:net';
+import type { Email } from '../../core/classes.email.js';
+
+/**
+ * SMTP client connection options
+ */
+export interface ISmtpClientOptions {
+  /** Hostname of the SMTP server */
+  host: string;
+  
+  /** Port to connect to */
+  port: number;
+  
+  /** Whether to use TLS for the connection */
+  secure?: boolean;
+  
+  /** Connection timeout in milliseconds */
+  connectionTimeout?: number;
+  
+  /** Socket timeout in milliseconds */
+  socketTimeout?: number;
+  
+  /** Domain name for EHLO command */
+  domain?: string;
+  
+  /** Authentication options */
+  auth?: ISmtpAuthOptions;
+  
+  /** TLS options */
+  tls?: tls.ConnectionOptions;
+  
+  /** Maximum number of connections in pool */
+  pool?: boolean;
+  maxConnections?: number;
+  maxMessages?: number;
+  
+  /** Enable debug logging */
+  debug?: boolean;
+  
+  /** Proxy settings */
+  proxy?: string;
+}
+
+/**
+ * Authentication options for SMTP
+ */
+export interface ISmtpAuthOptions {
+  /** Username */
+  user?: string;
+  
+  /** Password */
+  pass?: string;
+  
+  /** OAuth2 settings */
+  oauth2?: IOAuth2Options;
+  
+  /** Authentication method preference */
+  method?: 'PLAIN' | 'LOGIN' | 'OAUTH2' | 'AUTO';
+}
+
+/**
+ * OAuth2 authentication options
+ */
+export interface IOAuth2Options {
+  /** OAuth2 user identifier */
+  user: string;
+  
+  /** OAuth2 client ID */
+  clientId: string;
+  
+  /** OAuth2 client secret */
+  clientSecret: string;
+  
+  /** OAuth2 refresh token */
+  refreshToken: string;
+  
+  /** OAuth2 access token */
+  accessToken?: string;
+  
+  /** Token expiry time */
+  expires?: number;
+}
+
+/**
+ * Result of an email send operation
+ */
+export interface ISmtpSendResult {
+  /** Whether the send was successful */
+  success: boolean;
+  
+  /** Message ID from server */
+  messageId?: string;
+  
+  /** List of accepted recipients */
+  acceptedRecipients: string[];
+  
+  /** List of rejected recipients */
+  rejectedRecipients: string[];
+  
+  /** Error information if failed */
+  error?: Error;
+  
+  /** Server response */
+  response?: string;
+  
+  /** Envelope information */
+  envelope?: ISmtpEnvelope;
+}
+
+/**
+ * SMTP envelope information
+ */
+export interface ISmtpEnvelope {
+  /** Sender address */
+  from: string;
+  
+  /** Recipient addresses */
+  to: string[];
+}
+
+/**
+ * Connection pool status
+ */
+export interface IConnectionPoolStatus {
+  /** Total connections in pool */
+  total: number;
+  
+  /** Active connections */
+  active: number;
+  
+  /** Idle connections */
+  idle: number;
+  
+  /** Pending connection requests */
+  pending: number;
+}
+
+/**
+ * SMTP command response
+ */
+export interface ISmtpResponse {
+  /** Response code */
+  code: number;
+  
+  /** Response message */
+  message: string;
+  
+  /** Enhanced status code */
+  enhancedCode?: string;
+  
+  /** Raw response */
+  raw: string;
+}
+
+/**
+ * Connection state
+ */
+export enum ConnectionState {
+  DISCONNECTED = 'disconnected',
+  CONNECTING = 'connecting',
+  CONNECTED = 'connected',
+  AUTHENTICATED = 'authenticated',
+  READY = 'ready',
+  BUSY = 'busy',
+  CLOSING = 'closing',
+  ERROR = 'error'
+}
+
+/**
+ * SMTP capabilities
+ */
+export interface ISmtpCapabilities {
+  /** Supported extensions */
+  extensions: Set<string>;
+  
+  /** Maximum message size */
+  maxSize?: number;
+  
+  /** Supported authentication methods */
+  authMethods: Set<string>;
+  
+  /** Support for pipelining */
+  pipelining: boolean;
+  
+  /** Support for STARTTLS */
+  starttls: boolean;
+  
+  /** Support for 8BITMIME */
+  eightBitMime: boolean;
+}
+
+/**
+ * Internal connection interface
+ */
+export interface ISmtpConnection {
+  /** Socket connection */
+  socket: net.Socket | tls.TLSSocket;
+  
+  /** Connection state */
+  state: ConnectionState;
+  
+  /** Server capabilities */
+  capabilities?: ISmtpCapabilities;
+  
+  /** Connection options */
+  options: ISmtpClientOptions;
+  
+  /** Whether connection is secure */
+  secure: boolean;
+  
+  /** Connection creation time */
+  createdAt: Date;
+  
+  /** Last activity time */
+  lastActivity: Date;
+  
+  /** Number of messages sent */
+  messageCount: number;
+}
+
+/**
+ * Error context for detailed error reporting
+ */
+export interface ISmtpErrorContext {
+  /** Command that caused the error */
+  command?: string;
+  
+  /** Server response */
+  response?: ISmtpResponse;
+  
+  /** Connection state */
+  connectionState?: ConnectionState;
+  
+  /** Additional context data */
+  data?: Record<string, any>;
+}