/**
 * 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 } from '../interfaces.js';

// Define all needed types/interfaces directly in this file
export { SmtpState };

// Define EmailProcessingMode directly in this file
export type EmailProcessingMode = 'forward' | 'mta' | 'process';

/**
 * Envelope recipient information
 */
export interface IEnvelopeRecipient {
  /**
   * Email address of the recipient
   */
  address: string;
  
  /**
   * Additional SMTP command arguments
   */
  args: Record<string, string>;
}

/**
 * SMTP session envelope information
 */
export interface ISmtpEnvelope {
  /**
   * Envelope sender (MAIL FROM) information
   */
  mailFrom: {
    /**
     * Email address of the sender
     */
    address: string;
    
    /**
     * Additional SMTP command arguments
     */
    args: Record<string, string>;
  };
  
  /**
   * Envelope recipients (RCPT TO) information
   */
  rcptTo: IEnvelopeRecipient[];
}

/**
 * SMTP Session interface - represents an active SMTP connection
 */
export interface ISmtpSession {
  /**
   * Unique session identifier
   */
  id: string;
  
  /**
   * Current session state in the SMTP conversation
   */
  state: SmtpState;
  
  /**
   * Hostname provided by the client in EHLO/HELO command
   */
  clientHostname: string;
  
  /**
   * MAIL FROM email address (legacy format)
   */
  mailFrom: string;
  
  /**
   * RCPT TO email addresses (legacy format)
   */
  rcptTo: string[];
  
  /**
   * Raw email data being received
   */
  emailData: string;
  
  /**
   * Chunks of email data for more efficient buffer management
   */
  emailDataChunks?: string[];
  
  /**
   * Whether the connection is using TLS
   */
  useTLS: boolean;
  
  /**
   * Whether the connection has ended
   */
  connectionEnded: boolean;
  
  /**
   * Remote IP address of the client
   */
  remoteAddress: string;
  
  /**
   * Whether the connection is secure (TLS)
   */
  secure: boolean;
  
  /**
   * Whether the client has been authenticated
   */
  authenticated: boolean;
  
  /**
   * SMTP envelope information (structured format)
   */
  envelope: ISmtpEnvelope;
  
  /**
   * Email processing mode to use for this session
   */
  processingMode?: EmailProcessingMode;
  
  /**
   * Timestamp of last activity for session timeout tracking
   */
  lastActivity?: number;
  
  /**
   * Timeout ID for DATA command timeout
   */
  dataTimeoutId?: NodeJS.Timeout;
}

/**
 * SMTP authentication data
 */
export interface ISmtpAuth {
  /**
   * Authentication method used
   */
  method: 'PLAIN' | 'LOGIN' | 'OAUTH2' | string;
  
  /**
   * Username for authentication
   */
  username: string;
  
  /**
   * Password or token for authentication
   */
  password: string;
}

/**
 * SMTP server options
 */
export interface ISmtpServerOptions {
  /**
   * Port to listen on
   */
  port: number;
  
  /**
   * TLS private key (PEM format)
   */
  key: string;
  
  /**
   * TLS certificate (PEM format)
   */
  cert: string;
  
  /**
   * Server hostname for SMTP banner
   */
  hostname?: string;
  
  /**
   * Host address to bind to (defaults to all interfaces)
   */
  host?: string;
  
  /**
   * Secure port for dedicated TLS connections
   */
  securePort?: number;
  
  /**
   * CA certificates for TLS (PEM format)
   */
  ca?: string;
  
  /**
   * Maximum size of messages in bytes
   */
  maxSize?: number;
  
  /**
   * Maximum number of concurrent connections
   */
  maxConnections?: number;
  
  /**
   * Authentication options
   */
  auth?: {
    /**
     * Whether authentication is required
     */
    required: boolean;
    
    /**
     * Allowed authentication methods
     */
    methods: ('PLAIN' | 'LOGIN' | 'OAUTH2')[];
  };
  
  /**
   * Socket timeout in milliseconds (default: 5 minutes / 300000ms)
   */
  socketTimeout?: number;
  
  /**
   * Initial connection timeout in milliseconds (default: 30 seconds / 30000ms)
   */
  connectionTimeout?: number;
  
  /**
   * Interval for checking idle sessions in milliseconds (default: 5 seconds / 5000ms)
   * For testing, can be set lower (e.g. 1000ms) to detect timeouts more quickly
   */
  cleanupInterval?: number;
  
  /**
   * Maximum number of recipients allowed per message (default: 100)
   */
  maxRecipients?: number;
  
  /**
   * Maximum message size in bytes (default: 10MB / 10485760 bytes)
   * This is advertised in the EHLO SIZE extension
   */
  size?: number;
  
  /**
   * Timeout for the DATA command in milliseconds (default: 60000ms / 1 minute)
   * This controls how long to wait for the complete email data
   */
  dataTimeout?: number;
}

/**
 * Result of SMTP transaction
 */
export interface ISmtpTransactionResult {
  /**
   * Whether the transaction was successful
   */
  success: boolean;
  
  /**
   * Error message if failed
   */
  error?: string;
  
  /**
   * Message ID if successful
   */
  messageId?: string;
  
  /**
   * Resulting email if successful
   */
  email?: Email;
}

/**
 * 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, message: 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;
}