crypticorn-utils 0.1.0__py3-none-any.whl

crypticorn_utils/exceptions.py

@@ -0,0 +1,183 @@
+import json
+import logging
+from typing import Any, Optional
+
+from crypticorn_utils.errors import (
+    ApiError,
+    ApiErrorIdentifier,
+    ApiErrorLevel,
+    ApiErrorType,
+)
+from fastapi import FastAPI
+from fastapi import HTTPException as FastAPIHTTPException
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError, ResponseValidationError
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+try:
+    from enum import StrEnum
+except ImportError:
+    from strenum import StrEnum
+
+_logger = logging.getLogger("crypticorn")
+
+
+class _ExceptionType(StrEnum):
+    """The protocol the exception is called from"""
+
+    HTTP = "http"
+    WEBSOCKET = "websocket"
+
+
+class ExceptionDetail(BaseModel):
+    """Exception details returned to the client."""
+
+    message: Optional[str] = Field(None, description="An additional error message")
+    code: ApiErrorIdentifier = Field(..., description="The unique error code")
+    type: ApiErrorType = Field(..., description="The type of error")
+    level: ApiErrorLevel = Field(..., description="The level of the error")
+    status_code: int = Field(..., description="The HTTP status code")
+    details: Any = Field(None, description="Additional details about the error")
+
+
+class ExceptionContent(BaseModel):
+    """Exception content used when raising an exception."""
+
+    error: ApiError = Field(..., description="The unique error code")
+    message: Optional[str] = Field(None, description="An additional error message")
+    details: Any = Field(None, description="Additional details about the error")
+
+    def enrich(
+        self, _type: Optional[_ExceptionType] = _ExceptionType.HTTP
+    ) -> ExceptionDetail:
+        return ExceptionDetail(
+            message=self.message,
+            code=self.error.identifier,
+            type=self.error.type,
+            level=self.error.level,
+            status_code=(
+                self.error.http_code
+                if _type == _ExceptionType.HTTP
+                else self.error.websocket_code
+            ),
+            details=self.details,
+        )
+
+
+class HTTPException(FastAPIHTTPException):
+    """A custom HTTP exception wrapper around FastAPI's HTTPException.
+    It allows for a more structured way to handle errors, with a message and an error code. The status code is being derived from the detail's error.
+        The ApiError class is the source of truth. If the error is not yet implemented, there are fallbacks in place.
+    """
+
+    def __init__(
+        self,
+        content: ExceptionContent,
+        headers: Optional[dict[str, str]] = None,
+        _type: Optional[_ExceptionType] = _ExceptionType.HTTP,
+    ):
+        self.content = content
+        self.headers = headers
+        assert isinstance(content, ExceptionContent)
+        body = content.enrich(_type)
+        super().__init__(
+            status_code=body.status_code,
+            detail=body.model_dump(mode="json"),
+            headers=headers,
+        )
+
+
+class WebSocketException(HTTPException):
+    """A WebSocketException is to be used for WebSocket connections. It is a wrapper around the HTTPException class to maintain the same structure, but using a different status code.
+    To be used in the same way as the HTTPException.
+    """
+
+    def __init__(
+        self, content: ExceptionContent, headers: Optional[dict[str, str]] = None
+    ):
+        super().__init__(content, headers, _type=_ExceptionType.WEBSOCKET)
+
+    @classmethod
+    def from_http_exception(cls, http_exception: HTTPException):
+        """Helper method to convert an HTTPException to a WebSocketException."""
+        return WebSocketException(
+            content=http_exception.content,
+            headers=http_exception.headers,
+        )
+
+
+async def general_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Default exception handler for all exceptions."""
+    body = ExceptionContent(message=str(exc), error=ApiError.UNKNOWN_ERROR)
+    http_exc = HTTPException(content=body)
+    res = JSONResponse(
+        status_code=http_exc.status_code,
+        content=http_exc.detail,
+        headers=http_exc.headers,
+    )
+    _logger.error(f"General error: {json.loads(res.__dict__.get('body'))}")
+    return res
+
+
+async def request_validation_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    """Exception handler for all request validation errors."""
+    body = ExceptionContent(message=str(exc), error=ApiError.INVALID_DATA_REQUEST)
+    http_exc = HTTPException(content=body)
+    res = JSONResponse(
+        status_code=http_exc.status_code,
+        content=http_exc.detail,
+        headers=http_exc.headers,
+    )
+    _logger.error(f"Request validation error: {json.loads(res.__dict__.get('body'))}")
+    return res
+
+
+async def response_validation_handler(
+    request: Request, exc: ResponseValidationError
+) -> JSONResponse:
+    """Exception handler for all response validation errors."""
+    body = ExceptionContent(message=str(exc), error=ApiError.INVALID_DATA_RESPONSE)
+    http_exc = HTTPException(content=body)
+    res = JSONResponse(
+        status_code=http_exc.status_code,
+        content=http_exc.detail,
+        headers=http_exc.headers,
+    )
+    _logger.error(f"Response validation error: {json.loads(res.__dict__.get('body'))}")
+    return res
+
+
+async def http_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    """Exception handler for HTTPExceptions. It unwraps the HTTPException and returns the detail in a flat JSON response."""
+    res = JSONResponse(
+        status_code=exc.status_code, content=exc.detail, headers=exc.headers
+    )
+    _logger.error(f"HTTP error: {json.loads(res.__dict__.get('body'))}")
+    return res
+
+
+def register_exception_handlers(app: FastAPI):
+    """Utility to register serveral exception handlers in one go. Catches Exception, HTTPException and Data Validation errors, logs them and responds with a unified json body."""
+    app.add_exception_handler(Exception, general_handler)
+    app.add_exception_handler(FastAPIHTTPException, http_handler)
+    app.add_exception_handler(RequestValidationError, request_validation_handler)
+    app.add_exception_handler(ResponseValidationError, response_validation_handler)
+
+
+exception_response = {
+    "default": {"model": ExceptionDetail, "description": "Error response"}
+}
+
+
+class CrypticornException(Exception):
+    """A custom exception class for Crypticorn."""
+
+    def __init__(self, error: ApiError, message: str = None):
+        self.message = message
+        self.error = error
+
+    def __str__(self):
+        return f"{self.error.identifier}: {self.message}"

crypticorn_utils/logging.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from datetime import datetime
+from logging.handlers import RotatingFileHandler
+
+from crypticorn_utils.ansi_colors import AnsiColors as C
+from crypticorn_utils.mixins import ValidateEnumMixin
+
+try:
+    from enum import StrEnum
+except ImportError:
+    from strenum import StrEnum
+
+
+class LogLevel(ValidateEnumMixin, StrEnum):
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+    @classmethod
+    def get_color(cls, level: str) -> str:
+        """Get the ansi color based on the log level."""
+        if level == cls.DEBUG:
+            return C.GREEN_BRIGHT
+        elif level == cls.INFO:
+            return C.BLUE_BRIGHT
+        elif level == cls.WARNING:
+            return C.YELLOW_BRIGHT
+        elif level == cls.ERROR:
+            return C.RED_BRIGHT
+        elif level == cls.CRITICAL:
+            return C.RED_BOLD
+        else:
+            return C.RESET
+
+    @staticmethod
+    def get_level(level: "LogLevel") -> int:
+        """Get the integer value from a log level name."""
+        return logging._nameToLevel.get(level, logging.INFO)
+
+    @staticmethod
+    def get_name(level: int) -> "LogLevel":
+        """Get the level name from the integer value of a log level."""
+        return LogLevel(logging._levelToName.get(level, "INFO"))
+
+
+_LOGFORMAT = (
+    f"{C.CYAN_BOLD}%(asctime)s{C.RESET} - "
+    f"{C.GREEN_BOLD}%(name)s{C.RESET} - "
+    f"%(levelcolor)s%(levelname)s{C.RESET} - "
+    f"%(message)s"
+)
+_DATEFMT = "%Y-%m-%d %H:%M:%S.%f:"
+
+
+class _CustomFormatter(logging.Formatter):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def format(self, record):
+        color = LogLevel.get_color(record.levelname)
+        record.levelcolor = color
+        return super().format(record)
+
+    def formatTime(self, record, datefmt=_DATEFMT):
+        dt = datetime.fromtimestamp(record.created)
+        s = dt.strftime(datefmt)
+        return s[:-3]  # Trim last 3 digits to get milliseconds
+
+
+def configure_logging(
+    name: str = None,
+    fmt: str = _LOGFORMAT,
+    datefmt: str = _DATEFMT,
+    stdout_level: int = logging.INFO,
+    file_level: int = logging.INFO,
+    log_file: str = None,
+    filters: list[logging.Filter] = [],
+) -> None:
+    """Configures the logging for the application.
+    Run this function as early as possible in the application (for example using the `lifespan` parameter in FastAPI).
+    Then use can use the default `logging.getLogger(__name__)` method to get the logger (or <name> if you set the name parameter).
+    :param name: The name of the logger. If not provided, the root logger will be used. Use a name if you use multiple loggers in the same application.
+    :param fmt: The format of the log message.
+    :param datefmt: The date format of the log message.
+    :param stdout_level: The level of the log message to be printed to the console.
+    :param file_level: The level of the log message to be written to the file. Only used if `log_file` is provided.
+    :param log_file: The file to write the log messages to.
+    :param filters: A list of filters to apply to the log handlers.
+    """
+    logger = logging.getLogger(name) if name else logging.getLogger()
+
+    if logger.handlers:  # clear existing handlers to avoid duplicates
+        logger.handlers.clear()
+
+    logger.setLevel(min(stdout_level, file_level))  # set to most verbose level
+
+    # Configure stdout handler
+    stdout_handler = logging.StreamHandler(sys.stdout)
+    stdout_handler.setLevel(stdout_level)
+    stdout_handler.setFormatter(_CustomFormatter(fmt=fmt, datefmt=datefmt))
+    for filter in filters:
+        stdout_handler.addFilter(filter)
+    logger.addHandler(stdout_handler)
+
+    # Configure file handler
+    if log_file:
+        os.makedirs(os.path.dirname(log_file), exist_ok=True)
+        file_handler = RotatingFileHandler(
+            log_file, maxBytes=10 * 1024 * 1024, backupCount=5
+        )
+        file_handler.setLevel(file_level)
+        file_handler.setFormatter(_CustomFormatter(fmt=fmt, datefmt=datefmt))
+        for filter in filters:
+            file_handler.addFilter(filter)
+        logger.addHandler(file_handler)
+
+    if name:
+        logger.propagate = False
+
+
+def disable_logging():
+    """Disable logging for the crypticorn logger."""
+    logger = logging.getLogger("crypticorn")
+    logger.disabled = True

crypticorn_utils/metrics.py

@@ -0,0 +1,32 @@
+# metrics/registry.py
+from prometheus_client import CollectorRegistry, Counter, Histogram
+from crypticorn_utils._migration import has_migrated
+
+registry = CollectorRegistry()
+
+if has_migrated:
+    HTTP_REQUESTS_COUNT = Counter(
+        "http_requests_total",
+        "Total HTTP requests",
+        ["method", "endpoint", "status_code", "auth_type"],
+        registry=registry,
+    )
+
+    HTTP_REQUEST_DURATION = Histogram(
+        "http_request_duration_seconds",
+        "HTTP request duration in seconds",
+        ["endpoint", "method"],
+        registry=registry,
+    )
+
+    REQUEST_SIZE = Histogram(
+        "http_request_size_bytes", "Size of HTTP request bodies", ["method", "endpoint"]
+    )
+
+
+    RESPONSE_SIZE = Histogram(
+        "http_response_size_bytes",
+        "Size of HTTP responses",
+        ["method", "endpoint"],
+        registry=registry,
+    )

crypticorn_utils/middleware.py

@@ -0,0 +1,125 @@
+import time
+import warnings
+from contextlib import asynccontextmanager
+
+from crypticorn_utils.logging import configure_logging
+from crypticorn_utils.warnings import CrypticornDeprecatedSince217
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.base import BaseHTTPMiddleware
+from typing_extensions import deprecated
+from crypticorn_utils.metrics import has_migrated
+
+if has_migrated:
+    from crypticorn_utils.metrics import (
+    HTTP_REQUEST_DURATION,
+    HTTP_REQUESTS_COUNT,
+    REQUEST_SIZE,
+    RESPONSE_SIZE,
+)
+    # otherwise prometheus reqisters metrics twice, resulting in an exception
+    class PrometheusMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next):
+
+            if "authorization" in request.headers:
+                auth_type = (
+                    request.headers["authorization"].split()[0]
+                    if " " in request.headers["authorization"]
+                    else "none"
+                )
+            elif "x-api-key" in request.headers:
+                auth_type = "X-API-KEY"
+            else:
+                auth_type = "none"
+
+            try:
+                endpoint = request.get(
+                    "route"
+                ).path  # use /time/{type} instead of dynamic route to avoid high cardinality
+            except Exception:
+                endpoint = request.url.path
+
+            start = time.perf_counter()
+            response = await call_next(request)
+            duration = time.perf_counter() - start
+
+            HTTP_REQUESTS_COUNT.labels(
+                method=request.method,
+                endpoint=endpoint,
+                status_code=response.status_code,
+                auth_type=auth_type,
+            ).inc()
+
+            try:
+                body = await request.body()
+                size = len(body)
+            except Exception:
+                size = 0
+
+            REQUEST_SIZE.labels(
+                method=request.method,
+                endpoint=endpoint,
+            ).observe(size)
+
+            try:
+                body = await response.body()
+                size = len(body)
+            except Exception:
+                size = 0
+
+            RESPONSE_SIZE.labels(
+                method=request.method,
+                endpoint=endpoint,
+            ).observe(size)
+
+            HTTP_REQUEST_DURATION.labels(
+                endpoint=endpoint,
+                method=request.method,
+            ).observe(duration)
+
+            return response
+
+
+@deprecated("Use add_middleware instead", category=None)
+def add_cors_middleware(app: "FastAPI"):
+    warnings.warn(
+        "add_cors_middleware is deprecated. Use add_middleware instead.",
+        CrypticornDeprecatedSince217,
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=[
+            "http://localhost:5173",  # vite dev server
+            "http://localhost:4173",  # vite preview server
+        ],
+        allow_origin_regex="^https://([a-zA-Z0-9-]+.)*crypticorn.(dev|com)/?$",  # matches (multiple or no) subdomains of crypticorn.dev and crypticorn.com
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+def add_middleware(app: "FastAPI"):
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=[
+            "http://localhost:5173",  # vite dev server
+            "http://localhost:4173",  # vite preview server
+        ],
+        allow_origin_regex="^https://([a-zA-Z0-9-]+.)*crypticorn.(dev|com)/?$",  # matches (multiple or no) subdomains of crypticorn.dev and crypticorn.com
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    if has_migrated:
+        app.add_middleware(PrometheusMiddleware)
+
+
+@asynccontextmanager
+async def default_lifespan(app: FastAPI):
+    """Default lifespan for the applications.
+    This is used to configure the logging for the application.
+    To override this, pass a different lifespan to the FastAPI constructor or call this lifespan within a custom lifespan.
+    """
+    configure_logging()
+    yield

crypticorn_utils/mixins.py

@@ -0,0 +1,68 @@
+import logging
+import warnings
+from enum import EnumMeta
+
+from crypticorn_utils.warnings import CrypticornDeprecatedSince28
+
+_logger = logging.getLogger("crypticorn")
+
+
+class ValidateEnumMixin:
+    """
+    Mixin for validating enum values manually.
+
+    ⚠️ Note:
+    This does NOT enforce validation automatically on enum creation.
+    It's up to the developer to call `Class.validate(value)` where needed.
+
+    Usage:
+        >>> class Color(ValidateEnumMixin, StrEnum):
+        >>>     RED = "red"
+        >>>     GREEN = "green"
+
+        >>> Color.validate("red")     # True
+        >>> Color.validate("yellow")  # False
+
+    Order of inheritance matters — the mixin must come first.
+    """
+
+    @classmethod
+    def validate(cls, value) -> bool:
+        """Validate if a value is in the enum. True if so, False otherwise."""
+        try:
+            cls(value)
+            return True
+        except ValueError:
+            return False
+
+
+# This Mixin will be removed in a future version. And has no effect from now on
+class ExcludeEnumMixin:
+    """(deprecated) Mixin to exclude enum from OpenAPI schema. We use this to avoid duplicating enums when generating client code from the openapi spec."""
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if cls.__name__.startswith("ExcludeEnumMixin"):
+            warnings.warn(
+                "The `ExcludeEnumMixin` class is deprecated. Should be removed from enums inheriting this class.",
+                category=CrypticornDeprecatedSince28,
+            )
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema, handler):
+        schema = handler(core_schema)
+        # schema.pop("enum", None)
+        return schema
+
+
+class ApiErrorFallback(EnumMeta):
+    """Fallback for enum members that are not yet published to PyPI."""
+
+    def __getattr__(cls, name):
+        # Let Pydantic/internal stuff pass silently ! fragile
+        if name.startswith("__") or name.startswith("_pytest"):
+            raise AttributeError(name)
+        _logger.warning(
+            f"Unknown enum member '{name}' - update crypticorn package or check for typos"
+        )
+        return cls.UNKNOWN_ERROR

crypticorn_utils/openapi.py

@@ -0,0 +1,10 @@
+default_tags = [
+    {
+        "name": "Status",
+        "description": "These endpoints contain status operations.",
+    },
+    {
+        "name": "Admin",
+        "description": "These endpoints contain debugging and monitoring operations. They require admin scopes.",
+    },
+]