telegram-sendmail 1.0.0__py3-none-any.whl

telegram_sendmail/__init__.py

@@ -0,0 +1,13 @@
+"""
+Telegram Sendmail Bridge
+
+A drop-in `sendmail` replacement that forwards system emails to Telegram.
+
+This package is the sole source of truth for the project version.
+Hatchling reads `__version__` from this file via the `[tool.hatch.version]`
+path defined in `pyproject.toml`.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Theodosios Divolis"
+__license__ = "MIT"

telegram_sendmail/__main__.py

@@ -0,0 +1,480 @@
+"""
+CLI entry point for telegram-sendmail.
+
+This module is the sole owner of:
+- `argparse` argument parsing
+- Logging infrastructure bootstrap (syslog or console)
+- Top-level exception-to-exit-code mapping
+- Pipeline wiring (config -> spool -> parse -> send)
+
+It is the only module in the package that calls `sys.exit`.
+
+Entry point
+-----------
+The `main` function is registered in `pyproject.toml` under
+`[project.scripts]` and is invoked by the `telegram-sendmail`
+executable generated by the build backend.
+
+Exit codes
+----------
+- `0`  (EX_OK)       — message delivered successfully.
+- `1`  (EX_ERROR)    — operational failure (parse error, Telegram API error,
+                       interactive invocation, or unexpected exception).
+- `75` (EX_TEMPFAIL) — transient network failure (HTTP 429 or 5xx); the
+                       calling daemon should re-queue and retry.
+- `78` (EX_CONFIG)   — configuration error (missing/invalid config file).
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import logging.handlers
+import sys
+from collections.abc import Callable
+
+from telegram_sendmail import __version__
+from telegram_sendmail.client import _RETRY_STATUS_CODES, TelegramClient
+from telegram_sendmail.config import AppConfig, ConfigLoader
+from telegram_sendmail.exceptions import (
+    ConfigurationError,
+    ParsingError,
+    SpoolError,
+    TelegramAPIError,
+    TelegramSendmailError,
+)
+from telegram_sendmail.parser import EmailParser
+from telegram_sendmail.smtp import SMTPServer
+from telegram_sendmail.spool import MailSpooler
+
+logger = logging.getLogger(__name__)
+
+# EX_TEMPFAIL is defined in OS on POSIX; hardcode the value for portability
+_EX_OK = 0
+_EX_ERROR = 1
+_EX_TEMPFAIL = 75
+_EX_CONFIG = 78
+
+# Pipe-mode read cap matches the SMTP SIZE limit advertised in smtp.py so that
+# both entry points enforce the same ceiling consistently.
+_MAX_PIPE_SIZE: int = 10_485_760  # 10 MiB
+_PIPE_READ_CHUNK: int = 65_536
+
+
+# --------------------------------------------------------------------------
+# Delivery pipeline
+# --------------------------------------------------------------------------
+
+
+def _deliver(
+    raw_email: str,
+    sender_override: str | None,
+    config: AppConfig,
+) -> None:
+    """
+    Run the full email delivery pipeline for a single message.
+
+    Pipeline order:
+    1. **Spool**  — archive the raw email. Non-fatal: a `SpoolError` is
+                    logged at WARNING level and delivery continues.
+    2. **Parse**  — decode MIME structure and convert body to Telegram markup.
+    3. **Format** — wrap in the Telegram message envelope with truncation.
+    4. **Send**   — deliver via the Telegram Bot API.
+
+    Args:
+        raw_email:       Raw RFC 2822 email string.
+        sender_override: Envelope sender from `-f`/`-r` flag or SMTP
+                         `MAIL FROM`. Overrides the `From` header.
+        config:          Resolved `AppConfig` instance.
+
+    Raises:
+        ParsingError:     If the email body cannot be decoded.
+        TelegramAPIError: If Telegram delivery fails after all retries.
+    """
+    spooler = MailSpooler(config)
+    try:
+        spooler.write(raw_email)
+    except SpoolError:
+        pass  # Warning already emitted by MailSpooler.write
+
+    parser = EmailParser(config)
+    parsed = parser.parse(raw_email, sender_override=sender_override)
+    text = parser.format_for_telegram(parsed)
+
+    with TelegramClient(config) as client:
+        client.send(text)
+
+
+def _make_smtp_handler(config: AppConfig) -> Callable[[str, str | None], None]:
+    """
+    Return a closure that binds `config` to `_deliver` for use as the
+    `SMTPServer.on_message` callback.
+    """
+
+    def handler(raw_email: str, envelope_sender: str | None) -> None:
+        _deliver(raw_email, envelope_sender, config)
+
+    return handler
+
+
+def _bounded_stdin_read() -> str:
+    """
+    Read up to `_MAX_PIPE_SIZE` characters from `sys.stdin` in chunks.
+
+    Reading in fixed-size chunks prevents a single `sys.stdin.read()` call
+    from loading an arbitrarily large payload into memory before any
+    downstream truncation occurs. Once the accumulated size exceeds
+    `_MAX_PIPE_SIZE`, the overflow is drained without buffering and a
+    `WARNING` is emitted so syslog records the event; delivery continues
+    with the collected portion.
+
+    Returns:
+        The email content, at most `_MAX_PIPE_SIZE` characters long.
+    """
+    chunks: list[str] = []
+    total = 0
+    oversized = False
+
+    while True:
+        chunk = sys.stdin.read(_PIPE_READ_CHUNK)
+        if not chunk:
+            break
+
+        if oversized:
+            # Drain without buffering so the feeding process is not blocked.
+            continue
+
+        if total + len(chunk) > _MAX_PIPE_SIZE:
+            chunks.append(chunk[: _MAX_PIPE_SIZE - total])
+            total = _MAX_PIPE_SIZE
+            oversized = True
+        else:
+            chunks.append(chunk)
+            total += len(chunk)
+
+    if oversized:
+        logger.warning(
+            "Pipe-mode stdin exceeded %d bytes; input truncated to limit",
+            _MAX_PIPE_SIZE,
+        )
+
+    return "".join(chunks)
+
+
+# --------------------------------------------------------------------------
+# Logging bootstrap
+# --------------------------------------------------------------------------
+
+_SYSLOG_ADDRESS = "/dev/log"
+_SYSLOG_SOCKET_FALLBACK = "/var/run/syslog"
+
+
+class _TokenRedactFilter(logging.Filter):
+    """
+    Logging filter that replaces the bot token with a safe placeholder.
+
+    Installed on every root-logger handler after the token is known so that
+    third-party loggers (`urllib3`, `requests`) cannot leak the token at
+    DEBUG level.
+    """
+
+    def __init__(self, token: str) -> None:
+        super().__init__()
+        self._token = token
+        self._placeholder = f"{token[:8]}[…REDACTED…]"
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Redact the token from the fully formatted message."""
+        formatted = record.getMessage()
+        if self._token in formatted:
+            record.msg = formatted.replace(self._token, self._placeholder)
+            record.args = None
+        return True
+
+
+def _setup_logging(console: bool, debug: bool = False) -> None:
+    """
+    Configure the root logger before any module-level logger fires.
+
+    In production (`console=False`) log output goes to syslog under the
+    `LOG_MAIL` facility with the process identifier `telegram-sendmail`.
+    In console mode (`--console` flag) log output goes to `stderr` with
+    a human-readable format, which is useful for interactive debugging and
+    CI environments.
+
+    This function must be called before `ConfigLoader.load()` so that
+    configuration warnings are captured by the configured handler.
+
+    Args:
+        console: Route logs to `stderr` instead of syslog.
+        debug:   Set root log level to `DEBUG`; default is `INFO`.
+    """
+    level = logging.DEBUG if debug else logging.INFO
+
+    if console:
+        handler: logging.Handler = logging.StreamHandler(sys.stderr)
+        msgfmt = "[%(levelname)s] %(name)s: %(message)s"
+        handler.setFormatter(
+            logging.Formatter(msgfmt, datefmt="%Y-%m-%d %H:%M:%S"),
+        )
+    else:
+        syslog_address: str | tuple[str, int]
+        for candidate in (_SYSLOG_ADDRESS, _SYSLOG_SOCKET_FALLBACK):
+            try:
+                syslog_address = candidate
+                handler = logging.handlers.SysLogHandler(
+                    address=syslog_address,
+                    facility=logging.handlers.SysLogHandler.LOG_MAIL,
+                )
+                break
+            except OSError:
+                continue
+        else:
+            # Neither syslog socket is accessible; fall back to stderr so
+            # we do not silently swallow errors.
+            handler = logging.StreamHandler(sys.stderr)
+
+        msgfmt = "telegram-sendmail[%(process)d]: %(levelname)s %(name)s: %(message)s"
+        handler.setFormatter(
+            logging.Formatter(msgfmt, datefmt="%Y-%m-%d %H:%M:%S"),
+        )
+
+    logging.root.setLevel(level)
+    logging.root.addHandler(handler)
+
+
+# --------------------------------------------------------------------------
+# Argument parser
+# --------------------------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """
+    Construct the argument parser.
+
+    Sendmail-compatible flags are accepted and honoured or silently ignored
+    as documented. Positional recipient arguments (e.g.
+    `sendmail root@localhost`) are consumed via `nargs='*'` and discarded
+    so that system daemons calling `sendmail <recipient>` do not cause
+    argument parsing to fail.
+    """
+    parser = argparse.ArgumentParser(
+        prog="telegram-sendmail",
+        description="Forward system emails to Telegram.",
+        epilog="See https://github.com/theodiv/telegram-sendmail for documentation.",
+        add_help=False,
+    )
+
+    # Sendmail-compatible flags
+    parser.add_argument(
+        "-f",
+        "-r",
+        dest="sender",
+        metavar="ADDRESS",
+        help="set the envelope sender address (overrides the From header)",
+    )
+    parser.add_argument(
+        "-s",
+        dest="subject",
+        metavar="SUBJECT",
+        help="set the email subject (overrides the Subject header)",
+    )
+    parser.add_argument(
+        "-bs",
+        action="store_true",
+        help="run in SMTP server mode (read SMTP commands from stdin)",
+    )
+    parser.add_argument(
+        "-t",
+        action="store_true",
+        help=("extract recipients from message headers (ignored)"),
+    )
+    parser.add_argument(
+        "-i",
+        "-oi",
+        action="store_true",
+        dest="ignore_dots",
+        help="do not treat a line with only a dot as end-of-message (ignored)",
+    )
+
+    # Positional recipients consumed and discarded for drop-in compatibility.
+    # System tools like cron call: sendmail -oi -t root@localhost
+    parser.add_argument(
+        "recipients",
+        nargs="*",
+        metavar="RECIPIENT",
+        help="recipient addresses (ignored; all email is forwarded to Telegram chat)",
+    )
+
+    # Custom flags
+    parser.add_argument(
+        "--console",
+        action="store_true",
+        help="log to stderr instead of syslog (useful for debugging)",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="set log level to DEBUG",
+    )
+    parser.add_argument(
+        "--help",
+        action="help",
+        help="display this help message and exit",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"telegram-sendmail {__version__}",
+        help="output version information and exit",
+    )
+
+    return parser
+
+
+# --------------------------------------------------------------------------
+# Main entry point
+# --------------------------------------------------------------------------
+
+
+def main() -> None:
+    """
+    CLI entry point registered under `[project.scripts]` in `pyproject.toml`.
+
+    Dispatches to one of three operating modes:
+
+    - **SMTP mode** (`-bs`): runs `SMTPServer.run()` which speaks the
+      SMTP protocol on `stdin`/`stdout`.
+    - **Pipe mode** (stdin is not a TTY): reads a raw email from `stdin`
+      and delivers it via `_deliver()`.
+    - **Interactive mode** (stdin is a TTY): prints usage information and
+      exits with code `1`. This is not an error condition in the strict
+      sense; it just means the tool was invoked directly from a terminal.
+    """
+    arg_parser = _build_parser()
+    args, unknown = arg_parser.parse_known_args()
+
+    _setup_logging(console=args.console, debug=args.debug)
+
+    if unknown:
+        logger.debug("Ignoring unrecognised arguments: %s", " ".join(unknown))
+
+    if args.recipients:
+        logger.debug(
+            "Recipient argument(s) received and ignored (all mail goes to "
+            "configured Telegram chat_id): %s",
+            ", ".join(args.recipients),
+        )
+
+    # Loading configuration must happen after logging is set up so that
+    # permission warnings from ConfigLoader are captured.
+    try:
+        config = ConfigLoader.load()
+    except ConfigurationError as exc:
+        logger.error("Configuration error: %s", exc)
+        sys.exit(_EX_CONFIG)
+
+    token_filter = _TokenRedactFilter(config.token)
+    for handler in logging.root.handlers:
+        handler.addFilter(token_filter)
+
+    if args.bs:
+        sys.exit(_run_smtp_mode(config))
+    elif not sys.stdin.isatty():
+        sys.exit(_run_pipe_mode(args.sender, args.subject, config))
+    else:
+        sys.exit(_run_interactive_mode())
+
+
+def _run_smtp_mode(config: AppConfig) -> int:
+    """Launch the SMTP state machine and map exceptions to exit codes."""
+    logger.info("Starting SMTP server mode")
+    try:
+        server = SMTPServer(config, on_message=_make_smtp_handler(config))
+        server.run()
+        return _EX_OK
+    except KeyboardInterrupt:
+        logger.info("SMTP session interrupted by user")
+        return _EX_OK
+    except TelegramSendmailError as exc:
+        logger.error("%s", exc)
+        return _EX_ERROR
+    except Exception as exc:
+        logger.error("Unexpected error in SMTP mode: %s", exc)
+        return _EX_ERROR
+
+
+def _run_pipe_mode(
+    sender_override: str | None,
+    subject_override: str | None,
+    config: AppConfig,
+) -> int:
+    """Read email from stdin and deliver it; return an exit code."""
+    try:
+        raw_email = _bounded_stdin_read()
+    except Exception as exc:
+        logger.error("Failed to read email from stdin: %s", exc)
+        return _EX_ERROR
+
+    # The parser accepts sender_override; subject must be injected as a
+    # synthetic header when passed via the CLI flag so that the existing
+    # parser interface is not widened unnecessarily.
+    #
+    # RFC 2822 §2.2: field names are case-insensitive, so we must perform
+    # a case-insensitive search to avoid injecting a duplicate header when
+    # the original uses a non-canonical casing (e.g. "subject:" instead of
+    # "Subject:").
+    if subject_override and "subject:" not in raw_email[:500].lower():
+        raw_email = f"Subject: {subject_override}\n{raw_email}"
+
+    try:
+        _deliver(raw_email, sender_override, config)
+        return _EX_OK
+    except ParsingError as exc:
+        logger.error("Failed to parse email: %s", exc)
+        return _EX_ERROR
+    except TelegramAPIError as exc:
+        status = getattr(exc, "status_code", None)
+        if status is not None and status in _RETRY_STATUS_CODES:
+            # Transient HTTP failure: signal the caller to retry later.
+            logger.warning(
+                "Telegram API transient failure (HTTP %d); signalling EX_TEMPFAIL",
+                status,
+            )
+            return _EX_TEMPFAIL
+        logger.error("Telegram delivery failed: %s", exc)
+        return _EX_ERROR
+    except TelegramSendmailError as exc:
+        logger.error("%s", exc)
+        return _EX_ERROR
+    except Exception as exc:
+        logger.error("Unexpected error in pipe mode: %s", exc)
+        return _EX_ERROR
+
+
+def _run_interactive_mode() -> int:
+    """
+    Emit a helpful message when the tool is invoked directly from a terminal.
+
+    This is not a hard error, but the tool is not designed for interactive
+    use. Returns exit code 1 to signal to the shell that nothing was
+    delivered.
+    """
+    print(
+        f"telegram-sendmail {__version__}\n"
+        "\n"
+        "This tool is designed to be invoked by system daemons as a sendmail\n"
+        "replacement, not run interactively from a terminal.\n"
+        "\n"
+        "Pipe mode:  echo 'Subject: Test\\n\\nHello' | telegram-sendmail\n"
+        "SMTP mode:  telegram-sendmail -bs\n"
+        "Debug mode: echo 'test' | telegram-sendmail --console --debug\n"
+        "\n"
+        "For full documentation: telegram-sendmail --help",
+        file=sys.stderr,
+    )
+    return _EX_ERROR
+
+
+if __name__ == "__main__":
+    main()

telegram_sendmail/client.py

@@ -0,0 +1,201 @@
+"""
+Telegram Bot API client for telegram-sendmail.
+
+Public surface
+--------------
+- `TelegramClient` — sends formatted messages to a Telegram chat via the
+                     Bot API, with configurable retry and timeout behaviour.
+
+The client owns a `requests.Session` that is configured once at construction
+time and reused for all requests within a delivery pipeline invocation. It
+implements the context manager protocol so callers can use it with a `with`
+statement for deterministic session cleanup.
+"""
+
+from __future__ import annotations
+
+import logging
+from http import HTTPStatus
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from telegram_sendmail.config import AppConfig
+from telegram_sendmail.exceptions import TelegramAPIError
+
+logger = logging.getLogger(__name__)
+
+_TELEGRAM_API_BASE = "https://api.telegram.org"
+
+# HTTP status codes that warrant an automatic retry. 429 (Too Many Requests)
+# is the most common transient failure from the Telegram API.
+_RETRY_STATUS_CODES: frozenset[int] = frozenset({
+    HTTPStatus.TOO_MANY_REQUESTS,
+    HTTPStatus.INTERNAL_SERVER_ERROR,
+    HTTPStatus.BAD_GATEWAY,
+    HTTPStatus.SERVICE_UNAVAILABLE,
+    HTTPStatus.GATEWAY_TIMEOUT,
+})  # fmt: skip
+
+
+class TelegramClient:
+    """
+    Sends messages to the Telegram Bot API.
+
+    The underlying `requests.Session` is configured with an `HTTPAdapter`
+    backed by a `urllib3.Retry` strategy. Retry behaviour (attempt count,
+    backoff factor) is driven entirely by the values in `AppConfig`, so
+    operators can tune it for their network environment without touching code.
+
+    The class implements the context manager protocol. Although the session
+    is closed automatically when the object is garbage-collected, using the
+    context manager form is strongly preferred for production code paths
+    where deterministic cleanup matters::
+
+        with TelegramClient(config) as client:
+            client.send(message_text)
+
+    Args:
+        config: A fully resolved `AppConfig` instance.
+    """
+
+    def __init__(self, config: AppConfig) -> None:
+        self._token: str = config.token
+        self._chat_id: str = config.chat_id
+        self._timeout: int = config.telegram_timeout
+        self._disable_notification: bool = config.disable_notification
+        self._session: requests.Session = self._build_session(
+            max_retries=config.max_retries,
+            backoff_factor=config.backoff_factor,
+        )
+
+    def __enter__(self) -> TelegramClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Release the underlying `requests.Session` and its connections."""
+        self._session.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _build_session(max_retries: int, backoff_factor: float) -> requests.Session:
+        """
+        Construct a `requests.Session` with a retry-enabled HTTPS adapter.
+
+        Retries are attempted only on the HTTP methods and status codes that
+        are safe to repeat (POST on 429/5xx). The `raise_on_status` flag is
+        left `False` here; response status is checked explicitly in `send()`
+        so error messages can be extracted from the body.
+        """
+        retry_strategy = Retry(
+            total=max_retries,
+            backoff_factor=backoff_factor,
+            status_forcelist=list(_RETRY_STATUS_CODES),
+            allowed_methods=["POST"],
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        session = requests.Session()
+        session.mount("https://", adapter)
+
+        return session
+
+    def _api_url(self, method: str) -> str:
+        return f"{_TELEGRAM_API_BASE}/bot{self._token}/{method}"
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def send(self, text: str) -> None:
+        """
+        Send `text` to the configured Telegram chat.
+
+        Args:
+            text: Fully formatted message string with Telegram HTML markup.
+                  Must not exceed 4096 characters (Telegram hard limit).
+
+        Raises:
+            TelegramAPIError: If the API returns a non-OK response after all
+                              retry attempts are exhausted, or if the network
+                              request itself fails.
+        """
+        payload: dict[str, object] = {
+            "chat_id": self._chat_id,
+            "text": text,
+            "parse_mode": "HTML",
+            "disable_notification": self._disable_notification,
+            "link_preview_options": {"is_disabled": True},
+        }
+
+        logger.debug(
+            "Sending message to chat_id=%s (length=%d chars)",
+            self._chat_id,
+            len(text),
+        )
+
+        try:
+            response = self._session.post(
+                url=self._api_url("sendMessage"),
+                json=payload,
+                timeout=self._timeout,
+            )
+        except requests.exceptions.Timeout as exc:
+            raise TelegramAPIError(
+                f"Telegram API request timed out after {self._timeout}s: {exc}",
+            ) from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise TelegramAPIError(
+                f"Failed to connect to Telegram API: {exc}",
+            ) from exc
+        except requests.exceptions.RequestException as exc:
+            raise TelegramAPIError(
+                f"Telegram API request failed: {exc}",
+            ) from exc
+
+        self._check_response(response)
+        logger.info("Message delivered to Telegram (chat_id=%s)", self._chat_id)
+
+    def _check_response(self, response: requests.Response) -> None:
+        """
+        Validate the Telegram API JSON response.
+
+        The Telegram API always returns a JSON body with an `ok` boolean
+        field, even for error responses. We check that field in preference
+        to the HTTP status code because the API occasionally returns `200`
+        with `ok: false` for application-level errors (e.g. bad chat ID).
+
+        Raises:
+            TelegramAPIError: If `ok` is `false` or the response body
+                              cannot be decoded as JSON.
+        """
+        try:
+            body: dict[str, object] = response.json()
+        except ValueError as exc:
+            raise TelegramAPIError(
+                f"Telegram API returned non-JSON response "
+                f"(HTTP {response.status_code}): {response.text[:200]}",
+                status_code=response.status_code,
+            ) from exc
+
+        if not body.get("ok"):
+            description = body.get("description", "no description provided")
+            error_code = body.get("error_code", response.status_code)
+            raise TelegramAPIError(
+                f"Telegram API error {error_code}: {description}",
+                status_code=(
+                    int(error_code) if isinstance(error_code, (int, float)) else None
+                ),
+            )