Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Golimit A Distributed Rate limiter

Golimit is Uber ringpop based distributed and decentralized rate limiter. It is horizontally scalable and is based on shared nothing architecture. Every node in system is capable of handling read and writes of counters. It is designed to offer sub milliseconds latency to caller application. Recommended deployment topology is sidecar model. Every golimit node keeps local and global counter for api counter and local value is synchronized with other nodes on configurable periodic interval or at defined threshold.


Http server provides http interface to increment counter against any arbitrary Key string. It also exposes admin api to manage global configurations.

Store encapsulates the data structure and functions to store, manage and replicate counters. Counter synchronisation is done in asynchronous way so the caller application is never blocked for cluster sync. Synchronizer module keeps aggregating counters in memory and broadcast to other nodes on periodic intervals or when the counter has crossed threshold. the interval and threshold are configurable.

StatsD Emitter pushes metrics to configured statsd server.

Block Diagram


Suggested deployment model is to have golimit installed as sidecar. This will ensure application latency to sub milliseconds level. For Go applications golimit can be directly integrated as a module, the way of using golimit as module is explained later in document. Using as module takes away the pain of deployment and maintenance.

Block Diagram


  1. Build

    $ GOOS=linux GOARCH=amd64 go build  //Linux
    $ GOOS=darwin GOARCH=amd64 go build //OSX 
    $ GOOS=windows GOARCH=amd64 go build //Windows
  2. Configure

    Yml config

        clustername:  MyGolimitCluster # Cluster Name
        tchannelport: 2345 # Ringpop T Channel Port
        seed: "" # Seed node of cluster
        unsyncedctrlimit: 5  # Unsynced counter limit
        unsyncedtimelimit: 60000 # unsynced timeout in ms
        httpport: 8080  # Http server port
        statsdenabled: true # Enable statsd 
        statsdhostport: ""  # statsd host port
        statsdsamplerate: 1 # Statsd sampling rate
        apisecret: alpha # secret key to use admin apis
        hostname: ""
        unixsocketenable: true #enables unix socket,
                               #gives nearly 2x better performance in response time 
                               #when enabled tcp port config will be ignored and disabled 
        unixsocket: /tmp/golimit.sock #unix socket file location

    Note: Ensure the seed node is always reachable.

  3. Run

    $ ./golimitV3 --config=./golimitconfig.yml
  4. Use from Http Apis

    Param Description
    K Key a string, against this the counters are calculated
    C Count in number, numbers to increment in one api call, defaults to 1
    W Window in seconds, time window for which provided threshold is applicable
    T Threshold in number
    P PeakAveraged 0 or 1, if P=1 the provided rate limit is transposed to per second limit and then applied
    • INCR Request

      Application passes Key threshold and window and reply is block or not. This rate limiting is application driven as application has to pass all rate configuration in every call In following example second curl within 10 seconds gives back blocked =true

      $  curl -X POST "http://localhost:8080/incr?K=abc&T=1&W=10" 
      $  curl -X POST "http://localhost:8080/incr?K=abc&T=1&W=10" 
    • Create/Update global rate configuration, this is for rate limiting which is golimit cluster driven

      $ curl -X PUT  "http://localhost:8080/rate" -d '{"Window":60,"Limit":5,"Key":"a","PeakAveraged":false}' -H "apisecret: alpha" 
      $ curl -X POST  "http://localhost:8080/ratelimit?K=a" 
      # after 5 times
      # {"Block":true}
    • Ratelimit Request

       $ curl -X POST  "http://localhost:8080/ratelimit?K=a" 
    • Get All defined Rate Config

      $ curl  "http://localhost:8080/rateall" 
    • Get a specific Rate Config

      $ curl  "http://localhost:8080/rate?K=a" 
    • Get Cluster Info

      $ curl  "http://localhost:8080/clusterinfo" 
  5. Use as Go module

    If application is in golang, golimit can be used as module directly instead of deploying as separate process.

    To install library:

    go get

    package main
    import ("")
    func main() {
        //Instantiate Store object, Use single store instance in one application
        store := store.NewStore()
        blocked := store.Incr("key", 1, 1000, 60, true) // Increment api
        if (blocked) {
        //Ensure Store is closed on program exit


Golimit is Uber ringpop based distributed and decentralized rate limiter





No releases published


No packages published