httpthrottle

README

httpthrottle

Package httpthrottle provides a http.RoundTripper to rate limit HTTP requests.

Usage

package example

import (
    "errors"
    "net/http"
    "github.com/jybp/httpthrottle"
    "golang.org/x/time/rate"
)

func Example() {
    client := &http.Client{
        Transport: httpthrottle.Default(
            // Returns ErrQuotaExceeded if more than 36000 requests occured within an hour.
            httpthrottle.NewQuota(time.Hour, 36000), 
            // Blocks to never exceed 99 requests per second.
            rate.NewLimiter(99, 1), 
        ),
    }
    resp, err := client.Get("https://golang.org/")
    if errors.Is(err, httpthrottle.ErrQuotaExceeded) {
        // Handle err.
    }
    if err != nil {
        // Handle err.
    }
    _ = resp // Do something with resp.
}

Documentation

Overview

Package httpthrottle provides a http.RoundTripper to throttle http requests.

Example

package main

import (
	"net/http"
	"time"

	"github.com/jybp/httpthrottle"
	"golang.org/x/time/rate"
)

func main() {
	client := &http.Client{
		Transport: httpthrottle.Default(
			// Returns ErrQuotaExceeded if more than 36000 requests occured within an hour.
			httpthrottle.NewQuota(time.Hour, 36000),
			// Blocks to never exceed 99 requests per second.
			rate.NewLimiter(99, 1),
		),
	}
	resp, err := client.Get("https://golang.org/")
	if err == httpthrottle.ErrQuotaExceeded {
		// Handle err.
	}
	if err != nil {
		// Handle err.
	}
	_ = resp // Do something with resp.
}

Index

• Variables
• type MultiLimiter
  • func MultiLimiters(limiters ...RateLimiter) *MultiLimiter
  • func (l *MultiLimiter) Wait(ctx context.Context) error
• type Quota
  • func NewQuota(d time.Duration, n int) *Quota
  • func (q *Quota) Wait(ctx context.Context) error
• type RateLimiter
• type Transport
  • func Custom(t http.RoundTripper, r ...RateLimiter) *Transport
  • func Default(r ...RateLimiter) *Transport
  • func (t *Transport) RoundTrip(r *http.Request) (*http.Response, error)

Examples

• Package

Variables

var ErrQuotaExceeded = errors.New("quota exceeded")

Types

type MultiLimiter

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

MultiLimiter allows to enforce multiple RateLimiter.

func MultiLimiters

func MultiLimiters(limiters ...RateLimiter) *MultiLimiter

MultiLimiters creates a MultiLimiter from limiters.

func (*MultiLimiter) Wait

func (l *MultiLimiter) Wait(ctx context.Context) error

Wait invoke the Wait method of all Limiters concurrently.

type Quota

type Quota struct {
	Interval time.Duration
	Limit    int
	// contains filtered or unexported fields
}

A Quota controls how much events can happen within a timeframe. It is useful to enforce long-term rate limits where failing is more appropriate than blocking. The timeframe starts when Wait is called for the first time.

func NewQuota

func NewQuota(d time.Duration, n int) *Quota

NewQuota returns a new Quota that allows n events to occur wihin duration d.

func (*Quota) Wait

func (q *Quota) Wait(ctx context.Context) error

Wait does not block but returns ErrQuotaExceeded when the Limit is reached.

type RateLimiter

type RateLimiter interface {
	Wait(context.Context) error
}

RateLimiter interface compatible with golang.org/x/time/rate.

type Transport

type Transport struct {
	Transport http.RoundTripper // Used to make actual requests.
	Limiter   RateLimiter
}

Transport implements http.RoundTripper.

func Custom

func Custom(t http.RoundTripper, r ...RateLimiter) *Transport

Custom uses t to make actual requests.

func Default

func Default(r ...RateLimiter) *Transport

Default returns a RoundTripper capable of rate limiting http requests.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip ensures requests are performed within the rate limiting constraints.