From e1abac3e8f33ee517d8104dcdcba1ad25618b8a3 Mon Sep 17 00:00:00 2001 From: Jan Novak Date: Tue, 11 Aug 2026 22:21:28 +0200 Subject: [PATCH] Add plan: demo script for egress IP check via proxies Co-Authored-By: Claude --- docs/plans/2026-08-11-2220-demo-scripts.md | 33 ++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/plans/2026-08-11-2220-demo-scripts.md diff --git a/docs/plans/2026-08-11-2220-demo-scripts.md b/docs/plans/2026-08-11-2220-demo-scripts.md new file mode 100644 index 0000000..8b0d165 --- /dev/null +++ b/docs/plans/2026-08-11-2220-demo-scripts.md @@ -0,0 +1,33 @@ +# 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/-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](.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 (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 (unhealthy) ---` + - healthy → print a clear banner naming the proxy before the request, e.g. `=== via — http://: ===`, then `curl -sS --max-time 10 -x "http://${ip}:${port}" "$IP_ECHO_URL"`; print the JSON response. A failed probe prints `WARNING: request through 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](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.