px-service-client 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: af7a7e8bbce817e251279c1a31fe9737e05d7d2d
+  data.tar.gz: deef44499ba41a91b75c2d1efbf4a55568a5fa62
+SHA512:
+  metadata.gz: 7caf92bd8294aafe32fa12de6c5328d51960cee2c19c93ea42dd48a335778d13b83fa34b44e05a58a879f5720deb0954b0c6b5cfe6a84c1a8496752b46cfc60a
+  data.tar.gz: cc7781a37f252033c1e585d31e6eb125fc1c5bda0f15c7396a3de44ca767cfc91aff3fa6f2e280d48088220c3df459022464a5db30c6d98c4df0317ce7d4408e

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format documentation

data/.ruby-gemset

@@ -0,0 +1 @@
+px-service-client

data/.ruby-version

@@ -0,0 +1 @@
+2.1.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in px-service-client.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,19 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rsspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separetly)
+#  * 'just' rspec: 'rspec'
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 500px
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+px-service-client
+=================
+
+[![Build Status](https://semaphoreapp.com/api/v1/projects/3e3b69a9-7606-49d9-a9e1-acea22b026c4/277528/badge.png)](https://semaphoreapp.com/500px/ruby-service-client)
+
+A set of modules to add common functionality to a Ruby service client
+
+Usage
+-----
+
+```
+gem install px-service-client
+```
+
+Or, with bundler
+
+```ruby
+gem 'px-service-client'
+```
+
+Then use it:
+
+```ruby
+require 'px-service-client'
+
+class MyClient
+  include Px::Service::Client::::Caching
+  include Px::Service::Client::::CircuitBreaker
+end
+
+```
+
+Features
+--------
+
+This gem includes several common features used in 500px service client libraries.
+
+The features are:
+
+#### Px::Service::Client::::Caching
+
+```ruby
+include Px::Service::Client::::Caching
+
+self.cache_client =  Dalli::Client.new(...)
+self.cache_logger = Logger.new(STDOUT) # or Rails.logger, for example
+```
+
+Provides client-side response caching of service requests.  Responses are cached in memcached (using the provided cache client) in either a *last-resort* or *first-resort* manner.
+
+*last-resort* means that the cached value is only used when the service client request fails (with a
+`ServiceError`).  When using last-resort caching, a `refresh_probability` can be provided that causes the cached value
+to be refreshed probabilistically (rather than on every request).
+
+*first-resort* means that the cached value is always used, if present.  Requests to the service are only made
+when the cached value is close to expiry.
+
+#### Px::Service::Client::::CircuitBreaker
+
+```ruby
+def call_remote_service() ...
+
+circuit_method :call_remote_service
+
+# Optional
+circuit_handler do |handler|
+ handler.logger = Logger.new(STDOUT)
+ handler.failure_threshold = 5
+ handler.failure_timeout = 5
+ handler.invocation_timeout = 10
+ handler.excluded_exceptions += [NotConsideredFailureException]
+end
+```
+
+Provides a circuit breaker on the class, and turns the class into a singleton.  Each method named using
+`circuit_method` will be wrapped in a circuit breaker that will raise a `Px::Service::ServiceError` if the breaker
+is open.  The circuit will open on any exception from the wrapped method, or if the wrapped method
+runs for longer than the `invocation_timeout`.
+
+Note that `Px::Service::ServiceRequestError` exceptions do NOT trip the breaker, as these exceptions indicate an error
+on the caller's part (e.g. an HTTP 4xx error).
+
+The class is made a singleton using the standard `Singleton` module.  Access to the class's methods should be done
+using its `instance` class method (calls to `new` will fail).
+
+This module is based on (and uses) the [Circuit Breaker](https://github.com/wsargent/circuit_breaker) gem by Will Sargent.
+
+#### Px::Service::Client::::ListResponse
+
+```ruby
+  def get_something(page, page_size)
+    response = JSON.parse(http_get("http://some/url?p=#{page}&l=#{page_size}"))
+    return Px::Service::Client::::ListResponse(page_size, response, "items")
+  end
+
+```
+
+Wraps a deserialized response.  A `ListResponse` implements the Ruby `Enumerable` module, as well
+as the methods required to work with [WillPaginate](https://github.com/mislav/will_paginate).
+
+It assumes that the response resembles this form:
+```json
+{
+  "current_page": 1,
+  "total_items": 100,
+  "total_pages": 10,
+  "items": [
+    { /* item 1 */ },
+    { /* item 2 */ },
+    ...
+  ]
+}
+```
+
+The name of the `"items"` key is given in the third argument.
+
+License
+-------
+
+The MIT License (MIT)
+
+Copyright (c) 2014 500px, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/px/service/client/base.rb

@@ -0,0 +1,41 @@
+module Px::Service::Client
+  class Base
+    include Px::Service::Client::Caching
+    include Px::Service::Client::CircuitBreaker
+    cattr_accessor :logger
+
+    private
+
+    def parsed_body(response)
+      if response.success?
+        Hashie::Mash.new(JSON.parse(response.body))
+      else
+        if response.response_headers["Content-Type"] =~ %r{application/json}
+          JSON.parse(response.body)["error"] rescue response.body.try(:strip)
+        else
+          response.body.strip
+        end
+      end
+    end
+
+    def make_request(method, uri, query: nil, headers: nil, body: nil)
+      req = Typhoeus::Request.new(
+        uri,
+        method: method,
+        params: query,
+        body: body,
+        headers: headers)
+
+      start_time = Time.now
+      logger.debug "Making request #{method.to_s.upcase} #{uri}" if logger
+
+      req.on_complete do |response|
+        elapsed = (Time.now - start_time) * 1000
+        logger.debug "Completed request #{method.to_s.upcase} #{uri}, took #{elapsed.to_i}ms, got status #{response.response_code}" if logger
+      end
+
+      RetriableResponseFuture.new(req)
+    end
+
+  end
+end

data/lib/px/service/client/caching/cache_entry.rb

@@ -0,0 +1,95 @@
+module Px::Service::Client::Caching
+  class CacheEntry
+    attr_accessor :url, :data, :expires_at, :policy_group
+    attr_reader :cache_client
+
+    def initialize(cache_client, url, policy_group, data, expires_at = nil)
+      @cache_client = cache_client
+      self.url = url
+      self.data = data
+      self.expires_at = expires_at
+      self.policy_group = policy_group
+    end
+
+    def expired?
+      expires_at < DateTime.now
+    end
+
+    ##
+    # Store this entry in the cache with the given expiry.
+    def store(expires_in, refresh_window: 5.minutes)
+      self.expires_at = DateTime.now + expires_in
+
+      ActiveSupport::Notifications.instrument("store.caching", { url: url, policy_group: policy_group, expires_in: expires_in} ) do
+        real_expiry = real_cache_expiry(expires_in, refresh_window: refresh_window)
+        cache_client.multi do
+          cache_client.set(cache_key(:data), data.to_json, real_expiry)
+          cache_client.set(cache_key(:meta), metadata.to_json, real_expiry)
+        end
+      end
+    end
+
+    ##
+    # Fetch an entry from the cache.  Returns the entry if it's present, otherwise returns nil
+    def self.fetch(cache_client, url, policy_group)
+      key_values = nil
+      data_key = cache_key(url, policy_group, :data)
+      meta_key = cache_key(url, policy_group, :meta)
+      ActiveSupport::Notifications.instrument("get.caching", { url: url, policy_group: policy_group } ) do
+        key_values = cache_client.get_multi(data_key, meta_key)
+      end
+
+      data_json = key_values[data_key]
+      meta_json = key_values[meta_key]
+      if data_json && meta_json
+        data = JSON.parse(data_json)
+        meta = JSON.parse(meta_json)
+        CacheEntry.new(cache_client, meta['url'], meta['pg'], data, meta['expires_at'])
+      else
+        nil
+      end
+    end
+
+    ##
+    # Touch this entry in the cache, updating its expiry time but not its data
+    def touch(expires_in, refresh_window: 5.minutes)
+      self.expires_at = DateTime.now + expires_in
+
+      ActiveSupport::Notifications.instrument("touch.caching", { url: url, policy_group: policy_group, expires_in: expires_in} ) do
+        real_expiry = real_cache_expiry(expires_in, refresh_window: refresh_window)
+
+        cache_client.touch(cache_key(:data), real_expiry)
+        cache_client.set(cache_key(:meta), metadata.to_json, real_expiry)
+      end
+    end
+
+    private
+
+    def metadata
+      {
+        "url" => url,
+        "pg" => policy_group,
+        "expires_at" => expires_at,
+      }
+    end
+
+    def cache_key(type)
+      self.class.cache_key(url, policy_group, type)
+    end
+
+    def self.cache_key(url, policy_group, type)
+      "#{policy_group}_#{cache_key_base(url)}_#{type}"
+    end
+
+    ##
+    # Get the cache key for the given query string
+    def self.cache_key_base(url)
+      md5 = Digest::MD5.hexdigest(url.to_s)
+      "#{self.class.name.parameterize}_#{md5}"
+    end
+
+    def real_cache_expiry(expires_in, refresh_window: nil)
+      (expires_in + refresh_window).to_i
+    end
+  end
+end

data/lib/px/service/client/caching/log_subscriber.rb

@@ -0,0 +1,23 @@
+module Px::Service::Client::Caching
+  ##
+  # Prints caching events to the log
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    def get(event)
+      payload = event.payload
+      name  = color("  ServiceCache Get (#{event.duration.round(1)}ms)", GREEN, true)
+      debug("#{name} #{payload[:policy_group]}[#{payload[:url]}]")
+    end
+
+    def store(event)
+      payload = event.payload
+      name  = color("  ServiceCache Store (#{event.duration.round(1)}ms)", GREEN, true)
+      debug("#{name} #{payload[:expires_in].to_i}s => #{payload[:policy_group]}[#{payload[:url]}]")
+    end
+
+    def touch(event)
+      payload = event.payload
+      name  = color("  ServiceCache Touch (#{event.duration.round(1)}ms)", GREEN, true)
+      debug("#{name} #{payload[:expires_in].to_i}s => #{payload[:policy_group]}[#{payload[:url]}]")
+    end
+  end
+end

data/lib/px/service/client/caching/railtie.rb

@@ -0,0 +1,11 @@
+module Px::Service
+  module Client
+    module Caching
+      class Railtie < ::Rails::Railtie
+        initializer "service.client.caching" do
+          Px::Service::Client::Caching::LogSubscriber.attach_to :caching
+        end
+      end
+    end
+  end
+end

data/lib/px/service/client/caching.rb

@@ -0,0 +1,112 @@
+require 'px/service/client/caching/cache_entry'
+require 'dalli'
+
+if defined?(Rails)
+  require 'px/service/client/caching/log_subscriber'
+  require 'px/service/client/caching/railtie'
+end
+
+module Px::Service::Client
+  module Caching
+    extend ActiveSupport::Concern
+
+    STRATEGIES = [
+      NO_CACHE = :none,
+      LAST_RESORT = :last_resort,
+      FIRST_RESORT = :first_resort,
+    ]
+
+    included do
+      cattr_accessor :cache_client, :cache_logger
+    end
+
+    def cache_request(url, strategy: :last_resort, expires_in: 30.seconds, **options, &block)
+      case strategy
+      when :first_resort
+        cache_first_resort(url, expires_in: expires_in, **options, &block)
+      when :last_resort
+        cache_last_resort(url, expires_in: expires_in, **options, &block)
+      else
+        no_cache(url, &block)
+      end
+    end
+
+    private
+
+    ##
+    # Use the cache as a last resort.  This path will make the request each time, caching the result
+    # on success.  If an exception occurs, the cache is checked for a result.  If the cache has a result, it's
+    # returned and the cache entry is touched to prevent expiry.  Otherwise, the original exception is re-raised.
+    def cache_last_resort(url, policy_group: 'general', expires_in: nil, refresh_probability: 1, &block)
+      # Note we use a smaller refresh window here (technically, could even use 0)
+      # since we don't really need the "expired but not really expired" behaviour when caching as a last resort.
+      begin
+        response = block.call(url)
+
+        entry = CacheEntry.new(cache_client, url, policy_group, response)
+
+        # Only store a new result if we roll a 0
+        r = rand(refresh_probability)
+        entry.store(expires_in, refresh_window: 1.minute) if r == 0
+
+        response
+      rescue Px::Service::ServiceError => ex
+        cache_logger.error "Service responded with exception: #{ex.class.name}: #{ex.message}\n#{ex.backtrace.join('\n')}" if cache_logger
+
+        entry = CacheEntry.fetch(cache_client, url, policy_group)
+        if entry.nil?
+          # Re-raise the error, no cached response
+          raise ex
+        end
+
+        entry.touch(expires_in, refresh_window: 1.minute)
+        entry.data
+      end
+    end
+
+    ##
+    # Use the cache as a first resort.  This path will only make a request if there is no entry in the cache
+    # or if the cache entry has expired.  It follows logic similar to ActiveSupport::Cache.  If the cache entry
+    # has expired (but is still present) and the request fails, the cached value is still returned, as if this was
+    # cache_last_resort.
+    def cache_first_resort(url, policy_group: 'general', expires_in: nil, &block)
+      entry = CacheEntry.fetch(cache_client, url, policy_group)
+
+      if entry
+        if entry.expired?
+          # Cache entry exists but is expired.  This call to cache_first_resort will refresh the cache by
+          # calling the block, but to prevent lots of others from also trying to refresh, first it updates
+          # the expiry date on the entry so that other callers that come in while we're requesting the update
+          # don't also try to update the cache.
+          entry.touch(expires_in)
+        else
+          return entry.data
+        end
+      end
+
+      begin
+        response = block.call(url)
+
+        entry = CacheEntry.new(cache_client, url, policy_group, response)
+        entry.store(expires_in)
+        response
+      rescue Px::Service::ServiceError => ex
+        cache_logger.error "Service responded with exception: #{ex.class.name}: #{ex.message}\n#{ex.backtrace.join('\n')}" if cache_logger
+
+        if entry.nil?
+          # Re-raise the error, no cached response
+          raise ex
+        end
+
+        # Set the entry to be expired again (but reset the refresh window).  This allows the next call to try again
+        # (assuming the circuit breaker is reset) but keeps the value in the cache in the meantime
+        entry.touch(0.seconds)
+        entry.data
+      end
+    end
+
+    def no_cache(url, &block)
+      block.call(url)
+    end
+  end
+end

data/lib/px/service/client/circuit_breaker.rb

@@ -0,0 +1,47 @@
+require 'circuit_breaker'
+
+module Px::Service::Client
+  module CircuitBreaker
+    extend ActiveSupport::Concern
+
+    included do
+      include ::CircuitBreaker
+
+      # Default circuit breaker configuration.  Can be overridden
+      circuit_handler do |handler|
+        handler.failure_threshold = 5
+        handler.failure_timeout = 7
+        handler.invocation_timeout = 5
+        handler.excluded_exceptions = [Px::Service::ServiceRequestError]
+      end
+
+      class <<self
+        alias_method_chain :circuit_method, :exceptions
+      end
+    end
+
+
+    module ClassMethods
+      ##
+      # Takes a splat of method names, and wraps them with the circuit_handler.
+      # Overrides the circuit_method provided by ::CircuitBreaker
+      def circuit_method_with_exceptions(*methods)
+        circuit_handler = self.circuit_handler
+
+        methods.each do |meth|
+          m = instance_method(meth)
+          define_method(meth) do |*args|
+            begin
+              circuit_handler.handle(self.circuit_state, m.bind(self), *args)
+            rescue Px::Service::ServiceError, Px::Service::ServiceRequestError => ex
+              raise ex
+            rescue StandardError => ex
+              # Wrap other exceptions, includes CircuitBreaker::CircuitBrokenException
+              raise Px::Service::ServiceError.new(ex.message, 503), ex, ex.backtrace
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/px/service/client/future.rb

@@ -0,0 +1,91 @@
+# This is based on this code: https://github.com/bitherder/stitch
+
+require 'fiber'
+
+module Px::Service::Client
+  class Future
+    class AlreadyCompletedError < StandardError; end
+
+    ##
+    # Create a new future. If a block is given, it is executed and the future is automatically completed
+    # with the block's return value
+    def initialize
+      @completed = false
+      @pending_calls = []
+
+      if block_given?
+        Fiber.new do
+          begin
+            complete(yield)
+          rescue Exception => ex
+            complete(ex)
+          end
+        end.resume
+      end
+    end
+
+    def complete(value)
+      raise AlreadyCompletedError.new if @completed
+
+      @value = value
+      @completed = true
+      @pending_calls.each do |pending_call|
+        if value.kind_of?(Exception)
+          pending_call[:fiber].resume(value)
+        else
+          result = nil
+          begin
+            if pending_call[:method]
+              result = value.send(pending_call[:method], *pending_call[:args])
+            else
+              result = value
+            end
+          rescue Exception => ex
+            result = ex
+          end
+          pending_call[:fiber].resume(result)
+        end
+      end
+    end
+
+    def value
+      if @completed
+        @value
+      else
+        wait_for_value(nil)
+      end
+    end
+
+    def completed?
+      @completed
+    end
+
+    def method_missing(method, *args)
+      if @completed
+        raise @value if @value.kind_of?(Exception)
+
+        super unless respond_to_missing?(method)
+        @value.send(method, *args)
+      else
+        result = wait_for_value(method, *args)
+        raise result if result.kind_of?(Exception)
+        result
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      # NoMethodError is handled by method_missing here, so that exceptions
+      # are raised properly even though they don't respond_to the same things
+      # as the future values themselves
+      true
+    end
+
+    private
+
+    def wait_for_value(method, *args)
+      # TODO: check for root fiber
+      @pending_calls << { fiber: Fiber.current, method: method, args: args }
+      Fiber.yield
+    end
+  end
+end