jac-loadtest 0.1.0__tar.gz

jac_loadtest-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: jac-loadtest
+Version: 0.1.0
+Summary: HAR-based load testing CLI for jac-scale applications
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: jaclang==0.15.2
+Requires-Dist: jac-scale==0.2.16
+Requires-Dist: rich>=13.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-mock>=3.12; extra == "test"
+Requires-Dist: aiohttp[speedups]>=3.9; extra == "test"
+
+# jac-loadtest
+
+HAR-based load testing CLI for [jac-scale](https://github.com/jaseci-labs/jaseci/tree/main/jac-scale) applications. Capture real browser traffic via Chrome DevTools, export it as a `.har` file, and replay it under load — no scripting required.
+
+The tool registers itself as a `jac` subcommand, so after installation you run `jac loadtest` alongside `jac start`, `jac deploy`, and the rest of the jac ecosystem.
+
+## Quick Start
+
+```bash
+# Minimal: 1 VU, 30s
+jac loadtest recording.har --url http://localhost:8000
+
+# 50 VUs with 10s ramp-up
+jac loadtest recording.har --url http://localhost:8000 --vus 50 --ramp-up 10s --duration 60s
+
+# Authenticated test with per-VU credentials
+jac loadtest recording.har --url http://localhost:8000 --vus 20 --credentials-file creds.csv
+
+# CI-friendly with thresholds
+jac loadtest recording.har --url http://localhost:8000 \
+  --vus 10 --duration 30s --fail-on-p95 500 --fail-on-error-rate 1
+```
+
+## Developer Setup
+
+```bash
+# 1. Create and activate a conda env (Python 3.12 required)
+conda create -n load python=3.12
+conda activate load
+
+# 2. Install the package in editable mode (runtime deps only)
+pip install -e .
+
+# 3. Also install test dependencies (when running tests)
+pip install -e ".[test]"
+
+# 4. Verify the command is registered
+jac loadtest --help
+```
+
+## Project Layout
+
+```
+jac_loadtest/
+├── plugin.py      — registers `jac loadtest` via jaclang entry-points
+├── cli.py         — argument wiring; JacMetaImporter bootstrap
+├── config.py      — LoadTestConfig dataclass (three-layer resolution)
+├── core/          — HAR parser, load engine, metrics (no jac-scale knowledge)
+├── bridge/        — jac-scale-aware adapters (auth, topology)
+└── output/        — console, JSON, HTML reporters
+```
+
+The hard boundary between `core/` and `bridge/` is what keeps the eventual migration to `jac-scale[loadtest]` a file move rather than a rewrite.
+
+## HAR Compatibility
+
+Tested with HAR **1.1** and **1.2** (the format exported by Chrome DevTools, Firefox, Postman, and Insomnia). Files from other versions are parsed with a warning — open an issue if something breaks.
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md) — module map, data flow, design decisions
+- [Roadmap](docs/ROADMAP.md) — delivery phases and exit criteria
+- [Verification](docs/VERIFICATION.md) — phase-by-phase manual and automated verification checklists

jac_loadtest-0.1.0/README.md

@@ -0,0 +1,63 @@
+# jac-loadtest
+
+HAR-based load testing CLI for [jac-scale](https://github.com/jaseci-labs/jaseci/tree/main/jac-scale) applications. Capture real browser traffic via Chrome DevTools, export it as a `.har` file, and replay it under load — no scripting required.
+
+The tool registers itself as a `jac` subcommand, so after installation you run `jac loadtest` alongside `jac start`, `jac deploy`, and the rest of the jac ecosystem.
+
+## Quick Start
+
+```bash
+# Minimal: 1 VU, 30s
+jac loadtest recording.har --url http://localhost:8000
+
+# 50 VUs with 10s ramp-up
+jac loadtest recording.har --url http://localhost:8000 --vus 50 --ramp-up 10s --duration 60s
+
+# Authenticated test with per-VU credentials
+jac loadtest recording.har --url http://localhost:8000 --vus 20 --credentials-file creds.csv
+
+# CI-friendly with thresholds
+jac loadtest recording.har --url http://localhost:8000 \
+  --vus 10 --duration 30s --fail-on-p95 500 --fail-on-error-rate 1
+```
+
+## Developer Setup
+
+```bash
+# 1. Create and activate a conda env (Python 3.12 required)
+conda create -n load python=3.12
+conda activate load
+
+# 2. Install the package in editable mode (runtime deps only)
+pip install -e .
+
+# 3. Also install test dependencies (when running tests)
+pip install -e ".[test]"
+
+# 4. Verify the command is registered
+jac loadtest --help
+```
+
+## Project Layout
+
+```
+jac_loadtest/
+├── plugin.py      — registers `jac loadtest` via jaclang entry-points
+├── cli.py         — argument wiring; JacMetaImporter bootstrap
+├── config.py      — LoadTestConfig dataclass (three-layer resolution)
+├── core/          — HAR parser, load engine, metrics (no jac-scale knowledge)
+├── bridge/        — jac-scale-aware adapters (auth, topology)
+└── output/        — console, JSON, HTML reporters
+```
+
+The hard boundary between `core/` and `bridge/` is what keeps the eventual migration to `jac-scale[loadtest]` a file move rather than a rewrite.
+
+## HAR Compatibility
+
+Tested with HAR **1.1** and **1.2** (the format exported by Chrome DevTools, Firefox, Postman, and Insomnia). Files from other versions are parsed with a warning — open an issue if something breaks.
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md) — module map, data flow, design decisions
+- [Roadmap](docs/ROADMAP.md) — delivery phases and exit criteria
+- [Verification](docs/VERIFICATION.md) — phase-by-phase manual and automated verification checklists

jac_loadtest-0.1.0/jac_loadtest/bridge/auth.py

@@ -0,0 +1,15 @@
+"""jac-scale auth: login via /user/login, per-VU JWT injection.
+
+Implemented in Phase 2.
+"""
+from __future__ import annotations
+
+
+async def get_token(
+    session: object,
+    base_url: str,
+    username: str,
+    password: str,
+    login_path: str = "/user/login",
+) -> str:
+    raise NotImplementedError("Auth module is implemented in Phase 2.")

jac_loadtest-0.1.0/jac_loadtest/bridge/topology.py

@@ -0,0 +1,24 @@
+"""Build prefix→URL routing table from jac-scale ServiceRegistry or jac.toml.
+
+Implements longest-prefix matching to mirror jac-scale's gateway routing.
+Implemented in Phase 3.
+"""
+from __future__ import annotations
+
+
+def build_routing_table(
+    mode: str,
+    base_url: str | None = None,
+    services_map_json: str | None = None,
+) -> dict[str, str]:
+    raise NotImplementedError("Topology module is implemented in Phase 3.")
+
+
+def resolve_url(path: str, routing_table: dict[str, str], fallback_url: str | None) -> str:
+    """Longest-prefix match: mirrors jac-scale ServiceRegistry.match_route()."""
+    for prefix in sorted(routing_table, key=len, reverse=True):
+        if path.startswith(prefix):
+            return routing_table[prefix]
+    if fallback_url:
+        return fallback_url
+    raise ValueError(f"No route for path '{path}' and no --url fallback provided.")

jac_loadtest-0.1.0/jac_loadtest/cli.py

@@ -0,0 +1,56 @@
+# JacMetaImporter must be registered before any jac_scale import.
+# jac-scale's microservice modules are compiled Jac; without this the import fails.
+from jaclang.meta_importer import JacMetaImporter
+import sys
+
+if not any(isinstance(f, JacMetaImporter) for f in sys.meta_path):
+    sys.meta_path.insert(0, JacMetaImporter())
+
+
+def run(args: object) -> None:
+    import asyncio
+    import time
+
+    from jac_loadtest.config import from_args
+    from jac_loadtest.core.har_parser import parse_har
+    from jac_loadtest.core.engine import run_all_vus
+    from jac_loadtest.core.metrics import MetricsCollector
+    from jac_loadtest.output.reporter import render_console
+
+    config = from_args(args)
+
+    if not config.url:
+        print("Error: --url is required", file=sys.stderr)
+        sys.exit(2)
+
+    if not config.har_file:
+        print("Error: har_file positional argument is required", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        entries = parse_har(
+            config.har_file,
+            target_url=config.url,
+            include_static=config.include_static,
+            login_path=config.login_path,
+        )
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+    if not entries:
+        print(
+            "Error: no API entries found in HAR file after filtering. "
+            "Use --include-static to include static assets.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    metrics = MetricsCollector(max_samples=config.max_samples)
+    t_start = time.time()
+
+    asyncio.run(run_all_vus(entries, config, metrics))
+
+    duration_s = time.time() - t_start
+    stats = metrics.compute_endpoint_stats(duration_s)
+    render_console(stats, config)

jac_loadtest-0.1.0/jac_loadtest/config.py

@@ -0,0 +1,123 @@
+"""LoadTestConfig — three-layer resolution: jac.toml → CLI flags → built-in defaults.
+
+Phase 0: dataclass with built-in defaults only.
+Phase 2 will add jac.toml reading via jac_scale.config_loader.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+
+BUILT_IN_DEFAULTS: dict = {
+    "vus": 1,
+    "duration": "30s",
+    "ramp_up": "0s",
+    "timeout": "30s",
+    "mode": "monolith",
+    "think_time": "none",
+    "think_time_scale": 1.0,
+    "rps": 0,
+    "include_static": False,
+    "login_path": "/user/login",
+    "fail_on_error_rate": None,
+    "fail_on_p95": None,
+    "fail_on_p99": None,
+    "abort_on_fail": False,
+    "threshold_start_delay": "0s",
+    "report_format": "console",
+    "max_samples": 1_000_000,
+    "csrf": False,
+    "debug": False,
+}
+
+
+@dataclass
+class LoadTestConfig:
+    # Load shape
+    vus: int = 1
+    duration: str = "30s"
+    iterations: int | None = None
+    ramp_up: str = "0s"
+    timeout: str = "30s"
+
+    # Traffic
+    mode: str = "monolith"
+    think_time: str = "none"
+    think_time_scale: float = 1.0
+    rps: int = 0
+    include_static: bool = False
+
+    # Auth
+    login_path: str = "/user/login"
+    csrf: bool = False
+
+    # CI thresholds
+    fail_on_error_rate: float | None = None
+    fail_on_p95: float | None = None
+    fail_on_p99: float | None = None
+    abort_on_fail: bool = False
+    threshold_start_delay: str = "0s"
+
+    # Output
+    report_format: str = "console"
+    max_samples: int = 1_000_000
+    debug: bool = False
+
+    # CLI-only — not sourced from jac.toml (environment-specific or security-sensitive)
+    har_file: str = ""
+    url: str | None = None
+    username: str | None = None
+    password: str | None = None
+    credentials_file: str | None = None
+    services_map: str | None = None
+    report_out: str | None = None
+
+
+def parse_duration(s: str) -> float:
+    """Convert a duration string ('30s', '2m', '1h') to seconds."""
+    s = s.strip()
+    if s.endswith("h"):
+        return float(s[:-1]) * 3600
+    if s.endswith("m"):
+        return float(s[:-1]) * 60
+    if s.endswith("s"):
+        return float(s[:-1])
+    return float(s)
+
+
+def from_args(args: object) -> LoadTestConfig:
+    """Build LoadTestConfig by applying CLI args on top of built-in defaults.
+
+    Phase 2 will insert a jac.toml layer between defaults and CLI args.
+    """
+    def get(name: str, default=None):
+        return getattr(args, name, default)
+
+    return LoadTestConfig(
+        har_file=get("har_file", ""),
+        url=get("url"),
+        mode=get("mode", BUILT_IN_DEFAULTS["mode"]),
+        vus=get("vus", BUILT_IN_DEFAULTS["vus"]),
+        duration=get("duration", BUILT_IN_DEFAULTS["duration"]),
+        iterations=get("iterations"),
+        ramp_up=get("ramp_up", BUILT_IN_DEFAULTS["ramp_up"]),
+        timeout=get("timeout", BUILT_IN_DEFAULTS["timeout"]),
+        think_time=get("think_time", BUILT_IN_DEFAULTS["think_time"]),
+        think_time_scale=get("think_time_scale", BUILT_IN_DEFAULTS["think_time_scale"]),
+        username=get("username"),
+        password=get("password"),
+        credentials_file=get("credentials_file"),
+        login_path=get("login_path", BUILT_IN_DEFAULTS["login_path"]),
+        include_static=get("include_static", BUILT_IN_DEFAULTS["include_static"]),
+        rps=get("rps", BUILT_IN_DEFAULTS["rps"]),
+        max_samples=get("max_samples", BUILT_IN_DEFAULTS["max_samples"]),
+        services_map=get("services_map"),
+        csrf=get("csrf", BUILT_IN_DEFAULTS["csrf"]),
+        fail_on_error_rate=get("fail_on_error_rate"),
+        fail_on_p95=get("fail_on_p95"),
+        fail_on_p99=get("fail_on_p99"),
+        abort_on_fail=get("abort_on_fail", BUILT_IN_DEFAULTS["abort_on_fail"]),
+        threshold_start_delay=get("threshold_start_delay", BUILT_IN_DEFAULTS["threshold_start_delay"]),
+        report_format=get("report_format", BUILT_IN_DEFAULTS["report_format"]),
+        report_out=get("report_out"),
+        debug=get("debug", BUILT_IN_DEFAULTS["debug"]),
+    )

jac_loadtest-0.1.0/jac_loadtest/core/engine.py

@@ -0,0 +1,162 @@
+"""asyncio VU pool: ramp-up, duration/iteration control, graceful shutdown.
+
+core/ has zero knowledge of jac-scale internals.
+"""
+from __future__ import annotations
+
+import asyncio
+import signal
+import sys
+from typing import TYPE_CHECKING
+
+import aiohttp
+
+from jac_loadtest.config import parse_duration
+from jac_loadtest.core.metrics import RequestResult, normalize_path
+
+if TYPE_CHECKING:
+    from jac_loadtest.core.har_parser import HarEntry
+    from jac_loadtest.core.metrics import MetricsCollector
+    from jac_loadtest.config import LoadTestConfig
+
+
+async def run_all_vus(
+    entries: list[HarEntry],
+    config: LoadTestConfig,
+    metrics: MetricsCollector,
+    topology: object | None = None,
+    auth_provider: object | None = None,
+) -> None:
+    """Spawn N virtual user coroutines and run until duration/iterations/stop signal."""
+    stop_requested = asyncio.Event()
+    loop = asyncio.get_event_loop()
+
+    original_sigint = signal.getsignal(signal.SIGINT)
+
+    def _on_second_sigint(sig: int, frame: object) -> None:
+        sys.exit(130)
+
+    def _on_first_sigint(sig: int, frame: object) -> None:
+        stop_requested.set()
+        signal.signal(signal.SIGINT, _on_second_sigint)
+
+    signal.signal(signal.SIGINT, _on_first_sigint)
+
+    ramp_up_seconds = parse_duration(config.ramp_up)
+
+    tasks = [
+        asyncio.create_task(
+            _run_vu(
+                vu_id=i,
+                delay=(i / config.vus) * ramp_up_seconds if config.vus > 1 else 0.0,
+                entries=entries,
+                config=config,
+                metrics=metrics,
+                stop_requested=stop_requested,
+                loop=loop,
+            )
+        )
+        for i in range(config.vus)
+    ]
+
+    try:
+        await asyncio.gather(*tasks)
+    finally:
+        signal.signal(signal.SIGINT, original_sigint)
+
+
+async def _run_vu(
+    vu_id: int,
+    delay: float,
+    entries: list[HarEntry],
+    config: LoadTestConfig,
+    metrics: MetricsCollector,
+    stop_requested: asyncio.Event,
+    loop: asyncio.AbstractEventLoop,
+) -> None:
+    """Single virtual user: wait ramp delay, then replay HAR entries repeatedly."""
+    if delay > 0:
+        await asyncio.sleep(delay)
+
+    timeout = aiohttp.ClientTimeout(total=parse_duration(config.timeout))
+    duration_seconds = parse_duration(config.duration)
+    t_start = loop.time()
+    iteration = 0
+
+    async with aiohttp.ClientSession(timeout=timeout) as session:
+        while not stop_requested.is_set():
+            if loop.time() - t_start >= duration_seconds:
+                break
+            if config.iterations is not None and iteration >= config.iterations:
+                break
+
+            for entry in entries:
+                if stop_requested.is_set():
+                    break
+                result = await _send_request(
+                    session=session,
+                    entry=entry,
+                    vu_id=vu_id,
+                    config=config,
+                    loop=loop,
+                )
+                metrics.record(result)
+
+            iteration += 1
+
+
+async def _send_request(
+    session: aiohttp.ClientSession,
+    entry: HarEntry,
+    vu_id: int,
+    config: LoadTestConfig,
+    loop: asyncio.AbstractEventLoop,
+) -> RequestResult:
+    """Send one HTTP request and return a RequestResult."""
+    headers = dict(entry.headers)
+    t0 = loop.time()
+
+    try:
+        async with session.request(
+            method=entry.method,
+            url=entry.url,
+            headers=headers,
+            data=entry.body,
+            allow_redirects=False,
+        ) as resp:
+            body = await resp.read()
+            latency_ms = (loop.time() - t0) * 1000
+            return RequestResult(
+                endpoint=normalize_path(entry.url),
+                service="monolith",
+                status=resp.status,
+                latency_ms=latency_ms,
+                bytes_received=len(body),
+                timestamp=t0,
+                vu_id=vu_id,
+                error_type=None,
+            )
+
+    except asyncio.TimeoutError:
+        return RequestResult(
+            endpoint=normalize_path(entry.url),
+            service="monolith",
+            status=0,
+            latency_ms=parse_duration(config.timeout) * 1000,
+            bytes_received=0,
+            timestamp=t0,
+            vu_id=vu_id,
+            error_type="TIMEOUT",
+        )
+
+    except aiohttp.ClientConnectorError:
+        return RequestResult(
+            endpoint=normalize_path(entry.url),
+            service="monolith",
+            status=0,
+            latency_ms=0.0,
+            bytes_received=0,
+            timestamp=t0,
+            vu_id=vu_id,
+            error_type="CONNECTION_REFUSED",
+        )

jac_loadtest-0.1.0/jac_loadtest/core/har_parser.py

@@ -0,0 +1,161 @@
+"""Parse HAR 1.2 files, filter non-API entries, and rewrite URLs.
+
+core/ has zero knowledge of jac-scale internals.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from urllib.parse import urlparse, urlunparse
+
+
+_SKIP_MIME_PREFIXES = (
+    "image/",
+    "font/",
+    "text/css",
+    "application/javascript",
+    "text/javascript",
+    "application/wasm",
+)
+
+_STRIP_HEADERS = {"authorization", "cookie", "host", "content-length"}
+
+
+@dataclass
+class HarEntry:
+    method: str
+    url: str
+    headers: dict[str, str]
+    body: str | None
+    body_mime: str | None
+    think_time_ms: float
+    is_login: bool
+    original_url: str
+
+
+def _origin(url: str) -> str:
+    """Return scheme://host:port (no path) from a URL."""
+    p = urlparse(url)
+    return urlunparse((p.scheme, p.netloc, "", "", "", ""))
+
+
+def _rewrite_url(original: str, recorded_origin: str, target_url: str) -> str:
+    """Replace recorded origin with target_url, preserving path and query."""
+    p = urlparse(original)
+    t = urlparse(target_url)
+    rewritten = urlunparse((t.scheme, t.netloc, p.path, p.params, p.query, ""))
+    return rewritten
+
+
+def _is_static(mime: str) -> bool:
+    if not mime:
+        return False
+    mime_lower = mime.lower().split(";")[0].strip()
+    return any(mime_lower.startswith(prefix) for prefix in _SKIP_MIME_PREFIXES)
+
+
+def parse_har(
+    har_path: str,
+    target_url: str,
+    include_static: bool = False,
+    login_path: str = "/user/login",
+) -> list[HarEntry]:
+    """Parse a HAR 1.2 file and return filtered, URL-rewritten HarEntry objects."""
+    with open(har_path, encoding="utf-8") as f:
+        data = json.load(f)
+
+    if "log" not in data:
+        raise ValueError("Malformed HAR file: missing 'log' key")
+
+    _check_version(data["log"].get("version", "unknown"))
+
+    raw_entries = data["log"].get("entries", [])
+
+    if not raw_entries:
+        return []
+
+    recorded_origin = _origin(raw_entries[0]["request"]["url"])
+
+    # Security scan — warn once if any auth headers found
+    _security_scan(raw_entries)
+
+    result: list[HarEntry] = []
+    for entry in raw_entries:
+        req = entry["request"]
+        resp = entry.get("response", {})
+        content = resp.get("content", {})
+        mime = content.get("mimeType", "")
+
+        if not include_static and _is_static(mime):
+            continue
+
+        original_url = req["url"]
+        rewritten_url = _rewrite_url(original_url, recorded_origin, target_url)
+
+        headers = _sanitize_headers(req.get("headers", []))
+
+        post_data = req.get("postData", {}) or {}
+        body = post_data.get("text") or None
+        body_mime = post_data.get("mimeType") or None
+
+        timings = entry.get("timings", {})
+        think_time_ms = float(timings.get("wait", 0.0))
+
+        is_login = urlparse(original_url).path == login_path
+
+        result.append(
+            HarEntry(
+                method=req["method"].upper(),
+                url=rewritten_url,
+                headers=headers,
+                body=body,
+                body_mime=body_mime,
+                think_time_ms=think_time_ms,
+                is_login=is_login,
+                original_url=original_url,
+            )
+        )
+
+    return result
+
+
+_SUPPORTED_HAR_VERSIONS = {"1.1", "1.2"}
+
+
+def _check_version(version: str) -> None:
+    """Warn if the HAR version is outside the tested range."""
+    if version not in _SUPPORTED_HAR_VERSIONS:
+        print(
+            f"Warning: HAR version '{version}' is not tested with this tool "
+            f"(tested: {', '.join(sorted(_SUPPORTED_HAR_VERSIONS))}).\n"
+            "Parsing will continue but results may be incomplete or incorrect.\n"
+            "If the output looks wrong, check for a jac-loadtest update.",
+            file=sys.stderr,
+        )
+
+
+def _security_scan(entries: list[dict]) -> None:
+    """Emit a stderr warning if any HAR entry contains auth/cookie headers."""
+    for entry in entries:
+        for hdr in entry.get("request", {}).get("headers", []):
+            name = hdr.get("name", "").lower()
+            value = hdr.get("value", "")
+            if name in ("authorization", "cookie") and value:
+                print(
+                    "Warning: HAR file contains Authorization/Cookie headers from the "
+                    "recording session.\nThese headers are stripped before replay, but "
+                    "the file itself contains sensitive data.\n"
+                    "Do not commit this HAR file to version control.",
+                    file=sys.stderr,
+                )
+                return
+
+
+def _sanitize_headers(raw_headers: list[dict]) -> dict[str, str]:
+    """Strip session-specific headers; return clean dict."""
+    return {
+        h["name"]: h["value"]
+        for h in raw_headers
+        if h.get("name", "").lower() not in _STRIP_HEADERS
+    }

jac_loadtest-0.1.0/jac_loadtest/core/metrics.py

@@ -0,0 +1,161 @@
+"""Per-request recording, latency histograms, percentile calculation.
+
+Three-layer storage (Phase 4):
+  Layer 1 — total_count (always accurate RPS)
+  Layer 2 — deque(maxlen=max_samples) of RequestResult (percentiles)
+  Layer 3 — list[StatsSnapshot] every 5s (time-series charts)
+
+Phase 0: dataclasses only.
+"""
+from __future__ import annotations
+import math
+from dataclasses import dataclass, field
+from collections import deque
+
+
+@dataclass
+class RequestResult:
+    endpoint: str
+    service: str
+    status: int
+    latency_ms: float
+    bytes_received: int
+    timestamp: float
+    vu_id: int
+    error_type: str | None  # None | "TIMEOUT" | "CONNECTION_REFUSED" | "DNS_ERROR" | "SSL_ERROR"
+
+
+@dataclass
+class EndpointStats:
+    endpoint: str
+    service: str
+    total_requests: int
+    success_count: int
+    error_count: int
+    success_rate_pct: float
+    min_ms: float
+    max_ms: float
+    mean_ms: float
+    p50_ms: float
+    p95_ms: float
+    p99_ms: float
+    rps: float
+    error_breakdown: dict[str, int] = field(default_factory=dict)
+
+
+@dataclass
+class StatsSnapshot:
+    timestamp: float
+    p50_ms: float
+    p95_ms: float
+    p99_ms: float
+    rps: float
+    error_rate_pct: float
+
+
+def percentile(latencies: list[float], p: float) -> float:
+    if not latencies:
+        return 0.0
+    sorted_l = sorted(latencies)
+    idx = int(math.ceil(p / 100.0 * len(sorted_l))) - 1
+    return sorted_l[max(0, idx)]
+
+
+def normalize_path(url: str) -> str:
+    """Replace UUID and integer path segments with {id}, preserving full URL."""
+    import re
+    from urllib.parse import urlparse, urlunparse
+    parsed = urlparse(url)
+    segments = parsed.path.split("/")
+    normalized = []
+    for seg in segments:
+        if re.fullmatch(r"\d+", seg):
+            normalized.append("{id}")
+        elif re.fullmatch(r"[0-9a-f\-]{32,36}", seg):
+            normalized.append("{id}")
+        else:
+            normalized.append(seg)
+    normalized_path = "/".join(normalized)
+    return urlunparse((parsed.scheme, parsed.netloc, normalized_path, parsed.params, parsed.query, ""))
+
+
+class MetricsCollector:
+    def __init__(self, max_samples: int = 1_000_000) -> None:
+        self.total_count: int = 0
+        self._samples: deque[RequestResult] = deque(maxlen=max_samples)
+        self._snapshots: list[StatsSnapshot] = []
+
+    def record(self, result: RequestResult) -> None:
+        self.total_count += 1
+        self._samples.append(result)
+
+    def compute_endpoint_stats(self, duration_seconds: float) -> list[EndpointStats]:
+        """Aggregate per-endpoint stats from collected samples."""
+        groups: dict[str, list[RequestResult]] = {}
+        for result in self._samples:
+            groups.setdefault(result.endpoint, []).append(result)
+
+        stats: list[EndpointStats] = []
+        safe_duration = max(duration_seconds, 0.001)
+
+        for endpoint, results in groups.items():
+            latencies = [r.latency_ms for r in results]
+            total = len(results)
+            success_count = sum(
+                1 for r in results if r.error_type is None and 200 <= r.status < 300
+            )
+            error_count = total - success_count
+            success_rate = (success_count / total * 100.0) if total else 0.0
+
+            error_breakdown: dict[str, int] = {}
+            for r in results:
+                if r.error_type is not None:
+                    key = r.error_type
+                elif not (200 <= r.status < 300):
+                    key = str(r.status)
+                else:
+                    continue
+                error_breakdown[key] = error_breakdown.get(key, 0) + 1
+
+            service = results[0].service if results else "monolith"
+
+            stats.append(
+                EndpointStats(
+                    endpoint=endpoint,
+                    service=service,
+                    total_requests=total,
+                    success_count=success_count,
+                    error_count=error_count,
+                    success_rate_pct=round(success_rate, 1),
+                    min_ms=min(latencies) if latencies else 0.0,
+                    max_ms=max(latencies) if latencies else 0.0,
+                    mean_ms=sum(latencies) / len(latencies) if latencies else 0.0,
+                    p50_ms=percentile(latencies, 50),
+                    p95_ms=percentile(latencies, 95),
+                    p99_ms=percentile(latencies, 99),
+                    rps=self.total_count / safe_duration,
+                    error_breakdown=error_breakdown,
+                )
+            )
+
+        return stats
+
+    def flush_snapshot(self, timestamp: float, duration_seconds: float) -> None:
+        """Record a 5-second interval snapshot (for time-series charts)."""
+        latencies = [r.latency_ms for r in self._samples]
+        safe_duration = max(duration_seconds, 0.001)
+        total = len(self._samples)
+        error_count = sum(
+            1 for r in self._samples
+            if r.error_type is not None or not (200 <= r.status < 300)
+        )
+        self._snapshots.append(
+            StatsSnapshot(
+                timestamp=timestamp,
+                p50_ms=percentile(latencies, 50),
+                p95_ms=percentile(latencies, 95),
+                p99_ms=percentile(latencies, 99),
+                rps=self.total_count / safe_duration,
+                error_rate_pct=(error_count / total * 100.0) if total else 0.0,
+            )
+        )

jac_loadtest-0.1.0/jac_loadtest/output/reporter.py

@@ -0,0 +1,91 @@
+"""Console (Rich), JSON, and HTML report rendering.
+
+stdout: machine-readable output (json).
+stderr: all human-readable output (console table, progress bar, warnings).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from jac_loadtest.core.metrics import EndpointStats
+    from jac_loadtest.config import LoadTestConfig
+
+
+def render_console(stats: list[EndpointStats], config: LoadTestConfig) -> None:
+    """Print a Rich summary table to stderr."""
+    from rich.console import Console
+    from rich.table import Table
+    from rich import box
+    from jac_loadtest.config import parse_duration
+
+    console = Console(stderr=True, highlight=False)
+
+    table = Table(box=box.SIMPLE_HEAVY, show_footer=False)
+    table.add_column("Endpoint", style="cyan", no_wrap=True)
+    table.add_column("Reqs", justify="right")
+    table.add_column("OK%", justify="right")
+    table.add_column("p50", justify="right")
+    table.add_column("p95", justify="right")
+    table.add_column("p99", justify="right")
+    table.add_column("RPS", justify="right")
+    table.add_column("Errs", justify="right")
+
+    for s in stats:
+        table.add_row(
+            s.endpoint,
+            str(s.total_requests),
+            f"{s.success_rate_pct:.1f}",
+            f"{s.p50_ms:.0f}ms",
+            f"{s.p95_ms:.0f}ms",
+            f"{s.p99_ms:.0f}ms",
+            f"{s.rps:.1f}",
+            str(s.error_count),
+        )
+
+    # TOTAL footer row aggregated across all endpoints
+    if stats:
+        total_reqs = sum(s.total_requests for s in stats)
+        total_success = sum(s.success_count for s in stats)
+        total_errors = sum(s.error_count for s in stats)
+        overall_ok_pct = (total_success / total_reqs * 100.0) if total_reqs else 0.0
+
+        all_latencies: list[float] = []
+        for s in stats:
+            # Approximate from p50/p95/p99 — real latencies live in MetricsCollector.
+            # For the TOTAL row we compute a weighted mean of percentile values.
+            all_latencies.extend([s.p50_ms] * s.total_requests)
+
+        from jac_loadtest.core.metrics import percentile as pct
+        all_p50 = pct(all_latencies, 50)
+        all_p95 = pct(all_latencies, 95)
+        all_p99 = pct(all_latencies, 99)
+        total_rps = sum(s.rps for s in stats)
+
+        table.add_section()
+        table.add_row(
+            "[bold]TOTAL[/bold]",
+            f"[bold]{total_reqs}[/bold]",
+            f"[bold]{overall_ok_pct:.1f}[/bold]",
+            f"[bold]{all_p50:.0f}ms[/bold]",
+            f"[bold]{all_p95:.0f}ms[/bold]",
+            f"[bold]{all_p99:.0f}ms[/bold]",
+            f"[bold]{total_rps:.1f}[/bold]",
+            f"[bold]{total_errors}[/bold]",
+        )
+
+    console.print(table)
+
+    duration_s = parse_duration(config.duration)
+    console.print(
+        f"Duration: {duration_s:.0f}s   VUs: {config.vus}   "
+        f"Ramp-up: {config.ramp_up}   Mode: {config.mode}"
+    )
+
+
+def render_json(stats: list[EndpointStats], config: LoadTestConfig) -> str:
+    raise NotImplementedError("JSON reporter is implemented in Phase 5.")
+
+
+def render_html(stats: list[EndpointStats], config: LoadTestConfig) -> str:
+    raise NotImplementedError("HTML reporter is implemented in Phase 5.")

jac_loadtest-0.1.0/jac_loadtest/plugin.py

@@ -0,0 +1,77 @@
+"""Registers `jac loadtest` with jaclang's CommandRegistry at module import time.
+
+The @registry.command decorator fires when this module is imported (which happens
+when jaclang loads this entry-point). The JacLoadtestCmd class is a marker that
+the entry-point points to — importing it is what matters, not instantiating it.
+"""
+from jaclang.cli.registry import get_registry
+from jaclang.cli.command import Arg, ArgKind
+
+registry = get_registry()
+
+
+@registry.command(
+    name="loadtest",
+    help="HAR-based load testing for jac-scale apps",
+    args=[
+        Arg.create("har_file", kind=ArgKind.POSITIONAL, help="Path to .har file"),
+        Arg.create("url", typ=str, default=None, short="",
+                   help="Target base URL (e.g. http://localhost:8000)"),
+        Arg.create("mode", typ=str, default="monolith", short="",
+                   help="Deployment mode: monolith or microservice"),
+        Arg.create("vus", typ=int, default=1, short="",
+                   help="Number of virtual users"),
+        Arg.create("duration", typ=str, default="30s", short="",
+                   help="Test duration (e.g. 30s, 2m, 1h)"),
+        Arg.create("iterations", typ=int, default=None, short="",
+                   help="Iteration cap per VU (alternative to --duration)"),
+        Arg.create("ramp-up", typ=str, default="0s", short="",
+                   help="Time to ramp up to full VU count"),
+        Arg.create("timeout", typ=str, default="30s", short="",
+                   help="Per-request timeout"),
+        Arg.create("think-time", typ=str, default="none", short="",
+                   help="Inter-request delay: none, real, or scaled"),
+        Arg.create("think-time-scale", typ=float, default=1.0, short="",
+                   help="Multiplier when --think-time scaled"),
+        Arg.create("username", typ=str, default=None, short="",
+                   help="Username for shared-credential auth"),
+        Arg.create("password", typ=str, default=None, short="",
+                   help="Password for shared-credential auth"),
+        Arg.create("credentials-file", typ=str, default=None, short="",
+                   help="CSV file with username,password rows (one per VU)"),
+        Arg.create("login-path", typ=str, default="/user/login", short="",
+                   help="URL path detected as the login entry"),
+        Arg.create("include-static", typ=bool, default=False, short="",
+                   help="Do not skip image/font/CSS entries"),
+        Arg.create("rps", typ=int, default=0, short="",
+                   help="Global requests-per-second cap (0 = unlimited)"),
+        Arg.create("max-samples", typ=int, default=1_000_000, short="",
+                   help="Max raw request records kept in memory for percentile calc"),
+        Arg.create("services-map", typ=str, default=None, short="",
+                   help='JSON map of service name to URL e.g. \'{"svc":"http://host:port"}\''),
+        Arg.create("csrf", typ=bool, default=False, short="",
+                   help="Enable CSRF token detection and injection"),
+        Arg.create("fail-on-error-rate", typ=float, default=None, short="",
+                   help="Exit 1 if error rate exceeds N percent"),
+        Arg.create("fail-on-p95", typ=float, default=None, short="",
+                   help="Exit 1 if p95 latency exceeds N milliseconds"),
+        Arg.create("fail-on-p99", typ=float, default=None, short="",
+                   help="Exit 1 if p99 latency exceeds N milliseconds"),
+        Arg.create("abort-on-fail", typ=bool, default=False, short="",
+                   help="Stop test immediately when any threshold is breached"),
+        Arg.create("threshold-start-delay", typ=str, default="0s", short="",
+                   help="Delay threshold evaluation N seconds from test start"),
+        Arg.create("report-format", typ=str, default="console", short="",
+                   help="Output format: console, json, or html"),
+        Arg.create("report-out", typ=str, default=None, short="",
+                   help="Output file path for json/html reports"),
+        Arg.create("debug", typ=bool, default=False, short="",
+                   help="Print each request and response status to stderr during run"),
+    ],
+    group="testing",
+    source="jac-loadtest",
+)
+def loadtest(**kwargs) -> None:
+    import types
+    from jac_loadtest.cli import run
+    run(types.SimpleNamespace(**kwargs))

jac_loadtest-0.1.0/jac_loadtest.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: jac-loadtest
+Version: 0.1.0
+Summary: HAR-based load testing CLI for jac-scale applications
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: jaclang==0.15.2
+Requires-Dist: jac-scale==0.2.16
+Requires-Dist: rich>=13.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-mock>=3.12; extra == "test"
+Requires-Dist: aiohttp[speedups]>=3.9; extra == "test"
+
+# jac-loadtest
+
+HAR-based load testing CLI for [jac-scale](https://github.com/jaseci-labs/jaseci/tree/main/jac-scale) applications. Capture real browser traffic via Chrome DevTools, export it as a `.har` file, and replay it under load — no scripting required.
+
+The tool registers itself as a `jac` subcommand, so after installation you run `jac loadtest` alongside `jac start`, `jac deploy`, and the rest of the jac ecosystem.
+
+## Quick Start
+
+```bash
+# Minimal: 1 VU, 30s
+jac loadtest recording.har --url http://localhost:8000
+
+# 50 VUs with 10s ramp-up
+jac loadtest recording.har --url http://localhost:8000 --vus 50 --ramp-up 10s --duration 60s
+
+# Authenticated test with per-VU credentials
+jac loadtest recording.har --url http://localhost:8000 --vus 20 --credentials-file creds.csv
+
+# CI-friendly with thresholds
+jac loadtest recording.har --url http://localhost:8000 \
+  --vus 10 --duration 30s --fail-on-p95 500 --fail-on-error-rate 1
+```
+
+## Developer Setup
+
+```bash
+# 1. Create and activate a conda env (Python 3.12 required)
+conda create -n load python=3.12
+conda activate load
+
+# 2. Install the package in editable mode (runtime deps only)
+pip install -e .
+
+# 3. Also install test dependencies (when running tests)
+pip install -e ".[test]"
+
+# 4. Verify the command is registered
+jac loadtest --help
+```
+
+## Project Layout
+
+```
+jac_loadtest/
+├── plugin.py      — registers `jac loadtest` via jaclang entry-points
+├── cli.py         — argument wiring; JacMetaImporter bootstrap
+├── config.py      — LoadTestConfig dataclass (three-layer resolution)
+├── core/          — HAR parser, load engine, metrics (no jac-scale knowledge)
+├── bridge/        — jac-scale-aware adapters (auth, topology)
+└── output/        — console, JSON, HTML reporters
+```
+
+The hard boundary between `core/` and `bridge/` is what keeps the eventual migration to `jac-scale[loadtest]` a file move rather than a rewrite.
+
+## HAR Compatibility
+
+Tested with HAR **1.1** and **1.2** (the format exported by Chrome DevTools, Firefox, Postman, and Insomnia). Files from other versions are parsed with a warning — open an issue if something breaks.
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md) — module map, data flow, design decisions
+- [Roadmap](docs/ROADMAP.md) — delivery phases and exit criteria
+- [Verification](docs/VERIFICATION.md) — phase-by-phase manual and automated verification checklists

jac_loadtest-0.1.0/jac_loadtest.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+pyproject.toml
+jac_loadtest/__init__.py
+jac_loadtest/cli.py
+jac_loadtest/config.py
+jac_loadtest/plugin.py
+jac_loadtest.egg-info/PKG-INFO
+jac_loadtest.egg-info/SOURCES.txt
+jac_loadtest.egg-info/dependency_links.txt
+jac_loadtest.egg-info/entry_points.txt
+jac_loadtest.egg-info/requires.txt
+jac_loadtest.egg-info/top_level.txt
+jac_loadtest/bridge/__init__.py
+jac_loadtest/bridge/auth.py
+jac_loadtest/bridge/topology.py
+jac_loadtest/core/__init__.py
+jac_loadtest/core/engine.py
+jac_loadtest/core/har_parser.py
+jac_loadtest/core/metrics.py
+jac_loadtest/output/__init__.py
+jac_loadtest/output/reporter.py

jac_loadtest-0.1.0/jac_loadtest.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jac_loadtest-0.1.0/jac_loadtest.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[jac]
+loadtest = jac_loadtest.plugin:loadtest

jac_loadtest-0.1.0/jac_loadtest.egg-info/requires.txt

@@ -0,0 +1,9 @@
+jaclang==0.15.2
+jac-scale==0.2.16
+rich>=13.0.0
+
+[test]
+pytest>=8.0
+pytest-asyncio>=0.23
+pytest-mock>=3.12
+aiohttp[speedups]>=3.9

jac_loadtest-0.1.0/jac_loadtest.egg-info/top_level.txt

@@ -0,0 +1 @@
+jac_loadtest

jac_loadtest-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "jac-loadtest"
+version = "0.1.0"
+description = "HAR-based load testing CLI for jac-scale applications"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "jaclang==0.15.2",
+    "jac-scale==0.2.16",
+    "rich>=13.0.0",
+]
+
+[project.entry-points."jac"]
+loadtest = "jac_loadtest.plugin:loadtest"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-mock>=3.12",
+    "aiohttp[speedups]>=3.9",
+]
+
+[tool.setuptools.packages.find]
+include = ["jac_loadtest*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "unit: pure logic, no network",
+    "integration: in-process aiohttp test server",
+    "e2e: full pipeline smoke test",
+]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"

jac_loadtest-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+