satellite-provider/_docs/02_tasks/done/AZ-1133_perf_gate_preflight.md

Perf gate preflight — health-check before PT-01

Task: AZ-1133_perf_gate_preflight Name: Perf gate preflight — health-check before PT-01 Description: Add a preflight reachability check to scripts/run-performance-tests.sh so Step 15 fails fast with actionable instructions when the perf compose stack is not running. Complexity: 1 point Dependencies: AZ-492 (perf harness), AZ-1123 (perf compose documentation) Component: test tooling — scripts/run-performance-tests.sh + deployment/test env docs Tracker: AZ-1133 Epic: None

Problem

Cycle 13 Step 15 first run failed at PT-01 because API_URL (https://localhost:18980) was unreachable — the perf overlay (docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d) had not been started. The script proceeded through JWT mint/bootstrap and only surfaced the failure as a cryptic PT-01 HTTP error / non-zero exit, wasting operator time. This carry-over appears in cycle 13, 14, and 15 retros.

Outcome

• run-performance-tests.sh verifies API reachability after JWT mint and before PT-01
• Unreachable API exits with exit code 7 and prints the canonical compose-up command
• Reachable API proceeds to PT-01 unchanged
• environment.md and containerization.md document the preflight behavior

Scope

Included

• Add preflight_api_reachable (or equivalent) helper in scripts/run-performance-tests.sh:
  • Probe $API_URL with the same CURL_OPTS / TLS trust as PT-01 (e.g. curl --connect-timeout 5 to a lightweight endpoint — authenticated GET /api/satellite/tiles/latlon with valid coords is acceptable since JWT is already minted)
  • On connection failure / empty response → print error + docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build and exit 7
• Update _docs/02_document/tests/environment.md § Performance tests — mention script preflight + exit 7
• Update _docs/02_document/deployment/containerization.md § Compose overlays — cross-link preflight

Excluded

• Auto-starting the compose stack from the script (operator still starts it explicitly)
• Changing PT-01..PT-10 thresholds or scenario logic
• CI integration (perf remains local-only per ci_cd_pipeline.md)

Acceptance Criteria

AC-1: Preflight runs before PT-01 Given run-performance-tests.sh with valid JWT_SECRET / iss / aud When the script reaches the performance scenarios section Then a reachability probe executes after JWT mint and before the PT-01 banner.

AC-2: Unreachable API fails fast with instructions Given the perf compose stack is not running (API_URL connection refused or timeout) When run-performance-tests.sh is executed Then the script exits with code 7, stderr/stdout includes the perf overlay docker compose … up command, and PT-01 does not run.

AC-3: Reachable API proceeds unchanged Given the perf stack is up and API_URL accepts authenticated requests When run-performance-tests.sh is executed Then preflight passes silently (or with a single "API reachable" line) and PT-01..PT-10 behave as before.

AC-4: Documentation reflects preflight Given the post-task docs When environment.md and containerization.md are read Then both mention the script preflight and exit code 7 when the stack is down.

Non-Functional Requirements

Reliability

• Preflight must use the same TLS trust path as the rest of the script (CURL_OPTS / certs/api.crt).

Compatibility

• No change to default env vars (API_URL, PERF_REPEAT_COUNT, etc.).

Unit Tests

AC Ref	What to Test	Required Outcome
—	Shell-only change; no new C# unit tests required	N/A

Blackbox Tests

AC Ref	Initial Data/Conditions	What to Test	Expected Behavior	NFR References
AC-2	Perf stack stopped; JWT env set	./scripts/run-performance-tests.sh	Exit 7 + compose instruction; no PT-01 timing output	Reliability
AC-3	Perf stack running	./scripts/run-performance-tests.sh (smoke: PERF_REPEAT_COUNT=1 if needed)	Exit 0 or threshold fail only after PT-01 starts	Compatibility

Constraints

• Preserve set -euo pipefail globally — preflight must not mask real curl failures in scenario bodies.
• Exit code 7 is reserved for "stack not up" to match cycle 13 perf report convention.

Risks & Mitigation

Risk 1: False negative when API returns 401/403

• Risk: Preflight treats auth errors as "reachable" vs connection errors as "down" — must distinguish connection/TLS failure from HTTP 4xx.
• Mitigation: Use curl exit code / --connect-timeout; treat HTTP responses (even 401) as reachable.

Risk 2: Preflight adds latency to every perf run

• Risk: Extra round-trip before 10 scenarios.
• Mitigation: Single lightweight GET; acceptable vs minutes-long perf suite.