CrossClj

0.1.1 docs

SourceDocs



RECENT

    cooler

    Clojars

    Apr 18, 2017


    OWNER
    Dylan Paris
    Portland, OR

    Readme

    Index of all namespaces


    « Project + dependencies

    A distributed rate-limiting library based on the GCRA algorithm.

    cooler.coreDocsSource
    Clojure rate-limiting library.
    
    cooler.rate-limiter.coreDocsSource
    Core definition of RateLimiter protocol and related functionality.
    
    cooler.rate-limiter.gcraDocsSource
    Implementation of GCRA rate limiting algorithm. For more details,
    see the following links:
    
    * https://brandur.org/rate-limiting
    * https://github.com/throttled/throttled
    * https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm
    
    Credit to Brandur Leach and Andrew Metcalf for their work in implementing
    GCRA in the throttled library, upon which this implementation is based.
    cooler.schemas.rate-limit-resultDocsSource
    Schema which validates the result of calling rate-limit on
    an object which implements the RateLimiter protocol.
    cooler.schemas.rate-unitDocsSource
    Schema which validates a rate limit quota unit.
    
    cooler.store.coreDocsSource
    Core definition of RateLimitStore protocol and related functionality.
    
    cooler.store.redisDocsSource
    Implementation of RateLimitStore which uses Redis as a backing store.
    Requires at least redis 2.6, as it makes use of PEXPIRE to provide
    millisecond resolution for TTL values.
    The README below is fetched from the published project artifact. Some relative links may be broken.

    cooler

    A Clojure rate limiting library which provides GCRA-based distributed limiting backed by Redis.

    The Cooler

    I want you to be nice… until it’s time to not be nice.

    Clojars Project

    Usage

    (ns user
      (:require [cooler.core :as c]
                [cooler.rate-limiter.core :as crl]
                [cooler.store.redis :as csr))
    
    ;; Define a map of redis connection options. This follows the same format used
    ;; by the (awesome) clojure redis library carmine:
    ;; https://github.com/ptaoussanis/carmine#connections
    (def conn-opts
      {:pool {}
       :spec {}})
    
    ;; Define a redis store and a rate-limiter backed by that store with a quota
    ;; of 30 requests per minute
    (def redis-store (csr/make-redis-store conn-opts))
    (def rate-limiter (c/rate-limiter redis-store 30 :minute))
    
    
    ;; The rate-limit method will return a RateLimitResult map which can be used
    ;; to determine the correct rate limiting action to take. 
    (crl/rate-limit rate-limiter "test-limit" 1) ;; => {:limited?        false
                                                 ;;     :limit           1
                                                 ;;     :remaining       0
                                                 ;;     :reset-after-mus 2000000
                                                 ;;     :retry-after-mus nil}
    
    ;; Called again within two seconds
    (crl/rate-limit rate-limiter "test-limit" 1) ;; => {:limited?        true
                                                 ;;     :limit           1
                                                 ;;     :remaining       0
                                                 ;;     :reset-after-mus 1286882
                                                 ;;     :retry-after-mus 1286882}
                                                        
    ;; Since the second request exceeded the rate-limiter's quota, the second result
    ;; indicates that:
    ;;
    ;;   * The request was rate limited
    ;;   * The quota request pool will reset back to the limit (in this case just one) after ~1.2 seconds
    ;;   * The next request which won't be limited is estimated to occur in ~1.2 seconds
    
    

    Project Status

    Important! - This library is still in early development. Please be careful!

    That said, I will be using this library in a forthcoming commercial product, so I expect any issues found will be fixed in short order. The current test coverage is equivalent to the tests performed by the golang The Rainmaker Group for sponsoring the development of this library. If you’re interested in professional Clojure development, check out the careers page for potential openings.

    License

    Copyright © 2016 Dylan Paris

    Distributed under the MIT License