fine_tune 0.1.0 → 0.3.0

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3-p194

data/.travis.yml

@@ -1,5 +1,5 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.1.8
+  - 1.9.3
 before_install: gem install bundler -v 1.12.5

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Laknath
+Copyright (c) 2016 Vesess Inc. (laknath [at] vesess [dot] com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,41 +1,109 @@
-# FineTune
+[![Build Status](https://travis-ci.org/laknath/fine_tune.svg?branch=master)](https://travis-ci.org/laknath/fine_tune)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/fine_tune`. To experiment with that code, run `bin/console` for an interactive prompt.
+# FineTune - a flexible rate limiting/monitoring library
 
-TODO: Delete this and the text above, and describe your gem
+FineTune can be used to limit the rate of any given activity/event 
+stream such as outgoing emails for a user. It's not fixed on a
+particular implementation of throttling, rather it provides a framework
+to add custom implementations/algorithms.
+
+The main difference with other rate limiting libraries is the
+flexibility of using custom throttling algorithms and external
+data/cache stores. Also it doesn't need to be configured first, all
+options can be passed in each throttling request.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+    $ gem install fine_tune
 
-```ruby
-gem 'fine_tune'
-```
+## Usage
 
-And then execute:
+Throttle represents an occurrence of a defined event. It will return true
+if the threshold has reached. If not the count will be increased by one
+and will return false.
 
-    $ bundle
+  ```
+  $ FineTune.throttle(:transactions_per_hour, user_id, options)
+  ```
 
-Or install it yourself as:
+  * :transactions_per_hour - the name for the event
+  * user_id - some unique identifier for a resource (ie: user)
+  * options - configurations for the throttling implementation
 
-    $ gem install fine_tune
+An additional block can be passed, which will be called with event
+details. ie:
 
-## Usage
+  ```
+  $ FineTune.throttle(:transactions_per_hour, user_id, options) do 
+                                | count, comparison, id, strategy, options |
+        #something...
+    end
+  ```
+  
+In addition, there's a more charged version - throttle! which will raise
+a MaxRateError when reached the threshold. Same as throttle, it takes a 
+block.
 
-TODO: Write usage instructions here
+  ```
+  $ FineTune.throttle!(:transactions_per_hour, user_id, options)
+  ```
 
-## Development
+To get the current count of events:
+
+  ```
+  $ FineTune.count(:emails_per_day, user_id, options)
+  ```
+
+To check whether threshold has reached:
+
+  ```
+  $ FineTune.rate_exceeded?(:emails_per_day, user_id, options)
+  ```
+
+To reset the count of events for a resource:
+
+  ```
+  $ FineTune.reset(:emails_per_day, user_id, options)
+  ```
+
+###(Optional)
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+To configure default options:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+  ```
+    $ FineTune.add_limit(:hourly_emails, window: 3600, limit: 25)
+  ```
+Options passed here will be overridden by any options passed in
+the individual calls.
+
+To remove a pre-defined rule:
+
+  ```
+    $ FineTune.remove_limit(:hourly_emails, window: 3600, limit: 25)
+  ```
+
+###Supported implementations:
+
+  * [Leaky Bucket algorithm](https://en.wikipedia.org/wiki/Leaky_bucket)
+
+
+## Development
+
+After checking out the repo, run `bundle` to install dependencies. Then, run `rake test` to run the tests. 
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fine_tune. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/laknath/fine_tune. This project
+is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to 
+the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Credits
+
+Some of the behaviours were inspired by [Props](https://github.com/zendesk/prop). 
+
+Thanks you!
 
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/fine_tune.gemspec

@@ -17,9 +17,10 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "minitest-reporters", "~> 1.1.9"
-  spec.add_development_dependency "mocha", "~> 0.14.0"
+  spec.add_development_dependency "minitest-reporters", "~> 1.1"
+  spec.add_development_dependency "mocha", "~> 0.14"
+  spec.add_development_dependency "activesupport", "~> 4.2"
 end

data/lib/fine_tune/base.rb

@@ -1,15 +1,69 @@
+#
+# FineTune::Base provides a set of public methods and helpers to throttle
+# and fetch the event count through a singleton object. The mechanism used to
+# throttle and event counting is delegated to the defined strategy.
+#
+# Strategies can be defined for the entire library through 
+# FineTune.default_strategy=. Strategy can also be defined for each 
+# throttling call by passing <tt>:strategy</tt> option.
+#
+# Additionally, the datastore used to maintain event counts can be
+# also customized by setting FineTune.adapter=. It takes an 
+# ActiveSupport::Cache::Store[http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html] 
+# as an adapter.
+
 module FineTune
   class Base
     include Singleton
 
-    class << self; attr_accessor :default_strategy; end
+    class << self; 
+      # Used to set a default strategy for all calls.
+      attr_accessor :default_strategy
+
+      # Used to set the external data store.
+      attr_accessor :adapter
+
+      def registry #:nodoc:
+        @@registry
+      end
+
+      def find_strategy(strategy) #:nodoc:
+        registry.fetch(strategy, default_strategy).instance
+      end
+    end
 
+    # Currently supported strategies:
+    # * Leaky bucket algorithm
     @@registry = {
       :leaky_bucket => ::FineTune::Strategies::LeakyBucket,
       :sliding_window => ::FineTune::Strategies::SlidingWindow
     }
     @default_strategy = ::FineTune::Strategies::LeakyBucket
 
+    # Calling throttle represents an occurance of an event.
+    # Depends on the strategy used for the actual calculations.
+    # Returns true if the event should be throttled.
+    #
+    # ==== Attributes
+    #
+    # * +name+ - Name of the rule ie: emails_sent
+    # * +id+ - Identifier for a specific resource ie: abc@example.com
+    # * +options+ - Options for the strategy. Depends on the strategy choosen
+    #
+    # ==== Options
+    #
+    # * +:strategy+ - The strategy chosen. Valid options are:
+    #   - leaky_bucket
+    #
+    # Optionally, a block can be passed and it will be called with 
+    # calculated values
+    #
+    # ==== Examples
+    #   FineTune.throttle(:emails_sent, "abc@example.com",
+    #     {strategy: :leaky_bucket}) do |count, comparison, key, strategy, options|
+    #       # some calculation ...
+    #     end
+
     def throttle(name, id, options)
       strategy, key, options = current_strategy(name, id, options)
       count = strategy.increment(key, options)
@@ -20,46 +74,72 @@ module FineTune
       comp >= 0
     end
 
-    def throttle!(name, id, options)
-      block = Proc.new if block_given?
+    # The more forceful variant of throttle. Will raise a MaxRateError if the 
+    # defined threshold is exceeds.
+    #
+    # Attributes and options are same as for +throttle+.
 
-      throttle(name, id, options) do |count, comp, key, strategy, options|
-        block.call(count, comp, key, strategy, options) if block
+    def throttle!(name, id, options)
+      throttle(name, id, options) do |count, comp, key, strategy, opts|
+        yield count, comp, key, strategy, opts if block_given?
 
-        raise MaxRateError.new(key, count, comp, strategy, options) if comp >= 0
+        raise MaxRateError.new(key, count, comp, strategy, opts) if comp >= 0
       end
     end
 
+    # Returns true if current count exceeds the given limits.
+    #
+    # Attributes and options are same as for +throttle+.
     def rate_exceeded?(name, id, options)
       strategy, key, options = current_strategy(name, id, options)
       strategy.compare?(strategy.count(key, options), options) >= 0
     end
 
+    # Returns the current event count.
+    #
+    # Attributes and options are same as for +throttle+.
     def count(name, id, options)
       strategy, key, options = current_strategy(name, id, options)
       strategy.count(key, options)
     end
 
+    # Resets the counter for the given resource identifer to 0.
+    #
+    # Attributes and options are same as for +throttle+.
     def reset(name, id, options)
       strategy, key, options = current_strategy(name, id, options)
       strategy.reset(key, options)
     end
 
+    # Adds a preconfigured rule and options to the rule. These configs 
+    # can be overridden by passing different option values later when
+    # calling +throttle+.
+    #
+    # ==== Attributes
+    #
+    # * +name+ - Name of the rule ie: emails_sent
+    # * +options+ - Default options for the rule
+    #
+    # ==== Examples
+    #   FineTune.add_limit(:emails_sent_per_hour, {window: 3600})
+    #
     def add_limit(name, options = {})
       limits[name] ||= {}
       limits[name].merge!(options)
     end
 
+    # Removes a preconfigured rule and options.
     def remove_limit(name)
       limits.delete(name)
     end
 
+    # Returns all default limits defined
     def limits
       @limits ||= {}
     end
 
     private
-    def current_strategy(name, id, options)
+    def current_strategy(name, id, options) #:nodoc:
       options = (limits[name] || {}).merge(options)
       strategy = self.class.find_strategy(options[:strategy])
 
@@ -71,13 +151,5 @@ module FineTune
 
       [strategy, key, options]
     end
-
-    def self.find_strategy(strategy)
-      registry.fetch(strategy, default_strategy).instance
-    end
-
-    def self.registry
-      @@registry
-    end
   end
 end

data/lib/fine_tune/max_rate_error.rb

@@ -1,4 +1,5 @@
 module FineTune
+  # MaxRateError is thrown when a defined limit has reached
   class MaxRateError < StandardError
     attr_accessor :key, :comparison, :count, :strategy, :options  
 

data/lib/fine_tune/strategies/base.rb

@@ -1,5 +1,11 @@
 module FineTune
   module Strategies
+    # This class is only for the purpose of extending and implementing
+    # own strategies. Any subclass should implement:
+    # * +identifier+
+    # * +increment+
+    # * +count+
+    # * +reset+
     class Base
       include Singleton
 
@@ -8,7 +14,15 @@ module FineTune
       end
 
       def build_key(name, id, options)
-        [name, id].flatten.join('-')
+        [:fine_tune, name, identifier, id].flatten.join('/')
+      end
+
+      def adapter
+        FineTune.adapter
+      end
+
+      def identifier
+        raise "not defined"
       end
 
       def increment(key, options)
@@ -20,7 +34,11 @@ module FineTune
       end
 
       def validate?(options)
-        false
+        if adapter.nil?
+          raise "no adapter given"
+        end
+
+        true
       end
 
       def reset(key, options)

data/lib/fine_tune/strategies/leaky_bucket.rb

@@ -1,6 +1,132 @@
 module FineTune
   module Strategies
+
+    # Implements {LeakyBucket algorithm}[https://en.wikipedia.org/wiki/Leaky_bucket]
+    # as a FineTune::Strategy.
     class LeakyBucket < Base
+
+      class << self
+        # Set default values for window, average and maximum values so
+        # they won't need to be passed in every call
+        attr_accessor :default_window, :default_average, :default_maximum
+      end
+
+      # compares the count given and the burst value.
+      # Returns 0 if equal, -1 less and 1 greater
+      #
+      # ====== Attributes
+      #
+      # * +count+ - the current count
+      # * +options+ - Optional if default_maximum is set
+      #
+      # ====== Options
+      # * +:maximum - can be used to override default_maximum
+      def compare?(count, options)
+        count <=> maximum(options)
+      end
+
+      # Returns the current count incremented by one if it does not exceed the 
+      # maximum value given. If it exceeds the maximum value, then it returns
+      # the maximum value.
+      #
+      # ====== Attributes
+      #
+      # * +key+ - the identifier for the resource in cache store
+      # * +options+ - Optional if default_maximum, default_window and default_average set
+      #
+      # ====== Options
+      # * +:maximum+ - can be used to override default_maximum ie: 20
+      # * +:average+ - can be used to override default_average ie: 10
+      # * +:window+ - can be used to override default_window  ie: 3600 (one hour)
+      def increment(key, options)
+        count = count(key, options)
+        count = [maximum(options), count + 1].min
+        adapter.write(key, {count: count, timestamp: Time.now.to_i})
+        count
+      end
+
+      # Returns the current count after discounting for the time since
+      # last access.
+      #
+      # Attributes and options are same as +increment+
+      def count(key, options)
+        resource = adapter.fetch(key, options) do
+          zero_counts
+        end
+
+        loss = loss(Time.now.to_i, resource[:timestamp], average(options),
+                    window(options))
+        count = resource[:count] - loss
+        count > 0 ? count : 0
+      end
+
+      # Validates the options given. Window, average and maximum values must be set 
+      # either through default values or the options
+      #
+      # Options are same as +increment+
+      def validate?(options)
+        super(options)
+        error = nil
+        window, average, maximum = window(options), average(options), maximum(options)
+
+        error = if !window || !average || !maximum
+          "window, average and maximum options are required"
+        elsif !positive_integer?(window)
+          "time window must be a positive integer"
+        elsif !non_negative_numeric?(average)
+          "average should be non negative numbers"
+        elsif maximum < average
+          "maximum should not be less than the average"
+        end
+
+        raise ArgumentError.new(error) if error
+
+        true
+      end
+
+      # Reset the count of the resource identified by the key to 0.
+      #
+      # ====== Attributes
+      #
+      # * +key+ - the identifier for the resource in cache store
+      def reset(key, options)
+        adapter.write(key, zero_counts)
+      end
+
+      def identifier #:nodoc:
+        :leaky_bucket
+      end
+
+      # calculates the loss given an average, window and a time interval
+      def loss(now, last_accessed, average, window)
+        loss = ((now - last_accessed) * average).to_f/window
+        loss > 0 ? loss : 0
+      end
+
+      private
+      def zero_counts #:nodoc:
+        {count: 0, timestamp: Time.now.to_i}
+      end
+
+      def window(options) #:nodoc:
+        options[:window] || self.class.default_window
+      end
+
+      def average(options) #:nodoc:
+        options[:average] || self.class.default_average
+      end
+
+      def maximum(options) #:nodoc:
+        options[:maximum] || options[:limit] || self.class.default_maximum
+      end
+
+      def positive_integer?(e) #:nodoc:
+        e.is_a?(Integer) && e > 0
+      end
+
+      def non_negative_numeric?(e) #:nodoc:
+        e.is_a?(Numeric) && e >= 0
+      end
     end
   end
 end

data/lib/fine_tune/version.rb

@@ -1,3 +1,3 @@
 module FineTune
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/fine_tune.rb

@@ -1,3 +1,8 @@
+#
+# Author:: Laknath Semage (blaknath at gmail dot com)
+# Copyright:: Copyright (c) 2016 Vesess Inc.
+# License:: MIT License
+
 require "fine_tune/version"
 require 'singleton'
 require "forwardable"
@@ -8,11 +13,18 @@ end
 require "fine_tune/base"
 require "fine_tune/max_rate_error"
 
+##
+# FineTune helps throttle any kind of event sequence. It also supports 
+# custom throttling strategies using a common API. By default
+# it supports LeakyBucket[https://en.wikipedia.org/wiki/Leaky_bucket] algorithm.
+
 module FineTune
   class << self
     extend Forwardable
-    def_delegators :"FineTune::Base.instance", :adapter, :adapter=, :count,
-                    :reset, :throttle, :throttle!, :add_limit, :remove_limit, :rate_exceeded?
+    def_delegators :"FineTune::Base.instance", :count, :reset, :throttle, 
+                    :throttle!, :add_limit, :remove_limit, :rate_exceeded?
+    def_delegators :"FineTune::Base", :adapter, :adapter=, :default_strategy,
+                    :default_strategy=
   end
 end
 

metadata

@@ -1,85 +1,112 @@
 --- !ruby/object:Gem::Specification
 name: fine_tune
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
+  prerelease: 
 platform: ruby
 authors:
 - Laknath Semage
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-27 00:00:00.000000000 Z
+date: 2016-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
   name: minitest-reporters
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 1.1.9
+        version: '1.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 1.1.9
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: '0.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.2'
 description: A rate limiter without the worst case throttling of two times the defined
   threshold.
 email:
@@ -88,8 +115,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".travis.yml"
+- .gitignore
+- .ruby-version
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -105,25 +133,26 @@ files:
 homepage: https://github.com/vesess/fine_tune
 licenses:
 - MIT
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.5
+rubygems_version: 1.8.23
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Limits rate of a given event sequence with defined strategies.
 test_files: []

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 084b2f0a33fb235fae26629c06c4d3ea49832456
-  data.tar.gz: 36428f60b499e91fca15c2208edbb93b2ae21ec2
-SHA512:
-  metadata.gz: ef657f44b8ccc3516998568101b3192103f0591a81171875bf626718137d88ae2a79c804ac47893fa0d42abad4f34cebf3ee0dcad12db9ebfc52c2ed9d57d130
-  data.tar.gz: e41b1821a9e08b4d3323e7fc52a66ce353a3669946444c8316997a2988e5bca99dc0f93ef807f9a3c5e1131e7a98d4367f1555a6d2d2f6fb21829f304c9f3367