openbox-sdk-python 0.2.0__py3-none-any.whl

openbox_core/instrumentation/file.py

@@ -0,0 +1,239 @@
+"""File wrapper — governed open() with read/write/writelines counting.
+
+Preflight runs BEFORE the file handle is created (a BLOCK means the file is
+never opened). The returned handle is proxied to count bytes/lines; closing
+emits ONE completed telemetry event with the totals.
+
+Both ``builtins.open`` and ``io.open`` are patched: ``pathlib`` file helpers
+(``Path.open``/``read_text``/``write_text``) call ``io.open`` DIRECTLY and
+never touch ``builtins.open``, so patching only the builtin would leave every
+pathlib file access ungoverned. In CPython the two names reference the SAME
+object and a single logical open resolves through exactly ONE of them
+(direct ``open()`` -> builtins, pathlib -> io), so wiring both to one wrapper
+governs pathlib without any double wrapping or double evaluation.
+
+Noise control: paths under the interpreter prefix / site-packages / caches
+bypass governance entirely, and (like every hook) operations with no bound
+ActivityContext are skipped by the hook runtime.
+"""
+
+from __future__ import annotations
+
+import builtins
+import io
+import logging
+import sys
+import sysconfig
+import threading
+from typing import Any
+
+from ..contracts.otel_spans import HookType
+from ..otel.provider import get_tracer
+from .shared import get_hook_runtime
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["install_file_io", "uninstall_file_io", "GovernedFile"]
+
+# The genuine opener (``builtins.open`` == ``io.open`` pre-patch) — used both
+# to bypass governance and to create the handle after preflight. Non-None
+# while instrumentation is installed (doubles as the idempotency guard).
+_original_open: Any = None
+# Whether we replaced ``io.open`` too, so uninstall restores exactly what we
+# changed (skipped if a foreign wrapper already owned ``io.open`` at install).
+_patched_io: bool = False
+
+# Interpreter-owned trees (venv AND base install — they differ in venvs).
+_IGNORED_PATH_PREFIXES = tuple(
+    {
+        sys.prefix,
+        sys.exec_prefix,
+        sys.base_prefix,
+        sys.base_exec_prefix,
+        sysconfig.get_paths().get("stdlib", sys.base_prefix),
+        sysconfig.get_paths().get("platstdlib", sys.base_prefix),
+        sysconfig.get_paths().get("purelib", sys.prefix),
+        sysconfig.get_paths().get("platlib", sys.prefix),
+    }
+)
+
+
+def _mode_operation(mode: str) -> str:
+    if any(c in mode for c in ("w", "a", "x", "+")):
+        return "write"
+    return "read"
+
+
+def _file_span_name(mode: str) -> str:
+    return f"file.{_mode_operation(mode)}"
+
+
+def _coerce_path(file: Any) -> str | None:
+    """str path for str/bytes/os.PathLike; None for fds/unknowns (pass through)."""
+    import os
+
+    if isinstance(file, int):
+        return None  # file descriptor
+    try:
+        path = os.fspath(file)
+    except TypeError:
+        return None
+    return path.decode(errors="ignore") if isinstance(path, bytes) else path
+
+
+# Re-entrancy guard: governance evaluation opens files itself (httpx/ssl,
+# package-metadata scans). Governing those opens evaluates again and recurses
+# until RecursionError — any open on a thread already inside file-governance
+# work passes straight through.
+_reentrancy = threading.local()
+
+
+def _should_skip(path: str | None) -> bool:
+    if path is None:
+        return True
+    if "__pycache__" in path:
+        return True
+    return path.startswith(_IGNORED_PATH_PREFIXES)
+
+
+class GovernedFile:
+    """Transparent file proxy counting reads/writes for completed telemetry."""
+
+    def __init__(self, handle: Any, span: Any, path: str, mode: str, runtime: Any):
+        object.__setattr__(self, "_handle", handle)
+        object.__setattr__(self, "_span", span)
+        object.__setattr__(self, "_path", path)
+        object.__setattr__(self, "_mode", mode)
+        object.__setattr__(self, "_runtime", runtime)
+        object.__setattr__(self, "_bytes_read", 0)
+        object.__setattr__(self, "_bytes_written", 0)
+        object.__setattr__(self, "_lines_count", 0)
+        object.__setattr__(self, "_closed_reported", False)
+
+    # ── counted operations ────────────────────────────────────────────────
+
+    def read(self, *args, **kwargs):
+        data = self._handle.read(*args, **kwargs)
+        object.__setattr__(self, "_bytes_read", self._bytes_read + len(data))
+        return data
+
+    def write(self, data):
+        written = self._handle.write(data)
+        object.__setattr__(self, "_bytes_written", self._bytes_written + len(data))
+        return written
+
+    def writelines(self, lines):
+        materialized = list(lines)
+        result = self._handle.writelines(materialized)
+        object.__setattr__(
+            self, "_bytes_written", self._bytes_written + sum(len(line) for line in materialized)
+        )
+        object.__setattr__(self, "_lines_count", self._lines_count + len(materialized))
+        return result
+
+    def close(self):
+        result = self._handle.close()
+        self._report_completed()
+        return result
+
+    def _report_completed(self):
+        if self._closed_reported:
+            return
+        object.__setattr__(self, "_closed_reported", True)
+        _reentrancy.active = True
+        try:
+            self._span.end()
+            self._runtime.completed(
+                self._span,
+                hook_type=HookType.FILE_OPERATION,
+                fields={
+                    "file_path": self._path,
+                    "file_mode": self._mode,
+                    "file_operation": _mode_operation(self._mode),
+                    "bytes_read": self._bytes_read or None,
+                    "bytes_written": self._bytes_written or None,
+                    "lines_count": self._lines_count or None,
+                },
+            )
+        except Exception:
+            logger.debug("file completed telemetry failed", exc_info=True)
+        finally:
+            _reentrancy.active = False
+
+    # ── passthrough ───────────────────────────────────────────────────────
+
+    def __enter__(self):
+        self._handle.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        result = self._handle.__exit__(exc_type, exc_value, traceback)
+        self._report_completed()
+        return result
+
+    def __iter__(self):
+        return iter(self._handle)
+
+    def __getattr__(self, name):
+        return getattr(self._handle, name)
+
+
+def _governed_open(file, mode="r", *args, **kwargs):
+    runtime = get_hook_runtime()
+    path = _coerce_path(file)
+    if runtime is None or getattr(_reentrancy, "active", False) or _should_skip(path):
+        return _original_open(file, mode, *args, **kwargs)
+    operation = _mode_operation(mode)
+    span = get_tracer().start_span(_file_span_name(mode))
+    span.set_attribute("file.path", path)
+    span.set_attribute("file.mode", mode)
+    span.set_attribute("file.operation", operation)
+    _reentrancy.active = True
+    try:
+        # BLOCK/HALT raises here — the file handle is never created.
+        runtime.preflight(
+            span,
+            hook_type=HookType.FILE_OPERATION,
+            identifier=path,
+            fields={
+                "file_path": path,
+                "file_mode": mode,
+                "file_operation": operation,
+            },
+        )
+    finally:
+        _reentrancy.active = False
+    handle = _original_open(file, mode, *args, **kwargs)
+    return GovernedFile(handle, span, path, mode, runtime)
+
+
+def install_file_io() -> bool:
+    """Idempotent open() patch across builtins AND io.
+
+    Patching ``io.open`` is what brings ``pathlib`` file helpers under
+    governance — they bypass ``builtins.open`` entirely.
+    """
+    global _original_open, _patched_io
+    if _original_open is not None:
+        return True
+    _original_open = builtins.open
+    builtins.open = _governed_open
+    # pathlib routes through io.open. Only patch it if it is still the genuine
+    # opener — never clobber a foreign wrapper another tool installed first
+    # (that would also make it the wrapper we call as "_original_open").
+    if io.open is _original_open:
+        io.open = _governed_open
+        _patched_io = True
+    return True
+
+
+def uninstall_file_io() -> None:
+    """Restore both ``builtins.open`` and ``io.open`` to their originals."""
+    global _original_open, _patched_io
+    if _original_open is None:
+        return
+    builtins.open = _original_open
+    if _patched_io:
+        io.open = _original_open
+        _patched_io = False
+    _original_open = None

openbox_core/instrumentation/function.py

@@ -0,0 +1,121 @@
+"""Function decorator instrumentation — @governed for sync and async callables.
+
+Preflight runs before the wrapped function; a BLOCK/HALT means the function
+body never executes. Fast path: no active hook runtime or no bound context ⇒
+zero-governance passthrough.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from ..contracts.otel_spans import HookType
+from ..hooks.wrappers import run_governed_async, run_governed_sync
+from ..otel.provider import get_tracer
+from ..serialization import to_json_safe
+from .shared import get_hook_runtime
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["governed"]
+
+
+def _function_fields(func: Callable, args: tuple, kwargs: dict, capture_args: bool) -> dict:
+    fields: dict[str, Any] = {
+        "function": getattr(func, "__qualname__", getattr(func, "__name__", "function")),
+        "module": getattr(func, "__module__", None),
+    }
+    if capture_args:
+        try:
+            fields["args"] = to_json_safe({"args": list(args), "kwargs": kwargs})
+        except Exception:
+            fields["args"] = None
+    return fields
+
+
+def governed(
+    func: Callable | None = None,
+    *,
+    name: str | None = None,
+    capture_args: bool = True,
+    capture_result: bool = True,
+):
+    """Decorate a function with started/completed hook governance.
+
+    Usage::
+
+        @governed
+        def charge(amount): ...
+
+        @governed(name="billing.charge", capture_args=False)
+        async def acharge(amount): ...
+    """
+
+    def decorate(target: Callable) -> Callable:
+        span_name = name or getattr(target, "__qualname__", "function")
+
+        if inspect.iscoroutinefunction(target):
+
+            @functools.wraps(target)
+            async def async_wrapper(*args, **kwargs):
+                runtime = get_hook_runtime()
+                if runtime is None:
+                    return await target(*args, **kwargs)
+                span = get_tracer().start_span(f"function {span_name}")
+                started = _function_fields(target, args, kwargs, capture_args)
+                try:
+                    return await run_governed_async(
+                        runtime,
+                        target,
+                        args,
+                        kwargs,
+                        span=span,
+                        hook_type=HookType.FUNCTION_CALL,
+                        identifier=span_name,
+                        started_fields=started,
+                        completed_fields=(
+                            (lambda result: {"result": to_json_safe(result)})
+                            if capture_result
+                            else None
+                        ),
+                    )
+                finally:
+                    span.end()
+
+            return async_wrapper
+
+        @functools.wraps(target)
+        def sync_wrapper(*args, **kwargs):
+            runtime = get_hook_runtime()
+            if runtime is None:
+                return target(*args, **kwargs)
+            span = get_tracer().start_span(f"function {span_name}")
+            started = _function_fields(target, args, kwargs, capture_args)
+            try:
+                return run_governed_sync(
+                    runtime,
+                    target,
+                    args,
+                    kwargs,
+                    span=span,
+                    hook_type=HookType.FUNCTION_CALL,
+                    identifier=span_name,
+                    started_fields=started,
+                    completed_fields=(
+                        (lambda result: {"result": to_json_safe(result)})
+                        if capture_result
+                        else None
+                    ),
+                )
+            finally:
+                span.end()
+
+        return sync_wrapper
+
+    if func is not None:
+        return decorate(func)
+    return decorate