sf-veritas 0.9.7__py3-none-any.whl

sf_veritas/patches/web_frameworks/fastapi.py

@@ -0,0 +1,145 @@
+"""
+• SFTracingASGIMiddleware: propagates SAILFISH_TRACING_HEADER inbound → ContextVar.
+• SFTracingRoute:   per-endpoint hop capture (user code only).
+• patch_fastapi():  monkey-patch FastAPI.__init__ to inject both.
+"""
+
+from ...constants import SAILFISH_TRACING_HEADER
+from ...custom_excepthook import custom_excepthook
+from ...env_vars import SF_DEBUG
+from ...regular_data_transmitter import NetworkHopsTransmitter
+from ...thread_local import get_or_set_sf_trace_id
+from .utils import _is_user_code, _unwrap_user_func
+
+# ---------- FastAPI / Starlette imports (guarded) ----------
+try:
+    import fastapi
+    from fastapi.requests import Request
+    from fastapi.routing import APIRoute
+    from starlette.types import ASGIApp, Receive, Scope, Send
+except ImportError:  # FastAPI not installed – expose no-op
+
+    def patch_fastapi():
+        return
+
+else:
+
+    # ========================================================
+    # 1. Context-propagation middleware (already present)
+    # ========================================================
+    class SFTracingASGIMiddleware:
+        """Fastest possible ASGI middleware (no BaseHTTPMiddleware).
+
+        • Captures inbound SAILFISH_TRACING_HEADER header → ContextVar
+        • Catches all unhandled exceptions and funnels them through
+        `custom_excepthook`.
+        """
+
+        def __init__(self, app: ASGIApp):
+            self.app = app
+
+        async def __call__(self, scope: Scope, receive: Receive, send: Send):
+            # 1) Header capture (HTTP requests only)
+            if scope.get("type") == "http":
+                hdr = next(
+                    (
+                        val.decode()
+                        for name, val in scope.get("headers", [])
+                        if name.decode().lower() == SAILFISH_TRACING_HEADER.lower()
+                    ),
+                    None,
+                )
+                if hdr:
+                    get_or_set_sf_trace_id(hdr, is_associated_with_inbound_request=True)
+
+            # 2) Execute downstream app and trap unhandled exceptions
+            try:
+                await self.app(scope, receive, send)
+            except Exception as exc:  # noqa: BLE001
+                custom_excepthook(type(exc), exc, exc.__traceback__)
+                raise  # re-raise so FastAPI still returns a 500 response
+
+    # ========================================================
+    # 2. Hop-capturing APIRoute
+    # ========================================================
+    class SFTracingRoute(APIRoute):
+        """
+        Custom APIRoute that
+
+        • fires a single NetworkHop when user-code starts (skips Strawberry), and
+        • funnels **any** exception – including FastAPI's HTTPException – through
+        `custom_excepthook` before letting FastAPI continue its normal handling.
+        """
+
+        async def _emit_hop_if_needed(self, request: Request):
+            _, session_id = get_or_set_sf_trace_id()  # already seeded by middleware
+
+            endpoint_fn = _unwrap_user_func(self.endpoint)
+            filename = getattr(endpoint_fn, "__code__", None).co_filename
+
+            # Ignore non-user / Strawberry endpoints
+            if (
+                not filename
+                or not _is_user_code(filename)
+                or endpoint_fn.__module__.startswith("strawberry")
+            ):
+                return
+
+            line_no = endpoint_fn.__code__.co_firstlineno
+            name = endpoint_fn.__name__
+
+            if SF_DEBUG:
+                print(
+                    f"[[SFTracingRoute]] hop → {name} ({filename}:{line_no}) "
+                    f"session={session_id}",
+                    log=False,
+                )
+
+            NetworkHopsTransmitter().send(
+                session_id=session_id,
+                line=str(line_no),
+                column="0",
+                name=name,
+                entrypoint=filename,
+            )
+
+        # ------------------------------------------------------------------ #
+        # override FastAPI's handler factory so we can trap *all* exceptions
+        # ------------------------------------------------------------------ #
+        def get_route_handler(self):
+            original_route_handler = super().get_route_handler()
+
+            async def traced_route_handler(request: Request):
+                try:
+                    await self._emit_hop_if_needed(request)
+                    return await original_route_handler(request)
+                except Exception as exc:  # <-- catches
+                    custom_excepthook(type(exc), exc, exc.__traceback__)  # all FastAPI
+                    raise  # exceptions
+
+            return traced_route_handler
+
+    # ========================================================
+    # 3. Monkey-patch FastAPI.__init__
+    # ========================================================
+    def patch_fastapi():
+        """
+        • Inject SFTracingASGIMiddleware at app start-up.
+        • Force router.route_class = SFTracingRoute to wrap every endpoint.
+        """
+        original_init = fastapi.FastAPI.__init__
+
+        def patched_init(self, *args, **kwargs):
+            # Let FastAPI do its normal work first.
+            original_init(self, *args, **kwargs)
+            # Insert ASGI middleware at the very top.
+            self.add_middleware(SFTracingASGIMiddleware)
+            # Ensure all new routes use our tracing route class.
+            self.router.route_class = SFTracingRoute
+            if SF_DEBUG:
+                print(
+                    "[[patch_fastapi]] Tracing middleware + route class installed",
+                    log=False,
+                )
+
+        fastapi.FastAPI.__init__ = patched_init

sf_veritas/patches/web_frameworks/flask.py

@@ -0,0 +1,186 @@
+"""
+Adds:
+• before_request hook → ContextVar propagation (unchanged).
+• global add_url_rule / Blueprint.add_url_rule patch →
+  wraps every endpoint in a hop-emitting closure.
+"""
+
+from functools import wraps
+from types import MethodType
+from typing import Callable, Set, Tuple
+
+from ...constants import SAILFISH_TRACING_HEADER
+from ...custom_excepthook import custom_excepthook
+from ...env_vars import SF_DEBUG
+from ...regular_data_transmitter import NetworkHopsTransmitter
+from ...thread_local import get_or_set_sf_trace_id
+
+# ────────────────────────────────────────────────────────────────
+#   shared helpers
+# ────────────────────────────────────────────────────────────────
+from .utils import _is_user_code, _unwrap_user_func  # cached helpers
+
+
+def _make_hop_wrapper(
+    fn: Callable, hop_key: Tuple[str, int], fn_name: str, filename: str
+):
+    """
+    Return a wrapper that sends a NetworkHop exactly once per request.
+    Uses flask.g to remember which hops have fired.
+    """
+    from flask import g
+
+    @wraps(fn)
+    def _wrapped(*args, **kwargs):  # noqa: ANN001
+        _, session_id = get_or_set_sf_trace_id()
+
+        sent: Set[Tuple[str, int]] = getattr(g, "_sf_hops_sent", set())
+        if hop_key not in sent:
+            if SF_DEBUG:
+                print(
+                    f"[[SFTracingFlask]] hop → {fn_name} ({filename}:{hop_key[1]}) "
+                    f"session={session_id}",
+                    log=False,
+                )
+
+            NetworkHopsTransmitter().send(
+                session_id=session_id,
+                line=str(hop_key[1]),
+                column="0",
+                name=fn_name,
+                entrypoint=filename,
+            )
+            sent.add(hop_key)
+            g._sf_hops_sent = sent
+
+        return fn(*args, **kwargs)
+
+    return _wrapped
+
+
+def _wrap_if_user_view(endpoint_fn: Callable):
+    """
+    Decide whether to wrap `endpoint_fn`. Returns the (possibly wrapped)
+    callable.  Suppress wrapping for library code or Strawberry handlers.
+    """
+    real_fn = _unwrap_user_func(endpoint_fn)
+
+    # Skip Strawberry GraphQL views – Strawberry extension owns them
+    if real_fn.__module__.startswith("strawberry"):
+        return endpoint_fn
+
+    code = getattr(real_fn, "__code__", None)
+    if not code or not _is_user_code(code.co_filename):
+        return endpoint_fn
+
+    hop_key = (code.co_filename, code.co_firstlineno)
+    return _make_hop_wrapper(endpoint_fn, hop_key, real_fn.__name__, code.co_filename)
+
+
+# ────────────────────────────────────────────────────────────────
+#   Context-propagation (unchanged)
+# ────────────────────────────────────────────────────────────────
+def _install_before_request(app):
+    from flask import request
+
+    @app.before_request
+    def _extract_sf_trace():
+        hdr = request.headers.get(SAILFISH_TRACING_HEADER)
+        if hdr:
+            get_or_set_sf_trace_id(hdr, is_associated_with_inbound_request=True)
+
+
+# ────────────────────────────────────────────────────────────────
+#   Monkey-patch Flask & Blueprint
+# ────────────────────────────────────────────────────────────────
+try:
+    import flask
+    from flask import Blueprint
+
+    def _patch_add_url_rule(cls):
+        """
+        Patch *cls*.add_url_rule (cls is Flask or Blueprint) so the final
+        stored view function is wrapped after Flask registers it.  Works for:
+            • view_func positional
+            • endpoint string lookup
+            • CBV's as_view()
+        """
+        original_add = cls.add_url_rule
+
+        def patched_add(
+            self, rule, endpoint=None, view_func=None, **options
+        ):  # noqa: ANN001
+            # 1. Let Flask register the route first
+            original_add(self, rule, endpoint=endpoint, view_func=view_func, **options)
+
+            # 2. Resolve the canonical endpoint name
+            ep_name = endpoint or (view_func and view_func.__name__)
+            if not ep_name:
+                return  # should not happen, but be safe
+
+            target = self.view_functions.get(ep_name)
+            if not callable(target):
+                return
+
+            # 3. Wrap if user code
+            wrapped = _wrap_if_user_view(target)
+            self.view_functions[ep_name] = wrapped
+
+        cls.add_url_rule = patched_add
+
+    def patch_flask():
+        """
+        • Installs before_request header propagation
+        • Wraps every endpoint to emit a single NetworkHop
+        • **NEW:** patches Flask.handle_exception + handle_user_exception so ANY
+        exception—including flask.abort / HTTPException—triggers custom_excepthook.
+        """
+        if getattr(flask.Flask, "__sf_tracing_patched__", False):
+            return  # idempotent
+
+        # --- 1. Patch Flask.__init__ to add before_request every time -----------
+        original_flask_init = flask.Flask.__init__
+
+        def patched_init(self, *args, **kwargs):
+            original_flask_init(self, *args, **kwargs)
+            _install_before_request(self)
+
+        flask.Flask.__init__ = patched_init
+
+        # --- 2. Patch add_url_rule for both Flask and Blueprint -----------------
+        _patch_add_url_rule(flask.Flask)
+        _patch_add_url_rule(Blueprint)
+
+        # --- 3. Patch exception handlers once on the class ----------------------
+        _mw_path = "sf_veritas_exception_patch_applied"
+        if not getattr(flask.Flask, _mw_path, False):
+            orig_handle_exc = flask.Flask.handle_exception
+            orig_handle_user_exc = flask.Flask.handle_user_exception
+
+            def _patched_handle_exception(self, e):
+                custom_excepthook(type(e), e, e.__traceback__)
+                return orig_handle_exc(self, e)
+
+            def _patched_handle_user_exception(self, e):
+                custom_excepthook(type(e), e, e.__traceback__)
+                return orig_handle_user_exc(self, e)
+
+            flask.Flask.handle_exception = _patched_handle_exception  # 500 errors
+            flask.Flask.handle_user_exception = (
+                _patched_handle_user_exception  # HTTPExc.
+            )
+
+            setattr(flask.Flask, _mw_path, True)
+
+        flask.Flask.__sf_tracing_patched__ = True
+
+        if SF_DEBUG:
+            print(
+                "[[patch_flask]] tracing hooks + exception capture installed", log=False
+            )
+
+except ImportError:  # Flask not installed
+
+    def patch_flask():  # noqa: D401
+        """No-op when Flask is absent."""
+        return

sf_veritas/patches/web_frameworks/klein.py

@@ -0,0 +1,40 @@
+import functools
+
+from ...constants import SAILFISH_TRACING_HEADER
+from ...thread_local import get_or_set_sf_trace_id
+
+
+def patch_klein():
+    """
+    Monkey-patch Klein.route so that every @app.route endpoint first
+    extracts SAILFISH_TRACING_HEADER and sets our ContextVar, then calls the user handler.
+    No-op if Klein isn't installed.
+    """
+    try:
+        import klein
+    except ImportError:
+        return
+
+    original_route = klein.Klein.route
+
+    def patched_route(self, *args, **kwargs):
+        # Grab Klein's decorator for this pattern
+        original_decorator = original_route(self, *args, **kwargs)
+
+        def new_decorator(fn):
+            @functools.wraps(fn)
+            def wrapped(request, *f_args, **f_kwargs):
+                header = request.getHeader(SAILFISH_TRACING_HEADER)
+                if header:
+                    get_or_set_sf_trace_id(
+                        header, is_associated_with_inbound_request=True
+                    )
+                # Now that our ContextVar is set, call the real handler
+                return fn(request, *f_args, **f_kwargs)
+
+            # Register the wrapped handler instead of the raw one
+            return original_decorator(wrapped)
+
+        return new_decorator
+
+    klein.Klein.route = patched_route

sf_veritas/patches/web_frameworks/litestar.py

@@ -0,0 +1,217 @@
+import inspect
+import sys
+import sysconfig
+from functools import lru_cache
+from typing import Any, Callable, Optional, Set
+
+from ...constants import SAILFISH_TRACING_HEADER
+from ...custom_excepthook import custom_excepthook
+from ...env_vars import SF_DEBUG
+from ...regular_data_transmitter import NetworkHopsTransmitter
+from ...thread_local import get_or_set_sf_trace_id
+from .utils import _is_user_code, _unwrap_user_func
+
+_stdlib = sysconfig.get_paths()["stdlib"]
+
+
+@lru_cache(maxsize=512)
+def _is_user_code(path: Optional[str]) -> bool:
+    """
+    True only for “application” files (not stdlib or site-packages).
+    """
+    if not path or path.startswith("<"):
+        return False
+    if path.startswith(_stdlib):
+        return False
+    if "site-packages" in path or "dist-packages" in path:
+        return False
+    return True
+
+
+def _sf_tracing_factory(app: Callable) -> Callable:
+    """
+    ASGI middleware that
+      • propagates the inbound SAILFISH_TRACING_HEADER header, and
+      • reports any unhandled exception via `custom_excepthook`.
+    """
+
+    async def _middleware(scope, receive, send):
+        # Header propagation
+        if scope.get("type") == "http":
+            for name, val in scope.get("headers", []):
+                if name.decode().lower() == SAILFISH_TRACING_HEADER.lower():
+                    get_or_set_sf_trace_id(
+                        val.decode(), is_associated_with_inbound_request=True
+                    )
+                    break
+        # Exception capture
+        try:
+            await app(scope, receive, send)
+        except Exception as exc:  # noqa: BLE001
+            custom_excepthook(type(exc), exc, exc.__traceback__)
+            raise
+
+    return _middleware
+
+
+def _sf_profile_factory(app: Callable) -> Callable:
+    """
+    ASGI middleware that installs a one-shot profiler tracer to fire on the
+    first user-land Python call, then disables itself.  Emits exactly one
+    NetworkHop per request.
+    """
+
+    def _make_tracer():
+        def tracer(frame, event, _arg):
+            try:
+                # Skip any C-level events instantly
+                if event.startswith("c_"):
+                    return None
+
+                # Only care about the first Python call into user code
+                if event == "call" and _is_user_code(frame.f_code.co_filename):
+                    _, session_id = get_or_set_sf_trace_id()
+
+                    func_name = frame.f_code.co_name
+                    line_no = frame.f_lineno
+                    filename = frame.f_code.co_filename
+
+                    if SF_DEBUG:
+                        print(
+                            f"[[LitestarProfile]] SEND → {func_name} "
+                            f"({filename}:{line_no}) session={session_id}",
+                            log=False,
+                        )
+
+                    try:
+                        NetworkHopsTransmitter().send(
+                            session_id=session_id,
+                            line=str(line_no),
+                            column="0",
+                            name=func_name,
+                            entrypoint=filename,
+                        )
+                    except Exception as send_err:
+                        # Log send errors but don't break the request
+                        print(
+                            "[[LitestarProfile ERROR send]]", repr(send_err), log=False
+                        )
+                    finally:
+                        # Turn off profiling immediately
+                        sys.setprofile(None)
+
+                    return None
+
+                return tracer
+            except Exception as err:
+                # Any tracer error → disable profiling & log it
+                sys.setprofile(None)
+                print("[[LitestarProfile ERROR tracer]]", repr(err), log=False)
+                return None
+
+        return tracer
+
+    class _ProfileMiddleware:
+        def __init__(self, app: Callable):
+            self.app = app
+
+        async def __call__(self, scope, receive, send):
+            if scope.get("type") == "http":
+                # Install the one-shot tracer
+                sys.setprofile(_make_tracer())
+                try:
+                    await self.app(scope, receive, send)
+                except Exception as exc:  # noqa: BLE001
+                    custom_excepthook(type(exc), exc, exc.__traceback__)
+                    raise
+                finally:
+                    sys.setprofile(None)
+            else:
+                try:
+                    await self.app(scope, receive, send)
+                except Exception as exc:  # noqa: BLE001
+                    custom_excepthook(type(exc), exc, exc.__traceback__)
+                    raise
+
+    return _ProfileMiddleware(app)
+
+
+def patch_litestar() -> None:
+    """
+    Monkey-patch Litestar.__init__ so every instance auto-wraps with:
+      1) _sf_tracing_factory → inbound trace-header propagation
+      2) _sf_profile_factory → one-shot tracer for NetworkHops
+    Safe no-op if Litestar is not installed.
+    """
+    try:
+        import litestar
+        from litestar import Litestar
+        from litestar.middleware import DefineMiddleware
+    except ImportError:
+        return
+
+    original_init = Litestar.__init__
+
+    # ---------------------------------------------------------------------------
+    # UPDATED patched_init in patch_litestar.py  (entire function shown)
+    # ---------------------------------------------------------------------------
+    def patched_init(self, *args, **kwargs):
+        """
+        Injects Sailfish into every Litestar app instance by
+
+        1. Pre-pending two ASGI middlewares
+        • _sf_tracing_factory  – header propagation + last-chance catcher
+        • _sf_profile_factory  – one-shot hop emitter
+        2. Adding a **generic exception handler** so *any* exception—
+        including `HTTPException` and framework-level errors—triggers
+        `custom_excepthook` exactly once before Litestar builds the
+        response.
+        """
+
+        # ---------------------------------------------------------- #
+        # 1 | Middleware injection (existing behaviour)
+        # ---------------------------------------------------------- #
+        mw = list(kwargs.get("middleware", []))
+        from litestar.middleware import DefineMiddleware
+
+        mw.insert(0, DefineMiddleware(_sf_tracing_factory))
+        mw.insert(1, DefineMiddleware(_sf_profile_factory))
+        kwargs["middleware"] = mw
+
+        # ---------------------------------------------------------- #
+        # 2 | Universal exception handler
+        # ---------------------------------------------------------- #
+        def _sf_exception_handler(request, exc):  # type: ignore[valid-type]
+            """
+            Litestar calls this for **any** Exception once routing / dep-
+            resolution is done. We just forward to `custom_excepthook`
+            and re-raise so the builtin handler still produces a Response.
+            """
+            custom_excepthook(type(exc), exc, exc.__traceback__)
+            raise exc  # let Litestar fall back to its default logic
+
+        # Merge with user-supplied handlers (if any)
+        existing_handlers = kwargs.get("exception_handlers", {})
+        if isinstance(existing_handlers, dict):
+            existing_handlers.setdefault(Exception, _sf_exception_handler)
+        else:  # Litestar also accepts list[tuple[Exception, Handler]]
+            existing_handlers = list(existing_handlers)  # type: ignore[arg-type]
+            existing_handlers.append((Exception, _sf_exception_handler))
+        kwargs["exception_handlers"] = existing_handlers
+
+        # ---------------------------------------------------------- #
+        # 3 | Debug log
+        # ---------------------------------------------------------- #
+        if SF_DEBUG:
+            print(
+                "[[patch_litestar]] installed header+profile middleware AND "
+                "global exception handler",
+                log=False,
+            )
+
+        # ---------------------------------------------------------- #
+        # 4 | Delegate to original __init__
+        # ---------------------------------------------------------- #
+        return original_init(self, *args, **kwargs)
+
+    Litestar.__init__ = patched_init

sf_veritas/patches/web_frameworks/pyramid.py

@@ -0,0 +1,89 @@
+import inspect
+import sys
+import sysconfig
+from functools import lru_cache
+from typing import Any, Callable, Set, Tuple
+
+from ...constants import SAILFISH_TRACING_HEADER
+from ...custom_excepthook import custom_excepthook
+from ...regular_data_transmitter import NetworkHopsTransmitter
+from ...thread_local import get_or_set_sf_trace_id
+from .utils import _is_user_code  # cached helpers
+
+
+# ------------------------------------------------------------------ #
+# 1.2 Tween factory: header + one-shot profile tracer + exceptions   #
+# ------------------------------------------------------------------ #
+def _sf_tracing_tween_factory(handler, registry):
+    """
+    Pyramid tween that:
+      • Reads SAILFISH_TRACING_HEADER header → ContextVar.
+      • Sets a one-shot profiler to emit the first user-land NetworkHop.
+      • Funnels *all* exceptions (including HTTPException) through
+        `custom_excepthook` before letting Pyramid continue normal handling.
+    """
+
+    def _tween(request):
+        # ── 1) Propagate incoming trace header ──────────────────────────
+        hdr = request.headers.get(SAILFISH_TRACING_HEADER)
+        if hdr:
+            get_or_set_sf_trace_id(hdr, is_associated_with_inbound_request=True)
+
+        # ── 2) One-shot tracer to detect first user-code frame ──────────
+        def tracer(frame, event, _arg):
+            if event != "call":  # only Python calls
+                return tracer
+            fn_path = frame.f_code.co_filename
+            if _is_user_code(fn_path):
+                _, session_id = get_or_set_sf_trace_id()
+                func_name = frame.f_code.co_name
+                line_no = frame.f_lineno
+                NetworkHopsTransmitter().send(
+                    session_id=session_id,
+                    line=str(line_no),
+                    column="0",
+                    name=func_name,
+                    entrypoint=fn_path,
+                )
+                sys.setprofile(None)  # disable after first hop
+                return None
+            return tracer
+
+        sys.setprofile(tracer)
+
+        # ── 3) Call downstream handler & capture **all** exceptions ─────
+        try:
+            return handler(request)
+        except Exception as exc:  # HTTPException included
+            custom_excepthook(type(exc), exc, exc.__traceback__)
+            raise  # re-raise for Pyramid
+        finally:
+            sys.setprofile(None)  # safety-net cleanup
+
+    return _tween
+
+
+# ------------------------------------------------------------------ #
+# 1.3 Monkey-patch Configurator to auto-add our tween               #
+# ------------------------------------------------------------------ #
+def patch_pyramid():
+    """
+    Ensure every Pyramid Configurator implicitly registers our tween
+    at the INVOCATION stage (just above MAIN).
+    """
+    try:
+        import pyramid.config
+        import pyramid.tweens
+    except ImportError:
+        return  # Pyramid not installed
+
+    original_init = pyramid.config.Configurator.__init__
+
+    def patched_init(self, *args, **kwargs):
+        original_init(self, *args, **kwargs)
+        # Use a dotted name—implicit ordering places it just above MAIN
+        dotted = f"{_sf_tracing_tween_factory.__module__}._sf_tracing_tween_factory"
+        # 'over=pyramid.tweens.MAIN' ensures our tween runs *before* the main handler
+        self.add_tween(dotted, over=pyramid.tweens.MAIN)
+
+    pyramid.config.Configurator.__init__ = patched_init