README
¶
iocap
Go package for rate limiting data streams using the familiar io.Reader and
io.Writer interfaces.
iocap provides simple wrappers over arbitrary io.Reader and io.Writer
instances to allow throttling throughput of either read or write operations.
Data streams can be rate limited individually or grouped together to provide an
aggregate rate over multiple operations.
For examples and usage, see the godoc.
How it works
Under the hood, iocap uses a very simple leaky bucket implementation to
shape the flow of traffic. This implementation uses timestamps instead of a
constant-rate "leak" to empty the bucket. The reason for this is to allow
readers and writers to utilize the leaky bucket without requiring additional
setup, including starting/stopping of timers or other goroutines.
Documentation
¶
Overview ¶
Package iocap provides rate limiting for data streams using the familiar io.Reader and io.Writer interfaces.
Rates can be expressed in a few different units using helper functions:
rate := iocap.Kbps(512) // Kilobits/s rate := iocap.Mbps(10) // Megabits/s rate := iocap.Gbps(1) // Gigabits/s
Rates can also be described manually with any size or interval:
rate := iocap.RateOpts{
Interval: time.Second,
Size: 5 * 1024 * 1024, // 5MB/s
}
Readers and Writers are created by passing in an existing io.Reader or io.Writer along with a rate.
r = iocap.NewReader(r, rate) w = iocap.NewWriter(w, rate)
Rate limits can be applied to multiple readers and/or writers by creating a rate limiting group for them.
// Create the shared group g := iocap.NewGroup(rate) // Pull a new reader and writer off of the group. Rate limits are now // applied and enforced across both. r = g.NewReader(r) w = g.NewWriter(w)
Index ¶
Examples ¶
Constants ¶
const ( Kb // Kilobit Mb // Megabit Gb // Gigabit )
Variables ¶
var ( // The zero-value of RateOpts is used to indicate that no rate limit // should be applied to read/write operations. Unlimited = RateOpts{0, 0} )
Functions ¶
This section is empty.
Types ¶
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
Group is used to group multiple readers and/or writers onto the same bucket, thus enforcing the rate limit across multiple independent processes.
Example ¶
// Create a rate limiting group.
rate := Kbps(512)
g := NewGroup(rate)
// Create a new reader and writer on the group.
buf := new(bytes.Buffer)
r := g.NewReader(buf)
w := g.NewWriter(buf)
// Reader and writer are rate limited together
n, err := w.Write([]byte("hello world!"))
if err != nil {
fmt.Println(err)
return
}
out := make([]byte, n)
_, err = r.Read(out)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(out))
Output: hello world!
type RateOpts ¶
type RateOpts struct {
// Interval is the time period of the rate
Interval time.Duration
// Size is the number of bytes per interval
Size int
}
RateOpts is used to encapsulate rate limiting options.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader implements the io.Reader interface and limits the rate at which bytes come off of the underlying source reader.
Example ¶
// Create a buffer to read from.
buf := bytes.NewBufferString("hello world!")
// Create the rate limited reader.
rate := Kbps(512)
r := NewReader(buf, rate)
// Read from the reader.
out := make([]byte, buf.Len())
n, err := r.Read(out)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(n, string(out))
Output: 12 hello world!
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer implements the io.Writer interface and limits the rate at which bytes are written to the underlying writer.
Example ¶
// Create the buffer to write to.
buf := new(bytes.Buffer)
// Create the rate limited writer.
rate := Kbps(512)
r := NewWriter(buf, rate)
// Write data into the writer.
n, err := r.Write([]byte("hello world!"))
if err != nil {
fmt.Println(err)
return
}
fmt.Println(n, buf.String())
Output: 12 hello world!
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package httpcap provides rate limiting for HTTP handlers and response writers.
|
Package httpcap provides rate limiting for HTTP handlers and response writers. |
|
mapper
Package mapper provides HTTP request mapping based on arbitrary criteria, including the raw HTTP request details.
|
Package mapper provides HTTP request mapping based on arbitrary criteria, including the raw HTTP request details. |