kctl-api 0.2.0__py3-none-any.whl

kctl_api/commands/openapi.py

@@ -0,0 +1,299 @@
+"""OpenAPI spec management commands for kctl-api.
+
+Export, validate, diff, and analyze the API specification.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+from kctl_api.core.utils import find_project_root
+
+app = typer.Typer(name="openapi", help="OpenAPI spec — export, validate, diff, breaking changes.", no_args_is_help=True)
+
+
+def _fetch_spec(actx: AppContext) -> dict:
+    """Fetch OpenAPI spec from running API or raise."""
+    data = actx.client.get("/openapi.json")
+    if not data:
+        raise RuntimeError("Empty response from /openapi.json")
+    return data
+
+
+# ---------------------------------------------------------------------------
+# export
+# ---------------------------------------------------------------------------
+@app.command()
+def export(
+    ctx: typer.Context,
+    fmt: Annotated[str, typer.Option("--format", help="Output format: json or yaml.")] = "json",
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Write to file instead of stdout.")] = None,
+) -> None:
+    """Fetch /openapi.json from running API and export as JSON or YAML."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch spec: {e}")
+        raise typer.Exit(1) from None
+
+    if fmt.lower() == "yaml":
+        try:
+            import yaml  # type: ignore[import-untyped]
+
+            content = yaml.dump(spec, allow_unicode=True, sort_keys=False)
+        except ImportError:
+            out.error("PyYAML not installed. Run: uv add pyyaml")
+            raise typer.Exit(1) from None
+    else:
+        content = json.dumps(spec, indent=2)
+
+    if output:
+        import pathlib
+
+        pathlib.Path(output).write_text(content)
+        out.success(f"Spec written to {output}")
+    else:
+        typer.echo(content)
+
+
+# ---------------------------------------------------------------------------
+# validate
+# ---------------------------------------------------------------------------
+@app.command()
+def validate(ctx: typer.Context) -> None:
+    """Check spec completeness — missing descriptions, examples, error schemas."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch spec: {e}")
+        raise typer.Exit(1) from None
+
+    issues: list[dict] = []
+    paths = spec.get("paths", {})
+
+    for path, path_item in paths.items():
+        for method, operation in path_item.items():
+            if method not in ("get", "post", "put", "patch", "delete", "head", "options"):
+                continue
+            # Missing summary/description
+            if not operation.get("summary") and not operation.get("description"):
+                issues.append({"path": path, "method": method.upper(), "issue": "Missing summary/description"})
+
+            # Check for error response schemas (400/422/500)
+            responses = operation.get("responses", {})
+            has_error_schema = any(str(code) in responses for code in (400, 401, 403, 404, 422, 500))
+            if not has_error_schema:
+                issues.append({"path": path, "method": method.upper(), "issue": "No error response schema"})
+
+            # Check request body has examples
+            req_body = operation.get("requestBody", {})
+            if req_body:
+                content = req_body.get("content", {})
+                for media_type, media_obj in content.items():
+                    if not media_obj.get("example") and not media_obj.get("examples"):
+                        issues.append(
+                            {
+                                "path": path,
+                                "method": method.upper(),
+                                "issue": f"Request body missing example ({media_type})",
+                            }
+                        )
+
+    if not issues:
+        out.success(f"Spec validation passed — {len(paths)} paths checked, no issues found.")
+        return
+
+    rows = [[i["method"], i["path"], i["issue"]] for i in issues]
+    out.table(
+        title=f"Spec Issues ({len(issues)})",
+        columns=[("Method", "bold"), ("Path", ""), ("Issue", "yellow")],
+        rows=rows,
+        data_for_json=issues,
+    )
+    raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# diff
+# ---------------------------------------------------------------------------
+@app.command()
+def diff(
+    ctx: typer.Context,
+    base: Annotated[str, typer.Option("--base", help="Git ref to compare against.")] = "main",
+) -> None:
+    """Diff OpenAPI spec between current state and a git ref."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+
+    # Export current spec to temp file
+    try:
+        current_spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch current spec: {e}")
+        raise typer.Exit(1) from None
+
+    import pathlib
+    import tempfile
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        json.dump(current_spec, f, indent=2)
+        current_file = f.name
+
+    # Get spec from base ref
+    base_file = pathlib.Path(tempfile.mktemp(suffix=".json"))
+    result = subprocess.run(
+        ["git", "show", f"{base}:apps/api/openapi.json"],
+        cwd=str(root),
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        out.warn(f"Could not find spec at {base}:apps/api/openapi.json — showing current spec only.")
+        out.info("To generate a base spec: kctl-api openapi export -o apps/api/openapi.json && git commit")
+        raise typer.Exit(0)
+
+    base_file.write_text(result.stdout)
+
+    subprocess.run(["diff", "-u", str(base_file), current_file], capture_output=False)
+
+    pathlib.Path(current_file).unlink(missing_ok=True)
+    base_file.unlink(missing_ok=True)
+
+
+# ---------------------------------------------------------------------------
+# breaking
+# ---------------------------------------------------------------------------
+@app.command()
+def breaking(
+    ctx: typer.Context,
+    base: Annotated[str, typer.Option("--base", help="Git ref to compare against.")] = "main",
+) -> None:
+    """Detect breaking changes — removed endpoints, changed types, removed fields."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+
+    try:
+        current_spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch current spec: {e}")
+        raise typer.Exit(1) from None
+
+    # Attempt to load base spec from git
+    result = subprocess.run(
+        ["git", "show", f"{base}:apps/api/openapi.json"],
+        cwd=str(root),
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        out.warn(f"No base spec found at {base}:apps/api/openapi.json")
+        out.info("Commit your openapi.json to enable breaking change detection.")
+        raise typer.Exit(0)
+
+    try:
+        base_spec = json.loads(result.stdout)
+    except json.JSONDecodeError as e:
+        out.error(f"Could not parse base spec: {e}")
+        raise typer.Exit(1) from None
+
+    changes: list[dict] = []
+    base_paths = base_spec.get("paths", {})
+    curr_paths = current_spec.get("paths", {})
+
+    # Removed endpoints
+    for path in base_paths:
+        if path not in curr_paths:
+            changes.append({"severity": "BREAKING", "type": "Removed endpoint", "detail": path})
+        else:
+            for method in base_paths[path]:
+                if method not in ("get", "post", "put", "patch", "delete"):
+                    continue
+                if method not in curr_paths.get(path, {}):
+                    changes.append(
+                        {
+                            "severity": "BREAKING",
+                            "type": "Removed method",
+                            "detail": f"{method.upper()} {path}",
+                        }
+                    )
+
+    # New endpoints (informational)
+    for path in curr_paths:
+        if path not in base_paths:
+            changes.append({"severity": "INFO", "type": "New endpoint", "detail": path})
+
+    if not changes:
+        out.success("No breaking changes detected.")
+        return
+
+    rows = [[c["severity"], c["type"], c["detail"]] for c in changes]
+    out.table(
+        title=f"Breaking Change Analysis ({len(changes)} changes)",
+        columns=[("Severity", "bold"), ("Type", ""), ("Detail", "")],
+        rows=rows,
+        data_for_json=changes,
+    )
+
+    has_breaking = any(c["severity"] == "BREAKING" for c in changes)
+    if has_breaking:
+        out.error("Breaking changes detected!")
+        raise typer.Exit(1)
+    else:
+        out.warn("Non-breaking changes only.")
+
+
+# ---------------------------------------------------------------------------
+# clients
+# ---------------------------------------------------------------------------
+@app.command()
+def clients(ctx: typer.Context) -> None:
+    """Show information about generating client SDKs from the OpenAPI spec."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    url = actx.client.base_url.rstrip("/")
+    spec_url = f"{url}/openapi.json"
+
+    out.header("Client SDK Generation")
+    out.text("")
+    out.text("[bold]OpenAPI spec URL:[/bold]")
+    out.text(f"  {spec_url}")
+    out.text("")
+    out.text("[bold]Generate TypeScript client (openapi-typescript-codegen):[/bold]")
+    out.text(f"  npx openapi-typescript-codegen --input {spec_url} --output src/api --client axios")
+    out.text("")
+    out.text("[bold]Generate Python client (openapi-python-client):[/bold]")
+    out.text(f"  uvx openapi-python-client generate --url {spec_url}")
+    out.text("")
+    out.text("[bold]Export spec first:[/bold]")
+    out.text("  kctl-api openapi export --format json -o openapi.json")
+    out.text("  kctl-api openapi export --format yaml -o openapi.yaml")
+    out.text("")
+    out.text("[bold]Validate before generating:[/bold]")
+    out.text("  kctl-api openapi validate")
+
+    if actx.json_mode:
+        out.raw_json(
+            {
+                "spec_url": spec_url,
+                "tools": {
+                    "typescript": f"npx openapi-typescript-codegen --input {spec_url} --output src/api --client axios",
+                    "python": f"uvx openapi-python-client generate --url {spec_url}",
+                },
+            }
+        )

kctl_api/commands/perf.py

@@ -0,0 +1,307 @@
+"""Performance testing commands for kctl-api.
+
+Benchmarking, profiling, and latency analysis.
+"""
+
+from __future__ import annotations
+
+import statistics
+import time
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+
+app = typer.Typer(name="perf", help="Performance — bench, profile, latency, endpoints.", no_args_is_help=True)
+
+
+# ---------------------------------------------------------------------------
+# bench
+# ---------------------------------------------------------------------------
+@app.command()
+def bench(
+    ctx: typer.Context,
+    endpoint: Annotated[str, typer.Argument(help="Endpoint path to benchmark (e.g. /api/v1/health).")],
+    rps: Annotated[int, typer.Option("--rps", help="Target requests per second.")] = 10,
+    duration: Annotated[int, typer.Option("--duration", help="Test duration in seconds.")] = 10,
+    method: Annotated[str, typer.Option("--method", "-X", help="HTTP method.")] = "GET",
+) -> None:
+    """Load test an endpoint — target RPS for a duration."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    total_requests = rps * duration
+    interval = 1.0 / rps
+
+    out.info(f"Benchmarking {method} {endpoint} — {rps} RPS for {duration}s ({total_requests} requests) ...")
+
+    latencies: list[float] = []
+    errors: list[str] = []
+    status_counts: dict[int, int] = {}
+
+    start_time = time.monotonic()
+    next_send = start_time
+
+    for i in range(total_requests):
+        # Rate control
+        now = time.monotonic()
+        if now < next_send:
+            time.sleep(next_send - now)
+        next_send = time.monotonic() + interval
+
+        req_start = time.monotonic()
+        try:
+            response = actx.client.get_raw(endpoint)
+
+            elapsed_ms = (time.monotonic() - req_start) * 1000
+            latencies.append(elapsed_ms)
+            status = response.status_code
+            status_counts[status] = status_counts.get(status, 0) + 1
+        except Exception as e:
+            elapsed_ms = (time.monotonic() - req_start) * 1000
+            latencies.append(elapsed_ms)
+            errors.append(str(e)[:60])
+
+        # Progress every 10%
+        if (i + 1) % max(total_requests // 10, 1) == 0:
+            pct = round((i + 1) / total_requests * 100)
+            out.info(f"  Progress: {pct}% ({i + 1}/{total_requests})")
+
+    total_time = time.monotonic() - start_time
+    actual_rps = round(len(latencies) / max(total_time, 0.001))
+
+    if not latencies:
+        out.error("No requests completed.")
+        raise typer.Exit(1)
+
+    sorted_lat = sorted(latencies)
+    p50 = statistics.median(sorted_lat)
+    p95 = sorted_lat[int(len(sorted_lat) * 0.95)]
+    p99 = sorted_lat[int(len(sorted_lat) * 0.99)]
+    avg = statistics.mean(sorted_lat)
+    min_lat = min(sorted_lat)
+    max_lat = max(sorted_lat)
+
+    out.text("")
+    out.header(f"Benchmark Results: {endpoint}")
+    out.text(f"  Duration:    {round(total_time, 1)}s")
+    out.text(f"  Requests:    {len(latencies)}")
+    out.text(f"  Actual RPS:  {actual_rps}")
+    out.text(f"  Errors:      [{'red' if errors else 'green'}]{len(errors)}[/{'red' if errors else 'green'}]")
+    out.text("")
+    out.text("  Latency:")
+    out.text(f"    min:  {round(min_lat, 1)}ms")
+    out.text(f"    avg:  {round(avg, 1)}ms")
+    out.text(f"    p50:  {round(p50, 1)}ms")
+    out.text(f"    p95:  {round(p95, 1)}ms")
+    out.text(f"    p99:  {round(p99, 1)}ms")
+    out.text(f"    max:  {round(max_lat, 1)}ms")
+    out.text("")
+    if status_counts:
+        out.text("  Status codes: " + ", ".join(f"{k}:{v}" for k, v in sorted(status_counts.items())))
+
+    if actx.json_mode:
+        out.raw_json(
+            {
+                "endpoint": endpoint,
+                "method": method,
+                "duration_s": round(total_time, 2),
+                "requests": len(latencies),
+                "actual_rps": actual_rps,
+                "errors": len(errors),
+                "latency_ms": {
+                    "min": round(min_lat, 1),
+                    "avg": round(avg, 1),
+                    "p50": round(p50, 1),
+                    "p95": round(p95, 1),
+                    "p99": round(p99, 1),
+                    "max": round(max_lat, 1),
+                },
+                "status_counts": status_counts,
+            }
+        )
+
+
+# ---------------------------------------------------------------------------
+# profile
+# ---------------------------------------------------------------------------
+@app.command()
+def profile(
+    ctx: typer.Context,
+    endpoint: Annotated[str, typer.Argument(help="Endpoint path to profile.")],
+    samples: Annotated[int, typer.Option("--samples", "-n", help="Number of samples.")] = 10,
+    method: Annotated[str, typer.Option("--method", "-X", help="HTTP method.")] = "GET",
+) -> None:
+    """Profile endpoint execution — timing breakdown over N samples."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    out.info(f"Profiling {method} {endpoint} — {samples} samples ...")
+
+    latencies: list[float] = []
+    ttfbs: list[float] = []  # time to first byte (approximated)
+
+    for i in range(samples):
+        req_start = time.monotonic()
+        try:
+            actx.client.get_raw(endpoint)
+            elapsed_ms = (time.monotonic() - req_start) * 1000
+            latencies.append(elapsed_ms)
+            ttfbs.append(elapsed_ms)  # httpx doesn't expose TTFB separately without streaming
+        except Exception as e:
+            out.warn(f"Sample {i + 1} failed: {e}")
+
+    if not latencies:
+        out.error("All samples failed.")
+        raise typer.Exit(1)
+
+    rows = [[str(i + 1), f"{round(lat, 1)}ms"] for i, lat in enumerate(latencies)]
+    out.table(
+        title=f"Profile: {endpoint} ({len(latencies)} samples)",
+        columns=[("Sample", ""), ("Latency", "")],
+        rows=rows,
+        data_for_json=[{"sample": i + 1, "latency_ms": round(lat, 1)} for i, lat in enumerate(latencies)],
+    )
+
+    if len(latencies) > 1:
+        out.text("")
+        out.text(f"  avg: {round(statistics.mean(latencies), 1)}ms  stdev: {round(statistics.stdev(latencies), 1)}ms")
+
+
+# ---------------------------------------------------------------------------
+# latency
+# ---------------------------------------------------------------------------
+@app.command()
+def latency(
+    ctx: typer.Context,
+    endpoint: Annotated[str | None, typer.Argument(help="Endpoint to check (default: /api/v1/health).")] = None,
+    samples: Annotated[int, typer.Option("--samples", "-n", help="Number of samples.")] = 20,
+) -> None:
+    """Show latency percentiles for an endpoint."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    target = endpoint or "/api/v1/health"
+    out.info(f"Measuring latency: {target} ({samples} samples) ...")
+
+    latencies: list[float] = []
+    for _ in range(samples):
+        start = time.monotonic()
+        try:
+            actx.client.get_raw(target)
+            latencies.append((time.monotonic() - start) * 1000)
+        except Exception:
+            latencies.append(-1.0)
+
+    valid = [lat for lat in latencies if lat >= 0]
+    if not valid:
+        out.error("All requests failed.")
+        raise typer.Exit(1)
+
+    sorted_lat = sorted(valid)
+    percentiles = [50, 75, 90, 95, 99]
+
+    rows = [
+        [f"p{p}", f"{round(sorted_lat[min(int(len(sorted_lat) * p / 100), len(sorted_lat) - 1)], 1)}ms"]
+        for p in percentiles
+    ]
+    rows.insert(0, ["min", f"{round(min(sorted_lat), 1)}ms"])
+    rows.insert(1, ["avg", f"{round(statistics.mean(sorted_lat), 1)}ms"])
+    rows.append(["max", f"{round(max(sorted_lat), 1)}ms"])
+
+    failed = len(latencies) - len(valid)
+    out.table(
+        title=f"Latency Percentiles: {target} ({len(valid)} samples, {failed} failed)",
+        columns=[("Percentile", "bold"), ("Latency", "")],
+        rows=rows,
+        data_for_json={
+            "endpoint": target,
+            "samples": len(valid),
+            "failed": failed,
+            "percentiles": {
+                f"p{p}": round(sorted_lat[min(int(len(sorted_lat) * p / 100), len(sorted_lat) - 1)], 1)
+                for p in percentiles
+            },
+            "min": round(min(sorted_lat), 1),
+            "avg": round(statistics.mean(sorted_lat), 1),
+            "max": round(max(sorted_lat), 1),
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# endpoints
+# ---------------------------------------------------------------------------
+@app.command()
+def endpoints(
+    ctx: typer.Context,
+    samples: Annotated[int, typer.Option("--samples", "-n", help="Samples per endpoint.")] = 3,
+    tag: Annotated[str | None, typer.Option("--tag", help="Filter by OpenAPI tag.")] = None,
+) -> None:
+    """Measure response times for all GET endpoints from the OpenAPI spec."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    # Fetch spec
+    try:
+        spec_data = actx.client.get("/openapi.json")
+        if not spec_data:
+            raise RuntimeError("Empty spec")
+    except Exception as e:
+        out.error(f"Failed to fetch spec: {e}")
+        raise typer.Exit(1) from None
+
+    # Collect GET endpoints
+    get_endpoints: list[str] = []
+    for path, path_item in spec_data.get("paths", {}).items():
+        if "get" not in path_item:
+            continue
+        operation = path_item["get"]
+        # Skip paths with parameters (can't call them without values)
+        if "{" in path:
+            continue
+        if tag and tag not in operation.get("tags", []):
+            continue
+        get_endpoints.append(path)
+
+    if not get_endpoints:
+        out.warn("No GET endpoints without path parameters found.")
+        raise typer.Exit(0)
+
+    out.info(f"Testing {len(get_endpoints)} GET endpoints ({samples} samples each) ...")
+
+    results: list[dict] = []
+    for ep in get_endpoints:
+        ep_latencies: list[float] = []
+        last_status = 0
+        for _ in range(samples):
+            start = time.monotonic()
+            try:
+                resp = actx.client.get_raw(ep)
+                last_status = resp.status_code
+                ep_latencies.append((time.monotonic() - start) * 1000)
+            except Exception:
+                ep_latencies.append(-1.0)
+
+        valid = [lat for lat in ep_latencies if lat >= 0]
+        avg = round(statistics.mean(valid), 1) if valid else -1
+
+        results.append(
+            {
+                "endpoint": ep,
+                "status": last_status,
+                "avg_ms": avg,
+                "samples": len(valid),
+            }
+        )
+
+    results.sort(key=lambda x: -x["avg_ms"])
+
+    rows = [[r["endpoint"], str(r["status"]), f"{r['avg_ms']}ms", str(r["samples"])] for r in results]
+    out.table(
+        title="Endpoint Response Times (slowest first)",
+        columns=[("Endpoint", ""), ("Status", ""), ("Avg Latency", "bold"), ("Samples", "")],
+        rows=rows,
+        data_for_json=results,
+    )