timetracer 1.1.0__py3-none-any.whl

timetracer/policies/redaction.py

@@ -0,0 +1,165 @@
+"""
+Redaction policies for sensitive data.
+
+Removes or masks sensitive headers and body content before storage.
+Uses centralized constants for consistency.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from timetracer.constants import ALLOWED_HEADERS, Redaction
+
+
+def redact_headers(
+    headers: dict[str, str],
+    *,
+    mode: str = "drop",
+    additional_sensitive: set[str] | None = None,
+) -> dict[str, str]:
+    """
+    Redact sensitive headers.
+
+    Args:
+        headers: Original headers dict.
+        mode: "drop" to remove sensitive headers, "mask" to replace values.
+        additional_sensitive: Additional header names to treat as sensitive.
+
+    Returns:
+        New dict with sensitive headers removed or masked.
+    """
+    sensitive = Redaction.SENSITIVE_HEADERS
+    if additional_sensitive:
+        sensitive = sensitive | {h.lower() for h in additional_sensitive}
+
+    result = {}
+    for key, value in headers.items():
+        key_lower = key.lower()
+
+        if key_lower in sensitive:
+            if mode == "mask":
+                result[key] = Redaction.REDACTED_VALUE
+            # else: drop (don't include)
+        else:
+            result[key] = value
+
+    return result
+
+
+def redact_headers_allowlist(
+    headers: dict[str, str],
+    allowed: frozenset[str] | None = None,
+) -> dict[str, str]:
+    """
+    Keep only allowed headers (allowlist approach).
+
+    This is safer than blocklist - only explicitly allowed headers are kept.
+
+    Args:
+        headers: Original headers dict.
+        allowed: Set of allowed header names (lowercase). Defaults to ALLOWED_HEADERS.
+
+    Returns:
+        New dict with only allowed headers.
+    """
+    if allowed is None:
+        allowed = ALLOWED_HEADERS
+
+    return {
+        key: value
+        for key, value in headers.items()
+        if key.lower() in allowed
+    }
+
+
+def redact_body(
+    body: Any,
+    *,
+    additional_sensitive_keys: set[str] | None = None,
+) -> Any:
+    """
+    Redact sensitive keys in a body object.
+
+    Recursively processes dicts and lists.
+
+    Args:
+        body: The body data (usually a dict or list).
+        additional_sensitive_keys: Additional keys to redact.
+
+    Returns:
+        New object with sensitive values masked.
+    """
+    if body is None:
+        return None
+
+    sensitive_keys = Redaction.SENSITIVE_BODY_KEYS
+    if additional_sensitive_keys:
+        sensitive_keys = sensitive_keys | {k.lower() for k in additional_sensitive_keys}
+
+    return _redact_recursive(body, sensitive_keys)
+
+
+def _redact_recursive(obj: Any, sensitive_keys: frozenset[str]) -> Any:
+    """Recursively redact sensitive keys."""
+    if isinstance(obj, dict):
+        result = {}
+        for key, value in obj.items():
+            if _is_sensitive_key(key, sensitive_keys):
+                result[key] = Redaction.REDACTED_VALUE
+            else:
+                result[key] = _redact_recursive(value, sensitive_keys)
+        return result
+
+    elif isinstance(obj, list):
+        return [_redact_recursive(item, sensitive_keys) for item in obj]
+
+    elif isinstance(obj, str):
+        # Optionally mask token-like strings
+        return _mask_token_like(obj)
+
+    else:
+        return obj
+
+
+def _is_sensitive_key(key: str, sensitive_keys: frozenset[str]) -> bool:
+    """Check if a key is sensitive (case-insensitive substring match)."""
+    key_lower = key.lower()
+
+    # Exact match
+    if key_lower in sensitive_keys:
+        return True
+
+    # Substring match for compound keys
+    for sensitive in sensitive_keys:
+        if sensitive in key_lower:
+            return True
+
+    return False
+
+
+def _mask_token_like(value: str) -> str:
+    """
+    Mask token-like strings in values.
+
+    Patterns:
+    - JWT tokens (eyJ...)
+    - Bearer tokens
+    - API keys (long alphanumeric strings)
+    """
+    # JWT pattern
+    if value.startswith("eyJ") and value.count(".") == 2:
+        return Redaction.REDACTED_VALUE
+
+    # Bearer prefix
+    if value.lower().startswith("bearer "):
+        return f"Bearer {Redaction.REDACTED_VALUE}"
+
+    # Very long alphanumeric strings (likely API keys)
+    if len(value) > 32 and re.match(r"^[a-zA-Z0-9_-]+$", value):
+        # Only mask if it looks random (has mixed case or underscores)
+        if re.search(r"[a-z]", value) and re.search(r"[A-Z0-9_-]", value):
+            return Redaction.REDACTED_VALUE
+
+    return value

timetracer/replay/__init__.py

@@ -0,0 +1,6 @@
+"""Replay module for cassette playback."""
+
+from timetracer.replay.engine import ReplayEngine
+from timetracer.replay.errors import ReplayMismatchError
+
+__all__ = ["ReplayMismatchError", "ReplayEngine"]

timetracer/replay/engine.py

@@ -0,0 +1,75 @@
+"""
+Replay engine for Timetracer.
+
+The ReplayEngine manages cassette playback and event matching.
+Most functionality is in ReplaySession (session.py), this provides
+additional utilities.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from timetracer.cassette import read_cassette
+from timetracer.constants import EventType
+from timetracer.session import ReplaySession
+
+if TYPE_CHECKING:
+    from timetracer.types import Cassette, DependencyEvent
+
+
+class ReplayEngine:
+    """
+    Engine for replaying cassettes.
+
+    This is a convenience wrapper around ReplaySession for programmatic use.
+    Most applications will use ReplaySession directly via the middleware.
+    """
+
+    def __init__(
+        self,
+        cassette_path: str,
+        strict: bool = True,
+    ) -> None:
+        """
+        Initialize replay engine.
+
+        Args:
+            cassette_path: Path to the cassette file.
+            strict: If True, raise on mismatches.
+        """
+        self.cassette_path = cassette_path
+        self.strict = strict
+        self._cassette: Cassette | None = None
+        self._session: ReplaySession | None = None
+
+    def load(self) -> None:
+        """Load the cassette from disk."""
+        self._cassette = read_cassette(self.cassette_path)
+        self._session = ReplaySession(
+            cassette=self._cassette,
+            cassette_path=self.cassette_path,
+            strict=self.strict,
+        )
+
+    @property
+    def cassette(self) -> Cassette:
+        """Get loaded cassette."""
+        if self._cassette is None:
+            raise RuntimeError("Cassette not loaded. Call load() first.")
+        return self._cassette
+
+    @property
+    def session(self) -> ReplaySession:
+        """Get replay session."""
+        if self._session is None:
+            raise RuntimeError("Session not created. Call load() first.")
+        return self._session
+
+    def get_events_by_type(self, event_type: EventType) -> list[DependencyEvent]:
+        """Get all events of a specific type."""
+        return [e for e in self.cassette.events if e.event_type == event_type]
+
+    def get_http_events(self) -> list[DependencyEvent]:
+        """Get all HTTP client events."""
+        return self.get_events_by_type(EventType.HTTP_CLIENT)

timetracer/replay/errors.py

@@ -0,0 +1,9 @@
+"""
+Replay errors for Timetracer.
+
+Re-exports from the main exceptions module for convenience.
+"""
+
+from timetracer.exceptions import ReplayMismatchError
+
+__all__ = ["ReplayMismatchError"]

timetracer/replay/matching.py

@@ -0,0 +1,83 @@
+"""
+Signature matching for replay.
+
+Provides utilities for comparing recorded and actual call signatures.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+from timetracer.types import EventSignature
+
+
+def normalize_url(url: str) -> str:
+    """
+    Normalize a URL for comparison.
+
+    Removes query string, normalizes scheme/host/path.
+    """
+    parsed = urlparse(url)
+    return f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
+
+
+def normalize_query(query_string: str) -> dict[str, Any]:
+    """Normalize query string to sorted dict."""
+    parsed = parse_qs(query_string)
+    # Flatten single-value lists
+    return {k: v[0] if len(v) == 1 else sorted(v) for k, v in sorted(parsed.items())}
+
+
+def signatures_match(
+    expected: EventSignature,
+    actual: dict[str, Any],
+    *,
+    check_body_hash: bool = False,
+) -> tuple[bool, list[str]]:
+    """
+    Check if two signatures match.
+
+    Args:
+        expected: The recorded signature.
+        actual: The actual call signature dict.
+        check_body_hash: Whether to compare body hashes.
+
+    Returns:
+        Tuple of (matches, list of mismatch reasons).
+    """
+    mismatches: list[str] = []
+
+    # Check method
+    if expected.method != actual.get("method"):
+        mismatches.append(
+            f"method: expected {expected.method}, got {actual.get('method')}"
+        )
+
+    # Check URL
+    expected_url = normalize_url(expected.url) if expected.url else None
+    actual_url = normalize_url(actual.get("url", "")) if actual.get("url") else None
+
+    if expected_url != actual_url:
+        mismatches.append(
+            f"url: expected {expected_url}, got {actual_url}"
+        )
+
+    # Check body hash (optional)
+    if check_body_hash and expected.body_hash:
+        if expected.body_hash != actual.get("body_hash"):
+            mismatches.append(
+                f"body_hash: expected {expected.body_hash[:20]}..., got {actual.get('body_hash', 'none')[:20]}..."
+            )
+
+    return len(mismatches) == 0, mismatches
+
+
+def create_signature_summary(sig: EventSignature) -> str:
+    """Create a human-readable summary of a signature."""
+    parts = [sig.method]
+    if sig.url:
+        parts.append(sig.url)
+    if sig.query:
+        parts.append(f"?{len(sig.query)} params")
+    return " ".join(parts)