proofrun 0.1.1__py3-none-any.whl

proofrun/core/context.py

@@ -0,0 +1,185 @@
+"""Execution context and dynamic variable interpolation module for Proofrun.
+
+This module manages runtime state persistence across scenario steps, JSONPath
+variable extraction from API responses, nested payload interpolation, and
+built-in dynamic generators.
+"""
+
+import random
+import re
+import time
+import uuid
+from typing import Any
+
+from jsonpath_ng import parse
+
+
+class ContextError(Exception):
+    """Raised when variable extraction or interpolation fails."""
+
+
+class ExecutionContext:
+    """Manages runtime state and dynamic variable interpolation."""
+
+    VAR_PATTERN = re.compile(r"\$\{([a-zA-Z0-9_.$]+)\}")
+
+    def __init__(
+        self,
+        initial_vars: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the execution context.
+
+        Args:
+            initial_vars: Optional initial variables. The dictionary is copied.
+        """
+        self.variables: dict[str, Any] = (
+            dict(initial_vars) if initial_vars is not None else {}
+        )
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a runtime variable."""
+        self.variables[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a runtime variable."""
+        return self.variables.get(key, default)
+
+    def _get_dynamic_variable(self, var_name: str) -> Any | None:
+        """Resolve a built-in dynamic variable.
+
+        Note: These generate a new value every time they are called. Multiple
+        references to ${$uuid} in a single payload will yield different UUIDs.
+        """
+        if var_name == "$uuid":
+            return str(uuid.uuid4())
+
+        if var_name == "$timestamp":
+            return int(time.time())
+
+        if var_name == "$timestamp_ms":
+            return int(time.time() * 1000)
+
+        if var_name == "$iso_timestamp":
+            return time.strftime(
+                "%Y-%m-%dT%H:%M:%SZ",
+                time.gmtime(),
+            )
+
+        if var_name == "$random_int":
+            return random.randint(1000, 9999)
+
+        return None
+
+    def extract_variables(
+        self,
+        payload: dict[str, Any] | list[Any],
+        rules: dict[str, str],
+    ) -> None:
+        """Extract variables from a JSON payload using JSONPath.
+
+        Args:
+            payload: JSON response body.
+            rules: Mapping of variable names to JSONPath expressions.
+
+        Raises:
+            ContextError: If a JSONPath expression is invalid or produces
+                no matches.
+        """
+        for var_name, jsonpath_expr in rules.items():
+            try:
+                expression = parse(jsonpath_expr)
+                matches = [match.value for match in expression.find(payload)]
+            except Exception as err:
+                raise ContextError(
+                    f"Invalid JSONPath expression "
+                    f"'{jsonpath_expr}' for variable "
+                    f"'{var_name}': {err}"
+                ) from err
+
+            if not matches:
+                raise ContextError(
+                    f"JSONPath extraction failed: Path "
+                    f"'{jsonpath_expr}' did not match any value "
+                    "in response."
+                )
+
+            self.variables[var_name] = matches[0]
+
+    def interpolate_string(self, text: str) -> Any:
+        """Interpolate variables inside a string.
+
+        An exact variable reference preserves its original type.
+
+        For example:
+
+            "${user_id}"
+
+        can return:
+
+            123
+
+        while:
+
+            "User ${user_id}"
+
+        returns:
+
+            "User 123"
+        """
+        exact_match = self.VAR_PATTERN.fullmatch(text.strip())
+
+        if exact_match:
+            var_name = exact_match.group(1)
+
+            if var_name.startswith("$"):
+                dynamic_value = self._get_dynamic_variable(var_name)
+
+                if dynamic_value is not None:
+                    return dynamic_value
+
+            if var_name not in self.variables:
+                raise ContextError(
+                    f"Missing required context variable: '${{{var_name}}}'"
+                )
+
+            return self.variables[var_name]
+
+        def replace_var(match: re.Match[str]) -> str:
+            var_name = match.group(1)
+
+            if var_name.startswith("$"):
+                dynamic_value = self._get_dynamic_variable(var_name)
+
+                if dynamic_value is not None:
+                    return str(dynamic_value)
+
+            if var_name not in self.variables:
+                raise ContextError(
+                    f"Missing required context variable: '${{{var_name}}}'"
+                )
+
+            return str(self.variables[var_name])
+
+        return self.VAR_PATTERN.sub(replace_var, text)
+
+    def interpolate_data(self, data: Any) -> Any:
+        """Recursively interpolate strings inside nested request data.
+
+        This will interpolate strings found in dictionary values,
+        dictionary keys, and list items.
+        """
+        if isinstance(data, str):
+            return self.interpolate_string(data)
+
+        if isinstance(data, dict):
+            return {
+                (
+                    self.interpolate_string(key) if isinstance(key, str) else key
+                ): self.interpolate_data(value)
+                for key, value in data.items()
+            }
+
+        if isinstance(data, list):
+            return [self.interpolate_data(item) for item in data]
+
+        return data

proofrun/core/engine.py

@@ -0,0 +1,231 @@
+"""Asynchronous HTTP execution engine for Proofrun synthetic monitoring.
+
+This module executes multi-step HTTP monitoring scenarios using httpx,
+evaluates response assertions, extracts runtime variables into
+ExecutionContext, and records high-resolution latency metrics.
+"""
+
+from dataclasses import dataclass, field
+from time import perf_counter
+from typing import Any
+
+import httpx
+
+from proofrun.core.config import ScenarioConfig, StepConfig
+from proofrun.core.context import ExecutionContext
+
+
+class EngineError(Exception):
+    """Raised when HTTP step execution or assertion evaluation fails."""
+
+
+@dataclass
+class StepResult:
+    """Execution outcome and performance metrics for one scenario step."""
+
+    step_name: str
+    passed: bool
+    status_code: int
+    latency_ms: float
+    error: str | None = None
+
+
+@dataclass
+class ScenarioResult:
+    """Aggregated execution outcome for a complete scenario."""
+
+    scenario_name: str
+    passed: bool
+    total_latency_ms: float
+    step_results: list[StepResult] = field(default_factory=list)
+
+
+class ScenarioRunner:
+    """Execute multi-step HTTP monitoring scenarios asynchronously."""
+
+    def __init__(
+        self,
+        scenario: ScenarioConfig,
+        context: ExecutionContext | None = None,
+    ) -> None:
+        """Initialize a scenario runner.
+
+        Args:
+            scenario: Compiled scenario configuration.
+            context: Optional execution context shared across steps.
+        """
+        self.scenario = scenario
+        self.context = context if context is not None else ExecutionContext()
+
+    async def execute_step(
+        self,
+        step: StepConfig,
+        client: httpx.AsyncClient,
+    ) -> StepResult:
+        """Execute and validate a single scenario step.
+
+        The execution pipeline is:
+
+        1. Validate the scenario base URL.
+        2. Validate the resolved request timeout.
+        3. Interpolate path, headers, query parameters, and JSON payload.
+        4. Execute the HTTP request.
+        5. Validate the HTTP status code(s).
+        6. Validate the latency ceiling.
+        7. Validate expected response headers.
+        8. Parse JSON when schema validation or extraction is required.
+        9. Validate the pre-compiled JSON schema.
+        10. Extract runtime variables for subsequent steps.
+
+        Args:
+            step: Individual scenario step configuration.
+            client: Shared asynchronous HTTP client.
+
+        Returns:
+            A StepResult describing success/failure and timing.
+        """
+        start_time = perf_counter()
+        response: httpx.Response | None = None
+
+        try:
+            if not self.scenario.base_url:
+                raise EngineError(
+                    f"Scenario '{self.scenario.name}' is missing a valid base_url."
+                )
+
+            if step.request.timeout is None:
+                raise EngineError(
+                    f"Step '{step.name}' is missing a resolved request timeout."
+                )
+
+            interpolated_path = self.context.interpolate_string(step.request.path)
+
+            base_url = str(self.scenario.base_url).rstrip("/")
+            full_url = f"{base_url}/{str(interpolated_path).lstrip('/')}"
+
+            headers = self.context.interpolate_data(step.request.headers)
+            params = self.context.interpolate_data(step.request.params)
+            json_payload = self.context.interpolate_data(step.request.json_payload)
+
+            response = await client.request(
+                method=step.request.method,
+                url=full_url,
+                headers=headers,
+                params=params,
+                json=json_payload,
+                timeout=step.request.timeout,
+            )
+
+            latency_ms = (perf_counter() - start_time) * 1000
+
+            expected_statuses = (
+                [step.expect.status]
+                if isinstance(step.expect.status, int)
+                else step.expect.status
+            )
+            if response.status_code not in expected_statuses:
+                raise EngineError(
+                    f"Status code mismatch: expected one of "
+                    f"{expected_statuses}, got {response.status_code}"
+                )
+
+            if (
+                step.expect.max_latency_ms is not None
+                and latency_ms > step.expect.max_latency_ms
+            ):
+                raise EngineError(
+                    f"Latency limit exceeded: response took "
+                    f"{latency_ms:.2f} ms "
+                    f"(max allowed: "
+                    f"{step.expect.max_latency_ms} ms)"
+                )
+
+            for expected_header, expected_value in step.expect.headers.items():
+                actual_value = response.headers.get(expected_header)
+
+                if actual_value != expected_value:
+                    raise EngineError(
+                        f"Header '{expected_header}' mismatch: expected "
+                        f"'{expected_value}', got '{actual_value}'"
+                    )
+
+            response_data: Any = None
+
+            if step.expect._compiled_schema is not None or step.extract:
+                try:
+                    response_data = response.json()
+                except Exception as err:
+                    raise EngineError(
+                        f"Response body is not valid JSON: {err}"
+                    ) from err
+
+            if step.expect._compiled_schema is not None:
+                try:
+                    step.expect._compiled_schema(response_data)
+                except Exception as err:
+                    raise EngineError(f"Schema assertion failed: {err}") from err
+
+            if step.extract:
+                self.context.extract_variables(
+                    response_data,
+                    step.extract,
+                )
+
+            return StepResult(
+                step_name=step.name,
+                passed=True,
+                status_code=response.status_code,
+                latency_ms=round(latency_ms, 2),
+            )
+
+        except Exception as err:  # noqa: BLE001
+            latency_ms = (perf_counter() - start_time) * 1000
+
+            status_code = response.status_code if response is not None else 0
+
+            return StepResult(
+                step_name=step.name,
+                passed=False,
+                status_code=status_code,
+                latency_ms=round(latency_ms, 2),
+                error=str(err),
+            )
+
+    async def run(self, client: httpx.AsyncClient) -> ScenarioResult:
+        """Execute all scenario steps sequentially.
+
+        All steps share the same ExecutionContext, allowing values extracted
+        from earlier responses to be used by later requests.
+
+        Execution stops at the first failed step.
+
+        Args:
+            client: Shared asynchronous HTTP client for connection pooling.
+
+        Returns:
+            ScenarioResult containing the aggregate scenario outcome,
+            total execution latency, and individual step results.
+        """
+        step_results: list[StepResult] = []
+        scenario_passed = True
+
+        total_start = perf_counter()
+
+        client.cookies.clear()
+
+        for step in self.scenario.steps:
+            result = await self.execute_step(step, client)
+            step_results.append(result)
+
+            if not result.passed:
+                scenario_passed = False
+                break
+
+        total_latency_ms = (perf_counter() - total_start) * 1000
+
+        return ScenarioResult(
+            scenario_name=self.scenario.name,
+            passed=scenario_passed,
+            total_latency_ms=round(total_latency_ms, 2),
+            step_results=step_results,
+        )

proofrun/core/notifier.py

@@ -0,0 +1,75 @@
+"""Notification abstractions and generic webhook notification delivery."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import httpx
+from rich.console import Console
+
+from proofrun.core.state import Status
+
+console = Console()
+
+
+@dataclass(frozen=True)
+class NotificationEvent:
+    """Data payload for a scenario health-state transition notification."""
+
+    scenario_name: str
+    old_status: Status
+    new_status: Status
+    details: str = ""
+
+
+class Notifier(Protocol):
+    """Interface for delivering notification events."""
+
+    async def notify(self, event: NotificationEvent) -> None:
+        """Deliver a notification event."""
+        ...  # pragma: no cover
+
+
+class WebhookNotifier:
+    """Deliver notification events to a generic HTTP webhook."""
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        webhook_url: str,
+    ) -> None:
+        self.client = client
+        self.webhook_url = webhook_url
+
+    async def notify(self, event: NotificationEvent) -> None:
+        """Send a notification event as provider-neutral JSON."""
+        if event.new_status == Status.HEALTHY:
+            event_type = "scenario_recovered"
+        elif event.new_status == Status.FAILING:
+            event_type = "scenario_failed"
+        else:
+            return
+
+        payload = {
+            "event": event_type,
+            "scenario": event.scenario_name,
+            "previous_status": event.old_status.value,
+            "status": event.new_status.value,
+            "details": event.details,
+        }
+
+        try:
+            response = await self.client.post(
+                self.webhook_url,
+                json=payload,
+                timeout=5.0,
+            )
+            response.raise_for_status()
+
+            console.print(
+                f"[dim]Dispatched webhook alert for: {event.scenario_name}[/dim]"
+            )
+
+        except httpx.HTTPError as err:
+            console.print(f"[bold red]Failed to send webhook:[/bold red] {err}")

proofrun/core/provider.py

@@ -0,0 +1,55 @@
+"""Configuration loading and caching for Proofrun."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from proofrun.core.compiler import (
+    ConfigCompilerError,
+    load_and_compile_config,
+)
+from proofrun.core.config import ProofrunConfig
+
+
+@dataclass
+class ConfigProvider:
+    """Manage a cached, compiled Proofrun configuration."""
+
+    config_path: Path
+    _config: ProofrunConfig | None = None
+    _last_modified_ns: int | None = None
+
+    def load(self) -> tuple[ProofrunConfig | None, ConfigCompilerError | None]:
+        """Load the configuration when needed.
+
+        The configuration is compiled on the first call and whenever the
+        configuration file modification time changes.
+
+        If a changed configuration is invalid, the last known-good
+        configuration is retained and the compiler error is returned.
+
+        Returns:
+            A tuple containing the current configuration and an optional
+            compilation error.
+        """
+        try:
+            modified_ns = self.config_path.stat().st_mtime_ns
+        except OSError as err:
+            error = ConfigCompilerError(
+                f"Unable to access configuration file '{self.config_path}': {err}"
+            )
+            return self._config, error
+
+        if self._config is not None and self._last_modified_ns == modified_ns:
+            return self._config, None
+
+        try:
+            config = load_and_compile_config(self.config_path)
+        except ConfigCompilerError as err:
+            return self._config, err
+
+        self._config = config
+        self._last_modified_ns = modified_ns
+
+        return self._config, None

proofrun/core/state.py

@@ -0,0 +1,81 @@
+"""State management for tracking scenario health transitions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Status(Enum):
+    """The health status of a scenario."""
+
+    UNKNOWN = "UNKNOWN"
+    HEALTHY = "HEALTHY"
+    FAILING = "FAILING"
+
+
+@dataclass
+class ScenarioState:
+    """Tracks the current state of a single scenario."""
+
+    status: Status = Status.UNKNOWN
+    fail_count: int = 0
+    pass_count: int = 0
+
+
+@dataclass(frozen=True)
+class StateTransition:
+    """Describes a scenario health-state transition."""
+
+    scenario_name: str
+    old_status: Status
+    new_status: Status
+
+    @property
+    def changed(self) -> bool:
+        """Return whether the scenario changed health state."""
+        return self.old_status != self.new_status
+
+
+class StateManager:
+    """Manages state across all scenarios for alerting purposes."""
+
+    def __init__(self) -> None:
+        self.states: dict[str, ScenarioState] = {}
+
+    def update(
+        self,
+        scenario_name: str,
+        passed: bool,
+    ) -> StateTransition:
+        """Update scenario state and return the resulting transition."""
+        if scenario_name not in self.states:
+            self.states[scenario_name] = ScenarioState()
+
+        state = self.states[scenario_name]
+        old_status = state.status
+
+        if passed:
+            state.status = Status.HEALTHY
+            state.pass_count += 1
+            state.fail_count = 0
+        else:
+            state.status = Status.FAILING
+            state.fail_count += 1
+            state.pass_count = 0
+
+        return StateTransition(
+            scenario_name=scenario_name,
+            old_status=old_status,
+            new_status=state.status,
+        )
+
+    def sync(self, active_scenario_names: set[str]) -> None:
+        """Remove state for scenarios that no longer exist in the configuration.
+
+        Call this periodically or after a configuration hot-reload to prevent
+        memory leaks from deleted scenarios.
+        """
+        stale_keys = set(self.states.keys()) - active_scenario_names
+        for key in stale_keys:
+            del self.states[key]