---
phase: 06-performance-production-hardening
plan: "01"
subsystem: observability/rate-limiting/load-testing
tags: [wave-0, xfail-scaffold, structured-logging, rate-limiting, locust, nyquist]
dependency_graph:
  requires: []
  provides:
    - "backend/tests/test_logging.py — 5 xfail stubs for D-01/D-02"
    - "backend/tests/test_rate_limiting.py — 8 xfail stubs for D-11/D-12 + A1 gate"
    - "backend/load_tests/__init__.py — pytest exclusion marker"
    - "backend/load_tests/locustfile.py — Locust HttpUser skeleton"
  affects: []
tech_stack:
  added: []
  patterns:
    - "xfail(strict=False) Wave 0 scaffold — all stubs single-line body pytest.xfail('not implemented yet')"
    - "Locust HttpUser skeleton with NotImplementedError bodies and env-var credential pickup"
    - "Empty __init__.py package marker excludes load_tests from pytest discovery"
key_files:
  created:
    - backend/tests/test_logging.py
    - backend/tests/test_rate_limiting.py
    - backend/load_tests/__init__.py
    - backend/load_tests/locustfile.py
  modified: []
decisions:
  - "structlog 25.5.0 — approved by user as legitimate (hynek/structlog, CPython core contributor author). Will be added to backend/requirements.txt in plan 06-02."
  - "locust 2.34.0 — approved by user as legitimate (locustio/locust, 10+ year history, multi-million monthly downloads). Will be added to backend/requirements-dev.txt in plan 06-03 (dev-only, NOT in requirements.txt)."
  - "load_tests excluded from pytest via testpaths=tests in pytest.ini — no conftest exclusion needed; locustfile.py filename does not match test_*.py pattern"
metrics:
  duration: "~60s"
  completed: "2026-06-03"
  tasks_completed: 5
  files_created: 4
  files_modified: 0
---

# Phase 06 Plan 01: Wave 0 Nyquist Scaffold Summary

Wave 0 xfail test scaffold for Phase 6 structured logging (D-01/D-02), trusted-proxy rate limiting (D-11), per-account rate limiting (D-12), and Locust load-test skeleton (D-04/D-05/D-06).

## What Was Built

**backend/tests/test_logging.py** — 5 xfail stubs for D-01/D-02:
1. `test_setup_logging_emits_json_when_LOG_JSON_true` — JSON renderer through ProcessorFormatter
2. `test_correlation_id_middleware_binds_contextvar` — CorrelationIDMiddleware binds to structlog contextvars
3. `test_correlation_id_response_header_present` — X-Correlation-ID header on every response
4. `test_contextvars_cleared_between_requests` — Pitfall 2 guard: no context bleed between requests
5. `test_uvicorn_access_log_suppressed` — uvicorn.access propagate=False

**backend/tests/test_rate_limiting.py** — 8 xfail stubs for D-11/D-12 + A1 verification:
1. `test_get_client_ip_untrusted_returns_direct_peer` — untrusted peer ignores XFF
2. `test_get_client_ip_trusted_proxy_reads_xff_leftmost` — trusted peer reads leftmost XFF
3. `test_get_client_ip_trusted_proxy_no_xff_falls_back` — trusted peer with no XFF falls back to peer IP
4. `test_get_client_ip_invalid_peer_returns_none_or_string` — None client returns None safely
5. `test_account_limiter_key_uses_user_id` — key_func returns str(user.id)
6. `test_account_limiter_key_falls_back_to_ip_when_no_user` — no user on request.state → IP fallback, no crash
7. `test_account_limiter_key_ordering_assumption` — **A1 gate**: verifies slowapi reads request.state.current_user correctly before counting
8. `test_authenticated_endpoint_429_after_100_per_minute` — full integration 429 check

**backend/load_tests/__init__.py** — empty package marker (56 bytes)

**backend/load_tests/locustfile.py** — DocuVaultUser skeleton:
- `on_start`, `_auth_headers`, `list_documents`, `upload_document`, `refresh_token` stubs (all raise NotImplementedError)
- `check_sla` SLA listener registered via `@events.quitting.add_listener`
- Credentials from `LOAD_TEST_EMAIL`/`LOAD_TEST_PASSWORD` env vars only
- Zero application imports

## Test Suite Results

| Metric | Baseline | After Plan 06-01 | Delta |
|--------|----------|------------------|-------|
| Passed | 344 | 344 | 0 |
| Failed | 1 (pre-existing) | 1 (pre-existing) | 0 |
| Skipped | 5 | 5 | 0 |
| XFailed | 7 | 20 | +13 |

- 5 new XFAIL in `test_logging.py`
- 8 new XFAIL in `test_rate_limiting.py`
- Zero regressions
- Pre-existing failure: `test_extractor.py::test_extract_docx` (ModuleNotFoundError — carried over from 6.2)

## Package Legitimacy Decision (verbatim from checkpoint)

**structlog 25.5.0** — APPROVED
- PyPI: https://pypi.org/project/structlog/
- Author: Hynek Schlawack (CPython core contributor)
- Homepage: https://github.com/hynek/structlog
- Action: add to `backend/requirements.txt` in plan 06-02

**locust 2.34.0** — APPROVED (dev-only)
- PyPI: https://pypi.org/project/locust/
- Project: locustio/locust, 10+ years of releases, multi-million monthly downloads
- Action: add to `backend/requirements-dev.txt` in plan 06-03 (NOT in requirements.txt)

## Commits

| Task | Commit | Description |
|------|--------|-------------|
| 2 | e1f8874 | test(06-01): add 5 xfail stubs for structured logging (D-01/D-02) |
| 3 | 56d9da7 | test(06-01): add 8 xfail stubs for rate limiting (D-11/D-12 + A1) |
| 4 | 594eb46 | feat(06-01): add backend/load_tests/ package skeleton with Locust stub (D-04/D-05/D-06) |
| 5 | (verification only — no files changed) | Full suite regression check |

## Deviations from Plan

None — plan executed exactly as written.

## Notes for Downstream Plans

- **06-02 (structured logging):** Must turn the 5 `test_logging.py` stubs green. Install `structlog` in requirements.txt.
- **06-03 (Locust implementation):** Must fill in `DocuVaultUser` method bodies and `check_sla`. Install `locust` in requirements-dev.txt.
- **06-04 (rate limiting):** Must turn the 8 `test_rate_limiting.py` stubs green. The A1 verification test (`test_account_limiter_key_ordering_assumption`) must be promoted to PASS before applying `@account_limiter.limit("100/minute")` to all document/cloud endpoints — this test is the explicit gate that turns assumption A1 into a fact.
- **pytest discovery:** `testpaths = tests` in `pytest.ini` already excludes `backend/load_tests/`; no additional configuration needed.

## Self-Check: PASSED

All files created and all commits present:
- FOUND: backend/tests/test_logging.py
- FOUND: backend/tests/test_rate_limiting.py
- FOUND: backend/load_tests/__init__.py
- FOUND: backend/load_tests/locustfile.py
- FOUND: 06-01-SUMMARY.md
- FOUND: commit e1f8874 (test_logging.py)
- FOUND: commit 56d9da7 (test_rate_limiting.py)
- FOUND: commit 594eb46 (load_tests/ skeleton)