funnel

README

Funnel

Intro

Funnel is a distributed rate limter for golang. The project depends on redis and a number of redis related libs in order to accomplish distributed limited access to a resource.

Why do I need a rate limiter?

A common use for a rate limiter could be consuming commercial APIs or limiting access to a shared resource that has a connection threshold. If you are consuming an API from a rate limited service, and you have reached the capacity, your requests will fail. It's much more convenient to use a rate limiter on the client than to try and implement retry logic that just hammers the endpoint until you have access.

Why wouldn't I use the Rate Limiter from the GoWiki?

Funnel is a distributed solution for limiting control to a resource, while the one provided in the wiki only works if the access is limited to one process. Their solution doesn't hold up for scenarios when you have more than one apps (processes) trying to reach a resource.

How do I use funnel?

ENVs

REDIS_URL ENV needs to be set

Funnel is packaged with a thin redis client wrapper, MeshRedis. This dependency sets up a connection to redis, and uses redis to coordinate the distributed locking and list inclusions.

If REDIS_URL is not found, it will defer to the common localhost address: redis://127.0.0.1:6379"

Setup

Funnel needs three pieces of infomation to help you limit access to a resource:

• Max requests for a given time interval
• The duration (time interval) for the limiter
• A token to uniquely identify the limted resource

import "github.com/meshhq/funnel"

func main() {
    limiterInfo := &funnel.RateLimitInfo{
            Token:        "uniqueToken",
            MaxRequests:  20,
            TimeInterval: 1000,
        }
    rateLimiter := funnel.NewLimiter(limiterInfo)    
}

Use

After funnel is initialized, all you have to do is call Enter(). If there is room in the limiter, Enter() will let the execution continue. If the limtiter has reached it's max capacity for a given time interval, it will block until the limiter has expired.

import "github.com/meshhq/funnel"

func main() {
    // Limiter is set to a max of 20 Requests / Second
    limiterInfo := &funnel.RateLimitInfo{
            Token:        "uniqueToken",
            MaxRequests:  20,
            TimeInterval: 1000,
        }
    rateLimiter := funnel.NewLimiter(limiterInfo)    

    // Send 41 requests
    for i := 0; i < 41; i++ {
        // Enter limiter
        rateLimiter.Enter()
        // (Make Request)
    }
    // At least two seconds will have elapsed when the loop finishes
    // There were never more than 20 requests per second
}

Contributing

PRs are welcome, but will be rejected unless test coverage is updated

• Taylor Halliday
• Kevin Coleman

Documentation

Index

• type RateLimitInfo
• type RateLimiter
  • func NewLimiter(limitInfo *RateLimitInfo) (*RateLimiter, error)
  • func (r *RateLimiter) Enter() error

Types

type RateLimitInfo

type RateLimitInfo struct {
	// Token is the unique token that is used for tracking the limited request
	Token string

	// MaxRequests represents the maximum amount of requests that can occur over the given time period
	MaxRequests int

	// TimeInterval represents the time duration that the max requests can take place inside of
	TimeInterval int64
}

RateLimitInfo is an inteface that provides the sufficient information to create a RateLimiter

type RateLimiter

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

RateLimiter controls the amount of concurrent requests from GoHttp. All time is in milliseconds

func NewLimiter

func NewLimiter(limitInfo *RateLimitInfo) (*RateLimiter, error)

NewLimiter is a factory method for creating a rate limiter

func (*RateLimiter) Enter

func (r *RateLimiter) Enter() error

Enter attempts to enter the request into the current pool