3scale-3scale_ws_api_for_ruby 0.4.7

data/README

@@ -0,0 +1,63 @@
+= Interface for 3scale web service API monitoring system
+
+This plugin provides interface for communication with 3scale monitoring system.
+
+== Configuration
+
+If you are using rails 2.1 or newer, put this into your config/environment.rb
+file:
+
+  config.gem "3scale_interface"
+
+If you are using older version, put there this instead:
+
+  require "3scale_interface"
+
+== Usage
+
+First, create new interface object with 3scale backed hostname and Your
+private authentication key:
+
+  interface = ThreeScale::Interface.new("http://3scale.net", "a3b034...")
+
+Because the object is stateless, you can create just one and store it globally.
+
+Then for each request to Your service:
+
+1. Start the transaction with user key and (optionally) estimated resource
+usage (in this example it is: 1 hit and 42000 kilobytes of storage space),
+
+  transaction = interface.start(user_key, 'hits' => 1, 'storage' => 42000)
+
+This will return transaction data (if successful). It is a hash containing
+these fields:
+
+<tt>:id</tt>::
+  transaction id necessary for confirmation or cancellation of transaction
+  (see following steps).
+
+<tt>:provider_verification_key</tt>::
+  the provider should send this key back to user so he/she can verify the
+  authenticity of the response.
+
+<tt>:contract_name</tt>::
+  name of contract the user is signed for. This can be used to send
+  different response according to contract type, if that is desired.
+
+2. Process the request.
+
+2a. If the processing was successful:
+Call +confirm+:
+
+  interface.confirm(transaction[:id])
+
+Or call it with actual resource usage, if it differs from predicted one:
+
+  interface.confirm(transaction[:id], 'hits' => 1, 'storage' => 40500)
+
+2b. If there was some error, call +cancel+:
+
+  interface.cancel(transaction[:id])
+
+3. Send response back to the user together with +provider_verification_key+.
+

data/Rakefile

@@ -0,0 +1,29 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Run unit tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = '3scale interface'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = eval(File.read(File.dirname(__FILE__) + '/3scale_ws_api_for_ruby.gemspec'))
+
+Rake::GemPackageTask.new(spec) do |package|
+    package.need_tar = true
+end

data/init.rb

@@ -0,0 +1 @@
+require "#{File.dirname(__FILE__)}/lib/3scale_interface"

data/lib/3scale/interface.rb

@@ -0,0 +1,236 @@
+require 'cgi'
+require 'hpricot'
+require 'net/http'
+
+module ThreeScale # :nodoc:
+  class Error < StandardError; end
+
+  # Base class for exceptions caused by user.
+  class UserError < Error; end
+
+  # Exception raised when contract between user and provider is not active.
+  # Contract can be inactive when it is pending (requires confirmation from
+  # provider), suspended or canceled.
+  class ContractNotActive < UserError; end
+
+  # Exception raised when usage limits configured for contract are already
+  # exceeded.
+  class LimitsExceeded < UserError; end
+
+  # Exception raised when +user_key+ is not valid. This can mean that contract
+  # between provider and user does not exists, or the passed +user_key+ does
+  # not correspond to the key associated with this contract.
+  class UserKeyInvalid < UserError; end
+
+  
+  # Base class for exceptions caused by provider.
+  class ProviderError < Error; end
+
+  # Exception raised when some metric name in provider +usage+ hash does not
+  # correspond to metric configured for the service.
+  class MetricInvalid < ProviderError; end
+
+  # Exception raised when provider authentication key is not valid. The provider
+  # needs to make sure that the key used is the same as the one that was
+  # generated for him/her when he/she published a service on 3scale.
+  class ProviderKeyInvalid < ProviderError; end
+
+  # Exception raised when transaction corresponding to given +transaction_id+
+  # does not exists. Methods +confirm+ and +cancel+ need valid transaction id
+  # that is obtained by preceding call to +start+.
+  class TransactionNotFound < ProviderError; end
+
+
+  # Base class for exceptions caused by 3scale backend system.
+  class SystemError < Error; end
+
+  # Other error.
+  class UnknownError < SystemError; end
+
+
+  
+  # This class provides interface to 3scale monitoring system.
+  #
+  # Objects of this class are stateless and can be shared through multiple
+  # transactions and by multiple clients.
+  class Interface
+
+    # Hostname of 3scale server.
+    attr_accessor :host
+
+    # Key that uniquely identifies the provider. This key is known only to the
+    # provider and to 3scale.
+    attr_accessor :provider_authentication_key
+
+    # Create a 3scale interface object.
+    #
+    # == Arguments
+    # +host+:: Hostname of 3scale backend server.
+    # +provider_authentication_key+:: Unique key that identifies this provider.
+    def initialize(host = nil, provider_authentication_key = nil)
+      @host = host
+      @provider_authentication_key = provider_authentication_key
+    end
+
+
+    # Starts a transaction. This can be used also to report estimated resource
+    # usage of the request.
+    #
+    # == Arguments
+    # +user_key+:: Key that uniquely identifies an user of the service.
+    # +usage+::
+    #   A hash of metric names/values pairs that contains predicted resource
+    #   usage of this request.
+    #   
+    #   For example, if this request is going to take 10MB of storage space,
+    #   then this parameter could contain {'storage' => 10}. The values may be
+    #   only approximate or they can be missing altogether. In these cases, the
+    #   real values must be reported using method +confirm+.
+    #
+    # == Return values
+    # A hash containing there keys:
+    # <tt>:id</tt>::
+    #   Transaction id. This is required for confirmation/cancellation of the
+    #   transaction later.
+    # <tt>:provider_verification_key</tt>::
+    #   This key should be sent back to the user so he/she can use it to verify
+    #   the authenticity of the provider.
+    # <tt>:contract_name</tt>::
+    #   This is name of the contract the user is singed for. This information
+    #   can be used to serve different responses according to contract types,
+    #   if that is desirable.
+    #
+    # == Exceptions
+    #
+    # ThreeScale::UserKeyInvalid:: +user_key+ is not valid
+    # ThreeScale::ProviderKeyInvalid:: +provider_authentication_key+ is not valid
+    # ThreeScale::MetricInvalid:: +usage+ contains invalid metrics
+    # ThreeScale::ContractNotActive:: contract is not active
+    # ThreeScale::LimitsExceeded:: usage limits are exceeded
+    # ThreeScale::UnknownError:: some other unexpected error
+    #
+    def start(user_key, usage = {})
+      uri = URI.parse("#{host}/transactions.xml")
+      params = {
+        'user_key' => prepare_key(user_key),
+        'provider_key' => provider_authentication_key
+      }
+      params.merge!(encode_params(usage, 'usage'))
+      response = Net::HTTP.post_form(uri, params)
+
+      if response.is_a?(Net::HTTPSuccess)
+        element = Hpricot::XML(response.body).at('transaction')
+        [:id, :provider_verification_key, :contract_name].inject({}) do |memo, key|
+          memo[key] = element.at(key).inner_text if element.at(key)
+          memo
+        end
+      else
+        handle_error(response.body)
+      end
+    end
+
+    # Confirms a transaction.
+    #
+    # == Arguments
+    #
+    # +transaction_id+::
+    #   A transaction id obtained from previous call to +start+.
+    # +usage+::
+    #   A hash of metric names/values pairs containing actual resource usage
+    #   of this request. This parameter is required only if no usage information
+    #   was passed to method +start+ for this transaction, or if it was only
+    #   approximate.
+    #
+    # == Return values
+    #
+    # If there were no exceptions raised, returns true.
+    #
+    # == Exceptions
+    #
+    # ThreeScale::TransactionNotFound:: transactions does not exits
+    # ThreeScale::ProviderKeyInvalid:: +provider_authentication_key+ is not valid
+    # ThreeScale::MetricInvalid:: +usage+ contains invalid metrics
+    # ThreeScale::UnknownError:: some other unexpected error
+    #
+    def confirm(transaction_id, usage = {})
+      uri = URI.parse("#{host}/transactions/#{CGI.escape(transaction_id.to_s)}/confirm.xml")
+      params = {
+        'provider_key' => provider_authentication_key
+      }
+      params.merge!(encode_params(usage, 'usage'))
+
+      response = Net::HTTP.post_form(uri, params)
+      response.is_a?(Net::HTTPSuccess) ? true : handle_error(response.body)
+    end
+
+    # Cancels a transaction.
+    #
+    # Use this if request processing failed. Any estimated resource usage
+    # reported by preceding call to +start+ will be deleted. You don't have to
+    # call this if call to +start+ itself failed.
+    #
+    # == Arguments
+    #
+    # +transaction_id+::
+    #   A transaction id obtained from previous call to +start+.
+    #
+    # == Return values
+    #
+    # If there were no exceptions raised, returns true.
+    #
+    # == Exceptions
+    #
+    # ThreeScale::TransactionNotFound:: transactions does not exits
+    # ThreeScale::ProviderKeyInvalid:: +provider_authentication_key+ is not valid
+    # ThreeScale::UnknownError:: some other unexpected error
+    #
+    def cancel(transaction_id)
+      uri = URI.parse("#{host}/transactions/#{CGI.escape(transaction_id.to_s)}.xml" +
+          "?provider_key=#{CGI.escape(provider_authentication_key)}")
+
+      response = Net::HTTP.start(uri.host, uri.port) do |http|
+        http.delete("#{uri.path}?#{uri.query}")
+      end
+
+      response.is_a?(Net::HTTPSuccess) ? true : handle_error(response.body)
+    end
+
+    KEY_PREFIX = '3scale-' # :nodoc:
+
+    # This can be used to quickly distinguish between keys used with 3scale
+    # system and any other keys the provider might use. Returns true if the key
+    # is for 3scale system.
+    def system_key?(key)
+      # Key should start with prefix
+      key.index(KEY_PREFIX) == 0
+    end
+
+    private
+
+    # Encode hash into form suitable for sending it as params of HTTP request.
+    def encode_params(params, prefix)
+      params.inject({}) do |memo, (key, value)|
+        memo["#{prefix}[#{CGI.escape(key)}]"] = CGI.escape(value.to_s)
+        memo
+      end
+    end
+
+    def prepare_key(key)
+      system_key?(key) ? key[KEY_PREFIX.length..-1] : key
+    end
+
+    CODES_TO_EXCEPTIONS = {
+      'user.exceeded_limits' => LimitsExceeded,
+      'user.invalid_key' => UserKeyInvalid,
+      'user.inactive_contract' => ContractNotActive,
+      'provider.invalid_key' => ProviderKeyInvalid,
+      'provider.invalid_metric' => MetricInvalid,
+      'provider.invalid_transaction_id' => TransactionNotFound} # :nodoc:
+
+    def handle_error(response)
+      element = Hpricot::XML(response).at('error')
+      raise UnknownError unless element
+      raise CODES_TO_EXCEPTIONS[element[:id]] || UnknownError, element.inner_text
+    end
+  end
+end

data/lib/3scale_interface.rb

@@ -0,0 +1 @@
+require "#{File.dirname(__FILE__)}/3scale/interface"

data/test/interface_test.rb

@@ -0,0 +1,218 @@
+require 'rubygems'
+require 'activesupport'
+require 'fake_web'
+require 'mocha'
+require 'test/unit'
+
+require "#{File.dirname(__FILE__)}/../lib/3scale/interface"
+
+class InterfaceTest < Test::Unit::TestCase
+  def setup
+    @interface = ThreeScale::Interface.new('http://3scale.net', 'some_key')
+  end
+
+  def test_start_should_raise_exception_on_invalid_user_key
+    FakeWeb.register_uri('http://3scale.net/transactions.xml',
+      :status => ['403', 'Forbidden'],
+      :string => stub_error('user.invalid_key'))
+
+    assert_raise ThreeScale::UserKeyInvalid do
+      @interface.start('invalid_key')
+    end
+  end
+
+  def test_start_should_raise_exception_on_invalid_provider_key
+    FakeWeb.register_uri('http://3scale.net/transactions.xml',
+      :status => ['403', 'Forbidden'],
+      :string => stub_error('provider.invalid_key'))
+
+    assert_raise ThreeScale::ProviderKeyInvalid do
+      @interface.start('valid_key')
+    end
+  end
+
+  def test_start_should_raise_exception_on_inactive_contract
+    FakeWeb.register_uri('http://3scale.net/transactions.xml',
+      :status => ['403', 'Forbidden'],
+      :string => stub_error('user.inactive_contract'))
+
+    assert_raise ThreeScale::ContractNotActive do
+      @interface.start('valid_key', 'clicks' => 1)
+    end
+  end
+
+  def test_start_should_raise_exception_on_invalid_metric
+    FakeWeb.register_uri('http://3scale.net/transactions.xml',
+      :status => ['400', 'Bad Request'],
+      :string => stub_error('provider.invalid_metric'))
+
+    assert_raise ThreeScale::MetricInvalid do
+      @interface.start('valid_key', 'clicks' => 1)
+    end
+  end
+
+  def test_start_should_raise_exception_on_exceeded_limits
+    FakeWeb.register_uri('http://3scale.net/transactions.xml',
+      :status => ['403', 'Forbidden'],
+      :string => stub_error('user.exceeded_limits'))
+
+    assert_raise ThreeScale::LimitsExceeded do
+      @interface.start('valid_key', 'clicks' => 1)
+    end
+  end
+
+  def test_start_should_raise_exception_on_unexpected_error
+    FakeWeb.register_uri('http://3scale.net/transactions.xml',
+      :status => ['500', 'Internal Server Error'])
+
+    assert_raise ThreeScale::UnknownError do
+      @interface.start('valid_key', 'clicks' => 1)
+    end
+  end
+
+  def test_start_should_send_usage_data
+    Net::HTTP.expects(:post_form).
+      with(anything, has_entries('usage[hits]' => '1')).
+      returns(stub_response)
+
+    @interface.start('valid_key', 'hits' => 1)
+  end
+
+  def test_start_should_return_transaction_data_on_success
+    FakeWeb.register_uri('http://3scale.net/transactions.xml',
+      :status => ['200', 'OK'],
+      :string => {:id => '42', :provider_verification_key => 'some_key',
+        :contract_name => 'ultimate'}.to_xml(:root => 'transaction',
+        :dasherize => false))
+
+    result = @interface.start('valid_key', {'clicks' => 1})
+
+    assert_equal '42', result[:id]
+    assert_equal 'some_key', result[:provider_verification_key]
+    assert_equal 'ultimate', result[:contract_name]
+  end
+
+  def test_start_should_strip_3scale_prefix_from_user_key_before_sending
+    Net::HTTP.expects(:post_form).with(anything,
+      has_entries('user_key' => 'foo')).returns(stub_response)
+
+    @interface.start('3scale-foo')
+  end
+
+  def test_start_should_leave_user_key_unchanged_if_it_does_not_contain_3scale_prefix
+    Net::HTTP.expects(:post_form).with(anything,
+      has_entries('user_key' => 'foo')).returns(stub_response)
+
+    @interface.start('foo')
+  end
+
+  def test_confirm_should_raise_exception_on_invalid_transaction
+    FakeWeb.register_uri('http://3scale.net/transactions/42/confirm.xml',
+      :status => ['404', 'Not Found'],
+      :string => stub_error('provider.invalid_transaction_id'))
+
+    assert_raise ThreeScale::TransactionNotFound do
+      @interface.confirm(42)
+    end
+  end
+  
+  def test_confirm_should_raise_exception_on_invalid_provider_key
+    FakeWeb.register_uri('http://3scale.net/transactions/42/confirm.xml',
+      :status => ['403', 'Forbidden'],
+      :string => stub_error('provider.invalid_key'))
+
+    assert_raise ThreeScale::ProviderKeyInvalid do
+      @interface.confirm(42)
+    end
+  end
+
+  def test_confirm_should_raise_exception_on_invalid_metric
+    FakeWeb.register_uri('http://3scale.net/transactions/42/confirm.xml',
+      :status => ['400', 'Bad Request'],
+      :string => stub_error('provider.invalid_metric'))
+
+    assert_raise ThreeScale::MetricInvalid do
+      @interface.confirm(42, 'clicks' => 1)
+    end
+  end
+
+  def test_confirm_should_raise_exception_on_unexpected_error
+    FakeWeb.register_uri('http://3scale.net/transactions/42/confirm.xml',
+      :status => ['500', 'Internal Server Error'])
+
+    assert_raise ThreeScale::UnknownError do
+      @interface.confirm(42)
+    end
+  end
+
+  def test_confirm_should_return_true_on_success
+    FakeWeb.register_uri('http://3scale.net/transactions/42/confirm.xml',
+      :status => ['200', 'OK'])
+
+    result = @interface.confirm(42, 'clicks' => 1)
+    assert_equal true, result
+  end
+
+  def test_confirm_should_send_usage_data
+    Net::HTTP.expects(:post_form).
+      with(anything, has_entries('usage[hits]' => '1')).
+      returns(stub_response)
+
+    @interface.confirm(42, 'hits' => 1)
+  end
+
+  def test_cancel_should_raise_exception_on_invalid_transaction
+    FakeWeb.register_uri('http://3scale.net/transactions/42.xml?provider_key=some_key',
+      :status => ['404', 'Not Found'],
+      :string => stub_error('provider.invalid_transaction_id'))
+
+    assert_raise ThreeScale::TransactionNotFound do
+      @interface.cancel(42)
+    end
+  end
+
+  def test_cancel_should_raise_exception_on_invalid_provider_key
+    FakeWeb.register_uri('http://3scale.net/transactions/42.xml?provider_key=some_key',
+      :status => ['403', 'Forbidden'],
+      :string => stub_error('provider.invalid_key'))
+
+    assert_raise ThreeScale::ProviderKeyInvalid do
+      @interface.cancel(42)
+    end
+  end
+
+  def test_cancel_should_raise_exception_on_unexpected_error
+    FakeWeb.register_uri('http://3scale.net/transactions/42.xml?provider_key=some_key',
+      :status => ['500', 'Internal Server Error'])
+
+    assert_raise ThreeScale::UnknownError do
+      @interface.cancel(42)
+    end
+  end
+  
+  def test_cancel_should_return_true_on_success
+    FakeWeb.register_uri('http://3scale.net/transactions/42.xml?provider_key=some_key',
+      :status => ['200', 'OK'])
+
+    result = @interface.cancel(42)
+    assert_equal true, result
+  end
+
+  def test_should_identify_3scale_keys
+    assert  @interface.system_key?('3scale-foo')
+    assert !@interface.system_key?('foo')
+  end
+
+  private
+
+  def stub_error(id)
+    "<error id=\"#{id}\">blah blah</error>"
+  end
+
+  def stub_response
+    response = stub
+    response.stubs(:is_a?).with(Net::HTTPSuccess).returns(true)
+    response.stubs(:body).returns('<transaction></transaction>')
+    response
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: 3scale-3scale_ws_api_for_ruby
+version: !ruby/object:Gem::Version 
+  version: 0.4.7
+platform: ruby
+authors: 
+- "Adam Cig\xC3\xA1nek"
+- Josep M. Pujol
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-10-27 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.6.161
+    version: 
+description: 
+email: adam@3scale.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- init.rb
+- lib/3scale/interface.rb
+- lib/3scale_interface.rb
+- README
+- Rakefile
+- test/interface_test.rb
+has_rdoc: true
+homepage: http://www.3scale.net
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: 3scale web service management API for Ruby.
+test_files: 
+- test/interface_test.rb