How shopify/toxiproxy works
Toxiproxy is a TCP proxy for deterministic or randomized network fault simulation. Applications route test connections through its proxies; users configure proxy mappings and inject or update toxics through the HTTP API or Go client/CLI, then exercise the resulting degraded connections. The runtime path runs from API-managed proxy state through TCP connection handling into directional toxic chains and back to the upstream or client. The README also documents latency, outages, bandwidth limits, packet loss, slicing, timeouts, and related toxic behaviors. Unsampled handlers and proxy internals are represented only where README or excerpts support their role.
Main entry points: toxic_collection.go Toxic collection · proxy.go TCP proxy · link.go Directional links · metrics.go Metrics
Components 23
Control plane
- CLI commands
cmd/cli/cli.go - Go client
client/client.go - HTTP API
api.go - Server startup
cmd/server/server.go
TCP proxy
- Proxy collection
proxy_collection.go - TCP proxy
proxy.go - Directional links
link.go - Stream transport
stream
Fault simulation
- Toxic collection
toxic_collection.go - Toxic registry
toxics/toxic.go - Toxic pipeline
toxics/toxic.go - Latency toxic
toxics/latency.go - Bandwidth toxic
toxics/bandwidth.go - Packet loss toxic
toxics/packet_loss.go - Slicer toxic
toxics/slicer.go - Other toxics
toxics
Metrics
- Metrics
metrics.go - Proxy metrics
collectors/proxy.go - Runtime metrics
collectors/runtime.go
Other components
- Test application
- Operator
- Prometheus
- Upstream service
Connections 24
- Operator → CLI commands: runs commands
README.md - CLI commands → Go client: calls API
cmd/cli/cli.go - Go client → HTTP API: HTTP requests
- Server startup → HTTP API: starts server
cmd/server/server.go - HTTP API → Proxy collection: manages proxies
api.go - Proxy collection → TCP proxy: stores proxies
- TCP proxy → Upstream service: forwards TCP
- Test application → TCP proxy: connects through
README.md - TCP proxy → Toxic collection: starts links
- Toxic collection → Directional links: creates links
toxic_collection.go - Directional links → Stream transport: copies bytes
link.go - Directional links → Toxic pipeline: runs chain
link.go - Toxic collection → Toxic registry: resolves type
toxic_collection.go - Toxic pipeline → Stream transport: transforms chunks
toxics/toxic.go - Toxic collection → Latency toxic: configures toxic
- Toxic collection → Bandwidth toxic: configures toxic
- Toxic collection → Packet loss toxic: configures toxic
- Toxic collection → Slicer toxic: configures toxic
- Toxic collection → Other toxics: configures toxic
toxic_collection.go - Server startup → Metrics: creates metrics
cmd/server/server.go - Metrics → Proxy metrics: enables collectors
- Metrics → Runtime metrics: enables collectors
- Runtime metrics → Prometheus: exports metrics
- Proxy metrics → Prometheus: exports metrics