msmtp 1.0.0__py3-none-any.whl

msmtp/__init__.py

@@ -0,0 +1,119 @@
+"""Mercury SMTP - Production-grade async SMTP sender.
+
+A high-performance async SMTP library with connection pooling, circuit breakers,
+rate limiting, and automatic retry for transient failures.
+
+Example:
+    >>> import asyncio
+    >>> from msmtp import AsyncSMTPSender, SMTPServerConfig
+    >>>
+    >>> server = SMTPServerConfig(
+    ...     host="smtp.gmail.com",
+    ...     port=587,
+    ...     username="user@gmail.com",
+    ...     password="app-password",
+    ...     use_tls=True,
+    ... )
+    >>>
+    >>> async def send():
+    ...     async with AsyncSMTPSender([server]) as sender:
+    ...         result = await sender.send(
+    ...             from_addr="sender@example.com",
+    ...             to_addrs=["recipient@example.com"],
+    ...             subject="Hello",
+    ...             body_text="Hello World",
+    ...         )
+    ...         print(f"Sent: {result.success}")
+    >>>
+    >>> asyncio.run(send())
+"""
+
+from .circuit_breaker import (
+    CircuitBreaker,
+    CircuitBreakerConfig,
+    CircuitBreakerStats,
+    CircuitState,
+)
+from .connection_pool import (
+    AsyncConnectionPool,
+    ConnectionPoolException,
+    SMTPConnectionPool,
+    SMTPServerRuntime,
+)
+from .exceptions import (
+    MercurySMTPError,
+    SMTPAuthenticationError,
+    SMTPConnectionError,
+    SMTPRateLimitError,
+    SMTPSendError,
+)
+from .rate_limiter import (
+    RateLimiter,
+    RateLimiterConfig,
+    TokenBucket,
+)
+from .retry_queue import (
+    RetryConfig,
+    RetryItem,
+    RetryQueue,
+    RetryStatus,
+)
+from .sender import (
+    AsyncSMTPSender,
+    LoadBalancingStrategy,
+)
+from .types import (
+    BulkSendResult,
+    EmailResult,
+    SMTPServerConfig,
+)
+from .types import (
+    SMTPServerConfig as ServerConfig,  # Alias for backwards compat
+)
+from .validation import (
+    sanitize_header_value,
+    sanitize_subject,
+    validate_email_address,
+    validate_email_list,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Core sender
+    "AsyncSMTPSender",
+    "EmailResult",
+    "BulkSendResult",
+    "LoadBalancingStrategy",
+    # Configuration
+    "SMTPServerConfig",
+    "ServerConfig",
+    "CircuitBreakerConfig",
+    "RateLimiterConfig",
+    "RetryConfig",
+    # Components
+    "SMTPConnectionPool",
+    "AsyncConnectionPool",
+    "CircuitBreaker",
+    "CircuitBreakerStats",
+    "CircuitState",
+    "RateLimiter",
+    "TokenBucket",
+    "RetryQueue",
+    "RetryStatus",
+    "RetryItem",
+    # Runtime
+    "SMTPServerRuntime",
+    # Exceptions
+    "MercurySMTPError",
+    "SMTPAuthenticationError",
+    "SMTPConnectionError",
+    "SMTPRateLimitError",
+    "SMTPSendError",
+    "ConnectionPoolException",
+    # Validation
+    "validate_email_address",
+    "validate_email_list",
+    "sanitize_subject",
+    "sanitize_header_value",
+]

msmtp/circuit_breaker.py

@@ -0,0 +1,276 @@
+"""Circuit breaker pattern for SMTP servers."""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitState(Enum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Too many failures, stop trying
+    HALF_OPEN = "half_open"  # Testing if service recovered
+
+
+@dataclass
+class CircuitBreakerConfig:
+    """Configuration for circuit breaker."""
+
+    failure_threshold: int = 5  # Open circuit after N failures
+    success_threshold: int = 2  # Close circuit after N successes in half-open
+    timeout_seconds: int = 60  # Time to wait before trying half-open
+    monitor_window_seconds: int = 300  # Rolling window for failure counting
+
+
+@dataclass
+class CircuitBreakerStats:
+    """Statistics for circuit breaker."""
+
+    state: CircuitState
+    failure_count: int = 0
+    success_count: int = 0
+    last_failure_time: datetime | None = None
+    last_success_time: datetime | None = None
+    opened_at: datetime | None = None
+    total_opens: int = 0
+    total_trips: int = 0  # Total state changes
+    # Most-recent failure messages (kept small — last 5). The root cause
+    # of a circuit-open used to be invisible: the breaker would log "5
+    # failures in 300s" and operators had to dig through the per-recipient
+    # log to find that all 5 were the same iCloud 5.7.0 reject. Keeping
+    # the last few errors on the stats lets us include them in the
+    # OPENING log line AND in the "No SMTP servers available" cascade
+    # error so the cause is visible without log archaeology.
+    last_error_messages: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "state": self.state.value,
+            "failure_count": self.failure_count,
+            "success_count": self.success_count,
+            "last_failure_time": self.last_failure_time.isoformat()
+            if self.last_failure_time
+            else None,
+            "last_success_time": self.last_success_time.isoformat()
+            if self.last_success_time
+            else None,
+            "opened_at": self.opened_at.isoformat() if self.opened_at else None,
+            "total_opens": self.total_opens,
+            "total_trips": self.total_trips,
+            "last_error_messages": list(self.last_error_messages),
+        }
+
+
+class CircuitBreaker:
+    """
+    Circuit breaker for SMTP servers.
+
+    Prevents repeated attempts to failing servers by temporarily
+    disabling them after consecutive failures.
+    """
+
+    def __init__(self, server_name: str, config: CircuitBreakerConfig | None = None):
+        """
+        Initialize circuit breaker.
+
+        Args:
+            server_name: Name of SMTP server being protected
+            config: Circuit breaker configuration
+        """
+        self.server_name = server_name
+        self.config = config or CircuitBreakerConfig()
+        self._stats = CircuitBreakerStats(state=CircuitState.CLOSED)
+
+        # Rolling window for failure tracking
+        self._recent_failures: list[datetime] = []
+
+    def is_available(self) -> bool:
+        """
+        Check if circuit allows operations.
+
+        Returns:
+            True if circuit is closed or half-open
+        """
+        current_state = self._get_current_state()
+
+        if current_state == CircuitState.OPEN:
+            logger.warning(
+                "circuit_breaker_open",
+                extra={
+                    "server": self.server_name,
+                    "state": current_state.value,
+                    "failure_count": self._stats.failure_count,
+                    "last_errors": self._stats.last_error_messages[:3],
+                },
+            )
+            return False
+
+        return True
+
+    def _get_current_state(self) -> CircuitState:
+        """
+        Get current circuit state, handling automatic transitions.
+
+        Returns:
+            Current circuit state
+        """
+        # If closed, stay closed
+        if self._stats.state == CircuitState.CLOSED:
+            return CircuitState.CLOSED
+
+        # If open, check if timeout elapsed
+        if self._stats.state == CircuitState.OPEN:
+            if self._stats.opened_at:
+                elapsed = (datetime.now(timezone.utc) - self._stats.opened_at).total_seconds()
+                if elapsed >= self.config.timeout_seconds:
+                    # Transition to half-open
+                    logger.info(
+                        f"🔄 Circuit breaker transitioning to HALF-OPEN for {self.server_name} "
+                        f"(timeout elapsed: {elapsed:.1f}s)"
+                    )
+                    self._stats.state = CircuitState.HALF_OPEN
+                    self._stats.success_count = 0
+                    self._stats.total_trips += 1
+                    return CircuitState.HALF_OPEN
+            return CircuitState.OPEN
+
+        # If half-open, stay half-open
+        return CircuitState.HALF_OPEN
+
+    def record_success(self) -> None:
+        """Record successful operation."""
+        current_state = self._get_current_state()
+        now = datetime.now(timezone.utc)
+
+        self._stats.last_success_time = now
+
+        if current_state == CircuitState.HALF_OPEN:
+            self._stats.success_count += 1
+
+            # Close circuit if enough successes
+            if self._stats.success_count >= self.config.success_threshold:
+                logger.info(
+                    "circuit_breaker_closed",
+                    extra={
+                        "server": self.server_name,
+                        "success_count": self._stats.success_count,
+                        "success_threshold": self.config.success_threshold,
+                    },
+                )
+                self._stats.state = CircuitState.CLOSED
+                self._stats.failure_count = 0
+                self._stats.success_count = 0
+                self._recent_failures.clear()
+                self._stats.total_trips += 1
+
+        elif current_state == CircuitState.CLOSED:
+            # Reset failure counter on success
+            if self._stats.failure_count > 0:
+                self._stats.failure_count = 0
+                self._recent_failures.clear()
+
+    def record_failure(self, error: Exception) -> None:
+        """
+        Record failed operation.
+
+        Args:
+            error: Exception that occurred
+        """
+        current_state = self._get_current_state()
+        now = datetime.now(timezone.utc)
+
+        self._stats.last_failure_time = now
+        self._stats.failure_count += 1
+        self._recent_failures.append(now)
+
+        # Capture the error text on the stats (cap at 5 entries, FIFO).
+        # The actual diagnostic value is the unique-message set — repeated
+        # identical 5.7.0 rejects from iCloud occupy all 5 slots and tell
+        # the operator nothing they don't already know from one. So we
+        # dedupe by message text before appending.
+        msg = f"{type(error).__name__}: {str(error)[:200]}"
+        if msg not in self._stats.last_error_messages:
+            self._stats.last_error_messages.append(msg)
+            if len(self._stats.last_error_messages) > 5:
+                self._stats.last_error_messages.pop(0)
+
+        # Clean old failures outside monitoring window
+        cutoff = now - timedelta(seconds=self.config.monitor_window_seconds)
+        self._recent_failures = [f for f in self._recent_failures if f > cutoff]
+
+        # Check if we should open the circuit
+        if current_state == CircuitState.CLOSED:
+            if len(self._recent_failures) >= self.config.failure_threshold:
+                # Loud-log the root cause(s) on the same line as the OPEN
+                # event. The previous log just said "5 failures in 300s"
+                # with no hint of what kind of failures — operators had
+                # to grep failed-emails.txt to find that all 5 were the
+                # same iCloud 5.7.0 reject. Now the cause is visible
+                # inline.
+                causes = " | ".join(self._stats.last_error_messages) or "(no error captured)"
+                logger.error(
+                    "⚠️  Circuit breaker OPENING for %s "
+                    "(%d failures in %ds). Recent unique errors: %s",
+                    self.server_name,
+                    len(self._recent_failures),
+                    self.config.monitor_window_seconds,
+                    causes,
+                )
+                self._stats.state = CircuitState.OPEN
+                self._stats.opened_at = now
+                self._stats.total_opens += 1
+                self._stats.total_trips += 1
+
+        elif current_state == CircuitState.HALF_OPEN:
+            # Any failure in half-open immediately opens circuit
+            logger.warning(
+                "⚠️  Circuit breaker RE-OPENING for %s (failure during half-open state): %s",
+                self.server_name,
+                msg,
+            )
+            self._stats.state = CircuitState.OPEN
+            self._stats.opened_at = now
+            self._stats.success_count = 0
+            self._stats.total_opens += 1
+            self._stats.total_trips += 1
+
+    def force_open(self) -> None:
+        """Manually open circuit (for maintenance, etc.)."""
+        logger.warning(f"🔒 Manually opening circuit for {self.server_name}")
+        self._stats.state = CircuitState.OPEN
+        self._stats.opened_at = datetime.now(timezone.utc)
+        self._stats.total_opens += 1
+
+    def force_close(self) -> None:
+        """Manually close circuit (override)."""
+        logger.info(f"🔓 Manually closing circuit for {self.server_name}")
+        self._stats.state = CircuitState.CLOSED
+        self._stats.failure_count = 0
+        self._stats.success_count = 0
+        self._recent_failures.clear()
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get circuit breaker statistics."""
+        current_state = self._get_current_state()
+
+        stats = self._stats.to_dict()
+        stats["state"] = current_state.value  # Get current state
+        stats["recent_failures"] = len(self._recent_failures)
+        stats["is_available"] = current_state != CircuitState.OPEN
+
+        if self._stats.opened_at and current_state == CircuitState.OPEN:
+            elapsed = (datetime.now(timezone.utc) - self._stats.opened_at).total_seconds()
+            stats["seconds_until_half_open"] = max(0, self.config.timeout_seconds - elapsed)
+
+        return stats
+
+    def reset(self) -> None:
+        """Reset circuit breaker to initial state."""
+        logger.info(f"🔄 Resetting circuit breaker for {self.server_name}")
+        self._stats = CircuitBreakerStats(state=CircuitState.CLOSED)
+        self._recent_failures.clear()

msmtp/connection_pool.py

@@ -0,0 +1,302 @@
+"""SMTP connection pooling with circuit breaker and load balancing."""
+
+import asyncio
+import logging
+import ssl
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+import aiosmtplib
+
+from .circuit_breaker import CircuitBreaker, CircuitBreakerConfig
+from .exceptions import SMTPAuthenticationError, SMTPConnectionError
+from .types import SMTPServerConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionPoolException(Exception):
+    """Errors related to connection pool operations."""
+
+    pass
+
+
+def _create_circuit_breaker(
+    server_name: str = "default",
+    *,
+    failure_threshold: int = 5,
+    success_threshold: int = 3,
+    timeout_seconds: int = 60,
+    monitor_window_seconds: int = 300,
+) -> CircuitBreaker:
+    """Factory function to create a circuit breaker."""
+    return CircuitBreaker(
+        server_name=server_name,
+        config=CircuitBreakerConfig(
+            failure_threshold=failure_threshold,
+            success_threshold=success_threshold,
+            timeout_seconds=timeout_seconds,
+            monitor_window_seconds=monitor_window_seconds,
+        ),
+    )
+
+
+@dataclass
+class SMTPServerRuntime:
+    """Per-process mutable runtime state for an SMTP server."""
+
+    circuit_breaker: CircuitBreaker
+    current_minute_count: int = 0
+    current_hour_count: int = 0
+    total_sent: int = 0
+    total_failures: int = 0
+    consecutive_failures: int = 0
+    last_minute_reset: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    last_hour_reset: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    handshake_latencies: list[float] = field(default_factory=list)
+    send_latencies: list[float] = field(default_factory=list)
+
+    @property
+    def avg_handshake_latency(self) -> float | None:
+        """Get average connection handshake latency in seconds."""
+        if not self.handshake_latencies:
+            return None
+        return sum(self.handshake_latencies) / len(self.handshake_latencies)
+
+    @property
+    def avg_send_latency(self) -> float | None:
+        """Get average mail sending latency in seconds."""
+        if not self.send_latencies:
+            return None
+        return sum(self.send_latencies) / len(self.send_latencies)
+
+    def record_handshake(self, seconds: float) -> None:
+        """Record a connection handshake latency measurement."""
+        self.handshake_latencies.append(seconds)
+        if len(self.handshake_latencies) > 50:
+            self.handshake_latencies.pop(0)
+
+    def record_send(self, seconds: float) -> None:
+        """Record a mail sending latency measurement."""
+        self.send_latencies.append(seconds)
+        if len(self.send_latencies) > 50:
+            self.send_latencies.pop(0)
+
+
+class SMTPConnectionPool:
+    """
+    SMTP connection pool with health checks and circuit breaker.
+
+    Maintains a pool of persistent SMTP connections to reduce handshake overhead.
+    Includes health checks and automatic connection recycling.
+    """
+
+    def __init__(
+        self,
+        server: SMTPServerConfig,
+        max_connections: int = 10,
+        health_check_interval: int = 60,
+        max_idle_time: int = 300,
+    ):
+        """
+        Initialize connection pool.
+
+        Args:
+            server: SMTP server configuration
+            max_connections: Maximum pooled connections
+            health_check_interval: Seconds between health checks
+            max_idle_time: Recycle connection after this many idle seconds
+        """
+        self.server = server
+        self.max_connections = max_connections
+        self.health_check_interval = health_check_interval
+        self.max_idle_time = max_idle_time
+
+        self._pool: list[aiosmtplib.SMTP] = []
+        self._in_use: set[aiosmtplib.SMTP] = set()
+        self._lock = asyncio.Lock()
+        self._last_health_check = time.monotonic()
+
+        # Runtime state
+        self.runtime = SMTPServerRuntime(
+            circuit_breaker=_create_circuit_breaker(server.name or server.host)
+        )
+
+    async def acquire(self) -> aiosmtplib.SMTP:
+        """
+        Acquire a connection from the pool.
+
+        Returns:
+            SMTP connection
+
+        Raises:
+            ConnectionPoolException: If no connections available
+        """
+        async with self._lock:
+            # Try to get from pool
+            while self._pool:
+                conn = self._pool.pop()
+                if await self._is_healthy(conn):
+                    self._in_use.add(conn)
+                    return conn
+                # Unhealthy, close it
+                try:
+                    await conn.quit()
+                except Exception:
+                    pass
+
+            # Create new connection if under limit
+            if len(self._in_use) < self.max_connections:
+                conn = await self._create_connection()
+                self._in_use.add(conn)
+                return conn
+
+            raise ConnectionPoolException("No connections available")
+
+    async def release(self, conn: aiosmtplib.SMTP) -> None:
+        """Release a connection back to the pool."""
+        async with self._lock:
+            if conn in self._in_use:
+                self._in_use.remove(conn)
+                if await self._is_healthy(conn):
+                    self._pool.append(conn)
+                else:
+                    try:
+                        await conn.quit()
+                    except Exception:
+                        pass
+
+    async def _create_connection(self) -> aiosmtplib.SMTP:
+        """Create a new SMTP connection with SSL verification."""
+        start = time.perf_counter()
+
+        # Prepare SSL context
+        tls_context = self.server.ssl_context
+        if tls_context is None and (self.server.use_tls or self.server.use_ssl):
+            tls_context = ssl.create_default_context()
+
+            # Configure SSL verification
+            if not self.server.verify_ssl:
+                tls_context.check_hostname = False
+                tls_context.verify_mode = ssl.CERT_NONE
+                logger.warning(
+                    "ssl_verification_disabled",
+                    extra={
+                        "server": self.server.name,
+                        "host": self.server.host,
+                        "port": self.server.port,
+                    },
+                )
+
+        try:
+            smtp = aiosmtplib.SMTP(
+                hostname=self.server.host,
+                port=self.server.port,
+                timeout=self.server.timeout,
+                use_tls=self.server.use_ssl,
+                tls_context=tls_context,
+            )
+
+            await smtp.connect()
+
+            if self.server.use_tls and not self.server.use_ssl:
+                await smtp.starttls(tls_context=tls_context)
+
+            if self.server.username:
+                password = self.server.get_password()
+                await smtp.login(self.server.username, password)
+
+            # Record handshake latency
+            latency = time.perf_counter() - start
+            self.runtime.record_handshake(latency)
+
+            logger.info(
+                "smtp_connection_created",
+                extra={
+                    "server": self.server.name,
+                    "host": self.server.host,
+                    "port": self.server.port,
+                    "handshake_ms": latency * 1000,
+                    "use_tls": self.server.use_tls,
+                    "use_ssl": self.server.use_ssl,
+                    "verify_ssl": self.server.verify_ssl,
+                },
+            )
+
+            return smtp
+
+        except aiosmtplib.SMTPAuthenticationError as e:
+            logger.error(
+                "smtp_auth_failed",
+                extra={
+                    "server": self.server.name,
+                    "host": self.server.host,
+                    "username": self.server.username,
+                    "error": str(e),
+                },
+            )
+            raise SMTPAuthenticationError(f"Authentication failed: {e}") from e
+        except Exception as e:
+            logger.error(
+                "smtp_connection_failed",
+                extra={
+                    "server": self.server.name,
+                    "host": self.server.host,
+                    "port": self.server.port,
+                    "error_type": type(e).__name__,
+                    "error": str(e)[:200],
+                },
+            )
+            raise SMTPConnectionError(f"Connection failed: {e}") from e
+
+    async def _is_healthy(self, conn: aiosmtplib.SMTP) -> bool:
+        """Check if connection is healthy."""
+        try:
+            # Try NOOP command
+            await asyncio.wait_for(conn.noop(), timeout=5.0)
+            return True
+        except Exception:
+            return False
+
+    async def close_all(self) -> None:
+        """Close all connections in the pool."""
+        logger.info(
+            "closing_connection_pool",
+            extra={
+                "server": self.server.name,
+                "pooled_connections": len(self._pool),
+                "in_use_connections": len(self._in_use),
+            },
+        )
+
+        async with self._lock:
+            for conn in self._pool:
+                try:
+                    await conn.quit()
+                except Exception as e:
+                    logger.debug("connection_close_error", extra={"error": str(e)})
+            self._pool.clear()
+
+            for conn in self._in_use:
+                try:
+                    await conn.quit()
+                except Exception as e:
+                    logger.debug("connection_close_error", extra={"error": str(e)})
+            self._in_use.clear()
+
+
+class AsyncConnectionPool:
+    """Async context manager wrapper for connection pool."""
+
+    def __init__(self, pool: SMTPConnectionPool):
+        self.pool = pool
+        self._conn: aiosmtplib.SMTP | None = None
+
+    async def __aenter__(self) -> aiosmtplib.SMTP:
+        self._conn = await self.pool.acquire()
+        return self._conn
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):  # type: ignore[no-untyped-def]
+        if self._conn:
+            await self.pool.release(self._conn)