fastapi-ext-pkg 0.4.4__tar.gz → 0.7.0__tar.gz

fastapi_ext_pkg-0.7.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: fastapi-ext-pkg
+Version: 0.7.0
+Summary: A well-tailored utility set for FastAPI.
+Author-email: Dotz Developers <devs-dotz@dotz.com>
+Project-URL: Repository, https://github.com/DotzInc/fastapi-ext-pkg
+Keywords: fastapi,utilities
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Provides-Extra: apm
+Requires-Dist: elastic-apm<7,>=6.20; extra == "apm"
+
+# FastAPI Extension Package
+
+![Tests](https://github.com/DotzInc/fastapi-ext-pkg/actions/workflows/tests.yml/badge.svg?event=push)
+![PyPI - Version](https://img.shields.io/pypi/v/fastapi-ext-pkg)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fastapi-ext-pkg)
+
+A well-tailored utility set for FastAPI.
+
+## Requirements
+
+* Python 3.8+
+
+## Installation
+
+To install FastAPI Extension Package, use pip:
+
+```sh
+pip install fastapi-ext-pkg
+```
+
+## Shared middleware configuration
+
+`configure_middlewares` registers middleware on an existing FastAPI application
+before startup. Configure service values centrally while preserving routers and
+lifespan:
+
+```python
+from fastapi_extras.middlewares import configure_middlewares
+
+configure_middlewares(
+    app,
+    root_path=settings.ROOT_PATH,
+    apm_config=settings.ELASTIC_APM,
+    cors={"allow_origins": settings.ALLOW_ORIGINS},
+)
+```
+
+The default registration order is path removal, trace-header removal, APM,
+`extra_middlewares`, then CORS. Incoming requests traverse it in reverse. Use
+`order` to preserve a service-specific order; include every configured name
+exactly once. `MiddlewareSpec` defines custom middleware and named `overrides`
+for replacement or disabling (`enabled=False`).
+
+Use `root_path=None`, `remove_cloud_trace_headers=False`, `apm_enabled=False`,
+or `cors=None` to omit middleware. Pass either `apm_config` or `apm_client`.
+APM uses the upstream `elasticapm.contrib.starlette.ElasticAPM` by default and
+requires the optional `[apm]` dependency. This branch contains no custom APM
+implementation. To register another implementation supplied by the caller, pass
+`apm_middleware_class`; `apm_options` supplies its constructor options.

fastapi_ext_pkg-0.7.0/README.md

@@ -0,0 +1,49 @@
+# FastAPI Extension Package
+
+![Tests](https://github.com/DotzInc/fastapi-ext-pkg/actions/workflows/tests.yml/badge.svg?event=push)
+![PyPI - Version](https://img.shields.io/pypi/v/fastapi-ext-pkg)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fastapi-ext-pkg)
+
+A well-tailored utility set for FastAPI.
+
+## Requirements
+
+* Python 3.8+
+
+## Installation
+
+To install FastAPI Extension Package, use pip:
+
+```sh
+pip install fastapi-ext-pkg
+```
+
+## Shared middleware configuration
+
+`configure_middlewares` registers middleware on an existing FastAPI application
+before startup. Configure service values centrally while preserving routers and
+lifespan:
+
+```python
+from fastapi_extras.middlewares import configure_middlewares
+
+configure_middlewares(
+    app,
+    root_path=settings.ROOT_PATH,
+    apm_config=settings.ELASTIC_APM,
+    cors={"allow_origins": settings.ALLOW_ORIGINS},
+)
+```
+
+The default registration order is path removal, trace-header removal, APM,
+`extra_middlewares`, then CORS. Incoming requests traverse it in reverse. Use
+`order` to preserve a service-specific order; include every configured name
+exactly once. `MiddlewareSpec` defines custom middleware and named `overrides`
+for replacement or disabling (`enabled=False`).
+
+Use `root_path=None`, `remove_cloud_trace_headers=False`, `apm_enabled=False`,
+or `cors=None` to omit middleware. Pass either `apm_config` or `apm_client`.
+APM uses the upstream `elasticapm.contrib.starlette.ElasticAPM` by default and
+requires the optional `[apm]` dependency. This branch contains no custom APM
+implementation. To register another implementation supplied by the caller, pass
+`apm_middleware_class`; `apm_options` supplies its constructor options.

fastapi_ext_pkg-0.7.0/fastapi_ext_pkg.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: fastapi-ext-pkg
+Version: 0.7.0
+Summary: A well-tailored utility set for FastAPI.
+Author-email: Dotz Developers <devs-dotz@dotz.com>
+Project-URL: Repository, https://github.com/DotzInc/fastapi-ext-pkg
+Keywords: fastapi,utilities
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Provides-Extra: apm
+Requires-Dist: elastic-apm<7,>=6.20; extra == "apm"
+
+# FastAPI Extension Package
+
+![Tests](https://github.com/DotzInc/fastapi-ext-pkg/actions/workflows/tests.yml/badge.svg?event=push)
+![PyPI - Version](https://img.shields.io/pypi/v/fastapi-ext-pkg)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fastapi-ext-pkg)
+
+A well-tailored utility set for FastAPI.
+
+## Requirements
+
+* Python 3.8+
+
+## Installation
+
+To install FastAPI Extension Package, use pip:
+
+```sh
+pip install fastapi-ext-pkg
+```
+
+## Shared middleware configuration
+
+`configure_middlewares` registers middleware on an existing FastAPI application
+before startup. Configure service values centrally while preserving routers and
+lifespan:
+
+```python
+from fastapi_extras.middlewares import configure_middlewares
+
+configure_middlewares(
+    app,
+    root_path=settings.ROOT_PATH,
+    apm_config=settings.ELASTIC_APM,
+    cors={"allow_origins": settings.ALLOW_ORIGINS},
+)
+```
+
+The default registration order is path removal, trace-header removal, APM,
+`extra_middlewares`, then CORS. Incoming requests traverse it in reverse. Use
+`order` to preserve a service-specific order; include every configured name
+exactly once. `MiddlewareSpec` defines custom middleware and named `overrides`
+for replacement or disabling (`enabled=False`).
+
+Use `root_path=None`, `remove_cloud_trace_headers=False`, `apm_enabled=False`,
+or `cors=None` to omit middleware. Pass either `apm_config` or `apm_client`.
+APM uses the upstream `elasticapm.contrib.starlette.ElasticAPM` by default and
+requires the optional `[apm]` dependency. This branch contains no custom APM
+implementation. To register another implementation supplied by the caller, pass
+`apm_middleware_class`; `apm_options` supplies its constructor options.

{fastapi_ext_pkg-0.4.4 → fastapi_ext_pkg-0.7.0}/fastapi_ext_pkg.egg-info/SOURCES.txt

@@ -6,12 +6,22 @@ fastapi_ext_pkg.egg-info/dependency_links.txt
 fastapi_ext_pkg.egg-info/requires.txt
 fastapi_ext_pkg.egg-info/top_level.txt
 fastapi_extras/__init__.py
+fastapi_extras/apm/__init__.py
+fastapi_extras/apm/config.py
+fastapi_extras/apm/constants.py
+fastapi_extras/apm/decorators.py
+fastapi_extras/apm/labels.py
+fastapi_extras/apm/masking.py
+fastapi_extras/apm/middleware.py
+fastapi_extras/apm/processors.py
 fastapi_extras/databases/__init__.py
 fastapi_extras/databases/redis.py
 fastapi_extras/middlewares/__init__.py
+fastapi_extras/middlewares/configure.py
 fastapi_extras/middlewares/remove_cloud_trace_headers.py
 fastapi_extras/middlewares/remove_path.py
 fastapi_extras/orm/__init__.py
 fastapi_extras/orm/sqlalchemy.py
 fastapi_extras/security/__init__.py
-fastapi_extras/security/auth.py
+fastapi_extras/security/auth.py
+fastapi_extras/security/auth_async.py

fastapi_ext_pkg-0.7.0/fastapi_ext_pkg.egg-info/requires.txt

@@ -0,0 +1,5 @@
+fastapi
+httpx
+
+[apm]
+elastic-apm<7,>=6.20

fastapi_ext_pkg-0.7.0/fastapi_extras/apm/__init__.py

@@ -0,0 +1,19 @@
+from fastapi_extras.apm.config import build_apm_config
+from fastapi_extras.apm.constants import DEFAULT_SANITIZE_FIELD_NAMES
+from fastapi_extras.apm.decorators import capture_http_request
+from fastapi_extras.apm.labels import label_transaction
+from fastapi_extras.apm.masking import mask_sensitive_data, normalize_span_value
+from fastapi_extras.apm.middleware import ElasticAPMMiddleware
+from fastapi_extras.apm.processors import ALL_PROCESSORS, PROCESSORS
+
+__all__ = [
+    "ALL_PROCESSORS",
+    "DEFAULT_SANITIZE_FIELD_NAMES",
+    "PROCESSORS",
+    "ElasticAPMMiddleware",
+    "build_apm_config",
+    "capture_http_request",
+    "label_transaction",
+    "mask_sensitive_data",
+    "normalize_span_value",
+]

fastapi_ext_pkg-0.7.0/fastapi_extras/apm/config.py

@@ -0,0 +1,66 @@
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+import fastapi
+
+from fastapi_extras.apm.constants import (
+    DEFAULT_CAPTURE_BODY,
+    DEFAULT_CLOUD_PROVIDER,
+    DEFAULT_LOG_LEVEL,
+    DEFAULT_SANITIZE_FIELD_NAMES,
+)
+from fastapi_extras.apm.processors import ALL_PROCESSORS
+
+FieldNamesInput = Union[str, Iterable[str]]
+
+
+def parse_field_names(value: FieldNamesInput) -> List[str]:
+    items = value.split(",") if isinstance(value, str) else value
+    return [item.strip() for item in items if item.strip()]
+
+
+def unique(items: Iterable[str]) -> List[str]:
+    return list(dict.fromkeys(items))
+
+
+def has_credentials(server_url: Optional[str], secret_token: Optional[str]) -> bool:
+    return bool((server_url or "").strip() and (secret_token or "").strip())
+
+
+def build_apm_config(
+    service_name: str,
+    *,
+    server_url: Optional[str] = "",
+    secret_token: Optional[str] = "",
+    environment: str = "",
+    enabled: Optional[bool] = None,
+    log_level: str = DEFAULT_LOG_LEVEL,
+    capture_body: str = DEFAULT_CAPTURE_BODY,
+    sanitize_field_names: Optional[FieldNamesInput] = None,
+    extra_sanitize_field_names: FieldNamesInput = (),
+    extra_processors: Iterable[str] = (),
+    **overrides: Any,
+) -> Dict[str, Any]:
+    base_field_names = (
+        DEFAULT_SANITIZE_FIELD_NAMES
+        if sanitize_field_names is None
+        else parse_field_names(sanitize_field_names)
+    )
+    config: Dict[str, Any] = {
+        "ENABLED": has_credentials(server_url, secret_token) if enabled is None else enabled,
+        "SERVICE_NAME": service_name,
+        "SECRET_TOKEN": secret_token or "",
+        "SERVER_URL": server_url or "",
+        "ENVIRONMENT": environment,
+        "LOG_LEVEL": log_level,
+        "CLOUD_PROVIDER": DEFAULT_CLOUD_PROVIDER,
+        "FRAMEWORK_NAME": "fastapi",
+        "FRAMEWORK_VERSION": fastapi.__version__,
+        "CAPTURE_HEADERS": True,
+        "CAPTURE_BODY": capture_body,
+        "SANITIZE_FIELD_NAMES": unique(
+            [*base_field_names, *parse_field_names(extra_sanitize_field_names)]
+        ),
+        "PROCESSORS": (*ALL_PROCESSORS, *extra_processors),
+    }
+    config.update({key.upper(): value for key, value in overrides.items()})
+    return config

fastapi_ext_pkg-0.7.0/fastapi_extras/apm/constants.py

@@ -0,0 +1,46 @@
+EXTERNAL = "external"
+UNKNOWN = "UNKNOWN"
+UNKNOWN_STATUS_CODE = 999
+MAX_FIELD_LENGTH = 500
+MAX_RESPONSE_BODY_BYTES = 64 * 1024
+TRUNCATED_SUFFIX = "… [TRUNCATED]"
+UNREADABLE_RESPONSE = "<could not decode response>"
+RESPONSE_BODY_TOO_LARGE = "<response body too large>"
+RESPONSE_BODY_CONTEXT_KEY = "response_body"
+JSON_MEDIA_TYPE = "application/json"
+JSON_MEDIA_TYPE_SUFFIX = "+json"
+IDENTITY_ENCODING = "identity"
+DEFAULT_SANITIZE_FIELD_NAMES = (
+    "password",
+    "passwd",
+    "pwd",
+    "secret",
+    "*key",
+    "*token*",
+    "*session*",
+    "*credit*",
+    "*card*",
+    "*auth*",
+    "*principal*",
+    "set-cookie",
+    "pin",
+    "otp",
+    "*document*",
+    "*cpf*",
+    "*cnpj*",
+    "*email*",
+    "*phone*",
+    "*mobile*",
+    "*birth*",
+    "mother_name",
+    "rg",
+    "*account_number*",
+    "agency",
+    "pix_key",
+    "*cvv*",
+    "*salary*",
+    "*income*",
+)
+DEFAULT_LOG_LEVEL = "INFO"
+DEFAULT_CAPTURE_BODY = "off"
+DEFAULT_CLOUD_PROVIDER = "gcp"

fastapi_ext_pkg-0.7.0/fastapi_extras/apm/decorators.py

@@ -0,0 +1,127 @@
+import functools
+import inspect
+from typing import Any, Awaitable, Callable, Dict, Mapping, Optional, Tuple, TypeVar
+from urllib.parse import urlparse
+
+import elasticapm
+from elasticapm.conf.constants import MASK
+
+from fastapi_extras.apm.constants import EXTERNAL, UNKNOWN, UNKNOWN_STATUS_CODE, UNREADABLE_RESPONSE
+from fastapi_extras.apm.labels import to_label_value
+from fastapi_extras.apm.masking import (
+    FieldNames,
+    get_sanitize_field_names,
+    is_sensitive_key,
+    mask_sensitive_data,
+    normalize_span_value,
+)
+
+ReturnType = TypeVar("ReturnType")
+
+ERROR_BODY_ATTRIBUTES = ("errors", "content", "detail")
+
+
+def get_span_name(method: str, url: str) -> str:
+    parsed = urlparse(url)
+    path = parsed.path
+    if parsed.query:
+        path = f"{path}?{parsed.query}"
+    return f"{method.upper()} {path}"
+
+
+def is_outgoing_request(value: Any) -> bool:
+    return isinstance(getattr(value, "method", None), str) and isinstance(
+        getattr(value, "url", None), str
+    )
+
+
+def find_outgoing_request(args: Tuple[Any, ...], kwargs: Mapping[str, Any]) -> Any:
+    candidate = kwargs.get("request")
+    if is_outgoing_request(candidate):
+        return candidate
+    return next((arg for arg in args if is_outgoing_request(arg)), None)
+
+
+async def read_response(response: Any) -> Tuple[Optional[int], Any]:
+    status_code = getattr(response, "status", None)
+    if not isinstance(status_code, int):
+        status_code = getattr(response, "status_code", None)
+    if not isinstance(status_code, int):
+        return None, None
+    try:
+        text = response.text
+        body = text() if callable(text) else text
+        if inspect.isawaitable(body):
+            body = await body
+    except Exception:
+        body = UNREADABLE_RESPONSE
+    return status_code, body
+
+
+def read_error(error: Exception) -> Tuple[int, Any]:
+    status_code = getattr(error, "status_code", None)
+    if not isinstance(status_code, int):
+        return UNKNOWN_STATUS_CODE, repr(error)
+    body = {}
+    for attribute in ERROR_BODY_ATTRIBUTES:
+        value = getattr(error, attribute, None)
+        if value:
+            body[attribute] = value
+    return status_code, body
+
+
+def build_span_labels(
+    status_code: Optional[int],
+    response_body: Any,
+    payload: Any,
+    extra_labels: Optional[Mapping[str, Any]] = None,
+    field_names: Optional[FieldNames] = None,
+) -> Dict[str, Any]:
+    names = get_sanitize_field_names() if field_names is None else field_names
+    labels: Dict[str, Any] = {
+        "status_code": status_code,
+        "response_body": normalize_span_value(response_body),
+    }
+    if payload:
+        labels["payload"] = normalize_span_value(payload)
+    if extra_labels:
+        labels.update(extra_labels)
+    return {
+        key: MASK
+        if is_sensitive_key(key, names)
+        else to_label_value(mask_sensitive_data(value, names))
+        for key, value in labels.items()
+    }
+
+
+def capture_http_request(
+    func: Callable[..., Awaitable[ReturnType]],
+) -> Callable[..., Awaitable[ReturnType]]:
+    @functools.wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> ReturnType:
+        request = find_outgoing_request(args, kwargs)
+        method = getattr(request, "method", UNKNOWN)
+        url = getattr(request, "url", UNKNOWN)
+        payload = getattr(request, "payload", None)
+        status_code: Optional[int] = None
+        response_body: Any = None
+
+        async with elasticapm.async_capture_span(
+            get_span_name(method, url), span_type=EXTERNAL
+        ) as span:
+            try:
+                response = await func(*args, **kwargs)
+                status_code, response_body = await read_response(response)
+                return response
+            except Exception as error:
+                status_code, response_body = read_error(error)
+                raise
+            finally:
+                if span:
+                    span.label(
+                        **build_span_labels(
+                            status_code, response_body, payload, kwargs.get("labels")
+                        )
+                    )
+
+    return wrapper

fastapi_ext_pkg-0.7.0/fastapi_extras/apm/labels.py

@@ -0,0 +1,20 @@
+import json
+from typing import Any, Iterable, Mapping
+
+import elasticapm
+
+from fastapi_extras.apm.masking import get_sanitize_field_names, sanitize, truncate
+
+
+def to_label_value(value: Any) -> Any:
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, default=str)
+    return value
+
+
+def label_transaction(data: Mapping[str, Any], keys: Iterable[str]) -> None:
+    labels = {key: data[key] for key in keys if data.get(key) is not None}
+    if not labels:
+        return
+    safe_labels = truncate(sanitize(labels, get_sanitize_field_names()))
+    elasticapm.label(**{key: to_label_value(value) for key, value in safe_labels.items()})

fastapi_ext_pkg-0.7.0/fastapi_extras/apm/masking.py

@@ -0,0 +1,87 @@
+import base64
+import json
+import logging
+from typing import Any, Optional, Pattern, Sequence
+
+import elasticapm
+from elasticapm.conf.constants import BASE_SANITIZE_FIELD_NAMES, MASK
+from pydantic import BaseModel
+
+from fastapi_extras.apm.constants import MAX_FIELD_LENGTH, TRUNCATED_SUFFIX
+
+logger = logging.getLogger(__name__)
+
+FieldNames = Sequence[Pattern]
+
+
+def get_sanitize_field_names() -> FieldNames:
+    client = elasticapm.get_client()
+    if client is None:
+        return BASE_SANITIZE_FIELD_NAMES
+    return client.config.sanitize_field_names
+
+
+def is_sensitive_key(key: Any, field_names: FieldNames) -> bool:
+    if not isinstance(key, str):
+        return False
+    normalized = key.strip().lower()
+    return any(pattern.match(normalized) for pattern in field_names)
+
+
+def sanitize(data: Any, field_names: FieldNames) -> Any:
+    if isinstance(data, dict):
+        return {
+            key: MASK if is_sensitive_key(key, field_names) else sanitize(value, field_names)
+            for key, value in data.items()
+        }
+    if isinstance(data, (list, tuple)):
+        return [sanitize(item, field_names) for item in data]
+    return data
+
+
+def truncate(data: Any, max_length: int = MAX_FIELD_LENGTH) -> Any:
+    if isinstance(data, dict):
+        return {key: truncate(value, max_length) for key, value in data.items()}
+    if isinstance(data, (list, tuple)):
+        return [truncate(item, max_length) for item in data]
+    if data is None or isinstance(data, (bool, int, float)):
+        return data
+    text = data if isinstance(data, str) else str(data)
+    if len(text) > max_length:
+        return text[:max_length] + TRUNCATED_SUFFIX
+    return text
+
+
+def normalize_span_value(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        dump = getattr(value, "model_dump", None) or value.dict
+        return dump()
+    if isinstance(value, (bytes, bytearray)):
+        try:
+            return bytes(value).decode("utf-8")
+        except UnicodeDecodeError:
+            return base64.b64encode(bytes(value)).decode("ascii")
+    return value
+
+
+def parse_json(value: str) -> Any:
+    try:
+        return json.loads(value)
+    except ValueError:
+        return value
+
+
+def mask_sensitive_data(
+    data: Any,
+    field_names: Optional[FieldNames] = None,
+    max_length: int = MAX_FIELD_LENGTH,
+) -> Any:
+    names = get_sanitize_field_names() if field_names is None else field_names
+    try:
+        value = normalize_span_value(data)
+        if isinstance(value, str):
+            value = parse_json(value)
+        return truncate(sanitize(value, names), max_length)
+    except Exception:
+        logger.exception("Could not mask APM data")
+        return MASK