bandwidth

Documentation

Overview

Package bandwidth provides rate limiting utilities and middleware for TCP connections.

The NewListener function returns a net.Listener that wraps an existing listener and rate limit globally over all connections and each connection itself.

  // 1mbs
  serverRate := NewRateConfig(1024 * 1024, 1024 * 1024)
  // 200 kbs
  connRate := NewRateConfig(1024 * 200, 1024 * 200)

  ln, err := net.Listen("tcp", ":8080")
  if err != nil {
	// handle error
  }

  listener := bandwidth.NewListener(context, serverRate, connRate, ln)

  for {
   conn, err := ln.Accept()
   if err != nil {
	// handle error
   }
	go handleConnection(conn)
  }

Index

• Variables
• func NewListener(ctx context.Context, listenerConfig *ListenerConfig, listener net.Listener) net.Listener
• func NewRateLimitedConn(ctx context.Context, readLimiter Limiter, writeLimiter Limiter, conn net.Conn) net.Conn
• type Limiter
  • func NewBandwidthLimiter(conf *RateConfig) Limiter
• type ListenerConfig
  • func NewListenerConfig(rateConfig *RateConfig) *ListenerConfig
• type RateConfig
  • func NewRateConfig(limit int64, burst int) *RateConfig
  • func (conf *RateConfig) Burst() int
  • func (conf *RateConfig) Limit() int64
  • func (conf *RateConfig) SetBurst(burst int)
  • func (conf *RateConfig) SetLimit(limit int64)

Examples

• NewListener
• NewRateLimitedConn

Variables

var Inf int64 = math.MaxInt64

Inf infinite rate

Functions

func NewListener

func NewListener(ctx context.Context, listenerConfig *ListenerConfig, listener net.Listener) net.Listener

NewListener returns a net.Listener that will apply rate limits to each connection and also globally for all connections via the listenerConfig.ReadServerRate and listenerConfig.WriteServerRate configs.

Example

ExampleNewListener shows how reate limit an existing net.Listener

// Get a Listener, e.g tcp on any port
tcpListner, err := net.Listen("tcp", ":0")
if err != nil {
	panic(err)
}

ctx := context.Background()

// configure rate limit to:
// total read+write traffic == 1mbs
// Each connection read+write == 2kbs
// The maximum that can be read or written at any one time is 2kb
serverRate := NewRateConfig(1024*1024, 2048)
connRate := NewRateConfig(2048, 2048)

listener := NewListener(ctx, &ListenerConfig{
	ReadServerRate:  serverRate,
	WriteServerRate: serverRate,
	ReadConnRate:    connRate,
	WriteConnRate:   connRate,
}, tcpListner)

// Now use the listener
// e.g listener.Accept()

err = listener.Close()
if err != nil {
	fmt.Printf("error while closing listener %s", err)
}

func NewRateLimitedConn

func NewRateLimitedConn(ctx context.Context, readLimiter Limiter, writeLimiter Limiter, conn net.Conn) net.Conn

NewRateLimitedConn returns a net.Conn that has its Read method rate limited by the limiter.

Example

ExampleNewRateLimitedConn wrap an existing net.Con and rate limit its read write operations

// Setup a limiter with a 2kb/s limit, and max 2kb per read event.
readLimiter := NewBandwidthLimiter(NewRateConfig(2048, 2048))

// Setup a limiter infinite write limit
writeLimiter := NewBandwidthLimiter(NewRateConfig(Inf, 0))

ctx := context.Background()

conn := &mockConn{} // get a connection

rConn := NewRateLimitedConn(ctx, readLimiter, writeLimiter, conn)

// Write is not rate limited
_, _ = rConn.Write([]byte("test string"))

// Read is reate limited
_, _ = rConn.Read(make([]byte, 1))

_ = rConn.Close()

Types

type Limiter

type Limiter interface {
	// Wait blocks till n bytes per second are available.
	// This can be for the server or per connection
	WaitN(tx context.Context, n int) error
	Configure(conf *RateConfig)

	// Child create's a child limiter, that will call check the parent's limit before
	// checking its own limit
	Child(conf *RateConfig) Limiter
}

Limiter abstracts the idea of a rate limiter in this package. A Limiter can also create a hierarchy of parent child limiters.

func NewBandwidthLimiter

func NewBandwidthLimiter(conf *RateConfig) Limiter

NewBandwidthLimiter creates a limiter to use with tcp connection and tcp listener bytes per second rate limiting.

type ListenerConfig

type ListenerConfig struct {

	// ReadServerRate the global server read limit and burst config
	ReadServerRate *RateConfig

	// WriteServerRate the global server write limit and burst config
	WriteServerRate *RateConfig

	// ReadConnRate the per connection read limit and burst config
	ReadConnRate *RateConfig

	// WriteConnRate the per connection write limit and burst config
	WriteConnRate *RateConfig
}

ListenerConfig groups together the configuration for a Listener and the limiters that should be used.

func NewListenerConfig

func NewListenerConfig(rateConfig *RateConfig) *ListenerConfig

NewListenerConfig is a helper function to create a ListenerConfig from a single RateConfig. the ReadServerRate, WriterServerRate, ReadConnRate, and WriteConnRate are all set to the RateConfig.

type RateConfig

type RateConfig struct {
	// contains filtered or unexported fields
}

RateConfig holds the limiter configuration limit and burst values.

func NewRateConfig

func NewRateConfig(limit int64, burst int) *RateConfig

NewRateConfig contains the over limit in bytes per second and the burst; maximum bytes that can be read in a single call. The RateConfig instance that can be read and updated from multiple go routines.

func (*RateConfig) Burst

func (conf *RateConfig) Burst() int

Burst returns the burst in bytes per second.

func (*RateConfig) Limit

func (conf *RateConfig) Limit() int64

Limit returns the limit in bytes per second.

func (*RateConfig) SetBurst

func (conf *RateConfig) SetBurst(burst int)

SetBurst sets the number of bytes that can be consumed in a single Read call

func (*RateConfig) SetLimit

func (conf *RateConfig) SetLimit(limit int64)

SetLimit sets the overall bytes per second rate