jac-loadtest 0.1.0__tar.gz → 0.2.2__tar.gz

{jac_loadtest-0.1.0 → jac_loadtest-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jac-loadtest
-Version: 0.1.0
+Version: 0.2.2
 Summary: HAR-based load testing CLI for jac-scale applications
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -19,6 +19,25 @@ HAR-based load testing CLI for [jac-scale](https://github.com/jaseci-labs/jaseci
 
 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.
 
+## Testing Modes
+
+**Monolith mode** (default) — all requests go through a single `--url`. Use this for production-realistic load testing: it measures what users actually experience end-to-end through the gateway.
+
+**Microservice mode** — route requests directly to individual service processes by URL path prefix. Use this locally or inside your cluster to isolate per-service latency and identify which service is the bottleneck — without gateway overhead masking the signal.
+
+```bash
+# Monolith: all traffic through the gateway (default, production-realistic)
+jac loadtest recording.har --url http://localhost:8000 --vus 10 --duration 30s
+
+# Microservice: bypass gateway, route by path prefix to individual services
+jac loadtest recording.har --mode microservice \
+  --url http://localhost:8000 \
+  --services-map '{"order_service":"http://localhost:18001","inventory_service":"http://localhost:18002"}' \
+  --vus 10 --duration 30s
+```
+
+> **Note:** Microservice mode requires direct network access to service ports. This means it's only usable locally (`jac serve`) or from inside a Kubernetes cluster — not from outside production. For remote or production load testing, use monolith mode.
+
 ## Quick Start
 
 ```bash

{jac_loadtest-0.1.0 → jac_loadtest-0.2.2}/README.md

@@ -4,6 +4,25 @@ HAR-based load testing CLI for [jac-scale](https://github.com/jaseci-labs/jaseci
 
 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.
 
+## Testing Modes
+
+**Monolith mode** (default) — all requests go through a single `--url`. Use this for production-realistic load testing: it measures what users actually experience end-to-end through the gateway.
+
+**Microservice mode** — route requests directly to individual service processes by URL path prefix. Use this locally or inside your cluster to isolate per-service latency and identify which service is the bottleneck — without gateway overhead masking the signal.
+
+```bash
+# Monolith: all traffic through the gateway (default, production-realistic)
+jac loadtest recording.har --url http://localhost:8000 --vus 10 --duration 30s
+
+# Microservice: bypass gateway, route by path prefix to individual services
+jac loadtest recording.har --mode microservice \
+  --url http://localhost:8000 \
+  --services-map '{"order_service":"http://localhost:18001","inventory_service":"http://localhost:18002"}' \
+  --vus 10 --duration 30s
+```
+
+> **Note:** Microservice mode requires direct network access to service ports. This means it's only usable locally (`jac serve`) or from inside a Kubernetes cluster — not from outside production. For remote or production load testing, use monolith mode.
+
 ## Quick Start
 
 ```bash

jac_loadtest-0.2.2/jac_loadtest/bridge/auth.py

@@ -0,0 +1,114 @@
+"""jac-scale auth: per-VU JWT login and header injection.
+
+AuthProvider loads credentials from a CSV file or shared username/password,
+authenticates each VU independently against /user/login, and returns the
+Bearer token for injection into subsequent requests.
+"""
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import aiohttp
+
+if TYPE_CHECKING:
+    from jac_loadtest.config import LoadTestConfig
+
+
+class AuthenticationError(Exception):
+    """Raised when login fails; carries a human-readable message for the user."""
+
+
+@dataclass
+class Credential:
+    username: str
+    password: str
+
+
+class AuthProvider:
+    def __init__(
+        self,
+        credentials: list[Credential],
+        login_path: str = "/user/login",
+    ) -> None:
+        self._credentials = credentials
+        self._login_path = login_path
+
+    @classmethod
+    def from_config(cls, config: LoadTestConfig) -> AuthProvider | None:
+        """Return an AuthProvider if credentials are configured, else None."""
+        if config.credentials_file:
+            creds = _load_csv(config.credentials_file)
+        elif config.username and config.password:
+            creds = [Credential(config.username, config.password)]
+        else:
+            return None
+        return cls(creds, config.login_path)
+
+    def get_credential(self, vu_id: int) -> Credential:
+        """Wrap-around assignment: VU i gets row i % len(credentials)."""
+        return self._credentials[vu_id % len(self._credentials)]
+
+    async def authenticate(
+        self,
+        vu_id: int,
+        session: aiohttp.ClientSession,
+        base_url: str,
+    ) -> str:
+        """POST /user/login for VU vu_id and return the JWT token string.
+
+        identity.type is inferred: values containing '@' use 'email', else 'username'.
+        Raises AuthenticationError on 4xx/5xx so callers get a clear message.
+        """
+        cred = self.get_credential(vu_id)
+        identity_type = "email" if "@" in cred.username else "username"
+        payload = {
+            "identity": {"type": identity_type, "value": cred.username},
+            "credential": {"type": "password", "password": cred.password},
+        }
+        url = base_url.rstrip("/") + self._login_path
+        try:
+            async with session.post(url, json=payload) as resp:
+                if resp.status == 401:
+                    raise AuthenticationError(
+                        f"Login failed for VU {vu_id} ({identity_type}={cred.username!r}): "
+                        f"401 Unauthorized — check credentials."
+                    )
+                if not resp.ok:
+                    raise AuthenticationError(
+                        f"Login failed for VU {vu_id} ({identity_type}={cred.username!r}): "
+                        f"server returned {resp.status}."
+                    )
+                body = await resp.json()
+        except aiohttp.ClientConnectorError as exc:
+            raise AuthenticationError(
+                f"Cannot reach login endpoint {url!r}: {exc}"
+            ) from exc
+        try:
+            return body["data"]["token"]
+        except (KeyError, TypeError) as exc:
+            raise AuthenticationError(
+                f"Unexpected login response shape from {url!r}: {body!r}"
+            ) from exc
+
+
+def _load_csv(path: str) -> list[Credential]:
+    """Read credentials.csv and return a list of Credential objects.
+
+    Skips a header row if the first column value is 'username' (case-insensitive).
+    Raises ValueError if the file is empty or has no valid rows.
+    """
+    credentials: list[Credential] = []
+    with open(path, newline="") as f:
+        reader = csv.reader(f)
+        for i, row in enumerate(reader):
+            if len(row) < 2:
+                continue
+            username, password = row[0].strip(), row[1].strip()
+            if i == 0 and username.lower() == "username":
+                continue
+            credentials.append(Credential(username=username, password=password))
+    if not credentials:
+        raise ValueError(f"No credentials found in {path!r}")
+    return credentials

jac_loadtest-0.2.2/jac_loadtest/bridge/topology.py

@@ -0,0 +1,201 @@
+"""Build prefix→URL routing table from jac-scale ServiceRegistry or jac.toml.
+
+Implements longest-prefix matching to mirror jac-scale's gateway routing algorithm:
+    path == prefix  OR  path.startswith(prefix + "/")
+Empty prefix is a catch-all (used for monolith mode).
+
+Implemented in Phase 3.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from urllib.parse import urlparse, urlunparse
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from jac_loadtest.config import LoadTestConfig
+
+
+@dataclass
+class ServiceRoute:
+    name: str    # service label used in metrics/report (e.g. "order_service")
+    prefix: str  # path prefix for routing (e.g. "/walker/order"); "" = catch-all
+    url: str     # service base URL, no trailing slash (e.g. "http://localhost:18001")
+
+
+class TopologyRouter:
+    """Routes a HAR entry URL to the correct service URL and returns the service name.
+
+    Construction: TopologyRouter.from_config(config) is the normal entry point.
+    Direct construction (TopologyRouter(routes, fallback_url)) is used in tests.
+    """
+
+    def __init__(
+        self,
+        routes: list[ServiceRoute],
+        fallback_url: str | None = None,
+    ) -> None:
+        # Sort once at construction — longest prefix first (mirrors ServiceRegistry)
+        self._routes = sorted(routes, key=lambda r: len(r.prefix), reverse=True)
+        self._fallback_url = fallback_url
+
+    def resolve(self, entry_url: str) -> tuple[str, str]:
+        """Return (routed_full_url, service_name) for the given HAR entry URL.
+
+        Reconstructs the full URL using the matched service's base + original path + query.
+        Match logic mirrors jac-scale ServiceRegistry.match_route() exactly:
+            empty prefix  → catch-all (monolith)
+            path == prefix OR path.startswith(prefix + "/")
+        """
+        parsed = urlparse(entry_url)
+        path = parsed.path
+
+        for route in self._routes:
+            if _prefix_matches(path, route.prefix):
+                t = urlparse(route.url)
+                # Strip the gateway prefix before sending directly to the service.
+                # jac-scale's gateway strips the route prefix when forwarding; we replicate
+                # that so the service receives the path it actually handles.
+                # Empty prefix (monolith catch-all) keeps the path unchanged.
+                if route.prefix:
+                    service_path = path[len(route.prefix):] or "/"
+                else:
+                    service_path = path
+                base_path = t.path.rstrip("/") if t.path else ""
+                routed_path = f"{base_path}{service_path}" if base_path else service_path
+                routed = urlunparse((
+                    t.scheme, t.netloc,
+                    routed_path, parsed.params, parsed.query, "",
+                ))
+                return routed, route.name
+
+        if self._fallback_url:
+            t = urlparse(self._fallback_url)
+            base_path = t.path.rstrip("/") if t.path else ""
+            routed_path = f"{base_path}{path}" if base_path else path
+            routed = urlunparse((
+                t.scheme, t.netloc,
+                routed_path, parsed.params, parsed.query, "",
+            ))
+            return routed, "gateway"
+
+        raise ValueError(
+            f"No route for path '{path}' and no --url fallback provided. "
+            "Use --services-map or add [plugins.scale.microservices.routes] to jac.toml."
+        )
+
+    @classmethod
+    def from_config(cls, config: LoadTestConfig) -> TopologyRouter:
+        """Build a TopologyRouter from LoadTestConfig.
+
+        Monolith mode: single catch-all route to config.url.
+        Microservice mode: --services-map JSON (highest priority) or jac.toml auto-discovery.
+        """
+        if config.mode != "microservice":
+            return cls(
+                routes=[ServiceRoute(name="monolith", prefix="", url=config.url or "")],
+                fallback_url=None,
+            )
+        return cls._build_microservice(config)
+
+    @classmethod
+    def _build_microservice(cls, config: LoadTestConfig) -> TopologyRouter:
+        toml_routes = _load_toml_routes()   # service_name → prefix; {} if unavailable
+
+        routes: list[ServiceRoute]
+
+        if config.services_map:
+            try:
+                services_json: dict[str, str] = json.loads(config.services_map)
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"--services-map is not valid JSON: {exc}") from exc
+
+            routes = [
+                ServiceRoute(
+                    # Strip leading slash from name so service labels display cleanly
+                    name=name.lstrip("/") if name.startswith("/") else name,
+                    # Key starting with "/" is used directly as prefix; otherwise derive from key
+                    prefix=toml_routes.get(name, name if name.startswith("/") else f"/{name}"),
+                    url=url.rstrip("/"),
+                )
+                for name, url in services_json.items()
+            ]
+            return cls(routes, fallback_url=config.url)
+
+        # Auto-discovery: jac.toml routes + JAC_SV_<NAME>_URL env vars
+        if not toml_routes:
+            raise ValueError(
+                "Microservice mode requires either --services-map or "
+                "[plugins.scale.microservices.routes] in jac.toml. Neither was found."
+            )
+
+        routes = []
+        missing: list[str] = []
+        for name, prefix in toml_routes.items():
+            env_var = f"JAC_SV_{name.upper()}_URL"
+            url = os.environ.get(env_var)
+            if not url:
+                missing.append(env_var)
+            else:
+                routes.append(ServiceRoute(name=name, prefix=prefix, url=url.rstrip("/")))
+
+        if missing:
+            raise ValueError(
+                f"Microservice mode: missing environment variable(s): {', '.join(missing)}. "
+                "Expected format: JAC_SV_<SERVICE_NAME>_URL=http://host:port"
+            )
+
+        return cls(routes, fallback_url=config.url)
+
+
+def _prefix_matches(path: str, prefix: str) -> bool:
+    """Return True if path matches prefix using jac-scale's exact routing semantics."""
+    if not prefix:
+        return True  # empty prefix = catch-all (monolith)
+    return path == prefix or path.startswith(prefix + "/")
+
+
+def _load_toml_routes() -> dict[str, str]:
+    """Read [plugins.scale.microservices.routes] from jac.toml.
+
+    Returns {service_name: prefix} dict.
+    Returns {} on any error (missing file, missing section, jac_scale unavailable).
+
+    Isolated as a module-level function so tests can monkeypatch it without
+    importing jac_scale at all — keeping topology unit tests jac-scale-free.
+    """
+    try:
+        from pathlib import Path
+        from jac_scale.config_loader import get_scale_config, reset_scale_config
+        reset_scale_config()
+        ms_config = get_scale_config(project_dir=Path.cwd()).get_microservices_config()
+        return dict(ms_config.get("routes", {}))
+    except Exception:
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Backward-compat shims — kept so any external code that imported these names
+# does not break.  Neither is called by production or test code in this repo.
+# ---------------------------------------------------------------------------
+
+def build_routing_table(
+    mode: str,
+    base_url: str | None = None,
+    services_map_json: str | None = None,
+) -> dict[str, str]:
+    raise NotImplementedError(
+        "build_routing_table() is deprecated. Use TopologyRouter.from_config() instead."
+    )
+
+
+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-0.2.2}/jac_loadtest/cli.py

@@ -19,18 +19,20 @@ def run(args: object) -> None:
 
     config = from_args(args)
 
-    if not config.url:
-        print("Error: --url is required", file=sys.stderr)
+    # --url required for monolith mode; optional for microservice (becomes fallback)
+    if config.mode == "monolith" and not config.url:
+        print("Error: --url is required for monolith mode", 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)
 
+    # Parse HAR — monolith rewrites all URLs to config.url; microservice keeps originals
     try:
         entries = parse_har(
             config.har_file,
-            target_url=config.url,
+            target_url=config.url if config.mode == "monolith" else None,
             include_static=config.include_static,
             login_path=config.login_path,
         )
@@ -46,11 +48,39 @@ def run(args: object) -> None:
         )
         sys.exit(2)
 
+    from jac_loadtest.bridge.auth import AuthProvider, AuthenticationError
+
+    auth_provider = AuthProvider.from_config(config)
+
+    # In microservice mode, auth still goes to the gateway (--url); require it when set
+    if config.mode == "microservice" and auth_provider is not None and not config.url:
+        print(
+            "Error: --url (gateway URL) is required when using authentication "
+            "in microservice mode",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    # Build topology router — validates service map JSON and service URL availability
+    from jac_loadtest.bridge.topology import TopologyRouter
+
+    try:
+        topology = TopologyRouter.from_config(config)
+    except ValueError as exc:
+        print(f"Error: {exc}", 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))
+    try:
+        asyncio.run(
+            run_all_vus(entries, config, metrics, topology=topology, auth_provider=auth_provider)
+        )
+    except AuthenticationError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(2)
 
     duration_s = time.time() - t_start
     stats = metrics.compute_endpoint_stats(duration_s)
-    render_console(stats, config)
+    render_console(stats, config, actual_duration_s=duration_s)

jac_loadtest-0.2.2/jac_loadtest/config.py

@@ -0,0 +1,149 @@
+"""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
+from typing import Any
+
+
+BUILT_IN_DEFAULTS: dict = {
+    "vus": 1,
+    "duration": "30s",
+    "iterations": 1,
+    "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  = 1
+    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 _load_toml_defaults() -> dict:
+    """Read [plugins.scale.loadtest] from jac.toml using jac-scale's native config API.
+
+    Returns an empty dict if jac.toml is absent, the section is missing, or
+    the import fails (e.g. jac-scale not installed in a minimal test env).
+    """
+    try:
+        from pathlib import Path
+        from jac_scale.config_loader import get_scale_config, reset_scale_config
+        reset_scale_config()
+        scale_config = get_scale_config(project_dir=Path.cwd())
+        return scale_config.get_section("loadtest")
+    except Exception:
+        return {}
+
+
+def from_args(args: object) -> LoadTestConfig:
+    """Build LoadTestConfig using three-layer resolution: CLI > jac.toml > built-in defaults."""
+    toml = _load_toml_defaults()
+
+    # For toml-sourced fields, use CLI value if provided (not None), else toml value,
+    # else built-in default.
+    def resolve(name: str) -> Any:
+        cli_val = getattr(args, name, None)
+        if cli_val is not None:
+            return cli_val
+        if name in toml:
+            return toml[name]
+        return BUILT_IN_DEFAULTS.get(name)
+
+    return LoadTestConfig(
+        # CLI-only fields: not sourced from jac.toml
+        har_file=getattr(args, "har_file", "") or "",
+        url=getattr(args, "url", None),
+        username=getattr(args, "username", None),
+        password=getattr(args, "password", None),
+        credentials_file=getattr(args, "credentials_file", None),
+        services_map=getattr(args, "services_map", None),
+        report_out=getattr(args, "report_out", None),
+        # Three-layer resolved fields
+        iterations=resolve("iterations"),
+        mode=resolve("mode"),
+        vus=resolve("vus"),
+        duration=resolve("duration"),
+        ramp_up=resolve("ramp_up"),
+        timeout=resolve("timeout"),
+        think_time=resolve("think_time"),
+        think_time_scale=resolve("think_time_scale"),
+        login_path=resolve("login_path"),
+        include_static=resolve("include_static"),
+        rps=resolve("rps"),
+        max_samples=resolve("max_samples"),
+        csrf=resolve("csrf"),
+        fail_on_error_rate=resolve("fail_on_error_rate"),
+        fail_on_p95=resolve("fail_on_p95"),
+        fail_on_p99=resolve("fail_on_p99"),
+        abort_on_fail=resolve("abort_on_fail"),
+        threshold_start_delay=resolve("threshold_start_delay"),
+        report_format=resolve("report_format"),
+        debug=resolve("debug"),
+    )