prx_hyperresource 1.0.0

data/lib/hyper_resource/modules/data_type.rb

@@ -0,0 +1,96 @@
+class HyperResource
+  module Modules
+    module DataType
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # @private
+      def get_data_type_class(args)
+        self.class.get_data_type_class(args)
+      end
+
+      # @private
+      def get_data_type(args)
+        self.class.get_data_type(args)
+      end
+
+      module ClassMethods
+        ## Returns the class into which a given response should be
+        ## instantiated.  Class name is a combination of `resource.namespace`
+        ## and `get_data_type(args)'.  Creates this class if necessary.
+        ## Args are :resource, :link, :response, :body, :url.
+        # @private
+        def get_data_type_class(args)
+          url = args[:url] || args[:link].url
+          namespace = args[:resource].namespace_for_url(url.to_s)
+          namespace || "no namespace bish"
+          return self unless namespace
+
+          ## Make sure namespace class exists
+          namespace_str = sanitize_class_name(namespace.to_s)
+          if namespace.is_a?(String)
+            ns_class = begin
+              eval(namespace_str) # standard:disable Security/Eval
+            rescue
+              nil
+            end
+            if !ns_class
+              Object.module_eval("class #{namespace_str} < #{self}; end", __FILE__, __LINE__)
+              ns_class = eval(namespace_str) # standard:disable Security/Eval
+            end
+          end
+
+          ## If there's no identifiable data type, return the namespace class.
+          type = get_data_type(args)
+          return ns_class unless type
+
+          ## Make sure data type class exists
+          type = type[0, 1].upcase + type[1..]  ## capitalize
+          sanitized_type = sanitize_class_name(type)
+          data_type_str = "#{namespace_str}::#{sanitized_type}"
+          unless ns_class.constants.include?(sanitized_type.to_sym)
+            Object.module_eval("class #{data_type_str} < #{namespace_str}; end", __FILE__, __LINE__)
+          end
+          eval(data_type_str) # standard:disable Security/Eval
+        end
+
+        ## Given a body Hash and a response Faraday::Response, detect and
+        ## return a string describing this response's data type.
+        ## Args are :body and :response.
+        def get_data_type(args)
+          get_data_type_from_body(args[:body]) ||
+            get_data_type_from_response(args[:response])
+        end
+
+        ## Given a Faraday::Response, inspects the Content-type for data
+        ## type information and returns data type as a String,
+        ## for instance returning `Widget` given a media
+        ## type `application/vnd.example.com+hal+json;type=Widget`.
+        ## Override this method to change behavior.
+        ## Returns nil on failure.
+        def get_data_type_from_response(response)
+          return nil unless response
+          return nil unless (content_type = response["content-type"])
+          return nil unless (m = content_type.match(/;\s* type=([0-9A-Za-z:]+)/x))
+          m[1]
+        end
+
+        ## Given a response body Hash, returns the response's data type as
+        ## a string.  By default, it looks for a `_data_type` field in the
+        ## response.  Override this method to change behavior.
+        def get_data_type_from_body(body)
+          return nil unless body
+          body["_data_type"] || body["type"]
+        end
+
+        private
+
+        ## Remove all non-word, non-colon elements from a class name.
+        def sanitize_class_name(name)
+          name.gsub(/[^_0-9A-Za-z:]/, "")
+        end
+      end
+    end
+  end
+end

data/lib/hyper_resource/modules/deprecations.rb

@@ -0,0 +1,51 @@
+class HyperResource
+  module Modules
+    module Deprecations
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      ## Show a deprecation message.
+      # @private
+      def _hr_deprecate(*args)
+        self.class._hr_deprecate(*args)
+      end
+
+      module ClassMethods
+        ## Show a deprecation message.
+        # @private
+        def _hr_deprecate(message)
+          warn "#{message} (called from #{caller(3..3).first})"
+        end
+      end
+
+      ###### Deprecated stuff:
+
+      ## +response_body+, +response_object+, and +deserialized_response+
+      ##  are deprecated in favor of +body+.  (Sorry. Naming things is hard.)
+      ## Deprecated at 0.2. @private
+      def response_body
+        _hr_deprecate("HyperResource#response_body is deprecated. " \
+                      "Please use HyperResource#body instead.")
+        body
+      end
+
+      # @private
+      def response_object
+        _hr_deprecate("HyperResource#response_object is deprecated. " \
+                      "Please use HyperResource#body instead.")
+        body
+      end
+
+      # @private
+      def deserialized_response
+        _hr_deprecate("HyperResource#deserialized_response is deprecated. " \
+                      "Please use HyperResource#body instead.")
+        body
+      end
+
+      ## Deprecated at 0.9:
+      ## #create, #update, Link#create, Link#update
+    end
+  end
+end

data/lib/hyper_resource/modules/http.rb

@@ -0,0 +1,305 @@
+require "faraday"
+require "uri"
+require "cgi"
+require "json"
+require "digest/md5"
+
+class HyperResource
+  ## Returns this resource's fully qualified URL.  Returns nil when
+  ## `root` or `href` are malformed.
+  def url
+    URI.join(root, href || "").to_s
+  rescue
+    nil
+  end
+
+  ## Performs a GET request to this resource's URL, and returns a
+  ## new resource representing the response.
+  def get
+    to_link.get
+  end
+
+  ## Performs a GET request to this resource's URL, and returns a
+  ## `Faraday::Response` object representing the response.
+  def get_response
+    to_link.get_response
+  end
+
+  ## Performs a POST request to this resource's URL, sending all of
+  ## `attributes` as a request body unless an `attrs` Hash is given.
+  ## Returns a new resource representing the response.
+  def post(attrs = nil)
+    to_link.post(attrs)
+  end
+
+  ## Performs a POST request to this resource's URL, sending all of
+  ## `attributes` as a request body unless an `attrs` Hash is given.
+  ## Returns a `Faraday::Response` object representing the response.
+  def post_response(attrs = nil)
+    to_link.post_response(attrs)
+  end
+
+  ## Performs a PUT request to this resource's URL, sending all of
+  ## `attributes` as a request body unless an `attrs` Hash is given.
+  ## Returns a new resource representing the response.
+  def put(*args)
+    to_link.put(*args)
+  end
+
+  ## Performs a PUT request to this resource's URL, sending all of
+  ## `attributes` as a request body unless an `attrs` Hash is given.
+  ## Returns a `Faraday::Response` object representing the response.
+  def put_response(*args)
+    to_link.put_response(*args)
+  end
+
+  ## Performs a PATCH request to this resource's URL, sending
+  ## `attributes.changed_attributes` as a request body
+  ## unless an `attrs` Hash is given.  Returns a new resource
+  ## representing the response.
+  def patch(*args)
+    to_link.patch(*args)
+  end
+
+  ## Performs a PATCH request to this resource's URL, sending
+  ## `attributes.changed_attributes` as a request body
+  ## unless an `attrs` Hash is given.
+  ## Returns a `Faraday::Response` object representing the response.
+  def patch_response(*args)
+    to_link.patch_response(*args)
+  end
+
+  ## Performs a DELETE request to this resource's URL.  Returns a new
+  ## resource representing the response.
+  def delete
+    to_link.delete
+  end
+
+  ## Performs a DELETE request to this resource's URL.
+  ## Returns a `Faraday::Response` object representing the response.
+  def delete_response
+    to_link.delete_response
+  end
+
+  ## Creates a Link representing this resource.  Used for HTTP delegation.
+  # @private
+  def to_link(args = {})
+    self.class::Link.new(self,
+      href: args[:href] || href,
+      params: args[:params] || attributes)
+  end
+
+  # @private
+  def create(attrs)
+    _hr_deprecate("HyperResource#create is deprecated. Please use " \
+                  "#post instead.")
+    to_link.post(attrs)
+  end
+
+  # @private
+  def update(*args)
+    _hr_deprecate("HyperResource#update is deprecated. Please use " \
+                  "#put or #patch instead.")
+    to_link.put(*args)
+  end
+
+  module Modules
+    ## HyperResource::Modules::HTTP is included by HyperResource::Link.
+    ## It provides support for GET, POST, PUT, PATCH, and DELETE.
+    ## Each method returns a new object which is a kind_of HyperResource.
+    module HTTP
+      ## Loads and returns the resource pointed to by +href+.  The returned
+      ## resource will be blessed into its "proper" class, if
+      ## +self.class.namespace != nil+.
+      def get
+        new_resource_from_response(get_response)
+      end
+
+      ## Performs a GET request on the given link, and returns the
+      ## response as a `Faraday::Response` object.
+      ## Does not parse the response as a `HyperResource` object.
+      def get_response
+        ## Adding default_attributes to URL query params is not automatic
+        uri = URI.parse(url || "")
+        query = CGI.parse(uri.query || "")
+        str = URI.encode_www_form((resource.default_attributes || {}).merge(query))
+        uri.query = str.empty? ? nil : str
+        faraday_connection.get(uri.to_s)
+      end
+
+      ## By default, calls +post+ with the given arguments. Override to
+      ## change this behavior.
+      def create(*args)
+        _hr_deprecate("HyperResource::Link#create is deprecated. Please use " \
+                      "#post instead.")
+        post(*args)
+      end
+
+      ## POSTs the given attributes to this resource's href, and returns
+      ## the response resource.
+      def post(attrs = nil)
+        new_resource_from_response(post_response(attrs))
+      end
+
+      ## POSTs the given attributes to this resource's href, and returns the
+      ## response as a `Faraday::Response` object.
+      ## Does not parse the response as a `HyperResource` object.
+      def post_response(attrs = nil)
+        attrs ||= resource.attributes
+        attrs = (resource.default_attributes || {}).merge(attrs)
+        faraday_connection.post do |req|
+          req.headers["Content-Type"] ||= "application/json"
+          req.body = resource.adapter.serialize(attrs)
+        end
+      end
+
+      ## By default, calls +put+ with the given arguments.  Override to
+      ## change this behavior.
+      def update(*args)
+        _hr_deprecate("HyperResource::Link#update is deprecated. Please use " \
+                      "#put or #patch instead.")
+        put(*args)
+      end
+
+      ## PUTs this resource's attributes to this resource's href, and returns
+      ## the response resource.  If attributes are given, +put+ uses those
+      ## instead.
+      def put(attrs = nil)
+        new_resource_from_response(put_response(attrs))
+      end
+
+      ## PUTs this resource's attributes to this resource's href, and returns
+      ## the response as a `Faraday::Response` object.
+      ## Does not parse the response as a `HyperResource` object.
+      def put_response(attrs = nil)
+        attrs ||= resource.attributes
+        attrs = (resource.default_attributes || {}).merge(attrs)
+        faraday_connection.put do |req|
+          req.headers["Content-Type"] ||= "application/json"
+          req.body = resource.adapter.serialize(attrs)
+        end
+      end
+
+      ## PATCHes this resource's changed attributes to this resource's href,
+      ## and returns the response resource.  If attributes are given, +patch+
+      ## uses those instead.
+      def patch(attrs = nil)
+        new_resource_from_response(patch_response(attrs))
+      end
+
+      ## PATCHes this resource's changed attributes to this resource's href,
+      ## and returns the response as a `Faraday::Response` object.
+      ## Does not parse the response as a `HyperResource` object.
+      def patch_response(attrs = nil)
+        attrs ||= resource.attributes.changed_attributes
+        attrs = (resource.default_attributes || {}).merge(attrs)
+        faraday_connection.patch do |req|
+          req.headers["Content-Type"] ||= "application/json"
+          req.body = resource.adapter.serialize(attrs)
+        end
+      end
+
+      ## DELETEs this resource's href, and returns the response resource.
+      def delete
+        new_resource_from_response(delete_response)
+      end
+
+      ## DELETEs this resource's href, and returns the response as a
+      ## `Faraday::Response` object.
+      ## Does not parse the response as a `HyperResource` object.
+      def delete_response
+        faraday_connection.delete
+      end
+
+      private
+
+      ## Returns a raw Faraday connection to this resource's URL, with proper
+      ## headers (including auth).  Threadsafe.
+      def faraday_connection(url = nil)
+        rsrc = resource
+        url ||= self.url
+        headers = (rsrc.headers_for_url(url) || {}).merge(self.headers)
+        auth = rsrc.auth_for_url(url) || {}
+        fo = rsrc.faraday_options_for_url(url) || {}
+
+        key = ::Digest::MD5.hexdigest({
+          "faraday_connection" => {
+            "url" => url,
+            "headers" => headers,
+            "ba" => auth[:basic],
+            "fo" => fo
+          }
+        }.to_json)
+        return Thread.current[key] if Thread.current[key]
+
+        fc = Faraday.new(fo.merge(url: url))
+        fc.headers["User-Agent"] = rsrc.user_agent
+        fc.headers.merge!(headers)
+        if (ba = auth[:basic])
+          if fc.respond_to?(:basic_auth)
+            fc.basic_auth(*ba)
+          else
+            fc.request :authorization, :basic, *ba
+          end
+        end
+        Thread.current[key] = fc
+      end
+
+      ## Given a Faraday::Response object, create a new resource
+      ## object to represent it.  The new resource will be in its
+      ## proper class according to its configured `namespace` and
+      ## the response's detected data type.
+      def new_resource_from_response(response)
+        status = response.status
+        is_success = (status / 100 == 2)
+        adapter = resource.adapter || HyperResource::Adapter::HAL_JSON
+
+        body = nil
+        unless empty_body?(response.body)
+          begin
+            body = adapter.deserialize(response.body)
+          rescue => e
+            if is_success
+              raise HyperResource::ResponseError.new(
+                "Error when deserializing response body",
+                response: response,
+                cause: e
+              )
+            end
+          end
+        end
+
+        new_rsrc = resource.new_from(link: self,
+          body: body,
+          response: response)
+
+        if status / 100 == 2
+          new_rsrc
+        elsif status / 100 == 3
+          raise NotImplementedError,
+            "HyperResource has not implemented redirection."
+        elsif status / 100 == 4
+          raise HyperResource::ClientError.new(status.to_s,
+            response: response,
+            body: body)
+        elsif status / 100 == 5
+          raise HyperResource::ServerError.new(status.to_s,
+            response: response,
+            body: body)
+        else ## 1xx? really?
+          raise HyperResource::ResponseError.new("Unknown status #{status}",
+            response: response,
+            body: body)
+
+        end
+      end
+
+      def empty_body?(body)
+        return true if body.nil?
+        return true if body.respond_to?(:empty?) && body.empty?
+        return true if body.instance_of?(String) && body =~ /^['"]+$/ # special case for status code with optional body, example Grape API with status 405
+        false
+      end
+    end
+  end
+end

data/lib/hyper_resource/modules/internal_attributes.rb

@@ -0,0 +1,74 @@
+module HyperResource::Modules
+  module InternalAttributes
+    def self.included(base)
+      base.extend(ClassMethods)
+
+      base._hr_class_attributes.each do |attr|
+        base._hr_class_attribute attr
+      end
+
+      (base._hr_attributes - base._hr_class_attributes).each do |attr|
+        base.send(:attr_accessor, attr)
+      end
+
+      ## Fallback attributes fall back from instance to class.
+      (base._hr_attributes & base._hr_class_attributes).each do |attr|
+        base._hr_fallback_attribute attr
+      end
+    end
+
+    module ClassMethods
+      # @private
+      def _hr_class_attributes
+        [:root]
+      end
+
+      # @private
+      def _hr_attributes
+        [:root,
+          :href,
+          :request,
+          :response,
+          :body,
+          :attributes,
+          :links,
+          :objects,
+          :loaded]
+      end
+
+      ## Inheritable class attribute, kinda like in Rails.
+      # @private
+      def _hr_class_attribute(*names)
+        names.map(&:to_sym).each do |name|
+          instance_eval <<-EOT, __FILE__, __LINE__ + 1
+            def #{name}=(val)
+              @#{name} = val
+            end
+            def #{name}
+              return @#{name} if defined?(@#{name})
+              return superclass.#{name} if superclass.respond_to?(:#{name})
+              nil
+            end
+          EOT
+        end
+      end
+
+      ## Instance attributes which fall back to class attributes.
+      # @private
+      def _hr_fallback_attribute(*names)
+        names.map(&:to_sym).each do |name|
+          class_eval <<-EOT, __FILE__, __LINE__ + 1
+            def #{name}=(val)
+              @#{name} = val
+            end
+            def #{name}
+              return @#{name} if defined?(@#{name})
+              return self.class.#{name} if self.class.respond_to?(:#{name})
+              nil
+            end
+          EOT
+        end
+      end
+    end # ClassMethods
+  end
+end

data/lib/hyper_resource/objects.rb

@@ -0,0 +1,41 @@
+class HyperResource
+  class Objects < Hash
+    attr_accessor :_resource
+
+    def initialize(resource = nil)
+      self._resource = resource || HyperResource.new
+    end
+
+    # @private
+    def []=(attr, value)
+      super(attr.to_s, value)
+    end
+
+    ## When +key+ is a string, returns the array of objects under that name.
+    ## When +key+ is a number, returns +ith(key)+. Returns nil on lookup
+    ## failure.
+    def [](key)
+      case key
+      when String, Symbol
+        return super(key.to_s) if has_key?(key.to_s)
+        return super(key.to_sym) if has_key?(key.to_sym)
+      when Integer
+        return ith(key)
+      end
+      nil
+    end
+
+    # @private
+    def method_missing(method, *args) # standard:disable Style/MissingRespondToMissing
+      return self[method] if self[method]
+      raise NoMethodError, "undefined method `#{method}' for #{inspect}"
+    end
+
+    # @private
+    def respond_to?(method, *args)
+      method = method.to_s
+      return true if has_key?(method)
+      super
+    end
+  end
+end

data/lib/hyper_resource/version.rb

@@ -0,0 +1,3 @@
+class HyperResource
+  VERSION = "1.0.0"
+end