activeresource-five 5.0.0

data/lib/active_resource/callbacks.rb

@@ -0,0 +1,20 @@
+require 'active_support/core_ext/array/wrap'
+
+module ActiveResource
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    CALLBACKS = [
+      :before_validation, :after_validation, :before_save, :around_save, :after_save,
+      :before_create, :around_create, :after_create, :before_update, :around_update,
+      :after_update, :before_destroy, :around_destroy, :after_destroy
+    ]
+
+    included do
+      extend ActiveModel::Callbacks
+      include ActiveModel::Validations::Callbacks
+
+      define_model_callbacks :save, :create, :update, :destroy
+    end
+  end
+end

data/lib/active_resource/collection.rb

@@ -0,0 +1,92 @@
+require 'active_support/core_ext/module/delegation'
+require 'active_support/inflector'
+
+module ActiveResource # :nodoc:
+  class Collection # :nodoc:
+    SELF_DEFINE_METHODS = [:to_a, :collect!, :map!]
+    include Enumerable
+    delegate :to_yaml, :all?, *(Array.instance_methods(false) - SELF_DEFINE_METHODS), :to => :to_a
+
+    # The array of actual elements returned by index actions
+    attr_accessor :elements, :resource_class, :original_params
+
+    # ActiveResource::Collection is a wrapper to handle parsing index responses that
+    # do not directly map to Rails conventions.
+    #
+    # You can define a custom class that inherets from ActiveResource::Collection
+    # in order to to set the elements instance.
+    #
+    # GET /posts.json delivers following response body:
+    #   {
+    #     posts: [
+    #       {
+    #         title: "ActiveResource now has associations",
+    #         body: "Lorem Ipsum"
+    #       },
+    #       {...}
+    #     ],
+    #     next_page: "/posts.json?page=2"
+    #   }
+    #
+    # A Post class can be setup to handle it with:
+    #
+    #   class Post < ActiveResource::Base
+    #     self.site = "http://example.com"
+    #     self.collection_parser = PostCollection
+    #   end
+    #
+    # And the collection parser:
+    #
+    #   class PostCollection < ActiveResource::Collection
+    #     attr_accessor :next_page
+    #     def initialize(parsed = {})
+    #       @elements = parsed['posts']
+    #       @next_page = parsed['next_page']
+    #     end
+    #   end
+    #
+    # The result from a find method that returns multiple entries will now be a
+    # PostParser instance.  ActiveResource::Collection includes Enumerable and
+    # instances can be iterated over just like an array.
+    #    @posts = Post.find(:all) # => PostCollection:xxx
+    #    @posts.next_page         # => "/posts.json?page=2"
+    #    @posts.map(&:id)         # =>[1, 3, 5 ...]
+    #
+    # The initialize method will receive the ActiveResource::Formats parsed result
+    # and should set @elements.
+    def initialize(elements = [])
+      @elements = elements
+    end
+
+    def to_a
+      elements
+    end
+
+    def collect!
+      return elements unless block_given?
+      set = []
+      each { |o| set << yield(o) }
+      @elements = set
+      self
+    end
+    alias map! collect!
+
+    def first_or_create(attributes = {})
+      first || resource_class.create(original_params.update(attributes))
+    rescue NoMethodError
+      raise "Cannot create resource from resource type: #{resource_class.inspect}"
+    end
+
+    def first_or_initialize(attributes = {})
+      first || resource_class.new(original_params.update(attributes))
+    rescue NoMethodError
+      raise "Cannot build resource from resource type: #{resource_class.inspect}"
+    end
+
+    def where(clauses = {})
+      raise ArgumentError, "expected a clauses Hash, got #{clauses.inspect}" unless clauses.is_a? Hash
+      new_clauses = original_params.merge(clauses)
+      resource_class.where(new_clauses)
+    end
+  end
+end

data/lib/active_resource/connection.rb

@@ -0,0 +1,299 @@
+require 'active_support/core_ext/benchmark'
+require 'active_support/core_ext/uri'
+require 'active_support/core_ext/object/inclusion'
+require 'net/https'
+require 'date'
+require 'time'
+require 'uri'
+
+module ActiveResource
+  # Class to handle connections to remote web services.
+  # This class is used by ActiveResource::Base to interface with REST
+  # services.
+  class Connection
+
+    HTTP_FORMAT_HEADER_NAMES = {  :get => 'Accept',
+      :put => 'Content-Type',
+      :post => 'Content-Type',
+      :patch => 'Content-Type',
+      :delete => 'Accept',
+      :head => 'Accept'
+    }
+
+    attr_reader :site, :user, :password, :auth_type, :timeout, :open_timeout, :read_timeout, :proxy, :ssl_options
+    attr_accessor :format
+
+    class << self
+      def requests
+        @@requests ||= []
+      end
+    end
+
+    # The +site+ parameter is required and will set the +site+
+    # attribute to the URI for the remote resource service.
+    def initialize(site, format = ActiveResource::Formats::JsonFormat)
+      raise ArgumentError, 'Missing site URI' unless site
+      @proxy = @user = @password = nil
+      self.site = site
+      self.format = format
+    end
+
+    # Set URI for remote service.
+    def site=(site)
+      @site = site.is_a?(URI) ? site : URI.parse(site)
+      @ssl_options ||= {} if @site.is_a?(URI::HTTPS)
+      @user = URI.parser.unescape(@site.user) if @site.user
+      @password = URI.parser.unescape(@site.password) if @site.password
+    end
+
+    # Set the proxy for remote service.
+    def proxy=(proxy)
+      @proxy = proxy.is_a?(URI) ? proxy : URI.parse(proxy)
+    end
+
+    # Sets the user for remote service.
+    def user=(user)
+      @user = user
+    end
+
+    # Sets the password for remote service.
+    def password=(password)
+      @password = password
+    end
+
+    # Sets the auth type for remote service.
+    def auth_type=(auth_type)
+      @auth_type = legitimize_auth_type(auth_type)
+    end
+
+    # Sets the number of seconds after which HTTP requests to the remote service should time out.
+    def timeout=(timeout)
+      @timeout = timeout
+    end
+
+    # Sets the number of seconds after which HTTP connects to the remote service should time out.
+    def open_timeout=(timeout)
+      @open_timeout = timeout
+    end
+
+    # Sets the number of seconds after which HTTP read requests to the remote service should time out.
+    def read_timeout=(timeout)
+      @read_timeout = timeout
+    end
+
+    # Hash of options applied to Net::HTTP instance when +site+ protocol is 'https'.
+    def ssl_options=(options)
+      @ssl_options = options
+    end
+
+    # Executes a GET request.
+    # Used to get (find) resources.
+    def get(path, headers = {})
+      with_auth { request(:get, path, build_request_headers(headers, :get, self.site.merge(path))) }
+    end
+
+    # Executes a DELETE request (see HTTP protocol documentation if unfamiliar).
+    # Used to delete resources.
+    def delete(path, headers = {})
+      with_auth { request(:delete, path, build_request_headers(headers, :delete, self.site.merge(path))) }
+    end
+
+    # Executes a PATCH request (see HTTP protocol documentation if unfamiliar).
+    # Used to update resources.
+    def patch(path, body = '', headers = {})
+      with_auth { request(:patch, path, body.to_s, build_request_headers(headers, :patch, self.site.merge(path))) }
+    end
+
+    # Executes a PUT request (see HTTP protocol documentation if unfamiliar).
+    # Used to update resources.
+    def put(path, body = '', headers = {})
+      with_auth { request(:put, path, body.to_s, build_request_headers(headers, :put, self.site.merge(path))) }
+    end
+
+    # Executes a POST request.
+    # Used to create new resources.
+    def post(path, body = '', headers = {})
+      with_auth { request(:post, path, body.to_s, build_request_headers(headers, :post, self.site.merge(path))) }
+    end
+
+    # Executes a HEAD request.
+    # Used to obtain meta-information about resources, such as whether they exist and their size (via response headers).
+    def head(path, headers = {})
+      with_auth { request(:head, path, build_request_headers(headers, :head, self.site.merge(path))) }
+    end
+
+    private
+      # Makes a request to the remote service.
+      def request(method, path, *arguments)
+        result = ActiveSupport::Notifications.instrument("request.active_resource") do |payload|
+          payload[:method]      = method
+          payload[:request_uri] = "#{site.scheme}://#{site.host}:#{site.port}#{path}"
+          payload[:result]      = http.send(method, path, *arguments)
+        end
+        handle_response(result)
+      rescue Timeout::Error => e
+        raise TimeoutError.new(e.message)
+      rescue OpenSSL::SSL::SSLError => e
+        raise SSLError.new(e.message)
+      end
+
+      # Handles response and error codes from the remote service.
+      def handle_response(response)
+        case response.code.to_i
+          when 301, 302, 303, 307
+            raise(Redirection.new(response))
+          when 200...400
+            response
+          when 400
+            raise(BadRequest.new(response))
+          when 401
+            raise(UnauthorizedAccess.new(response))
+          when 403
+            raise(ForbiddenAccess.new(response))
+          when 404
+            raise(ResourceNotFound.new(response))
+          when 405
+            raise(MethodNotAllowed.new(response))
+          when 409
+            raise(ResourceConflict.new(response))
+          when 410
+            raise(ResourceGone.new(response))
+          when 422
+            raise(ResourceInvalid.new(response))
+          when 401...500
+            raise(ClientError.new(response))
+          when 500...600
+            raise(ServerError.new(response))
+          else
+            raise(ConnectionError.new(response, "Unknown response code: #{response.code}"))
+        end
+      end
+
+      # Creates new Net::HTTP instance for communication with the
+      # remote service and resources.
+      def http
+        configure_http(new_http)
+      end
+
+      def new_http
+        if @proxy
+          user = URI.parser.unescape(@proxy.user) if @proxy.user
+          password = URI.parser.unescape(@proxy.password) if @proxy.password
+          Net::HTTP.new(@site.host, @site.port, @proxy.host, @proxy.port, user, password)
+        else
+          Net::HTTP.new(@site.host, @site.port)
+        end
+      end
+
+      def configure_http(http)
+        apply_ssl_options(http).tap do |https|
+          # Net::HTTP timeouts default to 60 seconds.
+          if defined? @timeout
+            https.open_timeout = @timeout
+            https.read_timeout = @timeout
+          end
+          https.open_timeout = @open_timeout if defined?(@open_timeout)
+          https.read_timeout = @read_timeout if defined?(@read_timeout)
+        end
+      end
+
+      def apply_ssl_options(http)
+        http.tap do |https|
+          # Skip config if site is already a https:// URI.
+          if defined? @ssl_options
+            http.use_ssl = true
+
+            # All the SSL options have corresponding http settings.
+            @ssl_options.each { |key, value| http.send "#{key}=", value }
+          end
+        end
+      end
+
+      def default_header
+        @default_header ||= {}
+      end
+
+      # Builds headers for request to remote service.
+      def build_request_headers(headers, http_method, uri)
+        authorization_header(http_method, uri).update(default_header).update(http_format_header(http_method)).update(headers)
+      end
+
+      def response_auth_header
+        @response_auth_header ||= ""
+      end
+
+      def with_auth
+        retried ||= false
+        yield
+      rescue UnauthorizedAccess => e
+        raise if retried || auth_type != :digest
+        @response_auth_header = e.response['WWW-Authenticate']
+        retried = true
+        retry
+      end
+
+      def authorization_header(http_method, uri)
+        if @user || @password
+          if auth_type == :digest
+            { 'Authorization' => digest_auth_header(http_method, uri) }
+          else
+            { 'Authorization' => 'Basic ' + ["#{@user}:#{@password}"].pack('m').delete("\r\n") }
+          end
+        else
+          {}
+        end
+      end
+
+      def digest_auth_header(http_method, uri)
+        params = extract_params_from_response
+
+        request_uri = uri.path
+        request_uri << "?#{uri.query}" if uri.query
+
+        ha1 = Digest::MD5.hexdigest("#{@user}:#{params['realm']}:#{@password}")
+        ha2 = Digest::MD5.hexdigest("#{http_method.to_s.upcase}:#{request_uri}")
+
+        params.merge!('cnonce' => client_nonce)
+        request_digest = Digest::MD5.hexdigest([ha1, params['nonce'], "0", params['cnonce'], params['qop'], ha2].join(":"))
+        "Digest #{auth_attributes_for(uri, request_digest, params)}"
+      end
+
+      def client_nonce
+        Digest::MD5.hexdigest("%x" % (Time.now.to_i + rand(65535)))
+      end
+
+      def extract_params_from_response
+        params = {}
+        if response_auth_header =~ /^(\w+) (.*)/
+          $2.gsub(/(\w+)="(.*?)"/) { params[$1] = $2 }
+        end
+        params
+      end
+
+      def auth_attributes_for(uri, request_digest, params)
+        auth_attrs =
+          [
+            %Q(username="#{@user}"),
+            %Q(realm="#{params['realm']}"),
+            %Q(qop="#{params['qop']}"),
+            %Q(uri="#{uri.path}"),
+            %Q(nonce="#{params['nonce']}"),
+            %Q(nc="0"),
+            %Q(cnonce="#{params['cnonce']}"),
+            %Q(response="#{request_digest}")]
+
+        auth_attrs << %Q(opaque="#{params['opaque']}") unless params['opaque'].blank?
+        auth_attrs.join(", ")
+      end
+
+      def http_format_header(http_method)
+        {HTTP_FORMAT_HEADER_NAMES[http_method] => format.mime_type}
+      end
+
+      def legitimize_auth_type(auth_type)
+        return :basic if auth_type.nil?
+        auth_type = auth_type.to_sym
+        auth_type.in?([:basic, :digest]) ? auth_type : :basic
+      end
+  end
+end

data/lib/active_resource/custom_methods.rb

@@ -0,0 +1,127 @@
+require 'active_support/core_ext/object/blank'
+
+module ActiveResource
+  # A module to support custom REST methods and sub-resources, allowing you to break out
+  # of the "default" REST methods with your own custom resource requests. For example,
+  # say you use Rails to expose a REST service and configure your routes with:
+  #
+  #    map.resources :people, :new => { :register => :post },
+  #                           :member => { :promote => :put, :deactivate => :delete }
+  #                           :collection => { :active => :get }
+  #
+  # This route set creates routes for the following HTTP requests:
+  #
+  #    POST      /people/new/register.json # PeopleController.register
+  #    PATCH/PUT /people/1/promote.json    # PeopleController.promote with :id => 1
+  #    DELETE    /people/1/deactivate.json # PeopleController.deactivate with :id => 1
+  #    GET       /people/active.json       # PeopleController.active
+  #
+  # Using this module, Active Resource can use these custom REST methods just like the
+  # standard methods.
+  #
+  #   class Person < ActiveResource::Base
+  #     self.site = "https://37s.sunrise.com"
+  #   end
+  #
+  #   Person.new(:name => 'Ryan').post(:register)  # POST /people/new/register.json
+  #   # => { :id => 1, :name => 'Ryan' }
+  #
+  #   Person.find(1).put(:promote, :position => 'Manager') # PUT /people/1/promote.json
+  #   Person.find(1).delete(:deactivate) # DELETE /people/1/deactivate.json
+  #
+  #   Person.get(:active)  # GET /people/active.json
+  #   # => [{:id => 1, :name => 'Ryan'}, {:id => 2, :name => 'Joe'}]
+  #
+  module CustomMethods
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        alias :orig_delete :delete
+
+        # Invokes a GET to a given custom REST method. For example:
+        #
+        #   Person.get(:active)  # GET /people/active.json
+        #   # => [{:id => 1, :name => 'Ryan'}, {:id => 2, :name => 'Joe'}]
+        #
+        #   Person.get(:active, :awesome => true)  # GET /people/active.json?awesome=true
+        #   # => [{:id => 1, :name => 'Ryan'}]
+        #
+        # Note: the objects returned from this method are not automatically converted
+        # into ActiveResource::Base instances - they are ordinary Hashes. If you are expecting
+        # ActiveResource::Base instances, use the <tt>find</tt> class method with the
+        # <tt>:from</tt> option. For example:
+        #
+        #   Person.find(:all, :from => :active)
+        def get(custom_method_name, options = {})
+          hashified = format.decode(connection.get(custom_method_collection_url(custom_method_name, options), headers).body)
+          derooted  = Formats.remove_root(hashified)
+          derooted.is_a?(Array) ? derooted.map { |e| Formats.remove_root(e) } : derooted
+        end
+
+        def post(custom_method_name, options = {}, body = '')
+          connection.post(custom_method_collection_url(custom_method_name, options), body, headers)
+        end
+
+        def patch(custom_method_name, options = {}, body = '')
+          connection.patch(custom_method_collection_url(custom_method_name, options), body, headers)
+        end
+
+        def put(custom_method_name, options = {}, body = '')
+          connection.put(custom_method_collection_url(custom_method_name, options), body, headers)
+        end
+
+        def delete(custom_method_name, options = {})
+          # Need to jump through some hoops to retain the original class 'delete' method
+          if custom_method_name.is_a?(Symbol)
+            connection.delete(custom_method_collection_url(custom_method_name, options), headers)
+          else
+            orig_delete(custom_method_name, options)
+          end
+        end
+      end
+    end
+
+    module ClassMethods
+      def custom_method_collection_url(method_name, options = {})
+        prefix_options, query_options = split_options(options)
+        "#{prefix(prefix_options)}#{collection_name}/#{method_name}#{format_extension}#{query_string(query_options)}"
+      end
+    end
+
+    def get(method_name, options = {})
+      self.class.format.decode(connection.get(custom_method_element_url(method_name, options), self.class.headers).body)
+    end
+
+    def post(method_name, options = {}, body = nil)
+      request_body = body.blank? ? encode : body
+      if new?
+        connection.post(custom_method_new_element_url(method_name, options), request_body, self.class.headers)
+      else
+        connection.post(custom_method_element_url(method_name, options), request_body, self.class.headers)
+      end
+    end
+
+    def patch(method_name, options = {}, body = '')
+      connection.patch(custom_method_element_url(method_name, options), body, self.class.headers)
+    end
+
+    def put(method_name, options = {}, body = '')
+      connection.put(custom_method_element_url(method_name, options), body, self.class.headers)
+    end
+
+    def delete(method_name, options = {})
+      connection.delete(custom_method_element_url(method_name, options), self.class.headers)
+    end
+
+
+    private
+      def custom_method_element_url(method_name, options = {})
+        "#{self.class.prefix(prefix_options)}#{self.class.collection_name}/#{id}/#{method_name}#{self.class.format_extension}#{self.class.__send__(:query_string, options)}"
+      end
+
+      def custom_method_new_element_url(method_name, options = {})
+        "#{self.class.prefix(prefix_options)}#{self.class.collection_name}/new/#{method_name}#{self.class.format_extension}#{self.class.__send__(:query_string, options)}"
+      end
+  end
+end