Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

3.3 KB
Raw Blame
"""
Custom exceptions for the web module.

These exceptions are used to provide structured error handling
that can be caught by Flask error handlers and converted to
appropriate JSON responses.
"""

from typing import Any, Optional

from ..security import sanitize_error_details, sanitize_error_for_client


class WebAPIException(Exception):
    """Base exception for all web API related errors."""

    def __init__(
        self,
        message: str,
        status_code: int = 500,
        error_code: Optional[str] = None,
        details: Optional[dict[str, Any]] = None,
    ):
        """
        Initialize the web API exception.

        Args:
            message: Human-readable error message
            status_code: HTTP status code for the error
            error_code: Machine-readable error code for API consumers
            details: Additional error details/context
        """
        super().__init__(message)
        self.message = message
        self.status_code = status_code
        self.error_code = error_code or self.__class__.__name__
        self.details = details or {}

    def to_dict(self) -> dict[str, Any]:
        """Convert exception to dictionary for JSON response.

        This dict is returned straight to the client as a ``JSONResponse`` by
        the global ``WebAPIException`` handler registered in
        ``web/fastapi_app.py``. As a boundary backstop,
        the outgoing fields are scrubbed for credential shapes so that a future
        raise site, subclass, or external caller that lets a credential-bearing
        string in has it redacted before it ships:

        * ``message`` — through ``sanitize_error_for_client`` (credential
          redaction + control-char strip + 200-char cap; it is prose meant for
          display).
        * ``details`` string leaves — through ``sanitize_error_details`` (the
          shared helper, also used by ``NewsAPIException``).

        Redaction is credential-*shape* based (``Bearer``/``Authorization``,
        ``?api_key=``-style query params, known token prefixes, URL userinfo),
        so legitimate text is unchanged. It deliberately does NOT try to catch
        DSN userinfo beyond URL form, SQL, schema, or filesystem paths. The
        ``status`` literal and ``error_code`` are left untouched (``status_code``
        is not part of this body — it is applied by the handler as the HTTP
        status). ``self.message`` / ``self.details`` are not mutated, so the raw
        text is retained on the exception object for server-side diagnosis.
        """
        result: dict[str, Any] = {
            "status": "error",
            "message": sanitize_error_for_client(self.message),
            "error_code": self.error_code,
        }
        if self.details:
            result["details"] = sanitize_error_details(self.details)
        return result


class AuthenticationRequiredError(WebAPIException):
    """Raised when authentication is required but not available."""

    def __init__(
        self,
        message: str = "Authentication required: Please refresh the page and log in again.",
        username: Optional[str] = None,
    ):
        details = {}
        if username:
            details["username"] = username
        super().__init__(
            message,
            status_code=401,
            error_code="AUTHENTICATION_REQUIRED",
            details=details,
        )