rule-engine-core 0.0.4__tar.gz → 0.1.0__tar.gz

{rule_engine_core-0.0.4 → rule_engine_core-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rule-engine-core
-Version: 0.0.4
+Version: 0.1.0
 Summary: A rule engine core library for Python.
 Home-page: https://github.com/temp-noob/rule-engine
 Author: Mohit Tripathi

{rule_engine_core-0.0.4 → rule_engine_core-0.1.0}/rule_engine_core/metadata_store.py

@@ -13,6 +13,8 @@ import logging
 import os
 from urllib import error, request
 
+from rule_engine_core.tracing import trace_headers
+
 DEFAULT_METADATA_SERVICE_URL = "http://localhost:8000"
 DEFAULT_METADATA_SERVICE_TIMEOUT_SECONDS = 3
 
@@ -40,8 +42,11 @@ class MetadataStore:
                 os.getenv("METADATA_SERVICE_TIMEOUT_SECONDS", str(DEFAULT_METADATA_SERVICE_TIMEOUT_SECONDS))
             )
             get_all_metadata_url = f"{metadata_service_base_url}/metadata"
+            # Forward the trace id so metadata_service logs this fetch under the
+            # same trace as the recalc/eval cycle that triggered it.
+            metadata_req = request.Request(get_all_metadata_url, headers=trace_headers())
             try:
-                with request.urlopen(get_all_metadata_url, timeout=metadata_service_timeout_seconds) as response:
+                with request.urlopen(metadata_req, timeout=metadata_service_timeout_seconds) as response:
                     if response.status != 200:
                         raise RuntimeError(
                             f"Failed to fetch metadata from service: {get_all_metadata_url} returned status {response.status}"

rule_engine_core-0.1.0/rule_engine_core/tracing.py

@@ -0,0 +1,300 @@
+"""
+Distributed tracing primitives shared by every service in the monorepo.
+
+The model is deliberately lightweight (stdlib only, no OpenTelemetry): a single
+``trace_id`` string that
+
+  * is read from / written to the ``X-Trace-Id`` HTTP header at service edges,
+  * lives inside a process in a :class:`contextvars.ContextVar`,
+  * is stamped onto every log line via a log-record factory, and
+  * is explicitly re-bound whenever work crosses a thread / pool / event-loop
+    boundary (a ``ContextVar`` does not cross those on its own).
+
+Why ``contextvars`` rather than ``threading.local`` or an argument threaded
+through every call: it is the one primitive that works for FastAPI's "sync
+endpoints run in an anyio worker thread" model *and* for async code, and it
+exposes ``copy_context()`` — the snapshot we hand to child threads/pools.
+
+Typical wiring per service:
+
+    # main.py — before uvicorn.run
+    configure_logging(os.getenv("...LOG_LEVEL", "INFO"), filename=...)
+
+    # api.py — inside generate_fastapi_app(), after the app is built
+    install_tracing(app)
+
+    # background loop body — one fresh trace per unit of work
+    with new_trace_scope():
+        do_one_cycle()
+
+    # fan-out — workers inherit the submitter's trace
+    with TracedThreadPoolExecutor(max_workers=n) as pool:
+        pool.submit(work, ...)
+
+    # outbound HTTP — carry the trace to the next hop
+    requests.get(url, headers=trace_headers())
+"""
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import contextvars
+import logging
+import uuid
+import threading
+from contextlib import contextmanager
+from typing import Any, Callable, Iterable, Iterator, Optional
+
+__all__ = [
+    "TRACE_ID_HEADER",
+    "LOG_FORMAT",
+    "get_trace_id",
+    "new_trace_id",
+    "set_trace_id",
+    "reset_trace_id",
+    "bind_trace_id",
+    "new_trace_scope",
+    "install_trace_log_factory",
+    "configure_logging",
+    "TraceContextMiddleware",
+    "install_tracing",
+    "TracedThread",
+    "TracedThreadPoolExecutor",
+    "run_coro_threadsafe_with_trace",
+    "trace_headers",
+]
+
+# The header the trace id rides in across service boundaries. Mirrors the
+# existing X-User-Id convention platform_service already uses.
+TRACE_ID_HEADER = "X-Trace-Id"
+
+# When no trace is bound (e.g. a log line emitted at import time) records still
+# need a value so a "%(trace_id)s" format can never KeyError.
+_NO_TRACE = "-"
+
+_trace_id_var: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "trace_id", default=None
+)
+
+
+# ─── context primitives ──────────────────────────────────────────────────────
+
+def get_trace_id() -> Optional[str]:
+    """The trace id bound to the current context, or ``None`` if none is bound."""
+    return _trace_id_var.get()
+
+
+def new_trace_id() -> str:
+    """A fresh, opaque trace id (uuid4 hex — 32 chars, no dashes)."""
+    return uuid.uuid4().hex
+
+
+def set_trace_id(trace_id: Optional[str]) -> contextvars.Token:
+    """Low-level: bind ``trace_id`` and return the token needed to restore the
+    previous value. Prefer :func:`bind_trace_id` / :func:`new_trace_scope`."""
+    return _trace_id_var.set(trace_id)
+
+
+def reset_trace_id(token: contextvars.Token) -> None:
+    """Restore the trace id captured in ``token`` (from :func:`set_trace_id`)."""
+    _trace_id_var.reset(token)
+
+
+@contextmanager
+def bind_trace_id(trace_id: Optional[str] = None) -> Iterator[str]:
+    """Bind ``trace_id`` for the duration of the block, restoring the previous
+    value on exit. A new id is generated when ``trace_id`` is falsy, so this
+    doubles as "adopt the incoming id, or start one if there is none"."""
+    resolved = trace_id or new_trace_id()
+    token = _trace_id_var.set(resolved)
+    try:
+        yield resolved
+    finally:
+        _trace_id_var.reset(token)
+
+
+@contextmanager
+def new_trace_scope() -> Iterator[str]:
+    """Start a *fresh* trace for a self-contained unit of work — the right tool
+    for background loops (a recalc cycle, a poll tick, an evaluation round) whose
+    work is not tied to any inbound request."""
+    with bind_trace_id(new_trace_id()) as trace_id:
+        yield trace_id
+
+
+# ─── logging integration ─────────────────────────────────────────────────────
+
+# Shared format so all four services emit the trace id identically. A service may
+# pass its own format to configure_logging as long as it references
+# "%(trace_id)s".
+LOG_FORMAT = "%(asctime)s %(levelname)s [trace=%(trace_id)s] %(name)s:%(lineno)d %(message)s"
+
+_log_factory_installed = False
+
+
+def install_trace_log_factory() -> None:
+    """Wrap the global log-record factory so *every* LogRecord carries a
+    ``trace_id`` attribute (the bound id, or "-").
+
+    Using the record factory rather than a handler/logger ``Filter`` means
+    records from third-party loggers (uvicorn, etc.) also get the attribute, so a
+    format string containing "%(trace_id)s" can never KeyError regardless of
+    which logger emitted the record. Idempotent."""
+    global _log_factory_installed
+    if _log_factory_installed:
+        return
+    previous_factory = logging.getLogRecordFactory()
+
+    def factory(*args: Any, **kwargs: Any) -> logging.LogRecord:
+        record = previous_factory(*args, **kwargs)
+        record.trace_id = get_trace_id() or _NO_TRACE
+        return record
+
+    logging.setLogRecordFactory(factory)
+    _log_factory_installed = True
+
+
+def configure_logging(
+    level: Any = None,
+    *,
+    filename: Optional[str] = None,
+    format: str = LOG_FORMAT,
+    force: bool = False,
+) -> None:
+    """Install the trace record factory and configure root logging in one call —
+    a drop-in for the per-service ``logging.basicConfig(...)`` that also adds the
+    trace id to the format. ``level`` accepts a name ("INFO") or an int; ``None``
+    means INFO."""
+    install_trace_log_factory()
+    kwargs: dict[str, Any] = {
+        "format": format,
+        "level": level if level is not None else logging.INFO,
+    }
+    if filename:
+        kwargs["filename"] = filename
+    if force:
+        kwargs["force"] = True
+    logging.basicConfig(**kwargs)
+
+
+# ─── FastAPI / ASGI ingress ──────────────────────────────────────────────────
+
+def _header_value(headers: Iterable[tuple[bytes, bytes]], name: str) -> Optional[str]:
+    """Case-insensitive lookup in an ASGI raw-header list (list of (name, value)
+    byte tuples; names are already lowercased by the server)."""
+    target = name.lower().encode("latin-1")
+    for key, value in headers:
+        if key.lower() == target:
+            return value.decode("latin-1")
+    return None
+
+
+class TraceContextMiddleware:
+    """Pure-ASGI middleware that establishes the trace context for each request.
+
+    On every HTTP request it adopts an incoming ``X-Trace-Id`` header (or mints a
+    fresh id when absent), binds it into the context for the life of the request
+    — so all handler logs and any downstream calls carry it — and echoes it on
+    the response so the caller / next hop can correlate.
+
+    Deliberately pure ASGI rather than Starlette's ``BaseHTTPMiddleware``, which
+    has known ContextVar-scoping quirks (a var set in ``dispatch`` is not
+    reliably visible back out). Here we ``set`` the var before awaiting the app
+    and ``reset`` it after, which also reaches sync endpoints: FastAPI runs
+    ``def`` handlers via anyio's ``to_thread.run_sync``, which copies the current
+    context into the worker thread."""
+
+    def __init__(self, app: Any) -> None:
+        self.app = app
+
+    async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        incoming = _header_value(scope.get("headers") or [], TRACE_ID_HEADER)
+        trace_id = incoming or new_trace_id()
+        token = set_trace_id(trace_id)
+
+        header_pair = (TRACE_ID_HEADER.encode("latin-1"), trace_id.encode("latin-1"))
+
+        async def send_with_trace_header(message: dict) -> None:
+            if message["type"] == "http.response.start":
+                message.setdefault("headers", []).append(header_pair)
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_with_trace_header)
+        finally:
+            reset_trace_id(token)
+
+
+def install_tracing(app: Any) -> None:
+    """Add :class:`TraceContextMiddleware` to a FastAPI/Starlette app. Call once,
+    inside the app factory, after the app has been created."""
+    app.add_middleware(TraceContextMiddleware)
+
+
+# ─── thread / pool / event-loop propagation ──────────────────────────────────
+
+class TracedThread(threading.Thread):
+    """``threading.Thread`` that runs its target inside a snapshot of the
+    spawning thread's context, so the trace id (and any other ContextVars) cross
+    the thread boundary. Drop-in replacement — the snapshot is taken at
+    construction, the moment the parent's context is meaningful for a thread
+    spawned to continue the parent's work."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._trace_context = contextvars.copy_context()
+
+    def run(self) -> None:
+        self._trace_context.run(super().run)
+
+
+class TracedThreadPoolExecutor(concurrent.futures.ThreadPoolExecutor):
+    """``ThreadPoolExecutor`` whose workers run each task inside a snapshot of
+    the submitter's context. The snapshot is taken at ``submit`` time — not at
+    construction — because pools are typically built once at boot (no trace
+    bound) and only used later, from within a traced scope."""
+
+    def submit(self, fn: Callable, *args: Any, **kwargs: Any):  # type: ignore[override]
+        ctx = contextvars.copy_context()
+        return super().submit(lambda: ctx.run(fn, *args, **kwargs))
+
+
+def run_coro_threadsafe_with_trace(coro, loop: asyncio.AbstractEventLoop):
+    """Like :func:`asyncio.run_coroutine_threadsafe`, but re-binds the *current*
+    trace id inside the coroutine — which runs on ``loop``'s own thread.
+
+    ``run_coroutine_threadsafe`` does not copy the caller's context into the loop
+    thread, so a coroutine scheduled onto a background event loop (e.g.
+    position_server's security-update loop) would otherwise log with no trace. We
+    capture the id here and re-set it inside a wrapper coroutine, so the id — and
+    anything the coroutine awaits or spawns — is traced."""
+    trace_id = get_trace_id()
+
+    async def _traced():
+        token = set_trace_id(trace_id)
+        try:
+            return await coro
+        finally:
+            reset_trace_id(token)
+
+    return asyncio.run_coroutine_threadsafe(_traced(), loop)
+
+
+# ─── outbound HTTP egress ────────────────────────────────────────────────────
+
+def trace_headers(existing: Optional[dict] = None) -> dict:
+    """Return request headers with ``X-Trace-Id`` added when a trace is bound.
+
+    Merges onto ``existing`` (copied, never mutated). Works for ``requests``
+    (``headers=trace_headers()``), ``aiohttp`` (same), and ``urllib``
+    (``request.Request(url, headers=trace_headers())``). When no trace is bound
+    the header is omitted, so it is safe to call unconditionally."""
+    headers = dict(existing) if existing else {}
+    trace_id = get_trace_id()
+    if trace_id:
+        headers[TRACE_ID_HEADER] = trace_id
+    return headers

{rule_engine_core-0.0.4 → rule_engine_core-0.1.0}/rule_engine_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rule-engine-core
-Version: 0.0.4
+Version: 0.1.0
 Summary: A rule engine core library for Python.
 Home-page: https://github.com/temp-noob/rule-engine
 Author: Mohit Tripathi

{rule_engine_core-0.0.4 → rule_engine_core-0.1.0}/rule_engine_core.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ rule_engine_core/metadata_dao.py
 rule_engine_core/metadata_store.py
 rule_engine_core/parser.py
 rule_engine_core/rule.py
+rule_engine_core/tracing.py
 rule_engine_core.egg-info/PKG-INFO
 rule_engine_core.egg-info/SOURCES.txt
 rule_engine_core.egg-info/dependency_links.txt
@@ -19,4 +20,5 @@ rule_engine_core.egg-info/top_level.txt
 tests/test_metadata_dao.py
 tests/test_metadata_store_api_fetch.py
 tests/test_rule_creation_storage.py
-tests/test_rule_evaluation.py
+tests/test_rule_evaluation.py
+tests/test_tracing.py

{rule_engine_core-0.0.4 → rule_engine_core-0.1.0}/setup.py

@@ -13,8 +13,8 @@ def parse_requirements(filename):
     return requirements
 path = os.path.join(os.getenv('BUILD_PATH'), "requirements.txt")
 setup(
-    name="rule-engine-core",  
-    version="0.0.4",          
+    name="rule-engine-core",
+    version="0.1.0",
     author="Mohit Tripathi",     
     author_email="tripathimohit051@gmail.com",
     description="A rule engine core library for Python.",

rule_engine_core-0.1.0/tests/test_tracing.py

@@ -0,0 +1,219 @@
+"""
+Unit tests for rule_engine_core.tracing.
+
+Deliberately stdlib-only (no DB, no starlette/httpx) so they run fast and in
+isolation — the ASGI middleware is driven directly with a fake scope/send.
+"""
+import asyncio
+import logging
+import threading
+
+from rule_engine_core.tracing import (
+    TRACE_ID_HEADER,
+    TraceContextMiddleware,
+    TracedThread,
+    TracedThreadPoolExecutor,
+    bind_trace_id,
+    get_trace_id,
+    install_trace_log_factory,
+    new_trace_id,
+    new_trace_scope,
+    run_coro_threadsafe_with_trace,
+    trace_headers,
+)
+
+
+# ─── context primitives ──────────────────────────────────────────────────────
+
+def test_no_trace_bound_by_default():
+    assert get_trace_id() is None
+
+
+def test_bind_trace_id_sets_and_restores():
+    with bind_trace_id("abc"):
+        assert get_trace_id() == "abc"
+    assert get_trace_id() is None
+
+
+def test_bind_trace_id_generates_when_none():
+    with bind_trace_id() as tid:
+        assert tid and get_trace_id() == tid
+        assert len(tid) == 32  # uuid4 hex
+    assert get_trace_id() is None
+
+
+def test_new_trace_scope_is_fresh_each_time():
+    with new_trace_scope() as a:
+        pass
+    with new_trace_scope() as b:
+        pass
+    assert a != b
+
+
+def test_new_trace_id_unique():
+    assert new_trace_id() != new_trace_id()
+
+
+# ─── logging ─────────────────────────────────────────────────────────────────
+
+def test_log_record_carries_trace_id():
+    install_trace_log_factory()
+    factory = logging.getLogRecordFactory()
+
+    def make_record():
+        return factory("logger", logging.INFO, "path", 10, "msg", None, None)
+
+    with bind_trace_id("log-trace"):
+        assert make_record().trace_id == "log-trace"
+    # Outside any scope the placeholder keeps "%(trace_id)s" from KeyError-ing.
+    assert make_record().trace_id == "-"
+
+
+# ─── outbound egress ─────────────────────────────────────────────────────────
+
+def test_trace_headers_absent_when_unbound():
+    assert trace_headers() == {}
+    assert trace_headers({"A": "b"}) == {"A": "b"}
+
+
+def test_trace_headers_present_and_merged_when_bound():
+    with bind_trace_id("h"):
+        assert trace_headers()[TRACE_ID_HEADER] == "h"
+        merged = trace_headers({"A": "b"})
+        assert merged == {"A": "b", TRACE_ID_HEADER: "h"}
+
+
+def test_trace_headers_does_not_mutate_input():
+    original = {"A": "b"}
+    with bind_trace_id("h"):
+        trace_headers(original)
+    assert original == {"A": "b"}
+
+
+# ─── thread / pool propagation ───────────────────────────────────────────────
+
+def test_traced_thread_propagates_trace():
+    seen = {}
+    with bind_trace_id("thread-trace"):
+        t = TracedThread(target=lambda: seen.__setitem__("v", get_trace_id()))
+        t.start()
+    t.join()
+    assert seen["v"] == "thread-trace"
+
+
+def test_plain_thread_does_not_propagate():
+    # Documents *why* TracedThread exists: a vanilla thread starts with a fresh
+    # context and sees no trace.
+    seen = {}
+    with bind_trace_id("x"):
+        t = threading.Thread(target=lambda: seen.__setitem__("v", get_trace_id()))
+        t.start()
+        t.join()
+    assert seen["v"] is None
+
+
+def test_pool_propagates_submitter_trace():
+    with bind_trace_id("pool-trace"):
+        with TracedThreadPoolExecutor(max_workers=2) as pool:
+            fut = pool.submit(get_trace_id)
+        assert fut.result() == "pool-trace"
+
+
+def test_pool_captures_at_submit_not_construction():
+    # Pool built with no trace bound (as at boot); submit happens later inside a
+    # scope. Worker must see the submit-time trace, not the (empty) build-time one.
+    pool = TracedThreadPoolExecutor(max_workers=1)
+    try:
+        with bind_trace_id("later"):
+            fut = pool.submit(get_trace_id)
+        assert fut.result() == "later"
+    finally:
+        pool.shutdown()
+
+
+def test_pool_passes_through_args_and_result():
+    with bind_trace_id("t"):
+        with TracedThreadPoolExecutor(max_workers=1) as pool:
+            fut = pool.submit(lambda a, b: (a + b, get_trace_id()), 2, 3)
+        assert fut.result() == (5, "t")
+
+
+# ─── asyncio loop-in-a-thread ────────────────────────────────────────────────
+
+def test_run_coro_threadsafe_with_trace_propagates():
+    loop = asyncio.new_event_loop()
+    loop_thread = threading.Thread(target=loop.run_forever, daemon=True)
+    loop_thread.start()
+    try:
+        async def capture():
+            return get_trace_id()
+
+        with bind_trace_id("coro-trace"):
+            fut = run_coro_threadsafe_with_trace(capture(), loop)
+        assert fut.result(timeout=5) == "coro-trace"
+    finally:
+        loop.call_soon_threadsafe(loop.stop)
+        loop_thread.join(timeout=5)
+        loop.close()
+
+
+# ─── ASGI middleware ─────────────────────────────────────────────────────────
+
+def _drive_middleware(scope_headers):
+    """Run TraceContextMiddleware over a fake ASGI request; return
+    (trace seen inside the app, response messages sent)."""
+    seen = {}
+    sent = []
+
+    async def app(scope, receive, send):
+        seen["trace"] = get_trace_id()
+        await send({"type": "http.response.start", "status": 200, "headers": []})
+        await send({"type": "http.response.body", "body": b""})
+
+    async def receive():
+        return {"type": "http.request", "body": b"", "more_body": False}
+
+    async def send(message):
+        sent.append(message)
+
+    scope = {"type": "http", "headers": scope_headers}
+    asyncio.run(TraceContextMiddleware(app)(scope, receive, send))
+    return seen["trace"], sent
+
+
+def _response_headers(sent):
+    start = next(m for m in sent if m["type"] == "http.response.start")
+    return start["headers"]
+
+
+def test_middleware_adopts_incoming_header():
+    trace, sent = _drive_middleware([(b"x-trace-id", b"incoming-123")])
+    assert trace == "incoming-123"
+    assert (TRACE_ID_HEADER.encode(), b"incoming-123") in _response_headers(sent)
+    assert get_trace_id() is None  # reset after the request
+
+
+def test_middleware_generates_when_absent():
+    trace, sent = _drive_middleware([])
+    assert trace is not None and len(trace) == 32
+    assert (TRACE_ID_HEADER.encode(), trace.encode()) in _response_headers(sent)
+
+
+def test_middleware_ignores_non_http_scope():
+    # A lifespan/websocket scope should pass straight through untouched.
+    async def app(scope, receive, send):
+        send.append_marker = True
+
+    async def receive():
+        return {}
+
+    class _Send:
+        def __init__(self):
+            self.append_marker = False
+
+        async def __call__(self, message):
+            pass
+
+    send = _Send()
+    asyncio.run(TraceContextMiddleware(app)({"type": "lifespan"}, receive, send))
+    assert send.append_marker is True