strobengine 0.1.0__cp311-abi3-win_amd64.whl

strobengine/__init__.py

@@ -0,0 +1,19 @@
+from strobengine._strobengine import (
+    LoadProfile,
+    TestConfig,
+    TestSummary,
+    init_logging,
+    run_load_profiles,
+    run_load_test,
+)
+from strobengine.engine import StrobEngine
+
+__all__ = [
+    "LoadProfile",
+    "StrobEngine",
+    "TestConfig",
+    "TestSummary",
+    "init_logging",
+    "run_load_profiles",
+    "run_load_test",
+]

strobengine/_strobengine.pyi

@@ -0,0 +1,52 @@
+class LoadProfile:
+    @staticmethod
+    def constant(concurrency: int = 10, duration_secs: int = 10) -> LoadProfile: ...
+    @staticmethod
+    def ramp(
+        start_concurrency: int,
+        target_concurrency: int,
+        ramp_secs: int,
+        hold_secs: int,
+    ) -> LoadProfile: ...
+    @staticmethod
+    def spike(
+        baseline_concurrency: int,
+        peak_concurrency: int,
+        pre_spike_secs: int,
+        spike_secs: int,
+        post_spike_secs: int,
+    ) -> LoadProfile: ...
+    def total_duration(self) -> int: ...
+    def max_concurrency(self) -> int: ...
+    def target_concurrency(self, elapsed: float) -> int: ...
+
+class TestConfig:
+    url: str
+    concurrency: int
+    duration_secs: int
+    timeout_secs: int
+    def __init__(
+        self,
+        url: str,
+        concurrency: int = 10,
+        duration_secs: int = 10,
+        timeout_secs: int = 10,
+    ) -> None: ...
+
+class TestSummary:
+    @property
+    def total_requests(self) -> int: ...
+    @property
+    def total_errors(self) -> int: ...
+    @property
+    def average_latency_ms(self) -> float: ...
+    @property
+    def p95_latency_ms(self) -> float: ...
+    @property
+    def p99_latency_ms(self) -> float: ...
+
+def init_logging(level: str, log_file: str | None = None) -> None: ...
+def run_load_test(config: TestConfig) -> TestSummary: ...
+def run_load_profiles(
+    url: str, timeout_secs: int, profile: LoadProfile
+) -> TestSummary: ...

strobengine/cli.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Annotated
+
+import typer
+
+from strobengine._strobengine import init_logging
+from strobengine.engine import StrobEngine
+from strobengine.reporter import print_summary
+
+
+def _get_version() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("strobengine")
+    except PackageNotFoundError:
+        return "0.0.0-dev"
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"strobengine {_get_version()}")
+        raise typer.Exit()
+
+
+def _resolve_log_level(verbose_count: int, quiet: bool) -> str:
+    if quiet:
+        return "off"
+    return {0: "warn", 1: "info", 2: "debug"}.get(verbose_count, "trace")
+
+
+def _configure_logging(level: str, log_file: str | None = None) -> None:
+    import logging
+
+    python_level = {
+        "off": logging.CRITICAL + 1,
+        "warn": logging.WARNING,
+        "info": logging.INFO,
+        "debug": logging.DEBUG,
+        "trace": logging.DEBUG,
+    }.get(level, logging.WARNING)
+
+    handlers: list[logging.Handler] = [logging.StreamHandler(sys.stderr)]
+    if log_file:
+        handlers.append(logging.FileHandler(log_file))
+
+    logging.basicConfig(
+        level=python_level,
+        format="%(asctime)s [%(levelname)s] %(message)s",
+        handlers=handlers,
+        force=True,
+    )
+    init_logging(level, log_file)
+
+
+app = typer.Typer(
+    name="strobengine",
+    help="High-performance load testing engine powered by Rust.",
+    no_args_is_help=True,
+)
+
+KNOWN_SUBCOMMANDS = {"load", "stress", "spike"}
+HELP_FLAGS = {"-h", "--help"}
+VERSION_FLAGS = {"-V", "--version"}
+
+
+@app.callback()
+def _global_options(
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "-v",
+            "--verbose",
+            count=True,
+            help="Increase verbosity (-v INFO, -vv DEBUG, -vvv TRACE)",
+        ),
+    ] = 0,
+    quiet: Annotated[
+        bool, typer.Option("-q", "--quiet", help="Suppress all output")
+    ] = False,
+    log_file: Annotated[
+        str | None, typer.Option("--log-file", help="Write logs to file")
+    ] = None,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "-V",
+            "--version",
+            help="Show version and exit",
+            is_eager=True,
+            callback=_version_callback,
+        ),
+    ] = False,
+) -> None:
+    level = _resolve_log_level(verbose, quiet)
+    _configure_logging(level, log_file)
+
+
+def _output_results(summary, url: str, duration_secs: int, json_output: bool) -> None:
+    if json_output:
+        print(
+            json.dumps(
+                {
+                    "url": url,
+                    "total_requests": summary.total_requests,
+                    "total_errors": summary.total_errors,
+                    "average_latency_ms": summary.average_latency_ms,
+                    "p95_latency_ms": summary.p95_latency_ms,
+                    "p99_latency_ms": summary.p99_latency_ms,
+                },
+                indent=2,
+            )
+        )
+    else:
+        print_summary(summary, url=url, duration_secs=duration_secs)
+
+
+@app.command()
+def load(
+    url: Annotated[str, typer.Argument(help="Target HTTP/HTTPS URL")],
+    concurrency: Annotated[
+        int,
+        typer.Option("-c", "--concurrency", min=1, help="Number of concurrent workers"),
+    ] = 10,
+    duration: Annotated[
+        int,
+        typer.Option("-d", "--duration", min=1, help="Test duration in seconds"),
+    ] = 10,
+    timeout: Annotated[
+        int,
+        typer.Option("-t", "--timeout", min=1, help="Request timeout in seconds"),
+    ] = 10,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Output raw JSON results")
+    ] = False,
+) -> None:
+    engine = StrobEngine.load_test(
+        url=url, concurrency=concurrency, duration=duration, timeout=timeout
+    )
+    summary = engine.run()
+    _output_results(summary, url, duration, json_output)
+
+
+@app.command()
+def stress(
+    url: Annotated[str, typer.Argument(help="Target HTTP/HTTPS URL")],
+    start: Annotated[
+        int,
+        typer.Option("--from", help="Starting concurrency", min=1),
+    ] = 10,
+    target: Annotated[
+        int,
+        typer.Option("--to", help="Target concurrency", min=1),
+    ] = 200,
+    ramp: Annotated[
+        int,
+        typer.Option("--ramp", help="Ramp duration in seconds", min=1),
+    ] = 60,
+    hold: Annotated[
+        int,
+        typer.Option("--hold", help="Hold duration in seconds", min=0),
+    ] = 30,
+    timeout: Annotated[
+        int,
+        typer.Option("-t", "--timeout", help="Request timeout in seconds", min=1),
+    ] = 10,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Output raw JSON results")
+    ] = False,
+) -> None:
+    engine = StrobEngine.stress_test(
+        url=url,
+        start_concurrency=start,
+        max_concurrency=target,
+        ramp_duration=ramp,
+        hold_duration=hold,
+        timeout=timeout,
+    )
+    summary = engine.run()
+    _output_results(summary, url, ramp + hold, json_output)
+
+
+@app.command()
+def spike(
+    url: Annotated[str, typer.Argument(help="Target HTTP/HTTPS URL")],
+    baseline: Annotated[
+        int,
+        typer.Option("--baseline", help="Baseline concurrency", min=1),
+    ] = 5,
+    peak: Annotated[
+        int,
+        typer.Option("--peak", help="Peak concurrency", min=1),
+    ] = 500,
+    pre_spike: Annotated[
+        int,
+        typer.Option("--pre-spike", help="Pre-spike duration in seconds", min=0),
+    ] = 5,
+    spike_duration: Annotated[
+        int,
+        typer.Option("--spike-duration", help="Spike duration in seconds", min=1),
+    ] = 10,
+    post_spike: Annotated[
+        int,
+        typer.Option("--post-spike", help="Post-spike duration in seconds", min=0),
+    ] = 5,
+    timeout: Annotated[
+        int,
+        typer.Option("-t", "--timeout", help="Request timeout in seconds", min=1),
+    ] = 10,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Output raw JSON results")
+    ] = False,
+) -> None:
+    engine = StrobEngine.spike_test(
+        url=url,
+        baseline=baseline,
+        peak_concurrency=peak,
+        pre_spike_duration=pre_spike,
+        spike_duration=spike_duration,
+        post_spike_duration=post_spike,
+        timeout=timeout,
+    )
+    summary = engine.run()
+    _output_results(summary, url, pre_spike + spike_duration + post_spike, json_output)
+
+
+def _first_positional(argv: list[str]) -> str | None:
+    skip_next = False
+    for arg in argv:
+        if skip_next:
+            skip_next = False
+            continue
+        if arg.startswith("-"):
+            if arg in ("--log-file",):
+                skip_next = True
+            continue
+        return arg
+    return None
+
+
+def main(argv: list[str] | None = None) -> None:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if argv and set(argv) & (HELP_FLAGS | VERSION_FLAGS):
+        app(args=argv)
+        return
+
+    first = _first_positional(argv)
+    if first is not None and first not in KNOWN_SUBCOMMANDS:
+        argv = ["load", *argv]
+
+    try:
+        app(args=argv)
+    except SystemExit as e:
+        raise e
+
+
+if __name__ == "__main__":
+    main()

strobengine/engine.py

@@ -0,0 +1,122 @@
+import asyncio
+
+from strobengine._strobengine import (
+    LoadProfile,
+    TestConfig,
+    TestSummary,
+    run_load_profiles,
+    run_load_test,
+)
+
+
+class StrobEngine:
+    def __init__(
+        self,
+        url: str,
+        concurrency: int = 10,
+        duration: int = 10,
+        timeout: int = 10,
+        profile: LoadProfile | None = None,
+    ) -> None:
+        self._url = url
+        self._timeout = timeout
+
+        if profile is None:
+            if concurrency <= 0:
+                raise ValueError("Concurrency must be greater than 0")
+            if duration <= 0:
+                raise ValueError("Duration must be greater than 0")
+            if timeout <= 0:
+                raise ValueError("Timeout must be greater than 0")
+
+            self.config = TestConfig(
+                url=url,
+                concurrency=concurrency,
+                duration_secs=duration,
+                timeout_secs=timeout,
+            )
+            self._profile = None
+        else:
+            if timeout <= 0:
+                raise ValueError("Timeout must be greater than 0")
+
+            self.config = None
+            self._profile = profile
+
+    @classmethod
+    def load_test(
+        cls,
+        url: str,
+        concurrency: int = 10,
+        duration: int = 10,
+        timeout: int = 10,
+    ) -> "StrobEngine":
+        return cls(url=url, concurrency=concurrency, duration=duration, timeout=timeout)
+
+    @classmethod
+    def stress_test(
+        cls,
+        url: str,
+        start_concurrency: int = 10,
+        max_concurrency: int = 200,
+        ramp_duration: int = 60,
+        hold_duration: int = 30,
+        timeout: int = 10,
+    ) -> "StrobEngine":
+        if start_concurrency <= 0:
+            raise ValueError("start_concurrency must be greater than 0")
+        if max_concurrency <= 0:
+            raise ValueError("max_concurrency must be greater than 0")
+        if start_concurrency > max_concurrency:
+            raise ValueError("start_concurrency must be <= max_concurrency")
+        if ramp_duration < 0:
+            raise ValueError("ramp_duration must be >= 0")
+        if hold_duration < 0:
+            raise ValueError("hold_duration must be >= 0")
+
+        profile = LoadProfile.ramp(
+            start_concurrency=start_concurrency,
+            target_concurrency=max_concurrency,
+            ramp_secs=ramp_duration,
+            hold_secs=hold_duration,
+        )
+        return cls(url=url, timeout=timeout, profile=profile)
+
+    @classmethod
+    def spike_test(
+        cls,
+        url: str,
+        baseline: int = 5,
+        peak_concurrency: int = 500,
+        pre_spike_duration: int = 5,
+        spike_duration: int = 10,
+        post_spike_duration: int = 5,
+        timeout: int = 10,
+    ) -> "StrobEngine":
+        if baseline <= 0:
+            raise ValueError("baseline must be greater than 0")
+        if peak_concurrency <= 0:
+            raise ValueError("peak_concurrency must be greater than 0")
+        if pre_spike_duration < 0:
+            raise ValueError("pre_spike_duration must be >= 0")
+        if spike_duration < 0:
+            raise ValueError("spike_duration must be >= 0")
+        if post_spike_duration < 0:
+            raise ValueError("post_spike_duration must be >= 0")
+
+        profile = LoadProfile.spike(
+            baseline_concurrency=baseline,
+            peak_concurrency=peak_concurrency,
+            pre_spike_secs=pre_spike_duration,
+            spike_secs=spike_duration,
+            post_spike_secs=post_spike_duration,
+        )
+        return cls(url=url, timeout=timeout, profile=profile)
+
+    def run(self) -> TestSummary:
+        if self._profile is not None:
+            return run_load_profiles(self._url, self._timeout, self._profile)
+        return run_load_test(self.config)
+
+    async def run_async(self) -> TestSummary:
+        return await asyncio.to_thread(self.run)

strobengine/reporter.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+import sys
+
+from strobengine._strobengine import TestSummary
+
+_HAS_RICH = False
+try:
+    from rich.console import Console
+    from rich.table import Table
+
+    _HAS_RICH = True
+except ImportError:
+    pass
+
+
+def print_summary(
+    summary: TestSummary,
+    url: str,
+    duration_secs: int | None = None,
+) -> None:
+    if _HAS_RICH:
+        _print_rich(summary, url, duration_secs)
+    else:
+        _print_plain(summary, url, duration_secs)
+
+
+def _format_number(n: int) -> str:
+    return f"{n:,}"
+
+
+def _error_rate(total: int, errors: int) -> str:
+    if total == 0:
+        return "0.00%"
+    return f"{errors / total * 100:.2f}%"
+
+
+def _print_rich(
+    summary: TestSummary,
+    url: str,
+    duration_secs: int | None,
+) -> None:
+    console = Console()
+
+    table = Table(title="Load Test Results", show_lines=True, padding=(0, 1))
+    table.add_column("Metric", style="bold cyan", no_wrap=True)
+    table.add_column("Value", justify="right")
+
+    table.add_row("Target URL", url)
+    table.add_row("Total Requests", _format_number(summary.total_requests))
+
+    if summary.total_errors > 0:
+        rate = _error_rate(summary.total_requests, summary.total_errors)
+        table.add_row(
+            "Errors",
+            f"[bold red]{_format_number(summary.total_errors)} ({rate})[/]",
+        )
+    else:
+        table.add_row(
+            "Errors",
+            f"[green]{_format_number(summary.total_errors)} (0.00%)[/]",
+        )
+
+    if duration_secs is not None and duration_secs > 0:
+        rps = summary.total_requests / duration_secs
+        table.add_row("Requests/sec", f"{rps:.1f}")
+
+    table.add_row("Avg Latency", f"{summary.average_latency_ms:.2f} ms")
+    table.add_row("P95 Latency", f"{summary.p95_latency_ms:.2f} ms")
+    table.add_row("P99 Latency", f"{summary.p99_latency_ms:.2f} ms")
+
+    console.print()
+    console.print(table)
+    console.print()
+
+
+def _print_plain(
+    summary: TestSummary,
+    url: str,
+    duration_secs: int | None,
+) -> None:
+    use_color = (
+        not os.environ.get("NO_COLOR")
+        and hasattr(sys.stdout, "isatty")
+        and sys.stdout.isatty()
+    )
+
+    RED = "\033[91m" if use_color else ""
+    GREEN = "\033[92m" if use_color else ""
+    BOLD = "\033[1m" if use_color else ""
+    RESET = "\033[0m" if use_color else ""
+
+    width = 44
+    sep = "=" * width
+
+    lines = [
+        f"{BOLD}{'Load Test Results':^{width}}{RESET}",
+        sep,
+        f"  Target URL:     {url}",
+        f"  Total Requests: {_format_number(summary.total_requests)}",
+    ]
+
+    if summary.total_errors > 0:
+        rate = _error_rate(summary.total_requests, summary.total_errors)
+        lines.append(
+            f"  Errors:         {RED}{_format_number(summary.total_errors)} ({rate}){RESET}"
+        )
+    else:
+        lines.append(
+            f"  Errors:         {GREEN}{_format_number(summary.total_errors)} (0.00%){RESET}"
+        )
+
+    if duration_secs is not None and duration_secs > 0:
+        rps = summary.total_requests / duration_secs
+        lines.append(f"  Requests/sec:   {rps:.1f}")
+
+    lines.append(f"  Avg Latency:    {summary.average_latency_ms:.2f} ms")
+    lines.append(f"  P95 Latency:    {summary.p95_latency_ms:.2f} ms")
+    lines.append(f"  P99 Latency:    {summary.p99_latency_ms:.2f} ms")
+    lines.append(sep)
+
+    print("\n".join(lines))