hawkapi-sentry 0.1.0__py3-none-any.whl

hawkapi_sentry/__init__.py

@@ -0,0 +1,14 @@
+"""hawkapi-sentry — Sentry integration for HawkAPI."""
+
+from __future__ import annotations
+
+from hawkapi_sentry._middleware import SentryMiddleware
+from hawkapi_sentry._plugin import SentryPlugin
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SentryMiddleware",
+    "SentryPlugin",
+    "__version__",
+]

hawkapi_sentry/_context.py

@@ -0,0 +1,61 @@
+"""Request context helpers for Sentry event enrichment."""
+
+from __future__ import annotations
+
+from typing import Any
+
+_REDACT_HEADER_NAMES = frozenset(
+    [
+        "authorization",
+        "cookie",
+        "x-api-key",
+        "x-auth-token",
+        "proxy-authorization",
+    ]
+)
+
+_FILTERED = "[Filtered]"
+
+
+def redact_headers(headers: Any) -> dict[str, str]:
+    """Return a dict of headers with sensitive values masked.
+
+    Accepts any iterable of (key, value) pairs or an object with an .items()
+    method — covers both HawkAPI Headers (__iter__ yields tuples) and plain dicts.
+    """
+    result: dict[str, str] = {}
+    items: Any = headers.items() if hasattr(headers, "items") else headers
+    for key, value in items:
+        if key.lower() in _REDACT_HEADER_NAMES:
+            result[key] = _FILTERED
+        else:
+            result[key] = value
+    return result
+
+
+def status_class(status_code: int) -> str:
+    """Map an HTTP status code to an OTel/Sentry transaction status string."""
+    if status_code < 400:
+        return "ok"
+    if status_code < 500:
+        return "invalid_argument"
+    return "internal_error"
+
+
+def request_context(request: Any) -> dict[str, Any]:
+    """Build a Sentry request context dict from a HawkAPI Request."""
+    url: str = request.url
+    qs_raw: Any = request.query_string
+    qs: str = qs_raw.decode("latin-1") if hasattr(qs_raw, "decode") else str(qs_raw)
+    return {
+        "method": request.method,
+        "url": url,
+        "headers": redact_headers(request.headers),
+        "query_string": qs,
+    }
+
+
+# Keep underscore aliases so tests that import _redact_headers etc. still work
+_redact_headers = redact_headers
+_status_class = status_class
+_request_context = request_context

hawkapi_sentry/_middleware.py

@@ -0,0 +1,61 @@
+"""SentryMiddleware — per-request Sentry transaction and breadcrumb."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import sentry_sdk
+from hawkapi.middleware.base import Middleware
+from hawkapi.requests.request import Request
+from hawkapi.responses.json_response import JSONResponse
+from hawkapi.responses.response import Response
+
+from hawkapi_sentry._context import status_class
+
+
+class SentryMiddleware(Middleware):
+    """Starts a Sentry performance transaction for every HTTP request."""
+
+    async def before_request(self, request: Request) -> Request | Response | JSONResponse | None:
+        """Start a Sentry transaction and add a breadcrumb."""
+        method: str = request.method
+        path: str = request.path
+
+        # Extract traceparent for distributed tracing
+        traceparent = request.headers.get("sentry-trace") or request.headers.get("traceparent")
+
+        transaction = sentry_sdk.start_transaction(
+            op="http.server",
+            name=f"{method} {path}",
+            source="url",
+        )
+        if traceparent:
+            transaction.continuing_trace({"sentry-trace": traceparent})  # type: ignore[attr-defined]
+
+        request.state._sentry_tx = transaction  # type: ignore[attr-defined]
+        transaction.__enter__()  # type: ignore[attr-defined]
+
+        sentry_sdk.add_breadcrumb(
+            category="request",
+            message=f"{method} {path}",
+            level="info",
+        )
+
+        return None
+
+    async def after_response(
+        self, request: Request, response: Response | JSONResponse
+    ) -> Response | JSONResponse | None:
+        """Finish the Sentry transaction with HTTP metadata."""
+        tx: Any = getattr(getattr(request, "state", None), "_sentry_tx", None)
+        if tx is None:
+            return None
+
+        status_code: int = response.status_code
+        tx.set_tag("http.method", request.method)
+        tx.set_tag("http.status_code", str(status_code))
+        tx.set_tag("http.target", request.path)
+        tx.set_status(status_class(status_code))
+        tx.__exit__(None, None, None)  # type: ignore[attr-defined]
+
+        return None

hawkapi_sentry/_plugin.py

@@ -0,0 +1,127 @@
+"""SentryPlugin — HawkAPI Plugin that initialises and drives the Sentry SDK."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+import sentry_sdk
+from hawkapi.plugins import Plugin
+
+from hawkapi_sentry._context import redact_headers, request_context
+
+logger = logging.getLogger("hawkapi_sentry")
+
+_DEFAULT_IGNORE: tuple[int, ...] = (404, 401, 403)
+
+
+class SentryPlugin(Plugin):
+    """HawkAPI plugin that wires Sentry error and performance monitoring."""
+
+    def __init__(
+        self,
+        *,
+        dsn: str | None = None,
+        environment: str = "production",
+        release: str | None = None,
+        traces_sample_rate: float = 0.0,
+        profiles_sample_rate: float = 0.0,
+        include_user_data: bool = False,
+        user_getter: Callable[[Any], dict[str, Any]] | None = None,
+        before_send: Callable[[dict[str, Any], dict[str, Any]], dict[str, Any] | None]
+        | None = None,
+        tags: dict[str, str] | None = None,
+        ignore_status_codes: tuple[int, ...] = _DEFAULT_IGNORE,
+        transport: Any = None,
+    ) -> None:
+        self._dsn = dsn
+        self._environment = environment
+        self._release = release
+        self._traces_sample_rate = traces_sample_rate
+        self._profiles_sample_rate = profiles_sample_rate
+        self._include_user_data = include_user_data
+        self._user_getter = user_getter
+        self._before_send = before_send
+        self._tags: dict[str, str] = tags or {}
+        self._ignore_status_codes = ignore_status_codes
+        self._transport = transport
+        self._initialised = False
+
+    # ------------------------------------------------------------------
+    # Plugin hooks
+    # ------------------------------------------------------------------
+
+    def on_startup(self) -> None:
+        """Initialise the Sentry SDK. No-op when dsn is empty or None."""
+        if not self._dsn:
+            logger.info("hawkapi_sentry: no DSN provided — Sentry disabled (no-op mode)")
+            return
+
+        init_kwargs: dict[str, Any] = {
+            "dsn": self._dsn,
+            "environment": self._environment,
+            "traces_sample_rate": self._traces_sample_rate,
+            "profiles_sample_rate": self._profiles_sample_rate,
+        }
+        if self._release is not None:
+            init_kwargs["release"] = self._release
+        if self._before_send is not None:
+            init_kwargs["before_send"] = self._before_send
+        if self._transport is not None:
+            init_kwargs["transport"] = self._transport
+
+        sentry_sdk.init(**init_kwargs)
+        self._initialised = True
+
+        logger.info(
+            "hawkapi_sentry: Sentry initialised (environment=%s, traces_sample_rate=%s)",
+            self._environment,
+            self._traces_sample_rate,
+        )
+
+    def on_shutdown(self) -> None:
+        """Flush pending Sentry events before the process exits."""
+        sentry_sdk.flush(timeout=2.0)
+
+    def on_exception(self, request: Any, exc: Exception) -> None:
+        """Capture an unhandled exception in Sentry, enriched with request context."""
+        status_code = getattr(exc, "status_code", 500)
+        if status_code in self._ignore_status_codes:
+            return
+
+        with sentry_sdk.new_scope() as scope:
+            scope.set_context("request", request_context(request))
+
+            user_data = self._resolve_user(request)
+            if user_data:
+                scope.set_user(user_data)
+
+            for tag_key, tag_val in self._tags.items():
+                scope.set_tag(tag_key, tag_val)
+
+            sentry_sdk.capture_exception(exc)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _resolve_user(self, request: Any) -> dict[str, Any] | None:
+        """Return user dict from user_getter or request.state.user, or None."""
+        if self._user_getter is not None:
+            try:
+                return self._user_getter(request)
+            except Exception:
+                logger.debug("hawkapi_sentry: user_getter raised — skipping user context")
+                return None
+        if self._include_user_data:
+            state = getattr(request, "state", None)
+            if state is not None:
+                user = getattr(state, "user", None)
+                if isinstance(user, dict):
+                    return user  # type: ignore[return-value]
+        return None
+
+    def _redact_headers_helper(self, headers: Any) -> dict[str, str]:
+        """Delegate to module-level helper."""
+        return redact_headers(headers)

hawkapi_sentry-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: hawkapi-sentry
+Version: 0.1.0
+Summary: Sentry integration for HawkAPI — plugin + middleware
+Project-URL: Homepage, https://github.com/ashimov/hawkapi-sentry
+Project-URL: Repository, https://github.com/ashimov/hawkapi-sentry
+Project-URL: Issues, https://github.com/ashimov/hawkapi-sentry/issues
+Author-email: HawkAPI Contributors <hawkapi@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: error-tracking,hawkapi,monitoring,observability,sentry
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: hawkapi>=0.1.3
+Requires-Dist: sentry-sdk>=2.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hawkapi-sentry
+
+[![PyPI](https://img.shields.io/pypi/v/hawkapi-sentry)](https://pypi.org/project/hawkapi-sentry/)
+[![Python](https://img.shields.io/pypi/pyversions/hawkapi-sentry)](https://pypi.org/project/hawkapi-sentry/)
+[![License](https://img.shields.io/pypi/l/hawkapi-sentry)](LICENSE)
+[![CI](https://github.com/ashimov/hawkapi-sentry/actions/workflows/ci.yml/badge.svg)](https://github.com/ashimov/hawkapi-sentry/actions/workflows/ci.yml)
+[![Downloads](https://img.shields.io/pypi/dm/hawkapi-sentry)](https://pypi.org/project/hawkapi-sentry/)
+
+Sentry integration for [HawkAPI](https://github.com/ashimov/HawkAPI) — a plugin that initialises the Sentry SDK on startup and captures unhandled exceptions, plus a middleware that creates a performance transaction per request.
+
+---
+
+## Quickstart
+
+```bash
+pip install hawkapi-sentry
+```
+
+```python
+from hawkapi import HawkAPI
+from hawkapi_sentry import SentryPlugin, SentryMiddleware
+
+app = HawkAPI()
+
+app.add_plugin(
+    SentryPlugin(
+        dsn="https://key@sentry.io/123",
+        environment="production",
+        traces_sample_rate=0.1,
+    )
+)
+app.add_middleware(SentryMiddleware)
+```
+
+That's it. Every unhandled exception is captured with full request context; every request gets a Sentry performance transaction.
+
+---
+
+## `SentryPlugin` parameter reference
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `dsn` | `str \| None` | `None` | Sentry DSN. Empty/`None` = no-op mode (safe for local dev). |
+| `environment` | `str` | `"production"` | Sentry environment tag. |
+| `release` | `str \| None` | `None` | Release string. `None` = not set. |
+| `traces_sample_rate` | `float` | `0.0` | Fraction of transactions to sample for performance monitoring. |
+| `profiles_sample_rate` | `float` | `0.0` | Fraction of sampled transactions to profile. |
+| `include_user_data` | `bool` | `False` | When `True`, attach `request.state.user` dict to Sentry events. |
+| `user_getter` | `Callable[[Request], dict] \| None` | `None` | Custom callable to extract user data from the request. Takes priority over `include_user_data`. |
+| `before_send` | `Callable \| None` | `None` | Passed directly to `sentry_sdk.init`. Return `None` to drop an event. |
+| `tags` | `dict[str, str] \| None` | `None` | Global tags applied to every captured event. |
+| `ignore_status_codes` | `tuple[int, ...]` | `(404, 401, 403)` | HTTP status codes for which exceptions are **not** sent to Sentry. |
+
+---
+
+## Migration from `sentry-sdk[fastapi]`
+
+| FastAPI / starlette-sentry | hawkapi-sentry |
+|---|---|
+| `sentry_sdk.init(integrations=[StarletteIntegration(), FastApiIntegration()])` | `app.add_plugin(SentryPlugin(dsn=...))` |
+| `SentryAsgiMiddleware(app)` | `app.add_middleware(SentryMiddleware)` |
+| `before_send` kwarg to `sentry_sdk.init` | `SentryPlugin(before_send=...)` |
+| Manual `with sentry_sdk.push_scope() as scope: scope.set_user(...)` | `SentryPlugin(user_getter=lambda req: {...})` |
+
+The main difference: HawkAPI plugins own the SDK lifecycle, so you never call `sentry_sdk.init()` yourself — `SentryPlugin.on_startup()` does it.
+
+---
+
+## Development
+
+```bash
+# Clone and install in editable mode with dev extras
+git clone https://github.com/ashimov/hawkapi-sentry.git
+cd hawkapi-sentry
+uv sync --extra dev
+
+# Run tests
+uv run pytest tests/ -q
+
+# Lint
+uv run ruff check .
+uv run ruff format .
+
+# Type-check
+uv run pyright src/
+```
+
+---
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 HawkAPI Contributors.

hawkapi_sentry-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+hawkapi_sentry/__init__.py,sha256=60d3Nn5rfxisa4bUfuSfaWaw8jTGWAltMiKi37IoYHM,299
+hawkapi_sentry/_context.py,sha256=fqp4Vqc0HBrIbaSeNpIpASaYZFAY_r5s8-dpiMs-XmM,1749
+hawkapi_sentry/_middleware.py,sha256=p-EESG5_ZfE5e8ihMyGNHmdAdorxkkOJGLo23s-AO64,2152
+hawkapi_sentry/_plugin.py,sha256=UUKcAb45_Wv0Gbueiu1XY2zfTM_qzQaPILYz9bTl_BA,4703
+hawkapi_sentry-0.1.0.dist-info/METADATA,sha256=H_ystdiw6gQst9H08ZZkNCnoYevGLSgm9hdE-z-sBEc,4742
+hawkapi_sentry-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hawkapi_sentry-0.1.0.dist-info/licenses/LICENSE,sha256=_RpjhvsfLqqeG_gv2cRatjIxCTGXTpXhKU9jqLZXYa4,1077
+hawkapi_sentry-0.1.0.dist-info/RECORD,,

hawkapi_sentry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hawkapi_sentry-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HawkAPI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.