# shopify/toxiproxy architecture

> Architecture diagram of the GitHub repository shopify/toxiproxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shopify/toxiproxy
- Repository: https://github.com/shopify/toxiproxy

## Overview

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`](https://github.com/shopify/toxiproxy/blob/main/toxic_collection.go) (Toxic collection), [`proxy.go`](https://github.com/shopify/toxiproxy/blob/main/proxy.go) (TCP proxy), [`link.go`](https://github.com/shopify/toxiproxy/blob/main/link.go) (Directional links), [`metrics.go`](https://github.com/shopify/toxiproxy/blob/main/metrics.go) (Metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_cli["CLI commands<br/>[cli.go]"]
  node_go_client["Go client<br/>[client.go]"]
  node_api["HTTP API<br/>[api.go]"]
  node_server["Server startup<br/>[server.go]"]
end

subgraph group_proxy["TCP proxy"]
  node_proxy_collection["Proxy collection"]
  node_proxy["TCP proxy<br/>[proxy.go]"]
  node_link["Directional links<br/>[link.go]"]
  node_stream["Stream transport"]
end

subgraph group_faults["Fault simulation"]
  node_toxic_collection["Toxic collection"]
  node_toxic_registry["Toxic registry<br/>[toxic.go]"]
  node_toxic_pipeline["Toxic pipeline<br/>[toxic.go]"]
  node_latency["Latency toxic<br/>[latency.go]"]
  node_bandwidth["Bandwidth toxic<br/>[bandwidth.go]"]
  node_packet_loss["Packet loss toxic<br/>[packet_loss.go]"]
  node_slicer["Slicer toxic<br/>[slicer.go]"]
  node_other_toxics["Other toxics"]
end

subgraph group_observability["Metrics"]
  node_metrics["Metrics<br/>[metrics.go]"]
  node_proxy_metrics["Proxy metrics<br/>[proxy.go]"]
  node_runtime_metrics["Runtime metrics<br/>[runtime.go]"]
end

node_app(("Test application"))
node_user(("Operator"))
node_prometheus(("Prometheus"))
node_upstream(("Upstream service"))

node_user -->|"runs commands"| node_cli
node_cli -->|"calls API"| node_go_client
node_go_client -.->|"HTTP requests"| node_api
node_server -->|"starts server"| node_api
node_api -->|"manages proxies"| node_proxy_collection
node_proxy_collection -.->|"stores proxies"| node_proxy
node_proxy -.->|"forwards TCP"| node_upstream
node_app -->|"connects through"| node_proxy
node_proxy -.->|"starts links"| node_toxic_collection
node_toxic_collection -->|"creates links"| node_link
node_link -->|"copies bytes"| node_stream
node_link -->|"runs chain"| node_toxic_pipeline
node_toxic_collection -->|"resolves type"| node_toxic_registry
node_toxic_pipeline -->|"transforms chunks"| node_stream
node_toxic_collection -.->|"configures toxic"| node_latency
node_toxic_collection -.->|"configures toxic"| node_bandwidth
node_toxic_collection -.->|"configures toxic"| node_packet_loss
node_toxic_collection -.->|"configures toxic"| node_slicer
node_toxic_collection -.->|"configures toxic"| node_other_toxics
node_server -->|"creates metrics"| node_metrics
node_metrics -.->|"enables collectors"| node_proxy_metrics
node_metrics -.->|"enables collectors"| node_runtime_metrics
node_runtime_metrics -.->|"exports metrics"| node_prometheus
node_proxy_metrics -.->|"exports metrics"| node_prometheus

click node_cli "https://github.com/shopify/toxiproxy/blob/main/cmd/cli/cli.go"
click node_go_client "https://github.com/shopify/toxiproxy/blob/main/client/client.go"
click node_api "https://github.com/shopify/toxiproxy/blob/main/api.go"
click node_server "https://github.com/shopify/toxiproxy/blob/main/cmd/server/server.go"
click node_proxy_collection "https://github.com/shopify/toxiproxy/blob/main/proxy_collection.go"
click node_proxy "https://github.com/shopify/toxiproxy/blob/main/proxy.go"
click node_link "https://github.com/shopify/toxiproxy/blob/main/link.go"
click node_toxic_collection "https://github.com/shopify/toxiproxy/blob/main/toxic_collection.go"
click node_toxic_registry "https://github.com/shopify/toxiproxy/blob/main/toxics/toxic.go"
click node_toxic_pipeline "https://github.com/shopify/toxiproxy/blob/main/toxics/toxic.go"
click node_latency "https://github.com/shopify/toxiproxy/blob/main/toxics/latency.go"
click node_bandwidth "https://github.com/shopify/toxiproxy/blob/main/toxics/bandwidth.go"
click node_packet_loss "https://github.com/shopify/toxiproxy/blob/main/toxics/packet_loss.go"
click node_slicer "https://github.com/shopify/toxiproxy/blob/main/toxics/slicer.go"
click node_other_toxics "https://github.com/shopify/toxiproxy/tree/main/toxics"
click node_stream "https://github.com/shopify/toxiproxy/tree/main/stream"
click node_metrics "https://github.com/shopify/toxiproxy/blob/main/metrics.go"
click node_proxy_metrics "https://github.com/shopify/toxiproxy/blob/main/collectors/proxy.go"
click node_runtime_metrics "https://github.com/shopify/toxiproxy/blob/main/collectors/runtime.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_go_client,node_api,node_server toneBlue
class node_proxy_collection,node_proxy,node_link,node_stream toneAmber
class node_toxic_collection,node_toxic_registry,node_toxic_pipeline,node_latency,node_bandwidth,node_packet_loss,node_slicer,node_other_toxics toneMint
class node_metrics,node_proxy_metrics,node_runtime_metrics toneRose
class node_app,node_user,node_prometheus,node_upstream toneIndigo
```

## Components

### Control plane

- [CLI commands](https://github.com/shopify/toxiproxy/blob/main/cmd/cli/cli.go): `cmd/cli/cli.go`
- [Go client](https://github.com/shopify/toxiproxy/blob/main/client/client.go): `client/client.go`
- [HTTP API](https://github.com/shopify/toxiproxy/blob/main/api.go): `api.go`
- [Server startup](https://github.com/shopify/toxiproxy/blob/main/cmd/server/server.go): `cmd/server/server.go`

### TCP proxy

- [Proxy collection](https://github.com/shopify/toxiproxy/blob/main/proxy_collection.go): `proxy_collection.go`
- [TCP proxy](https://github.com/shopify/toxiproxy/blob/main/proxy.go): `proxy.go`
- [Directional links](https://github.com/shopify/toxiproxy/blob/main/link.go): `link.go`
- [Stream transport](https://github.com/shopify/toxiproxy/tree/main/stream): `stream`

### Fault simulation

- [Toxic collection](https://github.com/shopify/toxiproxy/blob/main/toxic_collection.go): `toxic_collection.go`
- [Toxic registry](https://github.com/shopify/toxiproxy/blob/main/toxics/toxic.go): `toxics/toxic.go`
- [Toxic pipeline](https://github.com/shopify/toxiproxy/blob/main/toxics/toxic.go): `toxics/toxic.go`
- [Latency toxic](https://github.com/shopify/toxiproxy/blob/main/toxics/latency.go): `toxics/latency.go`
- [Bandwidth toxic](https://github.com/shopify/toxiproxy/blob/main/toxics/bandwidth.go): `toxics/bandwidth.go`
- [Packet loss toxic](https://github.com/shopify/toxiproxy/blob/main/toxics/packet_loss.go): `toxics/packet_loss.go`
- [Slicer toxic](https://github.com/shopify/toxiproxy/blob/main/toxics/slicer.go): `toxics/slicer.go`
- [Other toxics](https://github.com/shopify/toxiproxy/tree/main/toxics): `toxics`

### Metrics

- [Metrics](https://github.com/shopify/toxiproxy/blob/main/metrics.go): `metrics.go`
- [Proxy metrics](https://github.com/shopify/toxiproxy/blob/main/collectors/proxy.go): `collectors/proxy.go`
- [Runtime metrics](https://github.com/shopify/toxiproxy/blob/main/collectors/runtime.go): `collectors/runtime.go`

### Other components

- **Test application**
- **Operator**
- **Prometheus**
- **Upstream service**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Go client: calls API (evidence: `cmd/cli/cli.go`)
- Go client → HTTP API: HTTP requests
- Server startup → HTTP API: starts server (evidence: `cmd/server/server.go`)
- HTTP API → Proxy collection: manages proxies (evidence: `api.go`)
- Proxy collection → TCP proxy: stores proxies
- TCP proxy → Upstream service: forwards TCP
- Test application → TCP proxy: connects through (evidence: `README.md`)
- TCP proxy → Toxic collection: starts links
- Toxic collection → Directional links: creates links (evidence: `toxic_collection.go`)
- Directional links → Stream transport: copies bytes (evidence: `link.go`)
- Directional links → Toxic pipeline: runs chain (evidence: `link.go`)
- Toxic collection → Toxic registry: resolves type (evidence: `toxic_collection.go`)
- Toxic pipeline → Stream transport: transforms chunks (evidence: `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 (evidence: `toxic_collection.go`)
- Server startup → Metrics: creates metrics (evidence: `cmd/server/server.go`)
- Metrics → Proxy metrics: enables collectors
- Metrics → Runtime metrics: enables collectors
- Runtime metrics → Prometheus: exports metrics
- Proxy metrics → Prometheus: exports metrics
