Roman2K-web-service 0.1.1

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2008-2009 Roman Le Négrate
+
+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.mdown

@@ -0,0 +1,147 @@
+# WebService
+
+REST client. Alternative to [`ActiveResource`](http://api.rubyonrails.org/classes/ActiveResource/Base.html).
+
+## Installation
+
+Since `WebService` depends on the gem `class-inheritable-attributes` which cannot be installed directly by RubyGems because the account name has to be prepended to the actual gem name, please refer to [`README`](http://github.com/Roman2K/class-inheritable-attributes/tree) for instructions on how to install that dependency manually.
+
+Then, install the `web-service` gem itself:
+
+    $ gem install Roman2K-web-service -s http://gems.github.com/
+
+## Usage example
+
+Let's say you have a Rails app exposing a RESTful API for articles and their comments:
+
+    map.resources :articles, :has_many => :comments
+
+When building the corresponding client for this API to consume these resources, the code could look like:
+
+    require 'web_service'
+    
+    class BasicResource < WebService::Resource
+      # Mandatory:
+      self.site = WebService::Site.new("http://login:password@host:port")
+      
+      # Optional (and possibly in subclasses):
+      self.site = WebService::Site.new("https://secure.site")
+      self.credentials = ["login", "password"]
+      self.element_name = "custom_element_name"
+      self.singleton = true   # /foo instead of /foos/1
+    end
+    
+    class Article < BasicResource
+      has_many :comments
+    end
+    
+    class Comment < BasicResource
+      belongs_to :article
+    end
+
+### Attributes
+
+    article = Article.new(:title => "First article")
+    article.title    # => "First article"
+    article.title?   # => true
+    article.title = " "
+    article.title?   # => false
+    article.body     # raises NoMethodError
+    article.body?    # raises NoMethodError
+
+### CRUD
+
+    article = Article.new(:title => "First article")
+    begin
+      article.save
+      # => POST /articles
+    rescue WebService::ResourceInvalid
+      article.body = "Like the title says."
+      article.save
+      # => POST /articles
+    end
+    
+    article.body += " Updated."
+    article.save
+    # => PUT /articles/1
+    
+    article.destroy
+    # => DELETE /articles/1
+
+### Fetching
+
+    article.id            # => 1
+    Article[1] == article # => true
+    Article[99]           # => nil
+    Article.find(99)      # raises WebService::ResourceNotFound
+    
+    Article.all           # => [Article[1], ..., Article[42]]
+    Article.first         # => Article[1]
+    Article.last          # => Article[42]
+    
+    comment = Comment.new(:article_id => 1)
+    comment.article       # => Article[1]
+    # => GET /articles/1
+    comment.article       # => Article[1]
+    # => (cache hit)
+
+### Nested resources (associations)
+
+Use `article.comments` like you would `Comment`, only scoped to `article`.
+
+    article.comments.all
+    # => GET /articles/1/comments
+
+Associating a comment with a article:
+
+    article.comments.create(:body => "First comment.")
+    # => POST /articles/1/comments
+
+The same in a more formal way:
+
+    comment = Comment.new(:body => "First comment.")
+    comment.article = article
+    comment.article == article  # => true
+    comment.article_id          # => 1
+    comment.save
+
+### Arbitrary actions
+
+All of resource classes, resource instances and association collections respond to all four HTTP verbs (`GET`, `POST`, `PUT` and `DELETE`) to issue requests to arbitrary actions.
+
+**Note:** these methods do not return resource instances, but rather plain unserialized objects, as returned by the server:
+
+    Article.delete(:unpopular)         # => [{'id' => 5, ...}, ...]
+    # => DELETE /articles/unpopular
+
+    Article.get(:popular, :page => 2)  # => [{'id' => 1, ...}, ...]
+    # => GET /articles/popular?page=2
+    
+    article.put(:publish, :at => 1.hour.from_now)
+    # => PUT /articles/1/publish {:at => 1.hour.from_now}
+    
+    article.comments.put(:spam, 5)
+    # => PUT /articles/1/comments/5/spam
+    
+    article.comments.get("/spam")
+    # => PUT /articles/1/comments/spam
+
+## Formats
+
+* Requests are sent **JSON**-encoded.
+* Responses can be returned either **JSON**- or **XML**-encoded.
+
+## Status
+
+*   Fetched resources should be cached in memory, so that the following returns true:
+
+        comments = article.comments
+        comments.all.object_id == comments.all.object_id
+
+*   There are **tests** left to be written. Run `rake coverage` to find out what still has to be tested. Note that for RCov to work with Ruby 1.8.7, you might need to install the latest `rcov` gem from [GitHub](http://github.com/spicycode/rcov):
+
+        gem install spicycode-rcov -s http://gems.github.com
+
+## Credits
+
+Written by [Roman Le Négrate](http://roman.flucti.com) ([contact](mailto:roman.lenegrate@gmail.com)). Released under the MIT license: see the `LICENSE` file.

data/Rakefile

@@ -0,0 +1,39 @@
+require "echoe"
+
+Echoe.new('web-service', '0.1.1') do |p|
+  p.description     = "REST client; an alternative to ActiveResource"
+  p.url             = "https://github.com/Roman2K/web-service"
+  p.author          = "Roman Le Négrate"
+  p.email           = "roman.lenegrate@gmail.com"
+  p.ignore_pattern  = "*.gemspec"
+  p.dependencies    = ["activesupport >=2.2.2", "class-inheritable-attributes"]
+  p.development_dependencies = ["mocha", "test-unit-ext"]
+  p.rdoc_options    = %w(--main README.mdown --inline-source --line-numbers --charset UTF-8)
+end
+
+# Weirdly enough, Echoe's default `test' task doesn't get overridden by the one
+# defined below. Even weirder, `rake test' runs both tasks! The same applies to
+# `coverage'. Dirty workaround:
+%w(test coverage).each do |name|
+  Rake.application.instance_eval("@tasks").delete(name)
+end
+
+task :default => :test
+
+desc "Run the test suite"
+task :test do
+  all_test_files.each { |test| require test }
+end
+
+desc "Measure test coverage"
+COVERAGE_OUT  = "doc/coverage"
+COVERAGE_CODE = %w(lib)
+task :coverage do
+  rm_rf COVERAGE_OUT; mkdir_p COVERAGE_OUT
+  sh %(rcov -I.:lib:test -x '^(?!#{COVERAGE_CODE * '|'})/' --text-summary --sort coverage --no-validator-links -o #{COVERAGE_OUT} #{all_test_files * ' '})
+  system %(open #{COVERAGE_OUT}/index.html)
+end
+
+def all_test_files
+  Dir['test/**/*_test.rb'].sort
+end

data/lib/web_service.rb

@@ -0,0 +1,36 @@
+require 'active_support'
+require 'class_inheritable_attributes'
+require 'ostruct'
+require 'cgi'
+require 'uri'
+require 'net/https'
+require 'web_service/core_ext'
+
+module WebService
+  autoload :Site,                 'web_service/site'
+  autoload :Resource,             'web_service/resource'
+  autoload :AttributeAccessors,   'web_service/attribute_accessors'
+  autoload :RemoteCollection,     'web_service/remote_collection'
+  autoload :ResponseHandling,     'web_service/response_handling'
+  autoload :NamedRequestMethods,  'web_service/named_request_methods'
+  autoload :CRUDOperations,       'web_service/crud_operations'
+  
+  class Error < StandardError
+  end
+  class ResourceNotSaved < Error
+  end
+  class NotResourceClass < Error
+  end
+  
+  class << self
+    def logger
+      @logger ||= begin
+        require 'logger'
+        Logger.new(STDOUT)
+      end
+    end
+    attr_writer :logger
+  end
+  
+  include ResponseHandling::Exceptions
+end

data/lib/web_service/attribute_accessors.rb

@@ -0,0 +1,147 @@
+module WebService
+  module AttributeAccessors
+    def initialize(attributes={})
+      self.attributes = attributes
+    end
+
+    def attributes
+      attribute_registry.dup
+    end
+
+    def attributes=(attributes)
+      # Resolve single-key hash
+      attributes = attributes[self.class.element_name] if attributes.size == 1 && attributes[self.class.element_name]
+      
+      # Clear previous attributes
+      attribute_registry.clear
+      
+      # Assign the ID first, so that it can be used while assigning the rest of the attributes
+      if id_key = [:id, "id"].find { |key| attributes.include? key }
+        self.id = attributes.delete(id_key)
+      end
+      attributes.each { |name, value| send("#{name}=", value) }
+    end
+
+    # TODO handle the argument for whether to include singleton methods or not
+    def methods
+      super | attribute_accessor_methods.to_a
+    end
+    
+    def respond_to?(method, include_private=false)
+      super || attribute_accessor_methods.include?(MethodList::TO_METHOD_NAME[method])
+    end
+    
+    def read_attribute(attr_name)
+      if (id = attribute_registry["#{attr_name}_id"])
+        association_registry[attr_name.to_s] ||= resource_class_for(attr_name).find(id)
+      else
+        attribute_registry[attr_name.to_s] || association_registry[attr_name.to_s]
+      end
+    end
+    
+    def attribute_readable?(attr_name)
+      attribute_registry.key?(attr_name) || association_registry.key?(attr_name) || attribute_registry.key?("#{attr_name}_id")
+    end
+    
+    def write_attribute(attr_name, value)
+      attr_name = attr_name.to_s
+      resolve_record_descriptor = lambda { |descriptor|
+        if Hash === descriptor && descriptor.size == 1
+          if attributes = descriptor[attr_name]
+            attributes
+          elsif klass = resource_class_for?(descriptor.keys.first)
+            klass.new(descriptor.values.first)
+          end
+        end
+      }
+      value = resolve_record_descriptor[value] || (value.kind_of?(Array) and value.map { |elt| resolve_record_descriptor[elt] || elt }) || value
+      association_registry[$`] &&= nil if attr_name =~ /_id$/
+      if value.nil?
+        attribute_registry[attr_name] = nil
+        attribute_registry["#{attr_name}_id"] &&= nil unless attr_name =~ /_id$/
+        association_registry[attr_name] &&= nil
+      elsif resource_class?(value.class)
+        value.saved? or raise ResourceNotSaved, "resource must have an ID in order to be associated to another resource"
+        attribute_registry["#{attr_name}_id"], association_registry[attr_name] = value.id, value
+      elsif Hash === value and id = value["id"] and klass = resource_class_for?(attr_name)
+        attribute_registry["#{attr_name}_id"], association_registry[attr_name] = id, klass.new(value)
+      else
+        attribute_registry[attr_name] = value
+      end
+    end
+    
+    def attribute_set?(attr_name)
+      !attribute_registry[attr_name.to_s].blank? || !attribute_registry["#{attr_name}_id"].blank?
+    end
+    
+  private
+    
+    def attribute_registry
+      @attributes ||= {}
+    end
+    
+    def association_registry
+      @associations ||= {}
+    end
+
+    def method_missing(method_id, *args)
+      method_name = method_id.to_s
+      case
+      when method_name =~ /=$/
+        write_attribute($`, *args)
+      when attribute_readable?(method_name)
+        read_attribute(method_name, *args)
+      when method_name =~ /\?$/
+        super unless respond_to?($`)
+        attribute_set?($`, *args)
+      else
+        super
+      end
+    end
+    
+    def attribute_accessor_methods
+      @attribute_accessor_methods ||= MethodList.new([attribute_registry, association_registry])
+    end
+    
+    def resource_class_for(association_name)
+      klass = association_name.to_s.camelize.constantize
+      unless resource_class?(klass)
+        raise NotResourceClass, "class #{klass} found for association `#{association_name}' is not a resource class"
+      end
+      klass
+    end
+    
+    def resource_class_for?(association_name)
+      resource_class_for(association_name)
+    rescue NameError
+      raise unless /uninitialized constant/ =~ $!
+    rescue NotResourceClass
+      raise unless /for association `#{association_name}'/ =~ $!
+    end
+    
+    def resource_class?(klass)
+      Class === klass && klass.respond_to?(:find) && klass.public_method_defined?(:saved?)
+    end
+  end
+  
+  class MethodList
+    TO_METHOD_NAME  = (Kernel.methods.first.kind_of?(String) ? :to_s : :to_sym).to_proc
+    METHOD_SUFFIXES = ["", "=", "?"]
+    
+    include Enumerable
+    
+    def initialize(registries)
+      @registries = registries
+    end
+    
+    def each
+      METHOD_SUFFIXES.each do |suffix|
+        @registries.each do |registry|
+          registry.each_key do |attr_name|
+            yield TO_METHOD_NAME["#{attr_name}#{suffix}"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/web_service/core_ext.rb

@@ -0,0 +1,36 @@
+Object.class_eval do
+  undef :id if method_defined?(:id)
+end
+
+Array.class_eval do
+  alias_method :index_without_block_form, :index
+  def index(*args, &block)
+    if args.empty? && block
+      each_with_index { |obj, idx| return idx if block.call(obj) }; nil
+    elsif args.size == 1
+      index_without_block_form(*args, &block)
+    else
+      raise ArgumentError, "wrong number of arguments (%d for 1)" % args.size
+    end
+  end
+end if Array.instance_method(:index).arity == 1
+
+def URI(object)
+  URI === object ? object : URI.parse(object.to_s)
+end
+
+URI.class_eval do
+  def obfuscate
+    returning(dup) do |obfuscated|
+      obfuscated.user &&= '***'
+      obfuscated.password &&= '***'
+    end
+  end
+end
+
+class << CGI
+  alias_method :old_escape, :escape
+  def escape(string)
+    old_escape(string).gsub(/\./, '%' + '.'.unpack('H2')[0])
+  end
+end

data/lib/web_service/crud_operations.rb

@@ -0,0 +1,114 @@
+module WebService
+  module CRUDOperations
+    include ResponseHandling::Exceptions
+    include Enumerable
+    
+    delegate :each, :to => :all
+    
+    def all(*args)
+      return @cache if @cache
+      expect(request(:get, *args), Net::HTTPOK) do |data|
+        instantiate_several_from_http_response_data(data)
+      end
+    end
+    
+    def cache=(collection)
+      @cache = collection.map { |res| instantiate_resource(res) }
+    end
+    
+    def flush_cache
+      @cache = nil
+      self
+    end
+    
+    def first(*args)
+      all(*args).first
+    end
+    
+    def last(*args)
+      all(*args).last
+    end
+    
+    def find(id, *args)
+      expect(request(:get, id, *args), Net::HTTPOK) do |data|
+        instantiate_single_from_http_response_data(data)
+      end
+    end
+    
+    def [](id)
+      find(id)
+    rescue ResourceNotFound
+      nil
+    end
+    
+    def build(attributes={})
+      default_attributes = respond_to?(:implicit_attributes) ? implicit_attributes : {}
+      instantiate_resource(default_attributes.stringify_keys.merge(attributes.stringify_keys))
+    end
+    
+    def create(attributes={})
+      expect(request(:post, body_for_create_or_update(attributes)), Net::HTTPCreated, Net::HTTPAccepted) do |data|
+        instantiate_single_from_http_response_data(data)
+      end
+    end
+    
+    def update(id, attributes={})
+      expect(request(:put, id, body_for_create_or_update(attributes)), Net::HTTPOK, Net::HTTPAccepted) do |data|
+        instantiate_single_from_http_response_data(data)
+      end
+    end
+    
+  private
+  
+    def element_name
+      @element_name ||= respond_to?(:resource_class) ? resource_class.element_name : super
+    end
+    
+    def expect(response, *types)
+      case response
+      when *types
+        yield response.data
+      else
+        raise ConnectionError.new(response, "unexpected response")
+      end
+    end
+    
+    def body_for_create_or_update(attributes)
+      {element_name => build(attributes).attributes}
+    end
+    
+    def instantiate_single_from_http_response_data(data)
+      return nil if data.to_s.blank?
+      
+      unless data.respond_to?(:key?) && data.respond_to?(:[])
+        raise ArgumentError, "wrong data type for marshalled resource: #{data.class} (expected a Hash)"
+      end
+      unless data.key?(element_name)
+        raise ArgumentError, "wrong format for marshalled resource: expected a Hash with #{element_name.inspect} as sole key"
+      end
+      instantiate_resource(data[element_name])
+    end
+    
+    def instantiate_several_from_http_response_data(data)
+      [data].flatten.map { |entry| instantiate_single_from_http_response_data(entry) }
+    end
+    
+    def instantiate_resource(*args, &block)
+      klass = respond_to?(:new) ? self : resource_class
+      
+      # TODO  Fix the need that hack:
+      #
+      #       It makes has_one saves work, as foo.bar builds a subclass of Bar
+      #       with singleton=true so that the RemoteCollection of foo.bar will
+      #       make POST requests to /foos/1/bar instead of /foos/1/bars.
+      #
+      #       See Resource#remote_collection
+      #
+      basic_collection = self if respond_to?(:resource_class) && resource_class.name.to_s.empty?
+      
+      resource = args.size == 1 && !block && klass === args.first ? args.first : klass.new(*args, &block)
+      resource.instance_variable_set(:@basic_remote_collection, basic_collection)
+      return resource
+    end
+  end
+end