traffical 0.3.0__py3-none-any.whl

traffical/__init__.py

@@ -0,0 +1,45 @@
+"""Traffical Python SDK.
+
+Public surface: TrafficalClient / AsyncTrafficalClient / TrafficalClientOptions
+plus the engine result types, the BYO assignment-logger types and the
+exceptions raised by the public constructors. The pure engine lives in
+traffical.engine.
+"""
+
+from traffical.async_client import AsyncTrafficalClient
+from traffical.client import TrafficalClient
+from traffical.config.source import ConfigSourceError
+from traffical.engine.types import (
+    ConfigBundle,
+    Context,
+    Decision,
+    DecisionMetadata,
+    LayerMetadata,
+    ParameterValue,
+)
+from traffical.events.assignments import (
+    AssignmentLogEntry,
+    AssignmentLogger,
+    AssignmentType,
+)
+from traffical.options import SDK_VERSION, EvaluationMode, TrafficalClientOptions
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "AssignmentLogEntry",
+    "AssignmentLogger",
+    "AssignmentType",
+    "AsyncTrafficalClient",
+    "ConfigBundle",
+    "ConfigSourceError",
+    "Context",
+    "Decision",
+    "DecisionMetadata",
+    "EvaluationMode",
+    "LayerMetadata",
+    "ParameterValue",
+    "TrafficalClient",
+    "TrafficalClientOptions",
+    "__version__",
+]

traffical/_fork.py

@@ -0,0 +1,41 @@
+"""Shared fork-safety registry.
+
+Threads and lock state do not survive ``os.fork()``: the child inherits locks
+that may be held by threads that no longer exist. Components with locks or
+background threads register here; an ``os.register_at_fork`` hook calls their
+``handle_fork()`` in the child to re-arm locks and drop dead thread handles so
+they restart lazily.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import weakref
+from typing import Protocol
+
+
+class ForkAware(Protocol):
+    def handle_fork(self) -> None: ...
+
+
+_registry: weakref.WeakSet[ForkAware] = weakref.WeakSet()
+_registry_lock = threading.Lock()
+_hook_installed = False
+
+
+def _after_in_child() -> None:
+    global _registry_lock
+    _registry_lock = threading.Lock()
+    for member in list(_registry):
+        member.handle_fork()
+
+
+def register_fork_aware(member: ForkAware) -> None:
+    """Registers ``member`` (weakly) for ``handle_fork()`` in forked children."""
+    global _hook_installed
+    with _registry_lock:
+        _registry.add(member)
+        if not _hook_installed and hasattr(os, "register_at_fork"):
+            os.register_at_fork(after_in_child=_after_in_child)
+            _hook_installed = True

traffical/async_client.py

@@ -0,0 +1,335 @@
+"""Asyncio Traffical client: same surface as TrafficalClient with async methods.
+
+Evaluation is pure CPU, so there is no global evaluation lock; only config
+delivery and event flushing run as asyncio tasks. The background poller is
+started lazily on the first async call (or via ``async with`` / ``start()``)
+because task creation needs a running event loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from traffical.client import (
+    RESOLVE_PATH,
+    DecisionCache,
+    build_decision_event,
+    build_exposure_event,
+    build_track_event,
+    decision_from_resolve_response,
+    fallback_decision,
+    overlay_assignments,
+    resolve_headers,
+    resolve_request_body,
+    surviving_exposure_layers,
+    utc_now_iso,
+)
+from traffical.config.poller import DEFAULT_INTERVAL_SECONDS, AsyncConfigPoller
+from traffical.config.readiness import AsyncBundleStore
+from traffical.config.source import ConfigSource, HTTPConfigSource, coerce_bundle
+from traffical.engine.ids import new_decision_id
+from traffical.engine.resolution import decide as engine_decide
+from traffical.engine.resolution import resolve_parameters
+from traffical.engine.types import ConfigBundle, Context, Decision, ParameterValue
+from traffical.events.assignments import AssignmentLogEmitter
+from traffical.events.dedup import (
+    DecisionDeduplicator,
+    decision_dedup_key,
+    hash_assignments,
+)
+from traffical.events.logger import AsyncEventPipeline
+from traffical.options import SDK_NAME, SDK_VERSION, TrafficalClientOptions
+
+logger = logging.getLogger("traffical")
+
+
+class AsyncTrafficalClient:
+    """Asyncio Traffical SDK client (bundle or server evaluation mode)."""
+
+    def __init__(self, options: TrafficalClientOptions) -> None:
+        self._options = options
+        self._closed = False
+        self._started = False
+
+        initial: ConfigBundle | None = (
+            coerce_bundle(options.local_config) if options.local_config is not None else None
+        )
+        self._store = AsyncBundleStore(initial=initial)
+
+        self._source: ConfigSource | None = None
+        self._owns_source = False
+        self._poller: AsyncConfigPoller | None = None
+        self._oneshot_task: asyncio.Task[float] | None = None
+        self._resolve_client: httpx.AsyncClient | None = None
+
+        if options.evaluation_mode == "bundle":
+            source = options.config_source
+            if source is None:
+                source = HTTPConfigSource(
+                    project_id=options.project_id,
+                    env=options.env,
+                    api_key=options.api_key,
+                    base_url=options.base_url,
+                    timeout=options.config_timeout_seconds,
+                    transport=options.transport,
+                )
+                self._owns_source = True
+            self._source = source
+            interval = (
+                options.refresh_interval_seconds
+                if options.refresh_interval_seconds > 0
+                else DEFAULT_INTERVAL_SECONDS
+            )
+            self._poller = AsyncConfigPoller(source, self._store, interval=interval)
+        else:
+            self._resolve_client = httpx.AsyncClient(
+                timeout=options.resolve_timeout_seconds, transport=options.async_transport
+            )
+
+        self._pipeline = AsyncEventPipeline(
+            base_url=options.base_url,
+            api_key=options.api_key,
+            batch_size=options.batch_size,
+            flush_interval=options.flush_interval_seconds,
+            max_queue_size=options.max_event_queue_size,
+            max_retries=options.event_max_retries,
+            request_timeout=options.events_timeout_seconds,
+            transport=options.async_transport,
+            disable_cloud_events=options.disable_cloud_events,
+        )
+        self._decision_dedup = DecisionDeduplicator(ttl_seconds=options.decision_dedup_ttl_seconds)
+        self._exposure_dedup = (
+            DecisionDeduplicator(ttl_seconds=options.exposure_session_ttl_seconds)
+            if options.deduplicate_exposures
+            else None
+        )
+        self._decision_cache = DecisionCache()
+        self._assignments = AssignmentLogEmitter(
+            options.assignment_logger,
+            deduplicate=options.deduplicate_assignment_logger,
+            org_id=options.org_id,
+            project_id=options.project_id,
+            env=options.env,
+            sdk_name=SDK_NAME,
+            sdk_version=SDK_VERSION,
+        )
+
+    @property
+    def options(self) -> TrafficalClientOptions:
+        return self._options
+
+    @property
+    def bundle(self) -> ConfigBundle | None:
+        return self._store.bundle
+
+    def start(self) -> None:
+        """Starts background config delivery; requires a running event loop."""
+        if self._closed or self._poller is None:
+            return
+        self._started = True
+        if self._options.refresh_interval_seconds > 0:
+            self._poller.start()
+        elif self._oneshot_task is None:
+            self._oneshot_task = asyncio.get_running_loop().create_task(self._poller.poll_once())
+
+    async def wait_for_ready(self, timeout: float | None = None) -> bool:
+        """Waits until a config bundle is available (always True in server mode)."""
+        if self._options.evaluation_mode == "server":
+            return True
+        self._ensure_alive()
+        return await self._store.wait_for_ready(timeout)
+
+    async def get_params(
+        self, context: Context, defaults: Mapping[str, ParameterValue]
+    ) -> dict[str, ParameterValue]:
+        """Resolved values for exactly the keys in ``defaults`` (fail-open)."""
+        try:
+            self._ensure_alive()
+            if self._options.evaluation_mode == "server":
+                data = await self._post_resolve(context, defaults)
+                if data is None:
+                    return dict(defaults)
+                return overlay_assignments(defaults, data.get("assignments") or {})
+            return resolve_parameters(self._store.bundle, context, defaults)
+        except Exception:
+            logger.exception("Traffical get_params failed; returning defaults")
+            return dict(defaults)
+
+    async def decide(self, context: Context, defaults: Mapping[str, ParameterValue]) -> Decision:
+        """Full decision with tracking metadata (fail-open to defaults)."""
+        timestamp = utc_now_iso()
+        try:
+            self._ensure_alive()
+            start = time.monotonic()
+            if self._options.evaluation_mode == "server":
+                data = await self._post_resolve(context, defaults)
+                decision = (
+                    decision_from_resolve_response(data, defaults)
+                    if data is not None
+                    else fallback_decision(defaults, timestamp)
+                )
+            else:
+                decision = engine_decide(
+                    self._store.bundle,
+                    context,
+                    defaults,
+                    decision_id=new_decision_id(),
+                    timestamp=timestamp,
+                )
+            latency_ms = round((time.monotonic() - start) * 1000.0)
+            self._decision_cache.put(decision)
+        except Exception:
+            logger.exception("Traffical decide failed; returning defaults")
+            return fallback_decision(defaults, timestamp)
+        try:
+            if self._options.track_decisions:
+                self._track_decision(decision, list(defaults), latency_ms)
+            self._assignments.emit(decision, "decision")
+        except Exception:
+            logger.exception("Traffical decision tracking failed; decision still returned")
+        return decision
+
+    def track_exposure(self, decision: Decision) -> None:
+        """Emits at most one exposure event for a decision (S4; fail-open).
+
+        The event carries only newly-exposed, non-attributionOnly layers;
+        session-deduped layers are suppressed and no event is emitted when
+        nothing survives filtering.
+        """
+        try:
+            self._assignments.emit(decision, "exposure")
+            layers = surviving_exposure_layers(decision, self._exposure_dedup)
+            event = build_exposure_event(decision, self._options, utc_now_iso(), layers)
+            if event is not None:
+                self._pipeline.emit(event)
+        except Exception:
+            logger.exception("Traffical track_exposure failed; event dropped")
+
+    def track(
+        self,
+        event_name: str,
+        properties: Mapping[str, Any] | None = None,
+        *,
+        decision_id: str | None = None,
+        unit_key: str | None = None,
+        value: float | None = None,
+        values: Mapping[str, float] | None = None,
+        event_timestamp: str | None = None,
+        user_id: str | None = None,
+        anonymous_id: str | None = None,
+        session_id: str | None = None,
+    ) -> None:
+        """Tracks a user event, auto-attributing from a cached decision (fail-open).
+
+        ``value``/``values`` carry primary and multi-objective numeric metrics;
+        ``event_timestamp`` records the original time for delayed events;
+        ``user_id``/``anonymous_id``/``session_id`` are optional identity fields.
+        """
+        try:
+            event = build_track_event(
+                event_name,
+                self._options,
+                utc_now_iso(),
+                properties,
+                decision_id,
+                unit_key,
+                self._decision_cache.attribution(decision_id),
+                value=value,
+                values=values,
+                event_timestamp=event_timestamp,
+                user_id=user_id,
+                anonymous_id=anonymous_id,
+                session_id=session_id,
+            )
+            self._pipeline.emit(event)
+        except Exception:
+            logger.exception("Traffical track failed; event dropped")
+
+    async def flush_events(self, timeout: float | None = None) -> bool:
+        """Flushes pending events; True if the queue drained within the timeout."""
+        try:
+            return await self._pipeline.flush(timeout)
+        except Exception:
+            logger.exception("Traffical flush_events failed")
+            return False
+
+    async def close(self, timeout: float | None = None) -> None:
+        """Flushes events and releases all background resources (idempotent)."""
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            if self._poller is not None:
+                await self._poller.stop()
+            if self._oneshot_task is not None and not self._oneshot_task.done():
+                self._oneshot_task.cancel()
+            if self._owns_source and isinstance(self._source, HTTPConfigSource):
+                self._source.close()
+            if self._resolve_client is not None:
+                await self._resolve_client.aclose()
+            await self._pipeline.close(timeout)
+        except Exception:
+            logger.exception("Traffical close failed")
+
+    async def __aenter__(self) -> AsyncTrafficalClient:
+        self.start()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    def _ensure_alive(self) -> None:
+        if self._poller is None or self._closed:
+            return
+        if not self._started:
+            self.start()
+            return
+        self._poller.ensure_alive()
+
+    async def _post_resolve(
+        self, context: Context, defaults: Mapping[str, ParameterValue]
+    ) -> Mapping[str, Any] | None:
+        assert self._resolve_client is not None
+        url = f"{self._options.base_url.rstrip('/')}{RESOLVE_PATH}"
+        try:
+            response = await self._resolve_client.post(
+                url,
+                json=resolve_request_body(context, self._options.env, defaults),
+                headers=resolve_headers(self._options),
+            )
+        except httpx.HTTPError as exc:
+            logger.warning("Traffical resolve request failed: %s", exc)
+            return None
+        if not response.is_success:
+            logger.warning("Traffical resolve returned HTTP %s", response.status_code)
+            return None
+        data = response.json()
+        if not isinstance(data, Mapping):
+            logger.warning("Traffical resolve returned a non-object payload")
+            return None
+        return data
+
+    def _track_decision(
+        self, decision: Decision, requested_parameters: list[str], latency_ms: int
+    ) -> None:
+        unit_key = decision.metadata.unit_key_value
+        if not unit_key:
+            return
+        key = decision_dedup_key(unit_key, hash_assignments(decision.assignments))
+        if not self._decision_dedup.check_and_mark(key):
+            return
+        event = build_decision_event(decision, self._options, requested_parameters, latency_ms)
+        if event is not None:
+            self._pipeline.emit(event)