egress-proxies-operator/docs/plans/2026-08-11-2220-demo-scripts.md

Plan: Demo script — egress IP check through each healthy proxy

Created: 2026-08-11 22:20

Context

First of a planned series of demo scripts under docs/demo/. This one showcases the discovery API end to end without leases: list proxies from $BASE_URL/v1/proxies, and for each healthy one, call an IP-echo site through it (curl -x) to show the egress IP that proxy provides — clearly labeling which proxy each request goes through. The user explicitly asked to start by switching to a new branch. The script will be iterated on: write it but do not commit it — the user wants to add things to it before anything is committed.

Steps

Step 0 — Branch

Create feat/demo-scripts off main. Commit only the plan copy (docs/plans/<timestamp>-demo-scripts.md, timestamp via date "+%Y-%m-%d-%H%M") per CLAUDE.md — nothing else gets committed this round.

Step 1 — docs/demo/show-egress-ips.sh (new file, executable, left uncommitted)

Style: match .devcontainer/post-install.sh — #!/bin/bash, set -euo pipefail, ERROR:/WARNING: messages, ${VAR} braces.

Behavior:

1. Args/env: BASE_URL is $1 (required; missing → usage text + exit 1, e.g. usage: show-egress-ips.sh <BASE_URL> (e.g. localhost:8090)). Optional env: TOKEN (bearer token, same name docs/api.md uses; when set, send Authorization: Bearer $TOKEN), IP_ECHO_URL (default https://api.ipify.org?format=json — returns {"ip":"..."}).
2. Dependency check: command -v curl, command -v jq → ERROR + exit 1 if missing.
3. Fetch "$BASE_URL/v1/proxies" once (no server-side healthy filter — fetch all so unhealthy ones can be shown as skipped, which makes the demo more informative). Fail with a clear error if curl or JSON parsing fails.
4. Iterate proxies with jq -c '.proxies[]'; for each, extract id, ip, port, healthy:
   • unhealthy → print --- skipping <id> (unhealthy) ---
   • healthy → print a clear banner naming the proxy before the request, e.g. === via <id> — http://<ip>:<port> ===, then curl -sS --max-time 10 -x "http://${ip}:${port}" "$IP_ECHO_URL"; print the JSON response. A failed probe prints WARNING: request through <id> failed and continues (guard so set -e doesn't kill the loop).
5. Finish with a one-line summary: N proxies, M probed, K skipped/failed.

Reference for API shapes: docs/api.md (proxies[].id/ip/port/healthy; curl -x http://ip:port usage is already documented there and in README).

Deliberately deferred (user will iterate on the script first)

• No commit of the script, no push beyond the plan commit, no MR, no execution summary, no CHANGELOG — all wait until the user says the script (or script set) is ready.