speedbump: github.com/etcinit/speedbump Index | Examples | Files | Directories

package speedbump

import "github.com/etcinit/speedbump"

Package speedbump provides a Redis-backed rate limiter.

Index

Examples

Package Files

hashers.go speedbump.go

type PerHourHasher Uses

type PerHourHasher struct {
    Clock clock.Clock
}

PerHourHasher generates hashes per hour. This means you can keep track of N request per hour.

func (PerHourHasher) Duration Uses

func (h PerHourHasher) Duration() time.Duration

Duration gets the duration of each period.

func (PerHourHasher) Hash Uses

func (h PerHourHasher) Hash(id string) string

Hash generates the hash for the current period and client.

type PerMinuteHasher Uses

type PerMinuteHasher struct {
    Clock clock.Clock
}

PerMinuteHasher generates hashes per minute. This means you can keep track of N request per minute.

func (PerMinuteHasher) Duration Uses

func (h PerMinuteHasher) Duration() time.Duration

Duration gets the duration of each period.

func (PerMinuteHasher) Hash Uses

func (h PerMinuteHasher) Hash(id string) string

Hash generates the hash for the current period and client.

type PerSecondHasher Uses

type PerSecondHasher struct {
    // Clock is the time reference that will be used by the hasher. If it is
    // not provided, the hashing function will use the default time. This can
    // be replaced with a mock clock object for testing.
    Clock clock.Clock
}

PerSecondHasher generates hashes per second. This means you can keep track of N request per second.

The following example shows how to create mock hashers for testing the rate limiter in your code:

Code:

// Create a mock clock.
mock := clock.NewMock()

// Create a new per second hasher with the mock clock.
hasher := PerMinuteHasher{
    Clock: mock,
}

// Generate two consecutive hashes. On most systems, the following should
// generate two identical hashes.
hashOne := hasher.Hash("127.0.0.1")
hashTwo := hasher.Hash("127.0.0.1")

// Now we push the clock forward by a minute (time travel).
mock.Add(time.Minute)

// The third hash should be different now.
hashThree := hasher.Hash("127.0.0.1")

fmt.Println(hashOne == hashTwo)
fmt.Println(hashOne == hashThree)

Output:

true
false

func (PerSecondHasher) Duration Uses

func (h PerSecondHasher) Duration() time.Duration

Duration gets the duration of each period.

func (PerSecondHasher) Hash Uses

func (h PerSecondHasher) Hash(id string) string

Hash generates the hash for the current period and client.

type RateHasher Uses

type RateHasher interface {
    // Hash is the hashing function.
    Hash(id string) string
    // Duration returns the duration of each period. This is used to determine
    // when to expire each counter key, and can also be used by other libraries
    // to generate messages that provide an estimate of when the limit will
    // expire.
    Duration() time.Duration
}

RateHasher is an object capable of generating a hash that uniquely identifies a counter to track the number of requests for an id over a certain time interval. The input of the Hash function can be any unique id, such as an IP address.

type RateLimiter Uses

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

RateLimiter is a Redis-backed rate limiter.

func NewLimiter Uses

func NewLimiter(
    client *redis.Client,
    hasher RateHasher,
    max int64,
) *RateLimiter

NewLimiter creates a new instance of a rate limiter.

Code:

// Create a Redis client.
client := createClient()

// Create a new hasher.
hasher := PerSecondHasher{}

// Create a new limiter that will only allow 10 requests per second.
limiter := NewLimiter(client, hasher, 10)

fmt.Println(limiter.Attempt("127.0.0.1"))

Output:

true <nil>

func (*RateLimiter) Attempt Uses

func (r *RateLimiter) Attempt(id string) (bool, error)

Attempt attempts to perform a request for an id and returns whether it was successful or not.

func (*RateLimiter) Attempted Uses

func (r *RateLimiter) Attempted(id string) (int64, error)

Attempted returns the number of attempted requests for an id in the current period. Attempted does not count attempts that exceed the max requests in an interval and only returns the max count after this is reached.

func (*RateLimiter) Has Uses

func (r *RateLimiter) Has(id string) (bool, error)

Has returns whether the rate limiter has seen a request for a specific id during the current period.

func (*RateLimiter) Left Uses

func (r *RateLimiter) Left(id string) (int64, error)

Left returns the number of remaining requests for id during a current period.

Directories

PathSynopsis
ginbumpPackage ginbump provides an example Speedbump middleware for the Gin framework.
negronibump

Package speedbump imports 4 packages (graph) and is imported by 16 packages. Updated 2016-12-27. Refresh now. Tools for package owners.