semian 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8660f920372dc867f6b4e8bbca1ad080a8bcf293
-  data.tar.gz: 477bc269271d94d9903ee2fb1c38b8929e5b4976
+  metadata.gz: 219d1e2e6ab5b6bbc6c90e0e418e47a38a6415cd
+  data.tar.gz: dfe7b83c1f95e26d0df6daa2cde3a914e98d2520
 SHA512:
-  metadata.gz: d050ac79d5e120acc0a5f8ac945ab090eac4d52c4df3b5a642ce45a11c1d580085136237b1a92dafd2a035fd63a92fc90b290b6b12ff88e13f8a4fa80056dad2
-  data.tar.gz: 46108108c10f883e833b13e8c5b1e4cd90c3a0cb8de17cbcbef79d868ea5955e11b355c80ea43b90f2a79b54ea11c9337058b71d758c450f3f54fd3da6a4b930
+  metadata.gz: 79f643b811ba718f89a1021c2227b210e4b3045cb5ebc919e6017dcc0334d65efe31a7d30695abf1287f24894794f2c513128e6b07b52553eb0e9cac4cb11e65
+  data.tar.gz: 267d1b19a1c8c6ab7e9786b639a0c326dc9e4669636dfb20a19f36f43386b669029b172ea3f38bf790cc173f7cef9470c1c5b488a694a2c73eb0385ae4ceaa5c

data/.travis.yml

@@ -1,6 +1,9 @@
 language: ruby
 
-sudo: false
+sudo: true
+
+before_install:
+  - scripts/install_toxiproxy.sh
 
 rvm:
   - 2.1.1

data/README.md

@@ -50,7 +50,7 @@ In a master process, register a resource with a specified number of tickets
 (number of concurrent clients):
 
 ```ruby
-Semian.register(:mysql_master, tickets: 3, timeout: 0.5)
+Semian.register(:mysql_master tickets: 3, timeout: 0.5, error_threshold: 3, error_timeout: 10, success_threshold: 2)
 ```
 
 Then in your child processes, you can use the resource:

data/Rakefile

@@ -29,19 +29,20 @@ else
   task :build do; end
 end
 
+task :populate_proxy do
+  require 'toxiproxy'
+  Toxiproxy.populate(File.expand_path('../test/fixtures/toxiproxy.json', __FILE__))
+end
+
 # ==========================================================
 # Testing
 # ==========================================================
 
 require 'rake/testtask'
 Rake::TestTask.new 'test' do |t|
-  t.test_files = if Semian.supported_platform?
-    FileList['test/test_semian.rb']
-  else
-    FileList['test/test_unsupported.rb']
-  end
+  t.pattern = "test/test_*.rb"
 end
-task :test => :build
+task :test => [:build, :populate_proxy]
 
 # ==========================================================
 # Documentation

data/ext/semian/semian.c

@@ -449,10 +449,10 @@ semian_resource_id(VALUE self)
 
 void Init_semian()
 {
-  VALUE cSemian, cResource, eBaseError;
+  VALUE cSemian, cResource;
   struct seminfo info_buf;
 
-  cSemian = rb_define_class("Semian", rb_cObject);
+  cSemian = rb_const_get(rb_cObject, rb_intern("Semian"));
 
   /*
    * Document-class: Semian::Resource
@@ -462,25 +462,19 @@ void Init_semian()
    *
    *  You should not create this class directly, it will be created indirectly via Semian.register.
    */
-  cResource = rb_define_class_under(cSemian, "Resource", rb_cObject);
-
-  /* Document-class: Semian::BaseError
-   *
-   * Base error class for all other Semian errors.
-   */
-  eBaseError = rb_define_class_under(cSemian, "BaseError", rb_eStandardError);
+  cResource = rb_const_get(cSemian, rb_intern("Resource"));
 
   /* Document-class: Semian::SyscallError
    *
    * Represents a Semian error that was caused by an underlying syscall failure.
    */
-  eSyscall = rb_define_class_under(cSemian, "SyscallError", eBaseError);
+  eSyscall = rb_const_get(cSemian, rb_intern("SyscallError"));
 
   /* Document-class: Semian::TimeoutError
    *
    * Raised when a Semian operation timed out.
    */
-  eTimeout = rb_define_class_under(cSemian, "TimeoutError", eBaseError);
+  eTimeout = rb_const_get(cSemian, rb_intern("TimeoutError"));
 
   /* Document-class: Semian::InternalError
    *
@@ -492,10 +486,10 @@ void Init_semian()
    * using the <code>ipcrm</code> command line tool. Semian will re-initialize
    * the semaphore in this case.
    */
-  eInternal = rb_define_class_under(cSemian, "InternalError", eBaseError);
+  eInternal = rb_const_get(cSemian, rb_intern("InternalError"));
 
   rb_define_alloc_func(cResource, semian_resource_alloc);
-  rb_define_method(cResource, "initialize", semian_resource_initialize, 4);
+  rb_define_method(cResource, "_initialize", semian_resource_initialize, 4);
   rb_define_method(cResource, "acquire", semian_resource_acquire, -1);
   rb_define_method(cResource, "count", semian_resource_count, 0);
   rb_define_method(cResource, "semid", semian_resource_id, 0);

data/lib/semian/circuit_breaker.rb

@@ -0,0 +1,135 @@
+module Semian
+  class CircuitBreaker
+    attr_reader :state
+
+    def initialize(exceptions:, success_threshold:, error_threshold:, error_timeout:)
+      @success_count_threshold = success_threshold
+      @error_count_threshold = error_threshold
+      @error_timeout = error_timeout
+      @exceptions = exceptions
+      reset
+    end
+
+    def acquire(&block)
+      raise OpenCircuitError unless request_allowed?
+
+      result = nil
+      begin
+        result = yield
+      rescue *@exceptions => error
+        mark_failed(error)
+        raise error
+      else
+        mark_success
+      end
+      result
+    end
+
+    def with_fallback(fallback, &block)
+      acquire(&block)
+    rescue *@exceptions
+      evaluate_fallback(fallback)
+    rescue OpenCircuitError
+      evaluate_fallback(fallback)
+    end
+
+    def request_allowed?
+      return true if closed?
+      half_open if error_timeout_expired?
+      !open?
+    end
+
+    def mark_failed(error)
+      increment_recent_errors
+
+      if closed?
+        open if error_threshold_reached?
+      elsif half_open?
+        open
+      end
+    end
+
+    def mark_success
+      return unless half_open?
+      @success_count += 1
+      close if success_threshold_reached?
+    end
+
+    def reset
+      @success_count = 0
+      @error_count = 0
+      @error_last_at = nil
+      close
+    end
+
+    private
+
+    def evaluate_fallback(fallback_value_or_block)
+      if fallback_value_or_block.respond_to?(:call)
+        fallback_value_or_block.call
+      else
+        fallback_value_or_block
+      end
+    end
+
+    def closed?
+      state == :closed
+    end
+
+    def close
+      log_state_transition(:closed)
+      @state = :closed
+      @error_count = 0
+    end
+
+    def open?
+      state == :open
+    end
+
+    def open
+      log_state_transition(:open)
+      @state = :open
+    end
+
+    def half_open?
+      state == :half_open
+    end
+
+    def half_open
+      log_state_transition(:half_open)
+      @state = :half_open
+      @success_count = 0
+    end
+
+    def increment_recent_errors
+      if error_timeout_expired?
+        @error_count = 0
+      end
+
+      @error_count += 1
+      @error_last_at = Time.now
+    end
+
+    def success_threshold_reached?
+      @success_count >= @success_count_threshold
+    end
+
+    def error_threshold_reached?
+      @error_count >= @error_count_threshold
+    end
+
+    def error_timeout_expired?
+      @error_last_at && (@error_last_at + @error_timeout < Time.now)
+    end
+
+    def log_state_transition(new_state)
+      return if @state.nil? || new_state == @state
+
+      str = "[#{self.class.name}] State transition from #{@state} to #{new_state}."
+      str << " success_count=#{@success_count} error_count=#{@error_count}"
+      str << " success_count_threshold=#{@success_count_threshold} error_count_threshold=#{@error_count_threshold}"
+      str << " error_timeout=#{@error_timeout} error_last_at=\"#{@error_last_at}\""
+      Semian.logger.info(str)
+    end
+  end
+end

data/lib/semian/instrumentable.rb

@@ -0,0 +1,22 @@
+module Semian
+  module Instrumentable
+    def subscribe(name = rand, &block)
+      subscribers[name] = block
+      name
+    end
+
+    def unsubscribe(name)
+      subscribers.delete(name)
+    end
+
+    def notify(*args)
+      subscribers.values.each { |subscriber| subscriber.call(*args) }
+    end
+
+    private
+
+    def subscribers
+      @subscribers ||= {}
+    end
+  end
+end

data/lib/semian/mysql2.rb

@@ -0,0 +1,77 @@
+require 'semian'
+require 'mysql2'
+
+module Mysql2
+  class SemianError < Mysql2::Error
+    def initialize(semian_identifier, *args)
+      super(*args)
+      @semian_identifier = semian_identifier
+    end
+
+    def to_s
+      "[#{@semian_identifier}] #{super}"
+    end
+  end
+
+  ResourceOccupiedError = Class.new(SemianError)
+  CircuitOpenError = Class.new(SemianError)
+end
+
+module Semian
+  module Mysql2
+    DEFAULT_HOST = 'localhost'
+    DEFAULT_PORT = 3306
+
+    # The naked methods are exposed as `raw_query` and `raw_connect` for instrumentation purpose
+    def self.included(base)
+      base.send(:alias_method, :raw_query, :query)
+      base.send(:remove_method, :query)
+
+      base.send(:alias_method, :raw_connect, :connect)
+      base.send(:remove_method, :connect)
+    end
+
+    def semian_identifier
+      @semian_identifier ||= begin
+        semian_options = query_options[:semian] || {}
+        unless name = semian_options['name'.freeze] || semian_options[:name]
+          host = query_options[:host] || DEFAULT_HOST
+          port = query_options[:port] || DEFAULT_PORT
+          name = "#{host}:#{port}"
+        end
+        :"mysql_#{name}"
+      end
+    end
+
+    def query(*args)
+      semian_resource.acquire(scope: :query) { raw_query(*args) }
+    rescue ::Semian::OpenCircuitError => error
+      raise ::Mysql2::CircuitOpenError.new(semian_identifier, error)
+    rescue ::Semian::BaseError => error
+      raise ::Mysql2::ResourceOccupiedError.new(semian_identifier, error)
+    end
+
+    private
+
+    def connect(*args)
+      semian_resource.acquire(scope: :connect) { raw_connect(*args) }
+    rescue ::Semian::OpenCircuitError => error
+      raise ::Mysql2::CircuitOpenError.new(semian_identifier, error)
+    rescue ::Semian::BaseError => error
+      raise ::Mysql2::ResourceOccupiedError.new(semian_identifier, error)
+    end
+
+    def semian_resource
+      @semian_resource ||= ::Semian.retrieve_or_register(semian_identifier, **semian_options)
+    end
+
+    def semian_options
+      options = query_options[:semian] || {}
+      options = options.map { |k, v| [k.to_sym, v] }.to_h
+      options.delete(:name)
+      options
+    end
+  end
+end
+
+::Mysql2::Client.include(Semian::Mysql2)

data/lib/semian/platform.rb

@@ -1,6 +1,6 @@
-class Semian
+module Semian
   # Determines if Semian supported on the current platform.
   def self.supported_platform?
-    RUBY_PLATFORM.end_with?('-linux')
+    /linux/.match(RUBY_PLATFORM)
   end
 end

data/lib/semian/protected_resource.rb

@@ -0,0 +1,36 @@
+require 'forwardable'
+
+module Semian
+  class ProtectedResource
+    extend Forwardable
+
+    def_delegators :@resource, :destroy, :count, :semid, :tickets, :name
+    def_delegators :@circuit_breaker, :reset
+
+    def initialize(resource, circuit_breaker)
+      @resource = resource
+      @circuit_breaker = circuit_breaker
+    end
+
+    def acquire(timeout: nil, scope: nil, &block)
+      @circuit_breaker.acquire do
+        begin
+          @resource.acquire(timeout: timeout) do
+            Semian.notify(:success, self, scope)
+            yield self
+          end
+        rescue ::Semian::TimeoutError
+          Semian.notify(:occupied, self, scope)
+          raise
+        end
+      end
+    rescue ::Semian::OpenCircuitError
+      Semian.notify(:circuit_open, self, scope)
+      raise
+    end
+
+    def with_fallback(fallback, &block)
+      @circuit_breaker.with_fallback(fallback) { @resource.acquire(&block) }
+    end
+  end
+end

data/lib/semian/resource.rb

@@ -0,0 +1,26 @@
+module Semian
+  class Resource #:nodoc:
+    attr_reader :tickets, :name
+
+    def initialize(name, tickets: , permissions: 0660, timeout: 0)
+      _initialize(name, tickets, permissions, timeout) if respond_to?(:_initialize)
+      @name = name
+      @tickets = tickets
+    end
+
+    def destroy
+    end
+
+    def acquire(*)
+      yield self
+    end
+
+    def count
+      0
+    end
+
+    def semid
+      0
+    end
+  end
+end

data/lib/semian/version.rb

@@ -1,3 +1,3 @@
-class Semian
-  VERSION = '0.0.8'
+module Semian
+  VERSION = '0.1.0'
 end

data/lib/semian.rb

@@ -1,3 +1,6 @@
+require 'logger'
+require 'semian/instrumentable'
+
 #
 # === Overview
 #
@@ -25,16 +28,28 @@
 # the timeout period has elapsed, the client will be unable to access the service and
 # an error will be raised.
 #
+# Resources also integrate a circuit breaker in order to fail faster and to let the
+# resource the time to recover. If `error_threshold` errors happen in the span of `error_timeout`
+# then the circuit will be opened and every attempt to acquire the resource will immediately fail.
+# 
+# Once in open state, after `error_timeout` is elapsed, the ciruit will transition in the half-open state.
+# In that state a single error will fully re-open the circuit, and the circuit will transition back to the closed
+# state only after the resource is acquired `success_threshold` consecutive times.
+#
 # A resource is registered by using the Semian.register method.
 #
 # ==== Examples
 #
 # ===== Registering a resource
 #
-#    Semian.register :mysql_shard0, tickets: 10, timeout: 0.5
+#    Semian.register(:mysql_shard0, tickets: 10, timeout: 0.5, error_threshold: 3, error_timeout: 10, success_threshold: 2)
 #
 # This registers a new resource called <code>:mysql_shard0</code> that has 10 tickets andd a default timeout of 500 milliseconds.
 #
+# After 3 failures in the span of 10 seconds the circuit will be open.
+# After an additional 10 seconds it will transition to half-open.
+# And finally after 2 successulf acquisitions of the resource it will transition back to the closed state.
+#
 # ===== Using a resource
 #
 #    Semian[:mysql_shard0].acquire do
@@ -52,42 +67,80 @@
 #
 # This is the same as the previous example, but overrides the timeout from the default value of 500 milliseconds to 1 second.
 #
-class Semian
-  class << self
-    # Registers a resource.
-    #
-    # +name+: Name of the resource - this can be either a string or symbol.
-    #
-    # +tickets+: Number of tickets. If this value is 0, the ticket count will not be set,
-    # but the resource must have been previously registered otherwise an error will be raised.
-    #
-    # +permissions+: Octal permissions of the resource.
-    #
-    # +timeout+: Default timeout in seconds.
-    #
-    # Returns the registered resource.
-    def register(name, tickets: 0, permissions: 0660, timeout: 1)
-      resource = Resource.new(name, tickets, permissions, timeout)
-      resources[name] = resource
-    end
+module Semian
+  extend self
+  extend Instrumentable
 
-    # Retrieves a resource by name.
-    def [](name)
-      resources[name]
-    end
+  BaseError = Class.new(StandardError)
+  SyscallError = Class.new(BaseError)
+  TimeoutError = Class.new(BaseError)
+  InternalError = Class.new(BaseError)
+  OpenCircuitError = Class.new(BaseError)
+
+  attr_accessor :logger
 
-    # Retrieves a hash of all registered resources.
-    def resources
-      @resources ||= {}
+  self.logger = Logger.new(nil)
+
+  # Registers a resource.
+  #
+  # +name+: Name of the resource - this can be either a string or symbol.
+  #
+  # +tickets+: Number of tickets. If this value is 0, the ticket count will not be set,
+  # but the resource must have been previously registered otherwise an error will be raised.
+  #
+  # +permissions+: Octal permissions of the resource.
+  #
+  # +timeout+: Default timeout in seconds.
+  #
+  # +error_threshold+: The number of errors that will trigger the circuit opening.
+  #
+  # +error_timeout+: The duration in seconds since the last error after which the error count is reset to 0.
+  #
+  # +success_threshold+: The number of consecutive success after which an half-open circuit will be fully closed.
+  #
+  # +exceptions+: An array of exception classes that should be accounted as resource errors.
+  #
+  # Returns the registered resource.
+  def register(name, tickets:, permissions: 0660, timeout: 0, error_threshold:, error_timeout:, success_threshold:, exceptions: [])
+    circuit_breaker = CircuitBreaker.new(
+      success_threshold: success_threshold,
+      error_threshold: error_threshold,
+      error_timeout: error_timeout,
+      exceptions: Array(exceptions) + [::Semian::BaseError],
+    )
+    resource = Resource.new(name, tickets: tickets, permissions: permissions, timeout: timeout)
+    resources[name] = ProtectedResource.new(resource, circuit_breaker)
+  end
+
+  def retrieve_or_register(name, **args)
+    self[name] || register(name, **args)
+  end
+
+  # Retrieves a resource by name.
+  def [](name)
+    resources[name]
+  end
+
+  def destroy(name)
+    if resource = resources.delete(name)
+      resource.destroy
     end
   end
+
+  # Retrieves a hash of all registered resources.
+  def resources
+    @resources ||= {}
+  end
 end
 
+require 'semian/resource'
+require 'semian/circuit_breaker'
+require 'semian/protected_resource'
 require 'semian/platform'
 if Semian.supported_platform?
   require 'semian/semian'
 else
-  require 'semian/unsupported'
+  Semian::MAX_TICKETS = 0
   $stderr.puts "Semian is not supported on #{RUBY_PLATFORM} - all operations will no-op"
 end
 require 'semian/version'

data/scripts/install_toxiproxy.sh

@@ -0,0 +1,25 @@
+set -e
+
+if which toxiproxy > /dev/null; then
+  echo "Toxiproxy is already installed."
+  exit 0
+fi
+
+if which apt-get > /dev/null; then
+  echo "Installing toxiproxy-1.0.0.deb"
+  wget -O /tmp/toxiproxy-1.0.0.deb https://github.com/Shopify/toxiproxy/releases/download/v1.0.0/toxiproxy_1.0.0_amd64.deb
+  sudo dpkg -i /tmp/toxiproxy-1.0.0.deb
+  sudo service toxiproxy start
+  exit 0
+fi
+
+if which brew > /dev/null; then
+  echo "Installing toxiproxy from homebrew."
+  brew tap shopify/shopify
+  brew install toxiproxy
+  brew info toxiproxy
+  exit 0
+fi
+
+echo "Sorry, there is no toxiproxy package available for your system. You might need to build it from source."
+exit 1

data/semian.gemspec

@@ -19,4 +19,7 @@ Gem::Specification.new do |s|
   s.files = `git ls-files`.split("\n")
   s.extensions = ['ext/semian/extconf.rb']
   s.add_development_dependency 'rake-compiler', '~> 0.9'
+  s.add_development_dependency 'timecop'
+  s.add_development_dependency 'mysql2'
+  s.add_development_dependency 'toxiproxy'
 end

data/test/fixtures/toxiproxy.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": "semian_test_mysql",
+    "upstream": "localhost:3306",
+    "listen": "localhost:13306"
+  }
+]