# 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).