breakers 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 60d7df3e3a44461c64b30339dd20504836c1458e
-  data.tar.gz: a958353efaaa1fec1b980fb1d166b3a365576590
+  metadata.gz: a99dbaa5b10dc377c242f0707ca01e138e5119b5
+  data.tar.gz: f65d7cc872f4d76c2902362baab53c0a4825b73a
 SHA512:
-  metadata.gz: 863f61f5192713f9fe300c7300b64c2eeb30c17e00c888e1f4b70843ea21347c3128cd5dab4cdafbc4018148e7f0e7f14d9f6639bc6c3d2a29df2a8821712ed6
-  data.tar.gz: c9ed0d652b46945975d130d05baea3af3f55af2630157403f3235486880fbd0aea04be41dce60c4e7ed9db36a658f5576a60352d1ab92078bc68d62e48ee50bc
+  metadata.gz: 7a6fcda690f8eb2757cc3a82e5240c7b5d3cd3bec48a1e4f9c9e3bb32f2b7ae5c08b8b12c2215750187aac5623860f7e6b2aa0548c0b64fd9736d17ed1643aa2
+  data.tar.gz: 78e50c255536dcc2dfe3cb460197b4e1ac836cb7caa684341ac66e002b8f01927921eea3fb1011cc17f1ef6cc555b8126a26e047c35e25dcf45571fef96ceee9

data/README.md

@@ -31,7 +31,7 @@ service = Breakers::Service.new(
 
 client = Breakers::Client.new(redis_connection: redis, services: [service])
 
-Breakers.set_client(client)
+Breakers.client = client
 
 connection = Faraday.new do |conn|
   conn.use :breakers
@@ -93,7 +93,7 @@ The logger should conform to Ruby's Logger API. See more information on plugins
 The client can be configured globally with:
 
 ```ruby
-Breakers.set_client(client)
+Breakers.client = client
 ```
 
 In a Rails app, it makes sense to create the services and client in an initializer and then apply them with this call. If you would like to
@@ -103,7 +103,7 @@ namespace the data in Redis with a prefix, you can make that happen with:
 Breakers.redis_prefix = 'custom-'
 ```
 
-The default prefix is brk-.
+The default prefix is an empty string.
 
 ### Using the Middleware
 
@@ -140,6 +140,20 @@ end
 
 It's ok for your plugin to implement only part of this interface.
 
+### Forcing an Outage
+
+Some services will have status endpoints that you can use to check their availability, and you may want to create an outage based on that.
+Because this is a middleware, it doesn't have the ability to periodically check these endpoints, but you can add that type of check to your
+application and then force an outage in breakers:
+
+```ruby
+service.begin_forced_outage!
+service.end_forced_outage!
+```
+
+Unlike with outages detected by the middleware, forced outages are not periodically tested to see if they have completed and must be
+manually ended with a call to `end_forced_outage!`.
+
 ### Redis Data Structure
 
 Data is stored in Redis with the following structure:

data/lib/breakers.rb

@@ -6,24 +6,38 @@ require 'breakers/version'
 
 require 'faraday'
 
+# Implement the main module for the gem, which includes methods for global configuration
 module Breakers
   Faraday::Middleware.register_middleware(breakers: lambda { UptimeMiddleware })
 
-  # rubocop:disable Style/AccessorMethodName
-  def self.set_client(client)
+  # Set the global client for use in the middleware
+  #
+  # @param client [Breakers::Client] the client
+  def self.client=(client)
     @client = client
   end
-  # rubocop:enable Style/AccessorMethodName
 
+  # Return the global client
+  #
+  # @return [Breakers::Client] the client
   def self.client
     @client
   end
 
+  # Breakers uses a number of Redis keys to store its data. You can pass an optional
+  # prefix here to use for the keys so that they will be namespaced properly. Note that
+  # it's also possible to create the Breakers::Client object with a Redis::Namespace
+  # object instead, in which case this is unnecessary.
+  #
+  # @param prefix [String] the prefix
   def self.redis_prefix=(prefix)
     @redis_prefix = prefix
   end
 
+  # Query for the Redis key prefix
+  #
+  # @return [String] the prefix
   def self.redis_prefix
-    @redis_prefix || 'brk-'
+    @redis_prefix || ''
   end
 end

data/lib/breakers/client.rb

@@ -1,10 +1,18 @@
 module Breakers
+  # The client contains all of the data required to operate Breakers. Creating one and
+  # setting it as the global client allows the middleware to operate without parameters
   class Client
     attr_reader :services
     attr_reader :plugins
     attr_reader :redis_connection
     attr_reader :logger
 
+    # Create the Client object.
+    #
+    # @param redis_connection [Redis] the Redis connection or namespace to use
+    # @param services [Breakers::Service] a list of services to be monitored
+    # @param plugins [Object] a list of plugins to call as events occur
+    # @param logger [Logger] a logger implementing the Ruby Logger interface to call as events occur
     def initialize(redis_connection:, services:, plugins: nil, logger: nil)
       @redis_connection = redis_connection
       @services = Array(services)
@@ -12,9 +20,13 @@ module Breakers
       @logger = logger
     end
 
+    # Given a request environment, return the service that should handle it.
+    #
+    # @param request_env [Faraday::Env] the request environment
+    # @return [Breakers::Service] the service object
     def service_for_request(request_env:)
       @services.find do |service|
-        service.handles_request?(request_env)
+        service.handles_request?(request_env: request_env)
       end
     end
   end

data/lib/breakers/outage.rb

@@ -1,77 +1,126 @@
 require 'multi_json'
 
 module Breakers
+  # A class defining an outage on a service
   class Outage
     attr_reader :service
     attr_reader :body
 
-    def self.find_last(service:)
+    # Return the most recent outage on the given service
+    #
+    # @param service [Breakers::Service] the service to look in
+    # @return [Breakers::Outage] the most recent outage, or nil
+    def self.find_latest(service:)
       data = Breakers.client.redis_connection.zrange(outages_key(service: service), -1, -1)[0]
-      data && new(service: service, data: data)
+      data && new(service: service, body: data)
     end
 
+    # Return all of the outages on the given service that begin in the time range
+    #
+    # @param service [Breakers::Service] the service to look in
+    # @param start_time [Time] the beginning of the time range
+    # @param end_time [Time] the end of the time range
+    # @return [Breakers::Outage] a list of the outages in the range
     def self.in_range(service:, start_time:, end_time:)
       data = Breakers.client.redis_connection.zrangebyscore(
         outages_key(service: service),
         start_time.to_i,
         end_time.to_i
       )
-      data.map { |item| new(service: service, data: item) }
+      data.map { |item| new(service: service, body: item) }
     end
 
-    def self.create(service:)
-      data = MultiJson.dump(start_time: Time.now.utc.to_i)
+    # Create a new outage on the given service
+    #
+    # @param service [Breakers::Service] the service to create it for
+    # @param forced [Boolean] is the service forced, or created via the middleware
+    # @return [Breakers::Outage] the new outage
+    def self.create(service:, forced: false)
+      data = MultiJson.dump(start_time: Time.now.utc.to_i, forced: forced)
       Breakers.client.redis_connection.zadd(outages_key(service: service), Time.now.utc.to_i, data)
 
-      Breakers.client.logger&.error(msg: 'Breakers outage beginning', service: service.name)
+      Breakers.client.logger&.error(msg: 'Breakers outage beginning', service: service.name, forced: forced)
 
       Breakers.client.plugins.each do |plugin|
-        plugin.on_outage_begin(Outage.new(service: service, data: data)) if plugin.respond_to?(:on_outage_begin)
+        plugin.on_outage_begin(Outage.new(service: service, body: data)) if plugin.respond_to?(:on_outage_begin)
       end
     end
 
+    # Get the key for storing the outage data in Redis for this service
+    #
+    # @param service [Breakers::Service] the service
+    # @return [String] the Redis key
     def self.outages_key(service:)
       "#{Breakers.redis_prefix}#{service.name}-outages"
     end
 
-    def initialize(service:, data:)
-      @body = MultiJson.load(data)
+    # Create a new outage
+    #
+    # @param service [Breakers::Service] the service the outage is for
+    # @param body [Hash] the data to store in the outage, with keys start_time, end_time, last_test_time, and forced
+    # @return [Breakers::Outage] the new outage
+    def initialize(service:, body:)
+      @body = MultiJson.load(body)
       @service = service
     end
 
+    # Check to see if the outage has ended
+    #
+    # @return [Boolean] the status
     def ended?
       @body.key?('end_time')
     end
 
+    # Was the outage forced?
+    #
+    # @return [Boolean] the status
+    def forced?
+      @body['forced']
+    end
+
+    # Tell the outage to end, which will allow requests to begin flowing again
     def end!
       new_body = @body.dup
       new_body['end_time'] = Time.now.utc.to_i
       replace_body(body: new_body)
 
-      Breakers.client.logger&.info(msg: 'Breakers outage ending', service: @service.name)
+      Breakers.client.logger&.info(msg: 'Breakers outage ending', service: @service.name, forced: forced?)
       Breakers.client.plugins.each do |plugin|
         plugin.on_outage_end(self) if plugin.respond_to?(:on_outage_begin)
       end
     end
 
+    # Get the time at which the outage started
+    #
+    # @return [Time] the time
     def start_time
       @body['start_time'] && Time.at(@body['start_time']).utc
     end
 
+    # Get the time at which the outage ended
+    #
+    # @return [Time] the time
     def end_time
       @body['end_time'] && Time.at(@body['end_time']).utc
     end
 
+    # Get the time at which the outage last received a new request
+    #
+    # @return [Time] the time
     def last_test_time
       (@body['last_test_time'] && Time.at(@body['last_test_time']).utc) || start_time
     end
 
+    # Update the last test time to now
     def update_last_test_time!
       new_body = @body.dup
       new_body['last_test_time'] = Time.now.utc.to_i
       replace_body(body: new_body)
     end
 
+    # Check to see if the outage should be retested to make sure it's still ongoing
+    #
+    # @return [Boolean] is it ready?
     def ready_for_retest?(wait_seconds:)
       (Time.now.utc - last_test_time) > wait_seconds
     end

data/lib/breakers/service.rb

@@ -1,4 +1,7 @@
 module Breakers
+  # A service defines a backend system that your application relies upon. This class
+  # allows you to configure the outage detection for a service as well as to define which
+  # requests belong to it.
   class Service
     DEFAULT_OPTS = {
       seconds_before_retry: 60,
@@ -6,35 +9,74 @@ module Breakers
       data_retention_seconds: 60 * 60 * 24 * 30
     }.freeze
 
+    # Create a new service
+    #
+    # @param [Hash] opts the options to create the service with
+    # @option opts [String] :name The name of the service for reporting and logging purposes
+    # @option opts [Proc] :request_matcher A proc taking a Faraday::Env as an argument that returns true if the service handles that request
+    # @option opts [Integer] :seconds_before_retry The number of seconds to wait after an outage begins before testing with a new request
+    # @option opts [Integer] :error_threshold The percentage of errors over the last two minutes that indicates an outage
+    # @option opts [Integer] :data_retention_seconds The number of seconds to retain success and error data in Redis
     def initialize(opts)
       @configuration = DEFAULT_OPTS.merge(opts)
     end
 
+    # Get the name of the service
+    #
+    # @return [String] the name
     def name
       @configuration[:name]
     end
 
-    def handles_request?(request_env)
+    # Given a Faraday::Env, return true if this service handles the request, via its matcher
+    #
+    # @param request_env [Faraday::Env] the request environment
+    # @return [Boolean] should the service handle the request
+    def handles_request?(request_env:)
       @configuration[:request_matcher].call(request_env)
     end
 
+    # Get the seconds before retry parameter
+    #
+    # @return [Integer] the value
     def seconds_before_retry
       @configuration[:seconds_before_retry]
     end
 
+    # Indicate that an error has occurred and potentially create an outage
     def add_error
       increment_key(key: errors_key)
       maybe_create_outage
     end
 
+    # Indicate that a successful response has occurred
     def add_success
       increment_key(key: successes_key)
     end
 
-    def last_outage
-      Outage.find_last(service: self)
+    # Force an outage to begin on the service. Forced outages are not periodically retested.
+    def begin_forced_outage!
+      Outage.create(service: self, forced: true)
     end
 
+    # End a forced outage on the service.
+    def end_forced_outage!
+      latest = Outage.find_latest(service: self)
+      if latest.forced?
+        latest.end!
+      end
+    end
+
+    # Return the most recent outage on the service
+    def latest_outage
+      Outage.find_latest(service: self)
+    end
+
+    # Return a list of all outages in the given time range
+    #
+    # @param start_time [Time] the beginning of the range
+    # @param end_time [Time] the end of the range
+    # @return [Array[Outage]] a list of outages that began in the range
     def outages_in_range(start_time:, end_time:)
       Outage.in_range(
         service: self,
@@ -43,12 +85,24 @@ module Breakers
       )
     end
 
-    def successes_in_range(start_time:, end_time:, sample_seconds: 3600)
-      values_in_range(start_time: start_time, end_time: end_time, type: :successes, sample_seconds: sample_seconds)
+    # Return data about the successful request counts in the time range
+    #
+    # @param start_time [Time] the beginning of the range
+    # @param end_time [Time] the end of the range
+    # @param sample_minutes [Integer] the rate at which to sample the data
+    # @return [Array[Hash]] a list of hashes in the form: { count: Integer, time: Unix Timestamp }
+    def successes_in_range(start_time:, end_time:, sample_minutes: 60)
+      values_in_range(start_time: start_time, end_time: end_time, type: :successes, sample_minutes: sample_minutes)
     end
 
-    def errors_in_range(start_time:, end_time:, sample_seconds: 3600)
-      values_in_range(start_time: start_time, end_time: end_time, type: :errors, sample_seconds: sample_seconds)
+    # Return data about the failed request counts in the time range
+    #
+    # @param start_time [Time] the beginning of the range
+    # @param end_time [Time] the end of the range
+    # @param sample_minutes [Integer] the rate at which to sample the data
+    # @return [Array[Hash]] a list of hashes in the form: { count: Integer, time: Unix Timestamp }
+    def errors_in_range(start_time:, end_time:, sample_minutes: 60)
+      values_in_range(start_time: start_time, end_time: end_time, type: :errors, sample_minutes: sample_minutes)
     end
 
     protected
@@ -61,7 +115,7 @@ module Breakers
       "#{Breakers.redis_prefix}#{name}-successes-#{align_time_on_minute(time: time).to_i}"
     end
 
-    def values_in_range(start_time:, end_time:, type:, sample_seconds:)
+    def values_in_range(start_time:, end_time:, type:, sample_minutes:)
       start_time = align_time_on_minute(time: start_time)
       end_time = align_time_on_minute(time: end_time)
       keys = []
@@ -73,7 +127,7 @@ module Breakers
         elsif type == :successes
           keys << successes_key(time: start_time)
         end
-        start_time += sample_seconds
+        start_time += sample_minutes * 60
       end
       Breakers.client.redis_connection.mget(keys).each_with_index.map do |value, idx|
         { count: value.to_i, time: times[idx] }

data/lib/breakers/uptime_middleware.rb

@@ -2,6 +2,7 @@ require 'faraday'
 require 'multi_json'
 
 module Breakers
+  # The faraday middleware
   class UptimeMiddleware < Faraday::Middleware
     def initialize(app)
       super(app)
@@ -14,13 +15,13 @@ module Breakers
         return @app.call(request_env)
       end
 
-      last_outage = service.last_outage
+      latest_outage = service.latest_outage
 
-      if last_outage && !last_outage.ended?
-        if last_outage.ready_for_retest?(wait_seconds: service.seconds_before_retry)
-          handle_request(service: service, request_env: request_env, current_outage: last_outage)
+      if latest_outage && !latest_outage.ended?
+        if latest_outage.ready_for_retest?(wait_seconds: service.seconds_before_retry)
+          handle_request(service: service, request_env: request_env, current_outage: latest_outage)
         else
-          outage_response(outage: last_outage, service: service)
+          outage_response(outage: latest_outage, service: service)
         end
       else
         handle_request(service: service, request_env: request_env)

data/lib/breakers/version.rb

@@ -1,3 +1,3 @@
 module Breakers
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.1.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: breakers
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Aubrey Holland
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-17 00:00:00.000000000 Z
+date: 2016-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -220,3 +220,4 @@ signing_key:
 specification_version: 4
 summary: Handle outages to backend systems with a Faraday middleware
 test_files: []
+has_rdoc: