Merge pull request #1306 from joshunrau/toxic-proxy

add toxic-proxy.sh and docs

Author: joshunrau

.env.template

@@ -73,6 +73,8 @@ LOGIN_REQUEST_THROTTLER_TTL=
 
 # The port to use for the NestJS development server
 API_DEV_SERVER_PORT=5500
+# The port where the toxic-proxy.sh script should run on
+API_DEV_TOXIC_PROXY_PORT=
 # The port to use for the Astro (outreach website) development server
 OUTREACH_DEV_SERVER_PORT=4000
 # The port for the playground

docs/en/2-tutorials/2.3-simulate-poor-network.md

@@ -0,0 +1,64 @@
+---
+title: Simulate Poor Network Conditions
+slug: en/docs/tutorials/simulate-poor-network
+sidebar:
+  order: 4
+---
+
+This guide explains how to use the staged toxic proxy setup to simulate poor network conditions when developing Open Data Capture.
+
+When you run `scripts/toxic-proxy.sh`, it configures Toxiproxy with the following simulated network conditions:
+
+- **Downstream bandwidth limit (API → browser):** capped at **5,000 bytes/second** (~5 KB/s).
+- **Upstream bandwidth limit (browser → API):** capped at **2,500 bytes/second** (~2.5 KB/s).
+- **Intermittent latency and jitter (downstream):**
+  - Base latency of **50 ms**, plus up to **500 ms of jitter**.
+  - Applied with **20% toxicity**, meaning only about 1 in 5 downstream requests/responses are delayed in this way.
+- **Occasional random connection resets (downstream):**
+  - Connections are **randomly reset/closed** from the proxy side.
+  - Applied with **10% toxicity**, so roughly 1 in 10 downstream connections will be abruptly terminated.
+
+Together, these toxics approximate a slow, unstable network where responses arrive slowly, some requests suffer extra delay, and a minority of connections fail unexpectedly.
+
+### Prerequisites
+
+- Install Toxiproxy (both `toxiproxy-server` and `toxiproxy-cli`) and ensure they are available on your `PATH`.
+
+### Steps
+
+<Steps>
+
+1. **Set the toxic proxy port in `.env`**
+
+   Choose a port for the toxic proxy (for example `5501`) and set:
+   - `API_DEV_TOXIC_PROXY_PORT=5501`
+
+2. **Point the frontend at the toxic proxy**
+
+   Update `API_BASE_URL` to use the same port on localhost:
+   - `API_BASE_URL=http://localhost:5501`
+
+3. **Start the toxic proxy**
+
+   Run:
+
+   ```bash
+   scripts/toxic-proxy.sh
+   ```
+
+   Leave this running. It creates a proxy that sits between the frontend and the API server and applies bandwidth limits.
+
+4. **Launch the app as normal**
+
+   In another terminal, run:
+
+   ```bash
+   pnpm dev
+   ```
+
+</Steps>
+
+### Notes
+
+- The proxy reads `API_DEV_SERVER_PORT` from `.env` to know where your API server is listening.
+- If `API_DEV_TOXIC_PROXY_PORT` is empty, the script exits without starting the proxy.

scripts/toxic-proxy.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+IFS=$'\n\t'
+
+[ "${BASH_VERSINFO:-0}" -ge 5 ] || (echo "Error: Bash >= 5.0 is required for this script" >&2 && exit 1)
+
+PROJECT_ROOT="$(dirname -- "$(dirname -- "$(readlink -f "$0")")")"
+
+source "${PROJECT_ROOT}/.env"
+
+API_DEV_SERVER_PORT="${API_DEV_SERVER_PORT:-}"
+API_DEV_TOXIC_PROXY_PORT="${API_DEV_TOXIC_PROXY_PORT:-}"
+
+if [[ -z "$API_DEV_SERVER_PORT" ]]; then
+  echo "Error: API_DEV_SERVER_PORT is not set" >&2
+  exit 1
+fi
+
+if [ -z "$API_DEV_TOXIC_PROXY_PORT" ]; then
+  exit 0
+fi
+
+cleanup() {
+  echo "Shutting down..."
+  kill "$TOXIPROXY_PID" 2>/dev/null || true
+  wait "$TOXIPROXY_PID" 2>/dev/null || true
+}
+
+trap cleanup EXIT
+
+toxiproxy-server &
+TOXIPROXY_PID=$!
+sleep 1
+
+toxiproxy-cli create --listen "0.0.0.0:$API_DEV_TOXIC_PROXY_PORT" --upstream "127.0.0.1:$API_DEV_SERVER_PORT" odc-api
+
+toxiproxy-cli toxic add -n downstream-bandwidth -t bandwidth -a rate=5000 -a type=downstream odc-api
+
+toxiproxy-cli toxic add -n upstream-bandwidth -t bandwidth -a rate=2500 -a type=upstream odc-api
+
+toxiproxy-cli toxic add -n latency -t latency -a latency=50 -a jitter=500 -a type=downstream -toxicity 0.2 odc-api
+
+toxiproxy-cli toxic add -n random-resets -t reset_peer -a type=tox_type=downstream -toxicity 0.1 odc-api
+
+wait "$TOXIPROXY_PID"
+