tylerhunt-relax 0.0.5

data/lib/relax/request.rb

@@ -0,0 +1,95 @@
+require 'relax/query'
+
+module Relax
+  # Request is intended to be a parent class for requests passed to
+  # Service#call.
+  class Request
+    @parameters = {}
+
+    # New takes an optional hash of default parameter values. When passed,
+    # the values will be set on the request if the key exists as a valid
+    # parameter name. 
+    def initialize(defaults = {})
+      # initialize default parameter values
+      self.class.parameters.each do |parameter, options|
+        if defaults.has_key?(parameter)
+          value = defaults[parameter]
+        elsif options[:value]
+          value = options[:value]
+        end
+
+        instance_variable_set("@#{parameter}", value) if value
+      end
+    end
+
+    # Converts this request into a Query object.
+    def to_query
+      self.class.parameters.keys.inject(Query.new) do |query, key|
+        value = send(key)
+        options = self.class.parameters[key]
+        if value && !options[:type]
+          query[convert_key(key)] = value if value
+        elsif options[:type]
+          options[:type].parameters.each do |parameter, options|
+            query[convert_complex_key(key, parameter)] = value.send(parameter) if value
+          end
+        end
+        query
+      end
+    end
+
+    # Converts this request into a query string for use in a URL.
+    def to_s
+      to_query.to_s
+    end
+
+    # Converts a key when the Request is converted to a query. By default, no
+    # conversion actually takes place, but this method can be overridden by
+    # child classes to perform standard manipulations, such as replacing
+    # underscores.
+    def convert_key(key)
+      key
+    end
+    protected :convert_key
+    
+    # Converts a complex key (i.e. a parameter with a custom type) when the
+    # Request is converted to a query. By default, this means the key name and
+    # the parameter name separated by two underscores. This method can be
+    # overridden by child classes.
+    def convert_complex_key(key, parameter)
+      "#{convert_key(key)}.#{convert_key(parameter)}"
+    end
+    protected :convert_complex_key
+
+    class << self
+      # Create the parameters hash for the subclass.
+      def inherited(subclass) #:nodoc:
+        subclass.instance_variable_set('@parameters', {})
+      end
+
+      # Specifies a parameter to create on the request class.
+      #
+      # Options:
+      # - <tt>:type</tt>: An optional custom data type for the parameter.
+      #   This must be a class that is a descendent of Request.
+      # - <tt>:value</tt>: The default value for this parameter.
+      def parameter(name, options = {})
+        attr_accessor name
+        options = @parameters[name].merge(options) if @parameters.has_key?(name)
+        @parameters[name] = options
+      end
+
+      # Adds a template value to a request class. Equivalent to creating a
+      # parameter with a default value.
+      def []=(key, value)
+        parameter(key, {:value => value})
+      end
+
+      # Returns a hash of all of the parameters for this request, including
+      # those that are inherited.
+      def parameters #:nodoc:
+        (superclass.respond_to?(:parameters) ? superclass.parameters : {}).merge(@parameters)
+      end
+    end
+  end
+end

data/lib/relax/response.rb

@@ -0,0 +1,78 @@
+module Relax
+  # Response is intended to be a parent class for responses passed to
+  # Service#call.
+  #
+  # A response is in essence an object used to facilitate XML parsing. It
+  # stores an XML document, and provides access to it through methods like
+  # #element and #attribute.
+  class Response
+    attr_accessor :raw
+    
+    # New takes in and parses the raw response.
+    #
+    # This will raise a MissingParameter error if a parameterd marked as
+    # required is not present in the parsed response.
+    def initialize(xml)
+      @raw    = xml
+      @parser = Relax::Parsers::Factory.get(parser_name).new(xml.to_s, self)
+    end
+    
+    def parser_name
+      self.class.instance_variable_get('@parser') || :default
+    end
+    
+    def method_missing(method, *args) #:nodoc:
+      if @parser.respond_to?(method)
+        @parser.__send__(method, *args)
+      else
+        super
+      end
+    end
+
+    class << self
+      # When a Response is extended, the superclass's parameters are copied
+      # into the new class. This behavior has the following side-effect: if
+      # parameters are added to the superclass after it has been extended,
+      # those new paramters won't be passed on to its children. This shouldn't
+      # be a problem in most cases.
+      def inherited(subclass)
+        @parameters.each do |name, options|
+          subclass.parameter(name, options)
+        end if @parameters
+        subclass.parser(@parser) if @parser
+      end
+
+      # Specifes a parameter that will be automatically parsed when the
+      # Response is instantiated.
+      #
+      # Options:
+      # - <tt>:attribute</tt>: An attribute name to use, or <tt>true</tt> to
+      #   use the <tt>:element</tt> value as the attribute name on the root.
+      # - <tt>:collection</tt>: A class used to instantiate each item when
+      #   selecting a collection of elements.
+      # - <tt>:element</tt>: The XML element name.
+      # - <tt>:object</tt>: A class used to instantiate an element.
+      # - <tt>:type</tt>: The type of the parameter. Should be one of
+      #   <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, or <tt>:date</tt>.
+      def parameter(name, options = {})
+        attr_accessor name
+        @parameters ||= {}
+        @parameters[name] = options
+      end
+      
+      # Specifies the parser to use when decoding the server response.  If 
+      # no parser is specified for the response, then the default parser will
+      # be used.
+      # 
+      # See Relax::Parsers for a list of available parsers.
+      def parser(name)
+        @parser ||= name
+      end
+
+      def ===(response)
+        response.is_a?(Class) ? response.ancestors.include?(self) : super
+      end
+    end
+
+  end
+end

data/lib/relax/service.rb

@@ -0,0 +1,101 @@
+require 'openssl'
+require 'net/https'
+require 'uri'
+require 'date'
+require 'base64'
+require 'erb'
+
+module Relax
+  # Service is the starting point for any REST consumer written with Relax. It
+  # is responsible for setting up the endpoint for the service, and issuing the
+  # HTTP requests for each call made.
+  #
+  # == Extending Service
+  #
+  # When writing consumers, you should start by extending Service by inheriting
+  # from it and calling its constructor with the endpoint for the service.
+  #
+  # === Example
+  #
+  #   class Service < Relax::Service
+  #     ENDPOINT = 'http://example.com/services/rest/'
+  #
+  #     def initialize
+  #       super(ENDPOINT)
+  #     end
+  #   end
+  #
+  # == Calling a Service
+  #
+  # Each call made to the service goes through the #call method of Service,
+  # which takes in a Request object and a Response class. The Request object is
+  # used to generate the query string that will be passed to the endpoint. The
+  # Reponse class is instantiated with the body of the response from the HTTP
+  # request.
+  #
+  # === Example
+  #
+  # This example show how to create a barebones call. This module can be then
+  # included into your Service class.
+  #
+  #   module Search
+  #     class SearchRequest < Relax::Request
+  #     end
+  #
+  #     class SearchResponse < Relax::Response
+  #     end
+  #
+  #     def search(options = {})
+  #       call(SearchRequest.new(options), SearchResponse)
+  #     end
+  #   end
+  #
+  class Service
+    attr_reader :endpoint
+
+    # This constructor should be called from your Service with the endpoint URL
+    # for the REST service.
+    def initialize(endpoint)
+      @endpoint = URI::parse(endpoint)
+    end
+
+    protected
+
+    # Calls the service using a query built from the Request object passed in
+    # as its first parameter. Once the response comes back from the service,
+    # the body of the response is used to instantiate the response class, and
+    # this response object is returned.
+    def call(request, response_class)
+      uri = @endpoint.clone
+      uri.query = query(request).to_s
+      response = request(uri)
+      puts "Response:\n#{response.body}\n\n" if $DEBUG
+      response_class.new(response.body)
+    end
+
+    private
+
+    def default_query
+      Query.new
+    end
+
+    def query(request)
+      Query.new(default_query.merge(request.to_query))
+    end
+
+    def request(uri)
+      puts "Request:\n#{uri.to_s}\n\n" if $DEBUG
+      http = Net::HTTP.new(uri.host, uri.port)
+
+      if uri.scheme == 'https'
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+
+      http.start do |http|
+        request = Net::HTTP::Get.new("#{uri.path}?#{uri.query}")
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/relax/symbolic_hash.rb

@@ -0,0 +1,79 @@
+module Relax
+  # SymbolicHash provides an extension of Hash, but one that only supports keys
+  # that are symbols. This has been done in an effort to prevent the case where
+  # both a string key and a symbol key are set on the same hash, and espcially
+  # for dealing with this particular case when convert the hash to a string.
+  #
+  # === Example
+  #
+  #   hash = Relax::SymbolicHash.new
+  #   hash[:one] = 1
+  #   hash['one'] = 2
+  #   puts hash[:one] # => 2
+  #
+  # === Credits
+  #
+  # Some of the inspiration (and code) for this class comes from the
+  # HashWithIndifferentAccess that ships with Rails.
+  class SymbolicHash < Hash
+    def initialize(constructor = {})
+      if constructor.is_a?(Hash)
+        super()
+        update(constructor)
+      else
+        super(constructor)
+      end
+    end
+
+    def [](key)
+      super(convert_key(key))
+    end
+
+    def []=(key, value)
+      super(convert_key(key), convert_value(value))
+    end
+
+    def update(other_hash)
+      other_hash.each_pair { |key, value| store(convert_key(key), convert_value(value)) }
+      self
+    end
+    alias :merge! :update
+
+    def fetch(key, *extras)
+      super(convert_key(key), *extras)
+    end
+
+    def values_at(*indices)
+      indices.collect { |key| self[convert_key(key)] }
+    end
+
+    def dup
+      SymbolicHash.new(self)
+    end
+
+    def merge(hash)
+      self.dup.update(hash)
+    end
+
+    def delete(key)
+      super(convert_key(key))
+    end
+
+    def key?(key)
+      super(convert_key(key))
+    end
+    alias :include? :key?
+    alias :has_key? :key?
+    alias :member? :key?
+
+    protected
+
+    def convert_key(key)
+      !key.kind_of?(Symbol) ? key.to_sym : key
+    end
+
+    def convert_value(value)
+      value
+    end
+  end
+end

data/lib/relax.rb

@@ -0,0 +1,13 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'relax/query'
+require 'relax/parsers'
+require 'relax/request'
+require 'relax/response'
+require 'relax/service'
+require 'relax/symbolic_hash'
+
+module Relax
+  class MissingParameter < ArgumentError ; end
+  class UnrecognizedParser < ArgumentError ; end
+end

data/spec/parsers/factory_spec.rb

@@ -0,0 +1,29 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+require 'relax'
+require 'relax/parsers/factory'
+
+class TestParser ; end
+
+describe 'a parser factory' do
+  
+  before(:each) do
+    @factory = Relax::Parsers::Factory
+    Relax::Parsers::Factory.register(:test, TestParser)
+  end
+  
+  it 'should raise UnrecognizedParser for un-registered names' do
+    lambda {
+      @factory.get(:bad_name)
+    }.should raise_error(Relax::UnrecognizedParser)
+  end
+  
+  it 'should return a registered parser class' do
+    @factory.get(:test).should ==TestParser
+  end
+  
+  it 'should register the first registered parser as the default' do
+    @factory.get(:default).should ==Relax::Parsers::Hpricot
+  end
+  
+end

data/spec/parsers/hpricot_spec.rb

@@ -0,0 +1,35 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require File.dirname(__FILE__) + '/../parser_helper'
+
+
+class HpricotTestResponse < Relax::Response
+  class Token < Relax::Response
+    parser :hpricot
+    parameter :token_id, :element => :tokenid
+    parameter :status
+  end
+
+  class Error < Relax::Response
+    parser :hpricot
+    parameter :code, :type => :integer
+    parameter :message
+  end
+  
+  parser :hpricot
+  parameter :status, :required => true
+  parameter :request_id, :element => :requestid, :type => :integer
+  parameter :valid_request, :element => :requestid, :attribute => :valid
+  parameter :tokens, :collection => Token
+  parameter :error, :type => Error
+end
+
+
+describe 'an Hpricot parser' do
+  
+  before(:each) do
+    @response = HpricotTestResponse.new(XML)
+  end
+  
+  it_should_behave_like 'a successfully parsed response'
+  
+end

data/spec/parsers/rexml_spec.rb

@@ -0,0 +1,40 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require File.dirname(__FILE__) + '/../parser_helper'
+
+
+class RexmlTestResponse < Relax::Response
+  class Token < Relax::Response
+    parser :rexml
+    parameter :token_id,  :element => 'TokenId'
+    parameter :status,    :element => 'Status'
+  end
+  
+  class Error < Relax::Response
+    parser :rexml
+    parameter :code,      :element => 'Code',         :type => :integer
+    parameter :message,   :element => 'Message'
+  end
+  
+  parser :rexml
+  parameter :status,        :element => 'Status',     :required => true
+  parameter :request_id,    :element => 'RequestId',  :type => :integer
+  parameter :valid_request, :element => 'RequestId',  :attribute => :valid
+  parameter :namespace,     :element => 'Namespace',  :namespace => 'ns1'
+  parameter :tokens,        :element => 'Tokens',     :collection => Token
+  parameter :error,         :element => 'Error',      :type => Error
+end
+
+
+describe 'a REXML parser' do
+  
+  before(:each) do
+    @response = RexmlTestResponse.new(XML)
+  end
+  
+  it_should_behave_like 'a successfully parsed response'
+  
+  it 'should parse namespaced parameters' do
+    @response.namespace.should eql('Passed')
+  end
+  
+end

data/spec/query_spec.rb

@@ -0,0 +1,60 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+require 'relax/query'
+
+describe 'a query' do
+  before(:each) do
+    @uri = URI::parse('http://example.com/?action=search&query=keyword')
+    @query = Relax::Query.new
+  end
+
+  it 'should convert to a query string' do
+    @query[:action] = 'Search'
+    @query[:query] = 'strings'
+    @query.to_s.should eql('action=Search&query=strings')
+  end
+
+  it 'should convert its values to strings' do
+    date = Date.today
+    @query[:date] = date
+    @query.to_s.should eql("date=#{date.to_s}")
+  end
+
+  it 'should escape its values using "+" instead of "%20"' do
+    Relax::Query.send(:escape_value, 'two words').should == 'two+words'
+  end
+  
+  it 'should sort its parameters' do
+    @query[:charlie] = 3
+    @query[:alpha] = 1
+    @query[:bravo] = 2
+    @query.to_s.should eql('alpha=1&bravo=2&charlie=3')
+  end
+
+  it 'should encode its parameter values' do
+    @query[:spaces] = 'two words'
+    @query[:url] = 'http://example.com/'
+    @query.to_s.should eql('spaces=two+words&url=http%3A%2F%2Fexample.com%2F')
+  end
+
+  it 'should be able to parse query strings' do
+    parsed_query = Relax::Query.parse(@uri)
+    parsed_query[:action].should eql('search')
+    parsed_query[:query].should eql('keyword')
+  end
+  
+  it 'should parse key value pairs into only two parts' do
+    parsed_query = Relax::Query.parse(URI.parse("http://example.com/?action=test=&foo=bar"))
+    parsed_query[:action].should eql('test=')
+  end
+  
+  it 'should unescape query string key-value pair keys' do
+    parsed_query = Relax::Query.parse(URI.parse("http://example.com/?action%20helper=test"))
+    parsed_query[:"action helper"].should eql('test')
+  end
+  
+  it 'should unescape query string key-value pair values' do
+    parsed_query = Relax::Query.parse(URI.parse("http://example.com/?action=test%20action"))
+    parsed_query[:action].should eql('test action')
+  end
+end

data/spec/request_spec.rb

@@ -0,0 +1,108 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+require 'relax/request'
+
+class Amount < Relax::Request
+  parameter :amount
+  parameter :currency
+end
+
+class TestRequest < Relax::Request
+  parameter :action
+  parameter :token_id
+  parameter :user_id
+  parameter :amount, :type => Amount
+end
+
+class ChildRequest < TestRequest
+  parameter :child_id
+end
+
+describe 'an option initialized request', :shared => true do
+  it 'should have its values set by the options hash' do
+    request = TestRequest.new(:action => 'FetchAll', :token_id => 123)
+    request.action.should eql('FetchAll')
+    request.token_id.should eql(123)
+    request.user_id.should be_nil
+  end
+end
+
+describe 'a request that converts to a query', :shared => true do
+  before(:each) do
+    @query = TestRequest.new(:action => 'Search', :token_id => 123).to_query
+  end
+
+  it 'should include its parameters in the query' do
+    @query[:action].should eql('Search')
+    @query[:token_id].should eql('123')
+    @query[:user_id].should be_nil
+    @query[:amount].should be_nil
+  end
+
+  it 'should only include parameters in the query if they are set' do
+    @query.key?(:action).should be_true
+    @query.key?(:token_id).should be_true
+    @query.key?(:user_id).should be_false
+    @query.key?(:amount).should be_false
+  end
+end
+
+describe 'a normal request' do
+  it_should_behave_like 'a request that converts to a query'
+  it_should_behave_like 'an option initialized request'
+end
+
+describe 'a template request' do
+  it_should_behave_like 'a request that converts to a query'
+  it_should_behave_like 'an option initialized request'
+
+  before(:each) do
+    # this syntax may need to go away unless we can find a way to make it work 
+    TestRequest[:api_key] = '123456'
+    TestRequest[:secret] = 'shhh!'
+  end
+
+  it 'should always have the template values in its query' do
+    request = TestRequest.new
+    request.api_key.should eql('123456')
+    request.secret.should eql('shhh!')
+  end
+
+  it 'should allow its template variables to be overridden' do
+    request = TestRequest.new(:secret => 'abracadabra')
+    request.api_key.should eql('123456')
+    request.secret.should eql('abracadabra')
+  end
+
+  it 'should pass its template on to its children' do
+    request = ChildRequest.new
+    request.api_key.should eql('123456')
+    request.secret.should eql('shhh!')
+  end
+
+  it 'should allow template parameters on its children that are additive' do
+    ChildRequest[:query] = '1a2b3c'
+    child = ChildRequest.new
+    child.api_key.should eql('123456')
+    child.secret.should eql('shhh!')
+    child.query.should eql('1a2b3c')
+
+    parent = TestRequest.new
+    parent.api_key.should eql('123456')
+    parent.secret.should eql('shhh!')
+    parent.respond_to?(:query).should be_false
+  end
+end
+
+describe 'a request with a custom type' do
+  before(:each) do
+    request = TestRequest.new(:action => 'Pay', :token_id => 123)
+    request.amount = Amount.new(:amount => 3.50, :currency => 'USD')
+    @query = request.to_query
+  end
+
+  it 'should add the type parameters to the query' do
+    @query.key?(:"amount.amount").should be_true
+    @query.key?(:"amount.currency").should be_true
+  end
+end