README
¶
BWLimit
BWLimit lets you configure a bandwidth limit on net.Conn,
io.Reader and io.Writer.
Quick Start
BWLimit can be used to throttle the bandwidth (bytes per second) either on the client or server.
See usage examples below:
Server Side
To limit the bandwidth on the server use
bwlimit.NewListener.
package main
import (
"io"
"log"
"net"
"net/http"
"github.com/conduitio/bwlimit"
)
const (
writeLimit = 1 * bwlimit.Mebibyte // write limit is 1048576 B/s
readLimit = 4 * bwlimit.KB // read limit is 4000 B/s
)
func main() {
ln, err := net.Listen("tcp", ":8080")
if err != nil {
log.Fatalf("Failed to listen: %v", err)
}
// limit the listener bandwidth
ln = bwlimit.NewListener(ln, writeLimit, readLimit)
http.Handle("/echo", http.HandlerFunc(echoHandler))
srv := &http.Server{Addr: addr}
log.Fatalf("Failed to serve: %v", srv.Serve(ln))
}
func echoHandler(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
_, _ = w.Write(body)
}
Client Side
To limit the bandwidth on the client use
bwlimit.NewDialer.
package main
import (
"io"
"net"
"net/http"
"time"
"github.com/conduitio/bwlimit"
)
const (
writeLimit = 1 * bwlimit.Mebibyte // write limit is 1048576 B/s
readLimit = 4 * bwlimit.KB // read limit is 4000 B/s
)
func main() {
// change dialer in the default transport to use a bandwidth limit
dialer := bwlimit.NewDialer(&net.Dialer{
Timeout: 30 * time.Second,
KeepAlive: 30 * time.Second,
}, writeLimit, readLimit)
http.DefaultTransport.(*http.Transport).DialContext = dialer.DialContext
// requests through the default client respect the bandwidth limit now
resp, _ := http.DefaultClient.Get("http://localhost:8080/echo")
_, _ = io.ReadAll(resp.Body)
}
gRPC Client Interceptor
The gRPC interceptor is provided in a separate module, import it with:
go get github.com/conduitio/bwlimit/bwgrpc
To limit the bandwidth on a gRPC client use
bwgrpc.WithBandwidthLimitedContextDialer.
package main
import (
"context"
"log"
"github.com/conduitio/bwlimit"
"github.com/conduitio/bwlimit/bwgrpc"
"github.com/conduitio/bwlimit/bwgrpc/testproto"
"google.golang.org/grpc"
)
const (
writeLimit = 1 * bwlimit.Mebibyte // write limit is 1048576 B/s
readLimit = 4 * bwlimit.KB // read limit is 4000 B/s
)
func main() {
// open connection with limited bandwidth
conn, err := grpc.DialContext(
context.Background(),
"localhost:8080",
// limit the bandwidth
bwgrpc.WithBandwidthLimitedContextDialer(writeLimit, readLimit, nil),
)
if err != nil {
log.Fatalf("Failed to dial: %v", err)
}
defer conn.Close()
// create gRPC client with the limited connection
c := testproto.NewTestServiceClient(conn)
// use client to send request
_, err = c.TestRPC(ctx, &testproto.TestRequest{})
if err != nil {
log.Fatalf("Failed to send RPC: %v", err)
}
}
Documentation
¶
Index ¶
- Constants
- type Byte
- type Conn
- func (c *Conn) Read(b []byte) (n int, err error)
- func (c *Conn) ReadBandwidthLimit() Byte
- func (c *Conn) SetBandwidthLimit(bytesPerSecond Byte)
- func (c *Conn) SetDeadline(t time.Time) error
- func (c *Conn) SetReadBandwidthLimit(bytesPerSecond Byte)
- func (c *Conn) SetReadDeadline(t time.Time) error
- func (c *Conn) SetWriteBandwidthLimit(bytesPerSecond Byte)
- func (c *Conn) SetWriteDeadline(t time.Time) error
- func (c *Conn) Write(b []byte) (n int, err error)
- func (c *Conn) WriteBandwidthLimit() Byte
- type Dialer
- func (d *Dialer) Dial(network, address string) (net.Conn, error)
- func (d *Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)
- func (d *Dialer) ReadBandwidthLimit() Byte
- func (d *Dialer) SetReadBandwidthLimit(bytesPerSecond Byte)
- func (d *Dialer) SetWriteBandwidthLimit(bytesPerSecond Byte)
- func (d *Dialer) WriteBandwidthLimit() Byte
- type Listener
- type Reader
- type Writer
Constants ¶
const ( Kibibyte Byte = 1024 KiB = Kibibyte Mebibyte = Kibibyte * 1024 MiB = Mebibyte Gibibyte = Mebibyte * 1024 GiB = Gibibyte )
Base-2 byte units.
const ( Kilobyte Byte = 1000 KB = Kilobyte Megabyte = Kilobyte * 1000 MB = Megabyte Gigabyte = Megabyte * 1000 GB = Gigabyte )
SI base-10 byte units.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Conn ¶
Conn is a net.Conn connection that limits the bandwidth of writes and reads.
func NewConn ¶
NewConn wraps an existing net.Conn and returns a Conn that limits the bandwidth of writes and reads. A zero value for writeLimitPerSecond or readLimitPerSecond means the corresponding action will not have a bandwidth limit.
func (*Conn) Read ¶
Read reads data from the connection. Read can be made to time out and return an error after a fixed time limit; see SetDeadline and SetReadDeadline. Read will limit the connection bandwidth if a limit is configured. If the size of b is bigger than the rate of bytes per second, reads will be split into smaller chunks. Note that since it's not known in advance how many bytes will be read, the bandwidth can burst up to 2x of the configured limit when reading the first 2 chunks.
func (*Conn) ReadBandwidthLimit ¶
ReadBandwidthLimit returns the current read bandwidth limit.
func (*Conn) SetBandwidthLimit ¶
SetBandwidthLimit sets the read and write bandwidth limits associated with the connection. It is equivalent to calling both SetReadBandwidthLimit and SetWriteBandwidthLimit.
func (*Conn) SetDeadline ¶
SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.
A deadline is an absolute time after which I/O operations fail instead of blocking. The deadline applies to all future and pending I/O, not just the immediately following call to Read or Write. After a deadline has been exceeded, the connection can be refreshed by setting a deadline in the future.
If the deadline is exceeded a call to Read or Write or to other I/O methods will return an error that wraps os.ErrDeadlineExceeded. This can be tested using errors.Is(err, os.ErrDeadlineExceeded). The error's Timeout method will return true, but note that there are other possible errors for which the Timeout method will return true even if the deadline has not been exceeded.
An idle timeout can be implemented by repeatedly extending the deadline after successful Read or Write calls.
A zero value for t means I/O operations will not time out.
func (*Conn) SetReadBandwidthLimit ¶
SetReadBandwidthLimit sets the bandwidth limit for future Read calls and any currently-blocked Read call. A zero value for bytesPerSecond means the bandwidth limit is removed.
func (*Conn) SetReadDeadline ¶
SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out.
func (*Conn) SetWriteBandwidthLimit ¶
SetWriteBandwidthLimit sets the bandwidth limit for future Write calls and any currently-blocked Write call. A zero value for bytesPerSecond means the bandwidth limit is removed.
func (*Conn) SetWriteDeadline ¶
SetWriteDeadline sets the deadline for future Write calls and any currently-blocked Write call. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out.
func (*Conn) Write ¶
Write writes data to the connection. Write can be made to time out and return an error after a fixed time limit; see SetDeadline and SetWriteDeadline. Write will limit the connection bandwidth if a limit is configured. If the size of b is bigger than the rate of bytes per second, writes will be split into smaller chunks.
func (*Conn) WriteBandwidthLimit ¶
WriteBandwidthLimit returns the current write bandwidth limit.
type Dialer ¶
Dialer is a net.Dialer that limits the bandwidth of the connections it creates.
func NewDialer ¶
NewDialer wraps an existing net.Dialer and returns a Dialer that limits the bandwidth of the connections it creates. A zero value for writeLimitPerSecond or readLimitPerSecond means the corresponding action will not have a bandwidth limit.
func (*Dialer) Dial ¶
Dial connects to the address on the named network. It returns a connection with the configured bandwidth limits. Each connection tracks its own bandwidth.
func (*Dialer) DialContext ¶
DialContext connects to the address on the named network using the provided context. It returns a connection with the configured bandwidth limits.
func (*Dialer) ReadBandwidthLimit ¶
ReadBandwidthLimit returns the current read bandwidth limit.
func (*Dialer) SetReadBandwidthLimit ¶
SetReadBandwidthLimit sets the bandwidth limit for reads on future connections opened in Accept. It has no effect on already opened connections. A zero value for bytesPerSecond means the bandwidth limit is removed.
func (*Dialer) SetWriteBandwidthLimit ¶
SetWriteBandwidthLimit sets the bandwidth limit for writes on future connections opened in Accept. It has no effect on already opened connections. A zero value for bytesPerSecond means the bandwidth limit is removed.
func (*Dialer) WriteBandwidthLimit ¶
WriteBandwidthLimit returns the current write bandwidth limit.
type Listener ¶
Listener is a net.Listener that limits the bandwidth of the connections it creates.
func NewListener ¶
NewListener wraps an existing net.Listener and returns a Listener that limits the bandwidth of the connections it creates. A zero value for writeLimitPerSecond or readLimitPerSecond means the corresponding action will not have a bandwidth limit.
func (*Listener) Accept ¶
Accept waits for and returns the next connection to the listener. It returns a connection with a configured bandwidth limit. Each connection tracks its own bandwidth.
func (*Listener) ReadBandwidthLimit ¶
ReadBandwidthLimit returns the current read bandwidth limit.
func (*Listener) SetReadBandwidthLimit ¶
SetReadBandwidthLimit sets the bandwidth limit for reads on future connections opened in Accept. It has no effect on already opened connections. A zero value for bytesPerSecond means the bandwidth limit is removed.
func (*Listener) SetWriteBandwidthLimit ¶
SetWriteBandwidthLimit sets the bandwidth limit for writes on future connections opened in Accept. It has no effect on already opened connections. A zero value for bytesPerSecond means the bandwidth limit is removed.
func (*Listener) WriteBandwidthLimit ¶
WriteBandwidthLimit returns the current write bandwidth limit.
type Reader ¶
Reader wraps an io.Reader and imposes a bandwidth limit on calls to Read.
func NewReader ¶
NewReader wraps an existing io.Reader and returns a Reader that limits the bandwidth of reads. A zero value for bytesPerSecond means that Read will not have a bandwidth limit.
func (*Reader) BandwidthLimit ¶
BandwidthLimit returns the current bandwidth limit.
func (*Reader) Close ¶
Close forwards the call to the wrapped io.Reader if it implements io.Closer, otherwise it is a noop.
func (*Reader) Read ¶
Read reads up to len(p) bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered.
Read will limit the speed of the reads if a bandwidth limit is configured. If the size of p is bigger than the rate of bytes per second, reads will be split into smaller chunks. Note that since it's not known in advance how many bytes will be read, the bandwidth can burst up to 2x of the configured limit when reading the first 2 chunks.
func (*Reader) SetBandwidthLimit ¶
SetBandwidthLimit sets the bandwidth limit for future Read calls and any currently-blocked Read call. A zero value for bytesPerSecond means the bandwidth limit is removed.
func (*Reader) SetDeadline ¶
SetDeadline sets the read deadline associated with the reader.
A deadline is an absolute time after which Read fails instead of blocking. The deadline applies to all future and pending calls to Read, not just the immediately following call to Read. After a deadline has been exceeded, the reader can be refreshed by setting a deadline in the future.
If the deadline is exceeded a call to Read will return an error that wraps os.ErrDeadlineExceeded. This can be tested using errors.Is(err, os.ErrDeadlineExceeded).
An idle timeout can be implemented by repeatedly extending the deadline after successful Read calls.
A zero value for t means that calls to Read will not time out.
type Writer ¶
Writer wraps an io.Writer and imposes a bandwidth limit on calls to Write.
func NewWriter ¶
NewWriter wraps an existing io.Writer and returns a Writer that limits the bandwidth of writes. A zero value for bytesPerSecond means that Write will not have a bandwidth limit.
func (*Writer) BandwidthLimit ¶
BandwidthLimit returns the current bandwidth limit.
func (*Writer) Close ¶
Close forwards the call to the wrapped io.Writer if it implements io.Closer, otherwise it is a noop.
func (*Writer) SetBandwidthLimit ¶
SetBandwidthLimit sets the bandwidth limit for future Write calls and any currently-blocked Write call. A zero value for bytesPerSecond means the bandwidth limit is removed.
func (*Writer) SetDeadline ¶
SetDeadline sets the write deadline associated with the writer.
A deadline is an absolute time after which Write fails instead of blocking. The deadline applies to all future and pending calls to Write, not just the immediately following call to Write. After a deadline has been exceeded, the writer can be refreshed by setting a deadline in the future.
If the deadline is exceeded a call to Write will return an error that wraps os.ErrDeadlineExceeded. This can be tested using errors.Is(err, os.ErrDeadlineExceeded).
An idle timeout can be implemented by repeatedly extending the deadline after successful Write calls.
A zero value for t means that calls to Write will not time out.
func (*Writer) Write ¶
Write writes len(p) bytes from p to the underlying data stream. It returns the number of bytes written from p (0 <= n <= len(p)) and any error encountered that caused the write to stop early.
Write will limit the speed of the writes if a bandwidth limit is configured. If the size of p is bigger than the rate of bytes per second, writes will be split into smaller chunks.
Source Files
Directories