proofrun 0.1.1__py3-none-any.whl

proofrun/__init__.py

@@ -0,0 +1,10 @@
+"""Proofrun synthetic API monitoring package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("proofrun")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

proofrun/__main__.py

@@ -0,0 +1,9 @@
+"""Entry point for the Proofrun CLI.
+
+Allows the package to be executed via `python -m proofrun`.
+"""
+
+from proofrun.cli import main
+
+if __name__ == "__main__":
+    main()

proofrun/cli.py

@@ -0,0 +1,325 @@
+"""Command Line Interface for Proofrun synthetic API monitoring daemon.
+
+Provides terminal rendering and workflow orchestration for running synthetic
+monitoring scenarios using Typer and Rich.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from pathlib import Path
+from typing import Annotated
+
+import httpx
+import typer
+import uvloop
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from proofrun import __version__
+from proofrun.core.engine import ScenarioResult, ScenarioRunner
+from proofrun.core.notifier import (
+    NotificationEvent,
+    Notifier,
+    WebhookNotifier,
+)
+from proofrun.core.provider import ConfigProvider
+from proofrun.core.state import StateManager, Status
+
+app = typer.Typer(
+    name="proofrun",
+    help="Synthetic API monitoring as code daemon.",
+    add_completion=False,
+)
+
+console = Console()
+
+
+def version_callback(value: bool) -> None:
+    """Print the Proofrun version and exit."""
+    if value:
+        console.print(
+            f"[bold cyan]Proofrun[/bold cyan] "
+            f"version [bold green]{__version__}[/bold green]"
+        )
+        raise typer.Exit(code=0)
+
+
+def render_scenario_result(result: ScenarioResult) -> None:
+    """Render a scenario result using Rich."""
+    status_style = "bold green" if result.passed else "bold red"
+    status_text = "PASSED" if result.passed else "FAILED"
+
+    table = Table(
+        title=f"Scenario: [bold white]{result.scenario_name}[/bold white]",
+        title_style="bold cyan",
+        show_header=True,
+        header_style="bold magenta",
+        expand=True,
+    )
+
+    table.add_column("Step Name", style="dim", min_width=25)
+    table.add_column("Status", justify="center", width=10)
+    table.add_column("HTTP Code", justify="right", width=10)
+    table.add_column("Latency", justify="right", width=12)
+    table.add_column("Error Details", style="red", min_width=20)
+
+    for step in result.step_results:
+        step_status = (
+            "[bold green]PASS[/bold green]"
+            if step.passed
+            else "[bold red]FAIL[/bold red]"
+        )
+
+        code_style = "green" if step.passed else "red"
+        code_str = f"[{code_style}]{step.status_code}[/{code_style}]"
+        latency_str = f"{step.latency_ms:.2f} ms"
+        error_str = step.error or "-"
+
+        table.add_row(
+            step.step_name,
+            step_status,
+            code_str,
+            latency_str,
+            error_str,
+        )
+
+    console.print(table)
+
+    summary_text = Text()
+    summary_text.append("Status: ", style="bold")
+    summary_text.append(status_text, style=status_style)
+    summary_text.append("    Total Latency: ", style="bold")
+    summary_text.append(
+        f"{result.total_latency_ms:.2f} ms",
+        style="cyan",
+    )
+
+    panel = Panel(
+        summary_text,
+        title="[bold]Summary[/bold]",
+        border_style="green" if result.passed else "red",
+        expand=False,
+    )
+
+    console.print(panel)
+    console.print()
+
+
+async def execute_config(
+    config_provider: ConfigProvider,
+    client: httpx.AsyncClient,
+    state_manager: StateManager | None = None,
+    notifier: Notifier | None = None,
+) -> tuple[bool, int]:
+    """Load and execute all scenarios concurrently.
+
+    Args:
+        config_provider: Cached configuration provider.
+        client: Reusable HTTP client for connection pooling.
+        state_manager: Tracks historical health across execution cycles.
+        notifier: Optional notification destination for state transitions.
+
+    Returns:
+        A tuple containing (all_passed, smallest_configured_interval).
+    """
+    proofrun_config, config_error = config_provider.load()
+
+    if config_error is not None:
+        console.print(f"[bold red]Configuration Error:[/bold red] {config_error}")
+
+        if proofrun_config is None:
+            return False, 60
+
+        console.print("[yellow]Using last known-good configuration.[/yellow]")
+
+    if proofrun_config is None:
+        console.print("[bold red]No valid configuration is available.[/bold red]")
+        return False, 60
+
+    if state_manager is not None:
+        active_scenario_names = {s.name for s in proofrun_config.scenarios}
+        state_manager.sync(active_scenario_names)
+
+    runners = [ScenarioRunner(scenario) for scenario in proofrun_config.scenarios]
+    tasks = [runner.run(client) for runner in runners]
+
+    results = await asyncio.gather(*tasks)
+
+    all_passed = True
+    scenario_intervals: list[int] = []
+
+    for result, scenario in zip(
+        results,
+        proofrun_config.scenarios,
+        strict=True,
+    ):
+        scenario_intervals.append(scenario.interval_seconds)
+
+        render_scenario_result(result)
+
+        if not result.passed:
+            all_passed = False
+
+        if state_manager is None:
+            continue
+
+        transition = state_manager.update(
+            scenario.name,
+            result.passed,
+        )
+
+        if notifier is None or not transition.changed:
+            continue
+
+        if transition.new_status == Status.FAILING:
+            errors = [
+                f"- {step.step_name}: {step.error}"
+                for step in result.step_results
+                if not step.passed
+            ]
+
+            event = NotificationEvent(
+                scenario_name=transition.scenario_name,
+                old_status=transition.old_status,
+                new_status=transition.new_status,
+                details="\n".join(errors),
+            )
+
+            await notifier.notify(event)
+
+        elif (
+            transition.old_status == Status.FAILING
+            and transition.new_status == Status.HEALTHY
+        ):
+            event = NotificationEvent(
+                scenario_name=transition.scenario_name,
+                old_status=transition.old_status,
+                new_status=transition.new_status,
+                details="All steps passing.",
+            )
+
+            await notifier.notify(event)
+
+    interval = min(scenario_intervals) if scenario_intervals else 60
+
+    return all_passed, interval
+
+
+@app.command()
+def run_command(
+    config_path: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            help="Path to YAML scenario configuration file.",
+        ),
+    ],
+    once: Annotated[
+        bool,
+        typer.Option(
+            "--once/--daemon",
+            help="Run scenarios once and exit, or loop continuously in daemon mode.",
+        ),
+    ] = True,
+    interval: Annotated[
+        int | None,
+        typer.Option(
+            "--interval",
+            "-i",
+            min=1,
+            help="Override configured scenario interval in seconds for daemon mode.",
+        ),
+    ] = None,
+    webhook_url: Annotated[
+        str | None,
+        typer.Option(
+            "--webhook-url",
+            envvar="PROOF_WEBHOOK_URL",
+            help="HTTP webhook URL for state transition alerts.",
+        ),
+    ] = None,
+    _show_version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-v",
+            help="Show Proofrun version and exit.",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = None,
+) -> None:
+    """Execute synthetic monitoring scenarios defined in YAML."""
+    console.print(
+        f"[bold cyan]Proofrun[/bold cyan] executing config: "
+        f"[bold yellow]{config_path}[/bold yellow]\n"
+    )
+
+    async def _run_loop() -> int:
+        config_provider = ConfigProvider(config_path)
+        state_manager = StateManager()
+
+        async with httpx.AsyncClient() as client:
+            notifier: Notifier | None = None
+
+            if webhook_url is not None:
+                notifier = WebhookNotifier(
+                    client=client,
+                    webhook_url=webhook_url,
+                )
+
+            if once:
+                passed, _ = await execute_config(
+                    config_provider,
+                    client,
+                )
+
+                return 0 if passed else 1
+
+            console.print(
+                "[bold green]Starting daemon mode... "
+                "Press Ctrl+C to stop.[/bold green]\n"
+            )
+
+            while True:
+                _, config_interval = await execute_config(
+                    config_provider,
+                    client,
+                    state_manager,
+                    notifier,
+                )
+
+                base_sleep = interval if interval is not None else config_interval
+
+                sleep_time = base_sleep * random.uniform(
+                    0.85,
+                    1.15,
+                )
+
+                console.print(
+                    f"[dim]Sleeping for {sleep_time:.1f}s "
+                    "(incl. jitter) before next execution cycle..."
+                    "[/dim]\n"
+                )
+
+                await asyncio.sleep(sleep_time)
+
+    try:
+        exit_code = uvloop.run(_run_loop())
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Daemon execution stopped by user.[/yellow]")
+        raise typer.Exit(code=0) from None
+
+    raise typer.Exit(code=exit_code)  # pragma: no cover
+
+
+def main() -> None:
+    """Run the Proofrun CLI."""
+    app()

proofrun/core/__init__.py

@@ -0,0 +1,40 @@
+"""Proofrun core package initialization."""
+
+from proofrun.core.compiler import ConfigCompilerError, load_and_compile_config
+from proofrun.core.config import (
+    ExpectConfig,
+    GlobalConfig,
+    ProofrunConfig,
+    RequestConfig,
+    ScenarioConfig,
+    StepConfig,
+)
+from proofrun.core.context import ExecutionContext
+from proofrun.core.engine import EngineError, ScenarioResult, ScenarioRunner, StepResult
+from proofrun.core.notifier import NotificationEvent, Notifier, WebhookNotifier
+from proofrun.core.provider import ConfigProvider
+from proofrun.core.state import ScenarioState, StateManager, StateTransition, Status
+
+__all__ = [
+    "ExpectConfig",
+    "GlobalConfig",
+    "ProofrunConfig",
+    "RequestConfig",
+    "ScenarioConfig",
+    "StepConfig",
+    "ConfigCompilerError",
+    "ConfigProvider",
+    "load_and_compile_config",
+    "ExecutionContext",
+    "EngineError",
+    "ScenarioResult",
+    "ScenarioRunner",
+    "StepResult",
+    "ScenarioState",
+    "StateManager",
+    "StateTransition",
+    "Status",
+    "NotificationEvent",
+    "Notifier",
+    "WebhookNotifier",
+]

proofrun/core/compiler.py

@@ -0,0 +1,136 @@
+"""AOT Schema Compiler for Proofrun scenario configurations.
+
+This module loads YAML configuration, validates it using Pydantic, resolves
+global defaults, and pre-compiles JSON schemas into executable validators.
+"""
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, cast
+
+import fastjsonschema
+import yaml
+from pydantic import ValidationError
+
+from proofrun.core.config import GlobalConfig, ProofrunConfig
+
+
+class ConfigCompilerError(Exception):
+    """Raised when configuration loading or compilation fails."""
+
+
+def load_and_compile_config(config_path: str | Path) -> ProofrunConfig:
+    """Load, validate, resolve, and compile a Proofrun configuration.
+
+    Args:
+        config_path: Path to the YAML configuration file.
+
+    Returns:
+        A validated and executable ProofrunConfig.
+
+    Raises:
+        ConfigCompilerError: If loading, validation, inheritance, or schema
+            compilation fails.
+    """
+    path = Path(config_path).resolve()
+
+    if not path.exists():
+        raise ConfigCompilerError(f"Configuration file not found: {path}")
+
+    try:
+        with path.open("r", encoding="utf-8") as file:
+            raw_data = yaml.safe_load(file)
+    except yaml.YAMLError as err:
+        raise ConfigCompilerError(f"Invalid YAML syntax in {path}: {err}") from err
+    except OSError as err:
+        raise ConfigCompilerError(
+            f"Failed to read configuration file {path}: {err}"
+        ) from err
+
+    if not isinstance(raw_data, dict):
+        raise ConfigCompilerError(
+            f"Invalid format in {path}. Expected a top-level YAML mapping."
+        )
+
+    try:
+        config = ProofrunConfig.model_validate(raw_data)
+    except ValidationError as err:
+        raise ConfigCompilerError(f"Config validation failed:\n{err}") from err
+
+    global_config = config.global_config or GlobalConfig()
+
+    global_base_url = global_config.base_url
+    global_timeout = global_config.timeout_seconds
+    global_headers = global_config.headers
+
+    for scenario in config.scenarios:
+        if scenario.base_url is None:
+            if global_base_url is None:
+                raise ConfigCompilerError(
+                    f"Scenario '{scenario.name}' is missing 'base_url' "
+                    "and no global 'base_url' is defined."
+                )
+
+            scenario.base_url = global_base_url
+
+        for step in scenario.steps:
+            if step.request.timeout is None:
+                step.request.timeout = global_timeout
+
+            step.request.headers = {
+                **global_headers,
+                **step.request.headers,
+            }
+
+            if step.expect.schema_data is None:
+                continue
+
+            raw_schema: dict[str, Any] | None = None
+
+            if isinstance(step.expect.schema_data, dict):
+                raw_schema = step.expect.schema_data
+
+            elif isinstance(step.expect.schema_data, str):
+                schema_file = path.parent / step.expect.schema_data
+
+                if not schema_file.exists():
+                    schema_file = Path(step.expect.schema_data)
+
+                if not schema_file.exists():
+                    raise ConfigCompilerError(
+                        f"JSON Schema file not found: "
+                        f"'{step.expect.schema_data}' "
+                        f"(referenced in scenario '{scenario.name}', "
+                        f"step '{step.name}')"
+                    )
+
+                try:
+                    with schema_file.open("r", encoding="utf-8") as file:
+                        raw_schema = json.load(file)
+                except (OSError, json.JSONDecodeError) as err:
+                    raise ConfigCompilerError(
+                        f"Failed to read JSON schema file "
+                        f"'{step.expect.schema_data}': {err}"
+                    ) from err
+
+            if raw_schema is None:  # pragma: no cover
+                raise ConfigCompilerError(
+                    f"Invalid schema configuration in scenario "
+                    f"'{scenario.name}', step '{step.name}'."
+                )
+
+            try:
+                compiled = fastjsonschema.compile(raw_schema)
+                step.expect._compiled_schema = cast(
+                    Callable[[Any], Any],
+                    compiled,
+                )
+            except Exception as err:
+                raise ConfigCompilerError(
+                    f"Failed to compile JSON schema in "
+                    f"scenario '{scenario.name}', "
+                    f"step '{step.name}': {err}"
+                ) from err
+
+    return config

proofrun/core/config.py

@@ -0,0 +1,150 @@
+"""Declarative configuration models for Proofrun synthetic monitoring scenarios.
+
+This module defines the Pydantic schemas used to parse, validate, and structure
+YAML monitoring scenarios, including global settings, request parameters,
+expectations, schema validations, and extraction rules.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, PrivateAttr
+
+
+class GlobalConfig(BaseModel):
+    """Global default settings applied across all scenarios and steps."""
+
+    base_url: HttpUrl | None = Field(
+        default=None,
+        description="Default root URL target for scenarios.",
+    )
+    timeout_seconds: float = Field(
+        default=10.0,
+        gt=0,
+        description="Default HTTP request timeout ceiling in seconds.",
+    )
+    headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Default HTTP headers sent with all requests.",
+    )
+
+
+class RequestConfig(BaseModel):
+    """Defines the parameters for an outgoing HTTP request."""
+
+    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] = Field(
+        ...,
+        description="HTTP method.",
+    )
+    path: str = Field(
+        ...,
+        description="Endpoint path relative to base_url.",
+    )
+    headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Key-value pairs for HTTP request headers.",
+    )
+    params: dict[str, Any] = Field(
+        default_factory=dict,
+        description="URL query parameters.",
+    )
+    json_payload: Any = Field(
+        default=None,
+        alias="json",
+        description="JSON serializable body payload.",
+    )
+    timeout: float | None = Field(
+        default=None,
+        gt=0,
+        description="Step-specific HTTP request timeout ceiling in seconds.",
+    )
+
+
+class ExpectConfig(BaseModel):
+    """Defines assertion criteria evaluated against the HTTP response."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    status: int | list[int] = Field(
+        ...,
+        description="Expected HTTP status code(s).",
+    )
+    headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Expected HTTP headers and their exact values.",
+    )
+    max_latency_ms: float | None = Field(
+        default=None,
+        gt=0,
+        description="Maximum allowed response latency in milliseconds.",
+    )
+    schema_data: str | dict[str, Any] | None = Field(
+        default=None,
+        alias="schema",
+        description="Path to a JSON schema file or inline schema dictionary.",
+    )
+
+    _compiled_schema: Callable[[Any], Any] | None = PrivateAttr(default=None)
+
+
+class StepConfig(BaseModel):
+    """Represents an atomic execution step in a multi-step API scenario."""
+
+    name: str = Field(
+        ...,
+        description="Human-readable identifier for the scenario step.",
+    )
+    request: RequestConfig = Field(
+        ...,
+        description="HTTP request specifications.",
+    )
+    expect: ExpectConfig = Field(
+        ...,
+        description="Response assertion rules.",
+    )
+    extract: dict[str, str] = Field(
+        default_factory=dict,
+        description="Mapping of variable names to JSONPath expressions.",
+    )
+
+
+class ScenarioConfig(BaseModel):
+    """Defines a sequence of dependent execution steps against a target host."""
+
+    name: str = Field(
+        ...,
+        description="Human-readable scenario suite name.",
+    )
+    base_url: HttpUrl | None = Field(
+        default=None,
+        description="Root URL target for all steps in this scenario.",
+    )
+    interval_seconds: int = Field(
+        default=60,
+        gt=0,
+        description="Execution interval in seconds for daemon mode.",
+    )
+    steps: list[StepConfig] = Field(
+        ...,
+        description="Ordered sequence of steps executed within shared context memory.",
+    )
+
+
+class ProofrunConfig(BaseModel):
+    """Root configuration model representing a parsed Proofrun YAML file."""
+
+    version: Literal["1.0"] = Field(
+        ...,
+        description="Configuration schema version. Currently only '1.0' is supported.",
+    )
+    global_config: GlobalConfig | None = Field(
+        default=None,
+        alias="global",
+        description="Global configuration settings applied across scenarios.",
+    )
+    scenarios: list[ScenarioConfig] = Field(
+        ...,
+        description="List of scenario workflows defined in the configuration file.",
+    )