feat(06-03): implement Locust load test — self-bootstrap strategy, 4 tasks, SLA listener (D-04/D-05/D-06)

backend/load_tests/README.md

@@ -0,0 +1,91 @@
+# DocuVault Load Tests
+
+Phase 6 load test suite targeting the D-04/D-05/D-06 SLA requirements.
+
+## Prerequisites
+
+1. Install load-test dependencies (host or dedicated venv — **not** the production container):
+
+   ```bash
+   pip install -r backend/requirements-dev.txt
+   ```
+
+2. Start the full stack:
+
+   ```bash
+   docker compose up
+   ```
+
+   Backend, PostgreSQL, and MinIO must all be healthy before running.
+
+## Running the load test
+
+```bash
+locust --headless \
+       --users 50 \
+       --spawn-rate 10 \
+       --run-time 5m \
+       --host http://localhost:8000 \
+       --csv backend/load_tests/results \
+       -f backend/load_tests/locustfile.py
+```
+
+Exit code `0` = SLA targets met. Exit code `1` = at least one threshold breached.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOAD_TEST_EMAIL` | `loadtest@example.com` | Email used to register/login the load-test user |
+| `LOAD_TEST_PASSWORD` | `Loadtest123!@#` | Password for the load-test account (meets AUTH-01 strength rules) |
+
+Override before running:
+
+```bash
+LOAD_TEST_EMAIL=mytest@staging.example.com \
+LOAD_TEST_PASSWORD='MyS3cure!Pass' \
+locust --headless ...
+```
+
+## SLA thresholds (D-06)
+
+| Metric | Threshold | On breach |
+|--------|-----------|-----------|
+| p95 response time | < 200 ms | exit code 1 |
+| p99 response time | < 500 ms | exit code 1 |
+| Error ratio | ≤ 1% | exit code 1 |
+
+## Task weights (D-05 realistic session)
+
+| Task | Weight | Endpoint |
+|------|--------|----------|
+| List documents | 5 | `GET /api/documents/` |
+| Get document | 3 | `GET /api/documents/{id}` |
+| Upload document | 2 | `POST /api/documents/upload` (direct multipart, `target_backend=minio`) |
+| Refresh token | 1 | `POST /api/auth/refresh` |
+
+## Credential strategy
+
+`on_start()` uses **self-bootstrapping** (Option A): it calls `POST /api/auth/register`
+first (idempotent — 409 is silently ignored if the user already exists), then logs in.
+No manual seeding step required.
+
+## Cleanup
+
+Remove the load-test user from the database when no longer needed:
+
+```bash
+docker compose exec postgres psql -U docuvault -c \
+    "DELETE FROM users WHERE email='loadtest@example.com';"
+```
+
+## Results
+
+CSV files are written to `backend/load_tests/results_*.csv` by the `--csv` flag.
+These files are gitignored. To view a summary after a headless run, add `--html backend/load_tests/report.html`.
+
+## Notes
+
+- Load tests run **outside** the production container — install on the host or a test venv.
+- Do **not** run against a production URL without an explicit `--host` override and stakeholder sign-off.
+- The synthetic upload file (`_FAKE_PDF`) is a minimal valid PDF — it will be stored in MinIO during the run and cleared when the load-test user is deleted.

backend/load_tests/locustfile.py

@@ -1,72 +1,128 @@
 """Locust load test for DocuVault — D-04, D-05, D-06.
 
-Run:
+Strategy: self-bootstrapping (Option A) — on_start registers the load-test
+user (409 ignored if already exists), then logs in to get an access token.
+
+Run (headless, matches Phase 6 SLA gate):
     locust --headless --users 50 --spawn-rate 10 --run-time 5m \\
            --host http://localhost:8000 \\
            --csv backend/load_tests/results \\
            -f backend/load_tests/locustfile.py
 
-Prerequisites: a user with LOAD_TEST_EMAIL/LOAD_TEST_PASSWORD must exist in the
+Prerequisites:
-DB, or on_start will register one automatically (idempotent — 409 is ignored).
+    pip install -r backend/requirements-dev.txt
+    docker compose up  # backend, postgres, minio must be running
 
-Full implementation is in plan 06-03. This skeleton defines the class shape and
+Exit codes (enforced by check_sla listener):
-SLA listener so downstream CI tooling can import the file without errors.
+    0 — all SLA thresholds met
+    1 — p95 > 200 ms, OR p99 > 500 ms, OR fail_ratio > 1%
+
+Cleanup the load-test user:
+    docker compose exec postgres psql -U docuvault -c \\
+        "DELETE FROM users WHERE email='loadtest@example.com';"
 """
 import os
+from io import BytesIO
 
 from locust import HttpUser, between, events, task
 
 TEST_EMAIL = os.environ.get("LOAD_TEST_EMAIL", "loadtest@example.com")
 TEST_PASSWORD = os.environ.get("LOAD_TEST_PASSWORD", "Loadtest123!@#")
+TEST_HANDLE = "loadtestuser"
+
+# Minimal synthetic PDF — valid enough for the upload parser
+_FAKE_PDF = b"%PDF-1.4\n1 0 obj<</Type/Catalog>>endobj\nxref\n0 2\ntrailer<</Size 2>>\n%%EOF"
 
 
 class DocuVaultUser(HttpUser):
-    """Simulated DocuVault end-user.
+    """Simulated DocuVault end-user exercising all authenticated endpoints.
 
-    Scenarios (weighted tasks):
+    Task weights mirror a realistic read-heavy session per D-05:
-      - list_documents  (weight 5) — GET /api/documents/
+      5 — list documents  (most common action)
-      - upload_document (weight 2) — POST /api/documents/upload-url flow
+      3 — get single document
-      - refresh_token   (weight 1) — POST /api/auth/refresh
+      2 — upload a document
+      1 — refresh access token
     """
 
     wait_time = between(0.5, 2.0)
     access_token: str = ""
 
     def on_start(self) -> None:
-        """Authenticate before running tasks.
+        self.client.post(
-
+            "/api/auth/register",
-        Registers the load-test user if it does not exist (409 is silently
+            json={"handle": TEST_HANDLE, "email": TEST_EMAIL, "password": TEST_PASSWORD},
-        ignored), then performs a login to obtain an access token.
+        )
-        """
+        resp = self.client.post(
-        raise NotImplementedError("implementation in 06-03")
+            "/api/auth/login",
+            json={"email": TEST_EMAIL, "password": TEST_PASSWORD},
+            name="POST /api/auth/login",
+        )
+        if resp.status_code == 200:
+            self.access_token = resp.json().get("access_token", "")
+        else:
+            self.environment.runner.quit()
 
     def _auth_headers(self) -> dict:
-        """Return Authorization header dict for authenticated requests."""
+        return {"Authorization": f"Bearer {self.access_token}"}
-        raise NotImplementedError("implementation in 06-03")
 
     @task(5)
     def list_documents(self) -> None:
-        """GET /api/documents/ — highest-frequency task."""
+        self.client.get("/api/documents/", headers=self._auth_headers(), name="GET /api/documents/")
-        raise NotImplementedError("implementation in 06-03")
+
+    @task(3)
+    def get_document(self) -> None:
+        resp = self.client.get(
+            "/api/documents/",
+            headers=self._auth_headers(),
+            name="GET /api/documents/ (for get_document)",
+        )
+        if resp.status_code == 200:
+            docs = resp.json()
+            if docs:
+                doc_id = docs[0]["id"]
+                self.client.get(
+                    f"/api/documents/{doc_id}",
+                    headers=self._auth_headers(),
+                    name="GET /api/documents/{id}",
+                )
 
     @task(2)
     def upload_document(self) -> None:
-        """Two-step presigned upload: POST /upload-url → PUT MinIO → POST /{id}/confirm."""
+        # Direct single-step upload to /api/documents/upload (confirmed against documents.py:
-        raise NotImplementedError("implementation in 06-03")
+        # accepts UploadFile `file` + Form `target_backend` — simpler than the presigned flow).
+        self.client.post(
+            "/api/documents/upload",
+            headers=self._auth_headers(),
+            files={"file": ("load_test.pdf", BytesIO(_FAKE_PDF), "application/pdf")},
+            data={"target_backend": "minio"},
+            name="POST /api/documents/upload",
+        )
 
     @task(1)
     def refresh_token(self) -> None:
-        """POST /api/auth/refresh — rotates the httpOnly refresh cookie."""
+        self.client.post(
-        raise NotImplementedError("implementation in 06-03")
+            "/api/auth/refresh",
+            headers=self._auth_headers(),
+            name="POST /api/auth/refresh",
+        )
 
 
 @events.quitting.add_listener
 def check_sla(environment, **kwargs) -> None:
-    """Fail the Locust run if SLA thresholds are breached.
+    """Gate the Locust exit code on D-06 SLA thresholds."""
+    stats = environment.runner.stats.total
+    p95 = stats.get_response_time_percentile(0.95)
+    p99 = stats.get_response_time_percentile(0.99)
+    fail_ratio = stats.fail_ratio
 
-    Thresholds (from D-06):
+    if fail_ratio > 0.01:
-      - p95 response time > 200 ms → exit code 1
+        print(f"SLA FAIL: fail_ratio={fail_ratio:.2%} > 1%")
-      - p99 response time > 500 ms → exit code 1
+        environment.process_exit_code = 1
-      - error ratio > 1%           → exit code 1
+    elif p95 > 200:
-    """
+        print(f"SLA FAIL: p95={p95:.0f}ms > 200ms")
-    raise NotImplementedError("implementation in 06-03")
+        environment.process_exit_code = 1
+    elif p99 > 500:
+        print(f"SLA FAIL: p99={p99:.0f}ms > 500ms")
+        environment.process_exit_code = 1
+    else:
+        print(f"SLA PASS: p95={p95:.0f}ms p99={p99:.0f}ms fail_ratio={fail_ratio:.2%}")