Categorygithub.com/processout/throttled
modulepackage
1.0.0
Repository: https://github.com/processout/throttled.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
10
Dependents
0
Files
576 SLOC

# README

Throttled build status GoDoc

Package throttled implements different throttling strategies for controlling access to HTTP handlers.

As of July 27, 2015, the package is now located under its own GitHub organization and uses gopkg.in for versioning, please adjust your imports to gopkg.in/throttled/throttled.v1.

Installation

go get gopkg.in/throttled/throttled.v1/...

Interval

The Interval function creates a throttler that allows requests to go through at a controlled, constant interval. The interval may be applied to all requests (vary argument == nil) or independently based on vary-by criteria.

For example:

th := throttled.Interval(throttled.PerSec(10), 100, &throttled.VaryBy{Path: true}, 50)
h := th.Throttle(myHandler)
http.ListenAndServe(":9000", h)

Creates a throttler that will allow a request each 100ms (10 requests per second), with a buffer of 100 exceeding requests before dropping requests with a status code 429 (by default, configurable using th.DeniedHandler or the package-global DefaultDeniedHandler variable). Different paths will be throttled independently, so that /path_a and /path_b both can serve 10 requests per second. The last argument, 50, indicates the maximum number of keys that the throttler will keep in memory.

MemStats

The MemStats function creates a throttler that allows requests to go through only if the memory statistics of the current process are below specified thresholds.

For example:

th := throttled.MemStats(throttled.MemThresholds(&runtime.MemStats{NumGC: 10}, 10*time.Millisecond)
h := th.Throttle(myHandler)
http.ListenAndServe(":9000", h)

Creates a throttler that will allow requests to go through until the number of garbage collections reaches the initial number + 10 (the MemThresholds function creates absolute memory stats thresholds from offsets). The second argument, 10ms, indicates the refresh rate of the memory stats.

RateLimit

The RateLimit function creates a throttler that allows a certain number of requests in a given time window, as is often implemented in public RESTful APIs.

For example:

th := throttled.RateLimit(throttled.PerMin(30), &throttled.VaryBy{RemoteAddr: true}, store.NewMemStore(1000))
h := th.Throttle(myHandler)
http.ListenAndServe(":9000", h)

Creates a throttler that will limit requests to 30 per minute, based on the remote address of the client, and will store the counter and remaining time of the current window in the provided memory store, limiting the number of keys to keep in memory to 1000. The store sub-package also provides a Redis-based Store implementations.

The RateLimit throttler sets the expected X-RateLimit-* headers on the response, and also sets a Retry-After header when the limit is exceeded.

Documentation

The API documentation is available as usual on godoc.org.

There is also a blog post explaining the package's usage on 0value.com.

Finally, many examples are provided in the /examples sub-folder of the repository.

License

The BSD 3-clause license. Copyright (c) 2014 Martin Angers and Contributors.

# Packages

No description provided by the author
Package store offers a memory-based and a Redis-based throttled.Store implementation.

# Functions

Custom creates a Throttler using the provided Limiter implementation.
Interval creates a throttler that controls the requests so that they go through at a constant interval.
MemStats creates a Throttler based on the memory statistics of the current process.
MemThresholds is a convenience function to create a thresholds memory stats from offsets to apply to the current memory stats.
RateLimit creates a throttler that limits the number of requests allowed in a certain time window defined by the Quota q.
RemainingSeconds is a helper function that returns the number of seconds remaining from an absolute timestamp in UTC.

# Variables

DefaultDeniedHandler handles the requests that were denied access because of a throttler.
The error returned if the key does not exist in the Store.
Error is the function to call when an error occurs on a throttled handler.

# Structs

Q represents a custom quota.
A Throttler controls access to HTTP handlers using a Limiter.
VaryBy defines the criteria to use to group requests.

# Interfaces

The Delayer interface defines the method to implement to describe a delay as required by the Interval throttler.
The Limiter interface defines the methods required to control access to a throttled handler.
The Quota interface defines the method to implement to describe a time-window quota, as required by the RateLimit throttler.
Store is the interface to implement to store the RateLimit state (number of requests per key, time-to-live or creation timestamp).

# Type aliases

D represents a custom delay.
ErrorFunc defines the function type for the Error variable.
PerDay represents a number of requests per day.
PerHour represents a number of requests per hour.
PerMin represents a number of requests per minute.
PerSec represents a number of requests per second.