freno-client 0.3.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ad998991ce9e268582944b14bcad1f95b3f256ae
-  data.tar.gz: 858a1e5eab82112e90e44559cc64f14a57eef065
+SHA256:
+  metadata.gz: 3f680a8adbf86c47eff50bcc58ae7b79993ef3f2f3c57ad99c9512937f92ba80
+  data.tar.gz: 50cf87848d1284d171457112ed5a297fd063532f78ef0399e5d669b1bc3ded33
 SHA512:
-  metadata.gz: d550f31be8158f7ec916d3b76475c8ec15e04e6039cc34473049ad276097397df72c1139bfd421175b1792eba997763fffadcd9023d4860eef6096f23040d024
-  data.tar.gz: c6c3826a47449958d2030fc8f8904eeba9cee2aeb72890fa6803d0c287542c13814df6934b0b47d03cb418544cef7a856623591700b4d149ca5ba4df0edd261b
+  metadata.gz: 6037e296652844e51cb469d3d6ca6dbb55e2baaa08c8c726b2885ad1b3ba6dd21857a85562d5b1491fb6b6cb86859ddc5fec0420f05089bb0c871c6ac69713cb
+  data.tar.gz: 352a0abcea1e4fb28d2e920812a1d95a8051b62e52ff8a1cbaf05340aff3409150ad74d6292461908e4c7a9408dce7507910ff6ae4448f7cf62a9f1c048cd0f9

data/.gitignore

@@ -8,6 +8,5 @@
 /pkg/
 /spec/reports/
 /tmp/
-/bin/
 /vendor/gems
 .ruby-version

data/.rubocop.yml

@@ -0,0 +1,179 @@
+require: rubocop-performance
+
+AllCops:
+  DisabledByDefault: true
+  TargetRubyVersion: 2.5
+
+Bundler/DuplicatedGem:
+  Enabled: true
+Bundler/OrderedGems:
+  Enabled: true
+
+Layout/BlockAlignment:
+  Enabled: true
+Layout/BlockEndNewline:
+  Enabled: true
+Layout/ConditionPosition:
+  Enabled: true
+Layout/DefEndAlignment:
+  Enabled: true
+Layout/EndOfLine:
+  Enabled: true
+Layout/IndentationStyle:
+  Enabled: true
+Layout/InitialIndentation:
+  Enabled: true
+Layout/SpaceAfterColon:
+  Enabled: true
+Layout/SpaceAfterComma:
+  Enabled: true
+Layout/SpaceAfterMethodName:
+  Enabled: true
+Layout/SpaceAfterNot:
+  Enabled: true
+Layout/SpaceAfterSemicolon:
+  Enabled: true
+Layout/SpaceAroundBlockParameters:
+  Enabled: true
+Layout/SpaceAroundEqualsInParameterDefault:
+  Enabled: true
+Layout/SpaceInsideArrayPercentLiteral:
+  Enabled: true
+Layout/SpaceInsideParens:
+  Enabled: true
+Layout/SpaceInsideRangeLiteral:
+  Enabled: true
+Layout/TrailingEmptyLines:
+  Enabled: true
+Layout/TrailingWhitespace:
+  Enabled: true
+
+Lint/CircularArgumentReference:
+  Enabled: true
+Lint/Debugger:
+  Enabled: true
+Lint/DeprecatedClassMethods:
+  Enabled: true
+Lint/DuplicateHashKey:
+  Enabled: true
+Lint/DuplicateMethods:
+  Enabled: true
+Lint/EachWithObjectArgument:
+  Enabled: true
+Lint/ElseLayout:
+  Enabled: true
+Lint/EmptyEnsure:
+  Enabled: true
+Lint/EmptyInterpolation:
+  Enabled: true
+Lint/EnsureReturn:
+  Enabled: true
+Lint/FlipFlop:
+  Enabled: true
+Lint/FloatOutOfRange:
+  Enabled: true
+Lint/FormatParameterMismatch:
+  Enabled: true
+Lint/LiteralInInterpolation:
+  Enabled: true
+Lint/Loop:
+  Enabled: true
+Lint/NextWithoutAccumulator:
+  Enabled: true
+Lint/RandOne:
+  Enabled: true
+Lint/RedundantSplatExpansion:
+  Enabled: true
+Lint/RedundantStringCoercion:
+  Enabled: true
+Lint/RequireParentheses:
+  Enabled: true
+Lint/RescueException:
+  Enabled: true
+Lint/UnderscorePrefixedVariableName:
+  Enabled: true
+Lint/UnreachableCode:
+  Enabled: true
+Lint/UselessComparison:
+  Enabled: true
+Lint/UselessSetterCall:
+  Enabled: true
+Lint/Void:
+  Enabled: true
+
+Naming/AsciiIdentifiers:
+  Enabled: true
+Naming/ClassAndModuleCamelCase:
+  Enabled: true
+Naming/FileName:
+  Enabled: true
+Naming/MethodName:
+  Enabled: true
+
+Performance/Count:
+  Enabled: true
+Performance/Detect:
+  Enabled: true
+Performance/DoubleStartEndWith:
+  Enabled: true
+Performance/EndWith:
+  Enabled: true
+Performance/FlatMap:
+  Enabled: true
+Performance/RedundantMerge:
+  Enabled: true
+  MaxKeyValuePairs: 1
+Performance/ReverseEach:
+  Enabled: true
+Performance/Size:
+  Enabled: true
+Performance/StartWith:
+  Enabled: true
+
+Security/Eval:
+  Enabled: true
+
+Style/ArrayJoin:
+  Enabled: true
+Style/BeginBlock:
+  Enabled: true
+Style/BlockComments:
+  Enabled: true
+Style/CaseEquality:
+  Enabled: true
+Style/CharacterLiteral:
+  Enabled: true
+Style/ClassMethods:
+  Enabled: true
+Style/DefWithParentheses:
+  Enabled: true
+Style/EndBlock:
+  Enabled: true
+Style/For:
+  Enabled: true
+Style/HashSyntax:
+  Enabled: true
+  EnforcedStyle: ruby19
+Style/LambdaCall:
+  Enabled: true
+Style/MethodCallWithoutArgsParentheses:
+  Enabled: true
+Style/MethodDefParentheses:
+  Enabled: true
+Style/MultilineIfThen:
+  Enabled: true
+Style/NilComparison:
+  Enabled: true
+Style/Not:
+  Enabled: true
+Style/OneLineConditional:
+  Enabled: true
+Style/RedundantSortBy:
+  Enabled: true
+Style/Sample:
+  Enabled: true
+Style/StabbyLambdaParentheses:
+  Enabled: true
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes

data/.travis.yml

@@ -1,5 +1,10 @@
-sudo: false
 language: ruby
 rvm:
-  - 2.4.1
-before_install: gem install bundler -v 1.14.6
+  - 2.5
+  - 2.6
+  - 2.7
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+script: bin/test

data/CONTRIBUTING.md

@@ -11,9 +11,9 @@ Please note that this project is released with a [Contributor Code of Conduct][c
 
 ## Submitting a pull request
 
-0. [Fork][fork] and clone the freno-clientsitory
-0. Configure and install the dependencies: `script/bootstrap`
-0. Make sure the tests pass on your machine: `rake`
+0. [Fork][fork] and clone the freno-client repository
+0. Configure and install the dependencies: `bin/setup`
+0. Make sure the tests pass on your machine: `bin/test`
 0. Create a new branch: `git checkout -b my-branch-name`
 0. Make your change, add tests, and make sure the tests still pass
 0. Push to your fork and [submit a pull request][pr]

data/Gemfile

@@ -1,3 +1,14 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 gemspec
+
+group :development do
+  gem "rake"
+end
+
+group :test do
+  gem "minitest", ">= 5"
+  gem "mocha"
+  gem "rubocop", "~> 0.85.1", require: false
+  gem "rubocop-performance", require: false
+end

data/README.md

@@ -1,6 +1,6 @@
-# Freno::Client
+# Freno Client [![Build Status](https://travis-ci.org/github/freno-client.svg?branch=master)](https://travis-ci.org/github/github/freno-client)
 
-A ruby client for [Freno](https://github.com/github/freno): the cooperative, highly available throttler service.
+A ruby client and throttling library for [Freno](https://github.com/github/freno): the cooperative, highly available throttler service.
 
 ## Current status
 
@@ -29,7 +29,7 @@ Or install it yourself as:
 To start using the client, give it a faraday instance pointing to Freno's base URL.
 
 ```ruby
-require 'freno/client'
+require "freno/client"
 
 FRENO_URL = "http://freno.domain.com:8111"
 faraday   = Faraday.new(FRENO_URL)
@@ -175,10 +175,187 @@ freno = Freno::Client.new(faraday) do |client|
 end
 ```
 
+### Throttler objects
+
+Apart from the operations above, freno-client comes with `Freno::Throttler`, a ruby library for throttling. You can use it in the following way:
+
+```ruby
+require "freno/throttler"
+
+client    = Freno::Client.new(faraday)
+throttler = Freno::Throttler.new(client: client, app: :my_app)
+context   = :my_cluster
+
+bid_data_set.each_slice(SLICE_SIZE) do |slice|
+  throttler.throttle(context) do
+    update(slice)
+  end
+end
+```
+
+In the above example, `Freno::Throttler#throttle(context, &block)` will check freno to determine whether is OK to proceed with the given block. If so, the block will be executed immediately, otherwise the throttler will sleep and try
+again.
+
+#### Throttler configuration
+
+```ruby
+module Freno
+  class Throttler
+
+    DEFAULT_WAIT_SECONDS = 0.5
+    DEFAULT_MAX_WAIT_SECONDS = 10
+
+    def initialize(client: nil,
+                    app: nil,
+                    mapper: Mapper::Identity,
+                    instrumenter: Instrumenter::Noop,
+                    circuit_breaker: CircuitBreaker::Noop,
+                    wait_seconds: DEFAULT_WAIT_SECONDS,
+                    max_wait_seconds: DEFAULT_MAX_WAIT_SECONDS)
+
+
+      @client           = client
+      @app              = app
+      @mapper           = mapper
+      @instrumenter     = instrumenter
+      @circuit_breaker  = circuit_breaker
+      @wait_seconds     = wait_seconds
+      @max_wait_seconds = max_wait_seconds
+
+      yield self if block_given?
+
+      validate_args
+    end
+
+    ...
+  end
+end
+```
+
+A Throttler instance will make calls to freno on behalf of the given `app`,
+using the given `client` (an instance of `Freno::Client`).
+
+You optionally provide the time you want the throttler to sleep in case the check to freno fails, this is `wait_seconds`.
+
+If replication lags badly, you can control until when you want to keep sleeping
+and retrying the check by setting `max_wait_seconds`. When that times out, the throttle will raise a `Freno::Throttler::WaitedTooLong` error.
+
+#### Instrumenting the throttler
+
+You can also configure the throttler with an `instrumenter` collaborator to subscribe to events happening during the `throttle` call.
+
+An instrumenter is an object that responds to `instrument(event_name, payload = {})` to receive events from the throttler. One could use `ActiveSupport::Notifications` as an instrumenter and subscribe to "freno.*" events somewhere else in the application, or implement one like the following to push some metrics to a stats system.
+
+```ruby
+  class StatsInstrumenter
+
+    attr_reader :stats
+
+    def initialize(stats:)
+      @stats = stats
+    end
+
+    def instrument(event_name, payload)
+      method = event_name.sub("throttler.", "")
+      send(method, payload) if respond_to?(method)
+    end
+
+    def called(payload)
+      increment("throttler.called", tags: extract_tags(payload))
+    end
+
+    def waited(payload)
+      stats.histogram("throttler.waited", payload[:waited], tags: extract_tags(payload))
+    end
+
+    ...
+
+    def circuit_open(payload)
+      stats.increment("throttler.circuit_open", tags: extract_tags(payload))
+    end
+
+    private
+
+    def extract_tags(payload)
+      cluster_names = payload[:store_names] || []
+      cluster_tags = cluster_names.map{ |cluster_name| "cluster:#{cluster_name}" }
+    end
+  end
+```
+
+#### Adding resiliency
+
+The throttler can also receive a `circuit_breaker` object to implement resiliency.
+
+With that information it receives, the circuit breaker determines whether or not to allow the next request. A circuit is said to be open when the next request is not allowed; and it's said to be closed when the next request is allowed
+
+If the throttler waited too long, or an unexpected error happened; the circuit breaker will receive a `failure`. If in contrast it succeeded, the circuit breaker will receive a `success` message.
+
+Once the circuit is open, the throttler will not try to throttle calls, an instead throw a `Freno::Throttler::CircuitOpen`
+
+The following is a simple per-process circuit breaker implementation:
+
+```ruby
+class MemoryCircuitBreaker
+
+  DEFAULT_CIRCUIT_RETRY_INTERVAL = 10
+
+  def initialize(circuit_retry_interval: DEFAULT_CIRCUIT_RETRY_INTERVAL)
+    @circuit_closed = true
+    @last_failure = nil
+    @circuit_retry_interval = circuit_retry_interval
+  end
+
+  def allow_request?
+    @circuit_closed || (Time.now - @last_failure) > @circuit_retry_interval
+  end
+
+  def success
+    @circuit_closed = true
+  end
+
+  def failure
+    @last_failure = Time.now
+    @circuit_closed = false
+  end
+end
+```
+
+#### Flexible throttling strategies
+
+The throttler uses a `mapper` to determine, based on the context provided to `#throttle`, the clusters which replication delay needs to be checked.
+
+By default the throttler uses `Mapper::Identity`, which expect the context to be the store name(s) to check:
+
+```ruby
+# will check my_cluster's health
+throttler.throttle(:my_cluster) { ... }
+# will check the health of cluster_a and cluster_b and throttle if any of them is not OK.
+throttler.throttle([:cluster_a, :cluster_b]) { ... }
+```
+
+You can create your own mapper, which is just an callable object (like a Proc, or any other object that responds to `call(context)`). The following is a mapper that knows how to throttle access to certain tables and shards.
+
+
+```ruby
+class ShardMapper
+  def call(context = {})
+    context.map do |table, shards|
+      DatabaseStructure.cluster_for(table, shards)
+    end
+  end
+end
+
+throttler = Freno::Throttler.new(client: freno, app: :my_app, mapper: ShardMapper.new)
+
+throttler.throttle(:users => [1,2,3], :repositories => 5) do
+  perform_writes
+end
+```
 
 ## Development
 
-After checking out the repo, run `script/bootstrap` to install dependencies. Then, run `script/test` to run the tests. You can also run `script/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 ## Contributing
 
@@ -189,13 +366,11 @@ This repository is open to [contributions](CONTRIBUTING.md). Contributors are ex
 If you are the current maintainer of this gem:
 
 1. Create a branch for the release: `git checkout -b cut-release-vx.y.z`
-1. Make sure your local dependencies are up to date: `script/bootstrap`
-1. Ensure that tests are green: `bundle exec rake test`
+1. Make sure your local dependencies are up to date: `bin/setup`
+1. Ensure that tests are green: `bin/test`
 1. Bump gem version in `lib/freno/client/version.rb`
 1. Merge a PR to github/freno-client containing the changes in the version file
-1. Tag and push: `git tag vx.xx.xx; git push --tags`
-1. Build the gem: `gem build freno-client`
-1. Push to rubygems.org: `gem push freno-client-x.y.z.gem`
+1. Run `bin/release`
 
 ## License