Initial commit of Descrybe v2 without local scratch artifacts.

Drop one-shot tmp/axe scripts and agent i18n scratch so the Gitea tree is deployable.
2026-08-09 22:47:43 +02:00
commit 8580c996c3
1285 changed files with 325780 additions and 0 deletions
@@ -0,0 +1,69 @@
+# API load / smoke harness
+
+Minimal stdlib Go harness for three critical read paths. Prefer this when **k6 / hey / vegeta** are not installed (none are required or vendored in this repo).
+
+## Endpoints
+
+| Name | Method | Path | Auth |
+|------|--------|------|------|
+| healthz | GET | `/healthz` | none |
+| feeds | GET | `/api/v1/feeds?limit=10&offset=0` | Bearer API key |
+| products | GET | `/api/v1/products?limit=10&offset=0` | Bearer API key |
+
+Default base URL matches `HTTP_ADDR` (`:28471` → `http://127.0.0.1:28471`). Demo key: see `docs/demo-user.md` (`dk_demo_local_descrybe_test_key_v1`).
+
+`RateLimitV1Process` applies only to heavy **POST** mutations (process / feed sync / export generate), not these GETs. DB and laptop CPU are still the real limits.
+
+## RPS assumptions
+
+| Profile | Flags | Intent | Aggregate RPS |
+|---------|-------|--------|---------------|
+| **smoke** (default) | `-c 2 -d 5s -rate 6` | Availability + latency sample; safe on local Postgres | **~6 RPS** capped (not “as fast as possible”) |
+| **load** (manual) | e.g. `-mode load -c 8 -d 30s -rate 40` | Staging / dedicated API only | Tens of RPS; watch p95 and Postgres |
+| **unlimited** | `-mode load -rate 0` | Intentional soak only | Uncapped — **do not** use against shared laptop DB |
+| **capacity** | external tool | Real soak / SLO | k6/hey/vegeta on staging |
+
+ASSUMPTION: smoke is a correctness/latency probe, not a capacity claim. Concurrency alone does not cap RPS — **`-rate` does**. Smoke refuses `-rate 0`.
+
+## Smoke (local)
+
+API must already be running (`scripts/run-api.ps1` or equivalent).
+
+```powershell
+cd f:\laragon\www\_MY\descrybe-v2\scripts\api-load-smoke
+go run .
+```
+
+Overrides:
+
+```powershell
+$env:API_BASE = "http://127.0.0.1:28471"
+$env:API_KEY = "dk_demo_local_descrybe_test_key_v1"
+cd f:\laragon\www\_MY\descrybe-v2\scripts\api-load-smoke
+go run . -c 2 -d 5s -rate 6 -mode smoke
+```
+
+Exit code `1` if any non-cancelled request fails (`-fail-on-error=false` to only print stats).
+
+## Larger tests
+
+Still this harness (gentle step-up):
+
+```powershell
+cd f:\laragon\www\_MY\descrybe-v2\scripts\api-load-smoke
+go run . -mode load -c 8 -d 30s -rate 40 -base http://127.0.0.1:28471
+```
+
+Or external tools (install separately; point at **staging**):
+
+```bash
+# hey — fixed request count
+hey -n 200 -c 8 -H "Authorization: Bearer $API_KEY" "$BASE/api/v1/products?limit=10"
+
+# vegeta — rate explicitly
+echo "GET $BASE/healthz" | vegeta attack -duration=30s -rate=20 | vegeta report
+
+# k6 — script your own scenarios; keep rate modest on shared DBs
+```
+
+Related: `docs/api-surface-smoke.md` (functional matrix), `docs/perf-notes.md` (list-path notes), `scripts/v1-process-smoke` (legacy items create/process + poll).