loaderup 0.1.0__tar.gz

loaderup-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: loaderup
+Version: 0.1.0
+Summary: Lightweight load-testing API and CLI built around FastAPI, k6, and decorator-based target registration.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.135.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-multipart>=0.0.24
+Requires-Dist: uvicorn>=0.44.0
+Requires-Dist: rich>=13.10.0
+
+# LoaderUp
+
+Lightweight load-testing API and CLI built around FastAPI, k6, and decorator-based target registration.
+
+## Requirements
+
+- Python `>=3.12`
+- `uv` (recommended package manager)
+- `k6` (optional but recommended for real load runs)
+
+## Install
+
+```bash
+uv pip install -e .
+```
+
+## Run API directly
+
+```bash
+python -m loader.main
+```
+
+Server starts on `http://127.0.0.1:8000` by default.
+
+## Run via CLI
+
+```bash
+python -m loaderup.cli up --app loader.main:app --targets loader.demo_registry_target --reload
+```
+
+This command opens the dashboard automatically at `http://127.0.0.1:8000/`.
+Use `--no-open-browser` if you want to disable auto-open.
+
+You can also use fallback-friendly forms like:
+
+```bash
+python -m loaderup.cli up --app main:app --targets demo_registry_targets --reload
+```
+
+## Health check
+
+```bash
+curl http://127.0.0.1:8000/health
+```
+
+## Dashboard
+
+Open:
+
+```bash
+http://127.0.0.1:8000/
+```
+
+Dashboard includes:
+
+- live status + progress stream
+- metrics cards + quick chart bars
+- saved run history (persisted in `artifacts/history/runs.jsonl`)
+- React-based multi-tab control center (`Run Now`, `Live`, `Registered Targets`, `History`)
+
+## Notes
+
+- Registry targets are loaded when the module is imported.
+- Use `/run/targets` to submit explicit targets.
+- Use `/run/registry` to run all decorator-registered targets.

loaderup-0.1.0/README.md

@@ -0,0 +1,65 @@
+# LoaderUp
+
+Lightweight load-testing API and CLI built around FastAPI, k6, and decorator-based target registration.
+
+## Requirements
+
+- Python `>=3.12`
+- `uv` (recommended package manager)
+- `k6` (optional but recommended for real load runs)
+
+## Install
+
+```bash
+uv pip install -e .
+```
+
+## Run API directly
+
+```bash
+python -m loader.main
+```
+
+Server starts on `http://127.0.0.1:8000` by default.
+
+## Run via CLI
+
+```bash
+python -m loaderup.cli up --app loader.main:app --targets loader.demo_registry_target --reload
+```
+
+This command opens the dashboard automatically at `http://127.0.0.1:8000/`.
+Use `--no-open-browser` if you want to disable auto-open.
+
+You can also use fallback-friendly forms like:
+
+```bash
+python -m loaderup.cli up --app main:app --targets demo_registry_targets --reload
+```
+
+## Health check
+
+```bash
+curl http://127.0.0.1:8000/health
+```
+
+## Dashboard
+
+Open:
+
+```bash
+http://127.0.0.1:8000/
+```
+
+Dashboard includes:
+
+- live status + progress stream
+- metrics cards + quick chart bars
+- saved run history (persisted in `artifacts/history/runs.jsonl`)
+- React-based multi-tab control center (`Run Now`, `Live`, `Registered Targets`, `History`)
+
+## Notes
+
+- Registry targets are loaded when the module is imported.
+- Use `/run/targets` to submit explicit targets.
+- Use `/run/registry` to run all decorator-registered targets.

loaderup-0.1.0/agents/analyzer.py

@@ -0,0 +1,78 @@
+import json
+from typing import Any, Dict, Tuple
+from loader.models import SummaryMetrics
+
+
+def _metric_value(metrics: Dict[str, Any], metric_name: str, field: str):
+    metric = metrics.get(metric_name, {})
+    if not isinstance(metric, dict):
+        return None
+    return metric.get(field)
+
+
+def _checks_pass_rate(metrics: Dict[str, Any]) -> float | None:
+    checks = metrics.get("checks", {})
+    if not isinstance(checks, dict):
+        return None
+
+    # Some k6 outputs provide "value"
+    if "value" in checks:
+        return checks.get("value")
+
+    passes = checks.get("passes")
+    fails = checks.get("fails")
+
+    if isinstance(passes, (int, float)) and isinstance(fails, (int, float)):
+        total = passes + fails
+        if total > 0:
+            return passes / total
+
+    return None
+
+
+def _http_req_failed_rate(metrics: Dict[str, Any]) -> float | None:
+    failed = metrics.get("http_req_failed", {})
+    if not isinstance(failed, dict):
+        return None
+
+    # Best source in k6 summary output
+    value = failed.get("value")
+    if isinstance(value, (int, float)):
+        return float(value)
+
+    # Some formats may expose "rate"
+    rate = failed.get("rate")
+    if isinstance(rate, (int, float)):
+        return float(rate)
+
+    # Fallback: in k6 this metric is a Rate metric, and "passes"
+    # usually means failed requests, while "fails" means non-failed requests.
+    passes = failed.get("passes")
+    fails = failed.get("fails")
+
+    if isinstance(passes, (int, float)) and isinstance(fails, (int, float)):
+        total = passes + fails
+        if total > 0:
+            return float(passes) / float(total)
+
+    return None
+
+
+def parse_k6_summary(summary_path: str) -> Tuple[SummaryMetrics, Dict[str, Any]]:
+    with open(summary_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    metrics = data.get("metrics", {})
+
+    parsed = SummaryMetrics(
+        total_requests=_metric_value(metrics, "http_reqs", "count"),
+        avg_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "avg"),
+        med_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "med"),
+        p90_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "p(90)"),
+        p95_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "p(95)"),
+        max_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "max"),
+        http_req_failed_rate=_http_req_failed_rate(metrics),
+        checks_pass_rate=_checks_pass_rate(metrics),
+    )
+
+    return parsed, data

loaderup-0.1.0/agents/generator.py

@@ -0,0 +1,110 @@
+import json
+from pathlib import Path
+from typing import List
+from loader.models import LoadTarget
+from loader.settings import ARTIFACTS_DIR
+
+
+def _js_string(value: str) -> str:
+    return json.dumps(value)
+
+
+def build_k6_script(
+    base_url: str,
+    targets: List[LoadTarget],
+    vus: int,
+    duration_seconds: int,
+) -> str:
+    target_entries = []
+
+    for target in targets:
+        entry = {
+            "name": target.name,
+            "method": target.method,
+            "path": target.path,
+            "headers": target.headers,
+            "payload": target.payload_example,
+            "expected_status": target.expected_status,
+            "weight": target.weight,
+        }
+        target_entries.append(entry)
+
+    targets_json = json.dumps(target_entries, indent=2)
+
+    script = f"""import http from 'k6/http';
+import {{ check, sleep }} from 'k6';
+
+export const options = {{
+  vus: {vus},
+  duration: '{duration_seconds}s',
+}};
+
+const BASE_URL = {_js_string(base_url.rstrip("/"))};
+const TARGETS = {targets_json};
+
+function weightedPick(targets) {{
+  const expanded = [];
+  for (const t of targets) {{
+    const weight = Math.max(1, Math.round(t.weight || 1));
+    for (let i = 0; i < weight; i++) {{
+      expanded.push(t);
+    }}
+  }}
+  const idx = Math.floor(Math.random() * expanded.length);
+  return expanded[idx];
+}}
+
+export default function () {{
+  const target = weightedPick(TARGETS);
+  const url = `${{BASE_URL}}${{target.path}}`;
+  const method = String(target.method || 'GET').toUpperCase();
+  const payloadMethods = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+  let res;
+
+  if (method === 'GET') {{
+    res = http.get(url, {{
+      headers: target.headers || {{}},
+      tags: {{
+        target_name: target.name,
+        method,
+        path: target.path,
+      }},
+    }});
+  }} else if (payloadMethods.has(method)) {{
+    const payload = target.payload ? JSON.stringify(target.payload) : null;
+    const headers = {{ ...(target.headers || {{}}) }};
+    if (payload !== null && !headers['Content-Type'] && !headers['content-type']) {{
+      headers['Content-Type'] = 'application/json';
+    }}
+
+    res = http.request(method, url, payload, {{
+      headers,
+      tags: {{
+        target_name: target.name,
+        method,
+        path: target.path,
+      }},
+    }});
+  }} else {{
+    throw new Error(`Unsupported method: ${{method}}`);
+  }}
+
+  check(res, {{
+    [`status is expected`]: (r) => r.status === target.expected_status,
+    [`status is < 500`]: (r) => r.status < 500,
+  }});
+
+  sleep(1);
+}}
+"""
+    return script
+
+
+def save_k6_script(job_id: str, script_text: str) -> str:
+    out_dir = ARTIFACTS_DIR / job_id
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    script_path = out_dir / "script.js"
+    script_path.write_text(script_text, encoding="utf-8")
+    return str(script_path)

loaderup-0.1.0/agents/runner.py

@@ -0,0 +1,40 @@
+import asyncio
+from loader.settings import ARTIFACTS_DIR
+
+
+async def run_k6(script_path: str, job_id: str) -> dict:
+    out_dir = ARTIFACTS_DIR / job_id
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    summary_path = out_dir / "summary.json"
+
+    process = await asyncio.create_subprocess_exec(
+        "k6",
+        "run",
+        "--summary-export",
+        str(summary_path),
+        script_path,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    stdout, stderr = await process.communicate()
+
+    stdout_text = stdout.decode(errors="replace")
+    stderr_text = stderr.decode(errors="replace")
+
+    if process.returncode != 0:
+        raise RuntimeError(
+            "k6 execution failed\n"
+            f"stdout:\n{stdout_text}\n"
+            f"stderr:\n{stderr_text}"
+        )
+
+    if not summary_path.exists():
+        raise RuntimeError("k6 completed but summary.json was not created")
+
+    return {
+        "summary_path": str(summary_path),
+        "stdout": stdout_text,
+        "stderr": stderr_text,
+    }

loaderup-0.1.0/loader/demo_registry_target.py

@@ -0,0 +1,25 @@
+# demo_registry_targets.py
+
+from loaderup import load_target
+
+
+@load_target(
+    name="home",
+    method="GET",
+    path="/",
+    expected_status=200,
+    tags=["public", "homepage"],
+)
+def home():
+    pass
+
+@load_target(
+    name="home",
+    method="POST",
+    path="/gg",
+    expected_status=200,
+    tags=["public", "homepage"],
+)
+def gg():
+    pass
+

loaderup-0.1.0/loader/history.py

@@ -0,0 +1,36 @@
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+from loader.models import Job
+
+HISTORY_FILE = (
+    Path(__file__).resolve().parents[1] / "artifacts" / "history" / "runs.jsonl"
+)
+
+
+def persist_job(job: Job) -> None:
+    HISTORY_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with HISTORY_FILE.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(job.model_dump(), ensure_ascii=True) + "\n")
+
+
+def list_runs(limit: int = 20) -> List[Dict[str, Any]]:
+    if not HISTORY_FILE.exists():
+        return []
+
+    rows: List[Dict[str, Any]] = []
+    with HISTORY_FILE.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+    if limit < 1:
+        return []
+
+    return list(reversed(rows[-limit:]))

loaderup-0.1.0/loader/main.py

@@ -0,0 +1,150 @@
+import asyncio
+import json
+import os
+from pathlib import Path
+import shutil
+import uuid
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from loader.models import Job, RunTargetsRequest, RunConfig
+from loader.history import list_runs
+from loaderup.importer import import_target_modules
+from loaderup.models import RunRegistryRequest
+from loader.store import create_job, get_job, get_queue, list_jobs
+from loader.pipeline import run_targets_pipeline
+from loader import demo_registry_target
+
+app = FastAPI(title="LoadAgent")
+WEB_DIR = Path(__file__).resolve().parent / "web"
+
+app.mount("/assets", StaticFiles(directory=str(WEB_DIR / "assets")), name="assets")
+
+
+@app.get("/", include_in_schema=False)
+async def dashboard():
+    return FileResponse(str(WEB_DIR / "index.html"))
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "k6_installed": shutil.which("k6") is not None}
+
+
+@app.on_event("startup")
+async def load_cli_target_modules():
+    modules_csv = os.getenv("LOADERUP_TARGET_MODULES", "").strip()
+    if not modules_csv:
+        return
+
+    modules = [name.strip() for name in modules_csv.split(",") if name.strip()]
+    if modules:
+        import_target_modules(modules)
+
+
+@app.post("/run/targets")
+async def run_targets(payload: RunTargetsRequest):
+    job_id = str(uuid.uuid4())
+
+    job = Job(job_id=job_id)
+    create_job(job)
+
+    config = RunConfig(
+        base_url=payload.base_url.rstrip("/"),
+        vus=payload.vus,
+        duration_seconds=payload.duration_seconds,
+        targets=payload.targets,
+    )
+
+    asyncio.create_task(run_targets_pipeline(job_id, config))
+
+    return {
+        "job_id": job_id,
+        "status": job.status,
+        "stream_url": f"/run/{job_id}/stream",
+        "result_url": f"/run/{job_id}/result",
+    }
+
+
+@app.get("/run/{job_id}/result")
+async def get_result(job_id: str):
+    job = get_job(job_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return job
+
+
+@app.get("/run/{job_id}/stream")
+async def stream_run(job_id: str):
+    q = get_queue(job_id)
+    if not q:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    async def event_generator():
+        while True:
+            item = await q.get()
+            if item is None:
+                break
+            yield f"data: {json.dumps(item)}\n\n"
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+@app.post("/run/registry")
+async def run_registry(payload: RunRegistryRequest):
+    from loaderup import collect_load_targets
+
+    registry_targets = collect_load_targets()
+    if not registry_targets:
+        raise HTTPException(status_code=400, detail="No registered targets found")
+
+    job_id = str(uuid.uuid4())
+
+    job = Job(job_id=job_id)
+    create_job(job)
+
+    config = RunConfig(
+        base_url=payload.base_url.rstrip("/"),
+        vus=payload.vus,
+        duration_seconds=payload.duration_seconds,
+        targets=registry_targets,
+    )
+
+    asyncio.create_task(run_targets_pipeline(job_id, config))
+
+    return {
+        "job_id": job_id,
+        "status": job.status,
+        "registered_targets": len(registry_targets),
+        "stream_url": f"/run/{job_id}/stream",
+        "result_url": f"/run/{job_id}/result",
+    }
+
+
+@app.get("/registry/targets")
+async def get_registry_targets():
+    from loaderup import collect_load_targets
+
+    targets = collect_load_targets()
+    return {
+        "count": len(targets),
+        "targets": [target.model_dump() for target in targets],
+    }
+
+
+@app.get("/runs/active")
+async def get_active_runs(limit: int = 20):
+    jobs = list_jobs(limit=limit)
+    return {"runs": [job.model_dump() for job in jobs]}
+
+
+@app.get("/runs/history")
+async def get_run_history(limit: int = 20):
+    return {"runs": list_runs(limit=limit)}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

loaderup-0.1.0/loader/models.py

@@ -0,0 +1,93 @@
+from enum import Enum
+from typing import Optional, List, Dict, Any, Literal
+from pydantic import BaseModel, Field, model_validator
+
+
+class JobStatus(str, Enum):
+    pending = "pending"
+    generating = "generating"
+    running = "running"
+    analyzing = "analyzing"
+    done = "done"
+    failed = "failed"
+
+
+class LoadTarget(BaseModel):
+    name: str
+    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+    path: str
+    headers: Dict[str, str] = Field(default_factory=dict)
+    payload_example: Optional[Dict[str, Any]] = None
+    weight: float = 1.0
+    tags: List[str] = Field(default_factory=list)
+    expected_status: int = 200
+
+    @model_validator(mode="after")
+    def validate_target(self):
+        if not self.path.startswith("/"):
+            raise ValueError("path must start with '/'")
+        return self
+
+
+class RunTargetsRequest(BaseModel):
+    base_url: str
+    targets: List[LoadTarget]
+    vus: int = 10
+    duration_seconds: int = 30
+
+    @model_validator(mode="after")
+    def validate_request(self):
+        if not self.base_url.startswith(("http://", "https://")):
+            raise ValueError("base_url must start with http:// or https://")
+        if not self.targets:
+            raise ValueError("targets cannot be empty")
+        if self.vus < 1:
+            raise ValueError("vus must be >= 1")
+        if self.duration_seconds < 1:
+            raise ValueError("duration_seconds must be >= 1")
+        return self
+
+
+class RunConfig(BaseModel):
+    base_url: str
+    vus: int
+    duration_seconds: int
+    targets: List[LoadTarget]
+
+
+class SummaryMetrics(BaseModel):
+    total_requests: Optional[int] = None
+    avg_http_req_duration_ms: Optional[float] = None
+    med_http_req_duration_ms: Optional[float] = None
+    p90_http_req_duration_ms: Optional[float] = None
+    p95_http_req_duration_ms: Optional[float] = None
+    max_http_req_duration_ms: Optional[float] = None
+    http_req_failed_rate: Optional[float] = None
+    checks_pass_rate: Optional[float] = None
+
+
+class TargetMetric(BaseModel):
+    name: str
+    method: str
+    path: str
+    expected_status: int
+    note: Optional[str] = None
+
+
+class JobResult(BaseModel):
+    config: Optional[RunConfig] = None
+    k6_script_path: Optional[str] = None
+    k6_summary_path: Optional[str] = None
+    k6_stdout: Optional[str] = None
+    k6_stderr: Optional[str] = None
+    metrics: Optional[SummaryMetrics] = None
+    target_metrics: List[TargetMetric] = Field(default_factory=list)
+    raw_summary: Optional[Dict[str, Any]] = None
+
+
+class Job(BaseModel):
+    job_id: str
+    status: JobStatus = JobStatus.pending
+    progress: List[str] = Field(default_factory=list)
+    error: Optional[str] = None
+    result: JobResult = Field(default_factory=JobResult)