cottus 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 98294e799b9473ff9c55f0b3673ac133661a62e0
+  data.tar.gz: 222dbb234ad98069ce4991591d4e9d9d3d6e9803
+SHA512:
+  metadata.gz: b4600796f17181e67de09adf662cf784306e121c110b4decc78a8853d1c136ca0e7dd4aadd92f581c5cbf5ddc27adf20d0c4061571ddb5560da7ed2d6ddc4754
+  data.tar.gz: 444b03bf8efb611f7e0c9570d6bb917da52f037b25fa57a76db38fe5c579737044d0d677e0f2e0a3d8aa111de96d5fe7e852131d36dda78934cf585c4898245f

data/README.md

@@ -0,0 +1,129 @@
+# cottus
+
+[![Build Status](https://travis-ci.org/mthssdrbrg/cottus.png?branch=master)](https://travis-ci.org/mthssdrbrg/cottus)
+[![Coverage Status](https://coveralls.io/repos/mthssdrbrg/cottus/badge.png?branch=master)](https://coveralls.io/r/mthssdrbrg/cottus?branch=master)
+
+Cottus, a multi limp HTTP client with an aim of making the use of multiple hosts
+providing the same service easier with regards to timeouts and automatic fail-over.
+
+Sure enough, if you don't mind using an ELB in EC2 and making your service public,
+or setting up something like HAProxy, then this is not a client library for you.
+
+Initialize a client with a list of hosts and it will happily round-robin load-balance
+requests among them.
+You could very well define your own strategy if you feel like it and inject it
+into Cottus, more on that further down.
+
+## Installation
+
+```
+gem install cottus
+```
+
+## Usage
+
+```ruby
+require 'cottus'
+
+client = Cottus::Client.new(['http://n1.com', 'http://n2.com', 'http://n3.com'])
+
+# This request will be made against http://n1.com
+response = client.get('/any/path', query: {id: 1337})
+puts response.body, response.code, response.message, response.headers.inspect
+
+# This request will be made against http://n2.com
+response = client.post('/any/path', query: {id: 1337}, body: { attribute: 'cool'})
+puts response.body, response.code, response.message, response.headers.inspect
+```
+
+That's about it! Cottus exposes almost all of the same methods with the same semantics as
+HTTParty does, with the exception of ```HTTParty#copy```.
+
+## Strategy
+
+A "Strategy" is merely a class implementing an ```execute``` method that is
+responsible for carrying out the action specified by the passed ```meth```
+argument.
+
+The Strategy class must however also implement an ```#initialize``` method which
+takes three parameters: ```hosts```, ```client``` and an ```options``` hash:
+
+```ruby
+class SomeStrategy
+  def initialize(hosts, client, options={})
+  end
+
+  def execute(meth, path, options={}, &block)
+    # do something funky here
+  end
+end
+```
+
+If you don't mind inheritance there's a base class (```Cottus::Strategy```) that
+you can inherit from and the above class would instead become:
+
+```ruby
+class SomeStrategy < Strategy
+  def execute(meth, path, options={}, &block)
+    # do something funky here
+  end
+end
+```
+
+If you'd like to do some initialization on your own and override
+```#initialize``` make sure to call ```#super``` or set the required instance
+variables (```@hosts```, ```@client```) on your own.
+
+It should be noted that I haven't decided on how strategies should be working to
+a 100% yet, so this might change in future releases.
+
+See ```lib/cottus/strategies.rb``` for further examples.
+
+### Using your own strategy
+
+In order to use your own Strategy class, supply the name of the class in the
+options hash as you create your instance, as such:
+
+```ruby
+require 'cottus'
+
+client = Cottus::Client.new(['http://n1.com', 'http://n2.com'], strategy: MyStrategy)
+```
+
+Want some additional options passed when your strategy is initialized?
+
+No problem! Pass them into the ```strategy_options``` sub-hash of the options
+hash to the client.
+
+```ruby
+require 'cottus'
+
+client = Cottus::Client.new(['http://n1.com', 'http://n2.com'], strategy: MyStrategy,
+  strategy_options: { an_option: 'cool stuff!'})
+```
+
+The options will be passed as an options hash to the strategy, as explained
+above.
+
+Boom! That's all there is, for the moment.
+
+## Cottus?
+
+Cottus was one of the Hecatonchires of Greek mythology.
+The Hecatonchires, "Hundred-Handed Ones" (also with 50 heads) were figures in an
+archaic stage of Greek mythology.
+Three giants of incredible strength and ferocity that surpassed that of all Titans whom they helped overthrow.
+
+## Copyright
+Copyright 2013 Mathias Söderberg
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

data/lib/cottus.rb

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+require 'httparty'
+
+require 'cottus/client'
+require 'cottus/strategies'

data/lib/cottus/client.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+module Cottus
+  class Client
+
+    attr_reader :hosts, :strategy
+
+    def initialize(hosts, options={})
+      @hosts = parse_hosts(hosts)
+      @strategy = create_strategy(options)
+    end
+
+    def get(path, options={}, &block)
+      @strategy.execute(:get, path, options, &block)
+    end
+
+    def put(path, options={}, &block)
+      @strategy.execute(:put, path, options, &block)
+    end
+
+    def post(path, options={}, &block)
+      @strategy.execute(:post, path, options, &block)
+    end
+
+    def delete(path, options={}, &block)
+      @strategy.execute(:delete, path, options, &block)
+    end
+
+    def head(path, options={}, &block)
+      @strategy.execute(:head, path, options, &block)
+    end
+
+    def patch(path, options={}, &block)
+      @strategy.execute(:patch, path, options, &block)
+    end
+
+    def options(path, options={}, &block)
+      @strategy.execute(:options, path, options, &block)
+    end
+
+    def move(path, options={}, &block)
+      @strategy.execute(:move, path, options, &block)
+    end
+
+    private
+
+    def parse_hosts(hosts)
+      hosts.is_a?(String) ? hosts.split(',') : hosts
+    end
+
+    def http
+      HTTParty
+    end
+
+    def create_strategy(options)
+      strategy = (options[:strategy] || RoundRobinStrategy).new(hosts, http, options[:strategy_options])
+    end
+  end
+end

data/lib/cottus/strategies.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+
+module Cottus
+
+  VALID_EXCEPTIONS = [
+    Timeout::Error,
+    Errno::ECONNREFUSED,
+    Errno::ETIMEDOUT,
+    Errno::ECONNRESET
+  ].freeze
+
+  class Strategy
+    def initialize(hosts, client, options={})
+      @hosts, @client = hosts, client
+    end
+
+    def execute(meth, path, options={}, &block)
+      raise NotImplementedError, 'implement me in subclass'
+    end
+  end
+
+  class RoundRobinStrategy < Strategy
+    def initialize(hosts, client, options={})
+      super
+
+      @current = 0
+      @mutex = Mutex.new
+    end
+
+    def execute(meth, path, options={}, &block)
+      tries = 0
+
+      begin
+        @client.send(meth, next_host + path, options, &block)
+      rescue *VALID_EXCEPTIONS => e
+        if tries >= @hosts.count
+          raise e
+        else
+          tries += 1
+          retry
+        end
+      end
+    end
+
+    private
+
+    def next_host
+      @mutex.synchronize do
+        h = @hosts[@current]
+        @current = (@current + 1) % @hosts.count
+        h
+      end
+    end
+  end
+
+  class RetryableRoundRobinStrategy < RoundRobinStrategy
+    def initialize(hosts, client, options={})
+      super
+
+      @timeouts = options[:timeouts] || [1, 3, 5]
+    end
+
+    def execute(meth, path, options={}, &block)
+      tries = 0
+      starting_host = host = next_host
+
+      begin
+        @client.send(meth, host + path, options, &block)
+      rescue *VALID_EXCEPTIONS => e
+        if tries < @timeouts.size
+          sleep @timeouts[tries]
+          tries += 1
+          retry
+        else
+          host = next_host
+          raise e if host == starting_host
+
+          tries = 0
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/cottus/version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module Cottus
+  VERSION = '0.1.3'.freeze
+end

data/spec/acceptance/cottus_acceptance_spec.rb

@@ -0,0 +1,182 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+module Cottus
+  describe 'Client acceptance spec' do
+    shared_examples 'exception handling' do
+      context 'exceptions' do
+        context 'Timeout::Error' do
+          it 'attempts to use each host until one succeeds' do
+            stub_request(verb, 'http://localhost:1234/some/path').to_timeout
+            stub_request(verb, 'http://localhost:12345/some/path').to_timeout
+            request = stub_request(verb, 'http://localhost:12343/some/path')
+
+            client.send(verb, '/some/path')
+            expect(request).to have_been_requested
+          end
+
+          it 'gives up after trying all hosts' do
+            stub_request(verb, 'http://localhost:1234/some/path').to_timeout
+            stub_request(verb, 'http://localhost:12345/some/path').to_timeout
+            stub_request(verb, 'http://localhost:12343/some/path').to_timeout
+
+            expect { client.send(verb, '/some/path') }.to raise_error(Timeout::Error)
+          end
+        end
+
+        [Errno::ETIMEDOUT, Errno::ECONNREFUSED, Errno::ECONNRESET].each do |error|
+          context "#{error}" do
+            it 'attempts to use each host until one succeeds' do
+              stub_request(verb, 'http://localhost:1234/some/path').to_raise(error)
+              stub_request(verb, 'http://localhost:12345/some/path').to_raise(error)
+              request = stub_request(verb, 'http://localhost:12343/some/path')
+
+              client.send(verb, '/some/path')
+              expect(request).to have_been_requested
+            end
+
+            it 'gives up after trying all hosts' do
+              stub_request(verb, 'http://localhost:1234/some/path').to_raise(error)
+              stub_request(verb, 'http://localhost:12345/some/path').to_raise(error)
+              stub_request(verb, 'http://localhost:12343/some/path').to_raise(error)
+
+              expect { client.send(verb, '/some/path') }.to raise_error(error)
+            end
+          end
+        end
+      end
+    end
+
+    shared_examples 'load balancing' do
+      context 'with several hosts' do
+        it 'uses the first host for the first request' do
+          request = stub_request(verb, 'http://localhost:1234/some/path')
+          client.send(verb, '/some/path')
+          expect(request).to have_been_requested
+        end
+
+        it 'uses the second host for the second request' do
+          stub_request(verb, 'http://localhost:1234/some/path')
+          request = stub_request(verb, 'http://localhost:12345/some/path')
+          2.times { client.send(verb, '/some/path') }
+          expect(request).to have_been_requested
+        end
+      end
+
+      context 'with a single host' do
+        let :client do
+          Client.new('http://localhost:1234')
+        end
+
+        it 'uses the single host for the first request' do
+          request = stub_request(verb, 'http://localhost:1234/some/path')
+          client.send(verb, '/some/path')
+          expect(request).to have_been_requested
+        end
+
+        it 'uses the single host for the second request' do
+          request = stub_request(verb, 'http://localhost:1234/some/path')
+          2.times { client.send(verb, '/some/path') }
+          expect(request).to have_been_requested.twice
+        end
+      end
+    end
+
+    let :client do
+      Client.new('http://localhost:1234,http://localhost:12345,http://localhost:12343')
+    end
+
+    describe '#get' do
+      include_examples 'load balancing' do
+        let(:verb) { :get }
+      end
+
+      include_examples 'exception handling' do
+        let(:verb) { :get }
+      end
+    end
+
+    describe '#post' do
+      include_examples 'load balancing' do
+        let(:verb) { :post }
+      end
+
+      include_examples 'exception handling' do
+        let(:verb) { :post }
+      end
+    end
+
+    describe '#put' do
+      include_examples 'load balancing' do
+        let(:verb) { :put }
+      end
+
+      include_examples 'exception handling' do
+        let(:verb) { :put }
+      end
+    end
+
+    describe '#head' do
+      include_examples 'load balancing' do
+        let(:verb) { :head }
+      end
+
+      include_examples 'exception handling' do
+        let(:verb) { :head }
+      end
+    end
+
+    describe '#patch' do
+      include_examples 'load balancing' do
+        let(:verb) { :patch }
+      end
+
+      include_examples 'exception handling' do
+        let(:verb) { :patch }
+      end
+    end
+
+    describe '#delete' do
+      include_examples 'load balancing' do
+        let(:verb) { :delete }
+      end
+
+      include_examples 'exception handling' do
+        let(:verb) { :delete }
+      end
+    end
+
+    describe '#move' do
+      include_examples 'load balancing' do
+        let(:verb) { :move }
+      end
+
+      include_examples 'exception handling' do
+        let(:verb) { :move }
+      end
+    end
+
+    describe '#options' do
+      include_examples 'load balancing' do
+        let(:verb) { :options }
+      end
+
+      include_examples 'exception handling' do
+        let(:verb) { :options }
+      end
+    end
+
+    describe '#copy' do
+      pending do
+        include_examples 'load balancing' do
+          let(:verb) { :options }
+        end
+
+        include_examples 'exception handling' do
+          let(:verb) { :options }
+        end
+      end
+    end
+  end
+end

data/spec/cottus/client_spec.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+module Cottus
+  describe Client do
+    describe '#initialize' do
+      it 'accepts an array of hosts w/ ports' do
+        client = described_class.new(['host1:123', 'host2:125'])
+        expect(client.hosts).to eq ['host1:123', 'host2:125']
+      end
+
+      it 'accepts a connection string w/ ports' do
+        client = described_class.new('host1:1255,host2:1255,host3:1255')
+        expect(client.hosts).to eq ['host1:1255', 'host2:1255', 'host3:1255']
+      end
+    end
+
+    context 'retry strategy' do
+      context 'by default' do
+        let :client do
+          described_class.new('http://host1.com/')
+        end
+
+        it 'uses a simple round-robin strategy' do
+          expect(client.strategy).to be_a RoundRobinStrategy
+        end
+      end
+
+      context 'when given an explicit strategy' do
+        let :client do
+          described_class.new('http://localhost:1234', strategy: strategy)
+        end
+
+        let :strategy do
+          double(:strategy, new: strategy_impl)
+        end
+
+        let :strategy_impl do
+          double(:strategy_impl)
+        end
+
+        it 'uses given strategy' do
+          expect(client.strategy).to eq(strategy_impl)
+        end
+
+        context 'strategy options' do
+          it 'passes explicit options when creating strategy' do
+            client = described_class.new('http://localhost:1234', strategy: strategy, strategy_options: {timeouts: [1, 3, 5]})
+            expect(strategy).to have_received(:new).with(anything, anything, {timeouts: [1, 3, 5]})
+          end
+        end
+      end
+    end
+  end
+end

data/spec/cottus/strategies_spec.rb

@@ -0,0 +1,186 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+module Cottus
+  describe Strategy do
+    let :strategy do
+      described_class.new(['http://n1.com', 'http://n2.com'], http)
+    end
+
+    let :http do
+      double(:http, meth: nil)
+    end
+
+    describe '#execute' do
+      it 'raises a NotImplementedError' do
+        expect { strategy.execute(:meth, '/some/path') }.to raise_error(NotImplementedError, 'implement me in subclass')
+      end
+    end
+  end
+
+  shared_examples 'a round-robin strategy' do
+    context 'with a single host' do
+      let :hosts do
+        ['n1']
+      end
+
+      it 'uses the single host for the first request' do
+        strategy.execute(:meth, '/some/path', query: { query: 1 })
+
+        expect(http).to have_received(:meth).with('n1/some/path', query: { query: 1 }).once
+      end
+
+      it 'uses the single host for the second request' do
+        2.times { strategy.execute(:meth, '/some/path', query: { query: 1 }) }
+
+        expect(http).to have_received(:meth).with('n1/some/path', query: { query: 1 }).twice
+      end
+    end
+
+    context 'with several hosts' do
+      let :hosts do
+        ['n1', 'n2', 'n3']
+      end
+
+      it 'uses the first host for the first request' do
+        strategy.execute(:meth, '/some/path', query: { query: 1 })
+
+        expect(http).to have_received(:meth).with('n1/some/path', query: { query: 1 }).once
+      end
+
+      it 'uses the second host for the second request' do
+        2.times { strategy.execute(:meth, '/some/path', query: { query: 1 }) }
+
+        expect(http).to have_received(:meth).with('n1/some/path', query: { query: 1 }).once
+        expect(http).to have_received(:meth).with('n2/some/path', query: { query: 1 }).once
+      end
+
+      it 'uses each host in turn' do
+        3.times { strategy.execute(:meth, '/some/path', query: { query: 1 }) }
+
+        expect(http).to have_received(:meth).with('n1/some/path', query: { query: 1 }).once
+        expect(http).to have_received(:meth).with('n2/some/path', query: { query: 1 }).once
+        expect(http).to have_received(:meth).with('n3/some/path', query: { query: 1 }).once
+      end
+    end
+  end
+
+  describe RoundRobinStrategy do
+    let :strategy do
+      described_class.new(hosts, http)
+    end
+
+    let :http do
+      double(:http, meth: nil)
+    end
+
+    describe '#execute' do
+      context 'without exceptions' do
+        it_behaves_like 'a round-robin strategy'
+      end
+
+      context 'with exceptions' do
+        [Timeout::Error, Errno::ETIMEDOUT, Errno::ECONNREFUSED, Errno::ECONNRESET].each do |error|
+          context "when #{error} is raised" do
+            context 'with a single host' do
+              let :hosts do
+                ['n1']
+              end
+
+              it 'gives up' do
+                hosts.each { |h| http.stub(:meth).with("#{h}/some/path", {}).and_raise(error) }
+
+                expect { strategy.execute(:meth, '/some/path') }.to raise_error(error)
+              end
+            end
+
+            context 'with several hosts' do
+              let :hosts do
+                ['n1', 'n2', 'n3']
+              end
+
+              it 'attempts to use each host until one succeeds' do
+                ['n1', 'n2'].each { |h| http.stub(:meth).with("#{h}/some/path", {}).and_raise(error) }
+
+                strategy.execute(:meth, '/some/path')
+                expect(http).to have_received(:meth).with('n3/some/path', {})
+              end
+
+              it 'gives up after trying all hosts' do
+                hosts.each { |h| http.stub(:meth).with("#{h}/some/path", {}).and_raise(error) }
+
+                expect { strategy.execute(:meth, '/some/path') }.to raise_error(error)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+  describe RetryableRoundRobinStrategy do
+    let :strategy do
+      described_class.new(hosts, http, timeouts: [0, 0, 0])
+    end
+
+    let :http do
+      double(:http, meth: nil)
+    end
+
+    describe '#execute' do
+      context 'without any exceptions' do
+        it_behaves_like 'a round-robin strategy'
+      end
+
+      context 'with exceptions' do
+        [Timeout::Error, Errno::ETIMEDOUT, Errno::ECONNREFUSED, Errno::ECONNRESET].each do |error|
+          context "when #{error} is raised" do
+            context 'with a single host' do
+              let :hosts do
+                ['n1']
+              end
+
+              it 'uses the single host for three consecutive exceptions' do
+                expect(http).to receive(:meth).with('n1/some/path', {}).exactly(3).times.and_raise(error)
+                expect(http).to receive(:meth).with('n1/some/path', {}).once
+                expect(strategy).to receive(:sleep).with(0).exactly(3).times
+
+                strategy.execute(:meth, '/some/path')
+              end
+
+              it 'gives up after three retries' do
+                expect(http).to receive(:meth).with('n1/some/path', {}).exactly(4).times.and_raise(error)
+                expect(strategy).to receive(:sleep).with(0).exactly(3).times
+
+                expect { strategy.execute(:meth, '/some/path') }.to raise_error(error)
+              end
+            end
+
+            context 'with several hosts' do
+              let :hosts do
+                ['n1', 'n2', 'n3']
+              end
+
+              it 'uses the same host for three consecutive exceptions' do
+                expect(http).to receive(:meth).with('n1/some/path', {}).exactly(3).times.and_raise(error)
+                expect(http).to receive(:meth).with('n1/some/path', {}).once
+                expect(strategy).to receive(:sleep).with(0).exactly(3).times
+
+                strategy.execute(:meth, '/some/path')
+              end
+
+              it 'switches host after three retries' do
+                expect(http).to receive(:meth).with('n1/some/path', {}).exactly(4).times.and_raise(error)
+                expect(http).to receive(:meth).with('n2/some/path', {}).once
+                expect(strategy).to receive(:sleep).with(0).exactly(3).times
+
+                strategy.execute(:meth, '/some/path')
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+require 'webmock/rspec'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.order = 'random'
+end
+
+require 'coveralls'
+require 'simplecov'
+
+if ENV.include?('TRAVIS')
+  Coveralls.wear!
+  SimpleCov.formatter = Coveralls::SimpleCov::Formatter
+end
+
+SimpleCov.start do
+  add_group 'Source', 'lib'
+  add_group 'Unit tests', 'spec/cottus'
+  add_group 'Acceptance tests', 'spec/acceptance'
+end
+
+require 'cottus'

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: cottus
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- Mathias Söderberg
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: HTTP client for making requests against a set of hosts
+email:
+- mths@sdrbrg.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/cottus/client.rb
+- lib/cottus/strategies.rb
+- lib/cottus/version.rb
+- lib/cottus.rb
+- README.md
+- spec/acceptance/cottus_acceptance_spec.rb
+- spec/cottus/client_spec.rb
+- spec/cottus/strategies_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/mthssdrbrg/cottus
+licenses:
+- Apache License 2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.6
+signing_key: 
+specification_version: 4
+summary: Multi limp HTTP client
+test_files:
+- spec/acceptance/cottus_acceptance_spec.rb
+- spec/cottus/client_spec.rb
+- spec/cottus/strategies_spec.rb
+- spec/spec_helper.rb