add toxic-proxy.sh and docs

[joshunrau]

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

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:

   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:

   pnpm dev

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.

Summary by CodeRabbit

• New Features

  • Network simulation capability now available to test application behavior under degraded conditions, including bandwidth throttling, latency, jitter, and occasional connection resets.

• Documentation

  • New tutorial added explaining how to set up and use network simulation tools for development and testing.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c8d9f3b3-89b2-4203-98ff-b478076c32a3

📥 Commits

Reviewing files that changed from the base of the PR and between c2d04cb and 1a03e01.

📒 Files selected for processing (3)

• .env.template
• docs/en/2-tutorials/2.3-simulate-poor-network.md
• scripts/toxic-proxy.sh

---

Walkthrough

Introduces a new toxic proxy setup for development to simulate degraded network conditions. Adds an environment variable, a Bash script that configures and runs Toxiproxy with specific network toxics (bandwidth limits, latency, jitter, connection resets), and documentation explaining the usage workflow.

Changes

Cohort / File(s)	Summary
Environment & Configuration .env.template	Added API_DEV_TOXIC_PROXY_PORT environment variable for configuring the Toxiproxy listening port.
Network Simulation Script scripts/toxic-proxy.sh	New Bash script that starts Toxiproxy server, creates an API proxy listening on the configured port, and applies toxics for simulating bandwidth limits (5000 bps downstream, 2500 bps upstream), latency (50ms + 500ms jitter at 20% toxicity), and connection resets (10% toxicity). Includes cleanup handling and validation of required port variables.
Documentation docs/en/2-tutorials/2.3-simulate-poor-network.md	New tutorial documenting the toxic proxy workflow, including prerequisites, configuration steps, usage with pnpm dev, and notes about environment variable behavior.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gdevenyi]

Glorious