caddythrottlelistener

README

Caddy Throttle Listener

A Caddy module that provides bandwidth throttling and chaos engineering features for incoming connections. This module allows you to simulate real-world network conditions by adding bandwidth limits, latency, and jitter. Note that the throttling applies for all bytes transmitted on the connection, including TLS handshake and HTTP headers.

Overview

This module allows you to throttle incoming connections to your Caddy server to prevent abuse and simulate chaotic network conditions for testing purposes. It provides:

• Bandwidth Throttling: Limit upload/download speeds per connection
• Latency Injection: Add fixed delays to simulate slow networks
• Jitter: Add random delays to simulate unstable networks

Perfect for preventing abuse, ensuring fair resource usage, and testing how your applications handle real-world network conditions.

Install

Follow the xcaddy install process here.

Then, build Caddy with this Go module plugged in. For example:

xcaddy build --with github.com/mohammed90/caddy-throttle-listener

Caddyfile Example

{
	servers {
		listener_wrappers {
			throttle {
				down 1MiB
				up 1MiB
			}
			tls
		}
	}
}
example.com {
	root * /var/www/html
	file_server
}

Configuration Options

Basic Throttling

{
	servers {
		listener_wrappers {
			throttle {
				down 512KB    # Download limit per connection
				up 1MB       # Upload limit per connection
			}
		}
	}
}

Chaos Engineering Features

Add network latency and jitter to test application resilience:

{
	servers {
		listener_wrappers {
			throttle {
				# Bandwidth limits
				down 1MiB
				up 512KB
				
				# Chaos engineering
				latency 100ms    # Fixed delay per read/write
				jitter 50ms      # Random delay (0-50ms) per operation
			}
		}
	}
}

Testing Scenarios

Slow Network Simulation

throttle {
	down 64KB
	up 32KB
	latency 200ms
	jitter 100ms
}

High-Latency Connection (Satellite/Cellular)

throttle {
	latency 800ms
	jitter 200ms
}

Unstable Connection

throttle {
	jitter 500ms  # High jitter without base latency
}

Documentation

Index

• type Listener
  • func (Listener) CaddyModule() caddy.ModuleInfo
  • func (l *Listener) Provision(caddy.Context) error
  • func (l *Listener) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (l *Listener) WrapListener(parent net.Listener) net.Listener

Types

type Listener

type Listener struct {
	// Up is the maximum upload speed. If not set, there is no limit.
	// The value is parsed using the `go-humanize` package and accepts
	// both the SI and the IEC prefixes. Values without units are interepreted
	// as bytes.
	Up string `json:"up,omitempty"`

	// Down is the maximum upload speed. If not set, there is no limit.
	// The value is parsed using the `go-humanize` package and accepts
	// both the SI and the IEC prefixes. Values without units are interepreted
	// as bytes.
	Down string `json:"down,omitempty"`

	// Latency adds a fixed delay to each read/write operation.
	// Accepts duration strings like "10ms", "1s", "500us".
	Latency caddy.Duration `json:"latency,omitempty"`

	// Jitter adds random delay (0 to jitter value) to each read/write operation.
	// Accepts duration strings like "5ms", "100ms", "1s".
	Jitter caddy.Duration `json:"jitter,omitempty"`
	// contains filtered or unexported fields
}

The `throttle` listener limits the bandwidth of the connection to the given values and can inject chaos engineering features like latency and jitter.

func (Listener) CaddyModule

func (Listener) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Listener) Provision

func (l *Listener) Provision(caddy.Context) error

Provision implements caddy.Provisioner.

func (*Listener) UnmarshalCaddyfile

func (l *Listener) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler.

func (*Listener) WrapListener

func (l *Listener) WrapListener(parent net.Listener) net.Listener

WrapListener implements caddy.ListenerWrapper.