hyperresource 0.2.4 → 0.9.0

data/lib/hyper_resource/configuration.rb

@@ -0,0 +1,159 @@
+require 'uri'
+require 'fuzzyurl'
+
+class HyperResource
+
+  ## HyperResource::Configuration is a class which implements a hostmask-
+  ## scoped set of configurations.  Key/value pairs are stored under hostmasks
+  ## like 'api.example.com:8080', 'api.example.com', '*.example.com', or '*'.
+  ## Values are retrieved using a hostname and a key, preferring more specific
+  ## hostmasks when more than one matching hostmask and key are present.
+  ##
+  ## HyperResource users are not expected to use this class directly.
+  class Configuration
+
+    ## Creates a new HyperResource::Configuration, with the given initial
+    ## internal state if provided.
+    def initialize(cfg={})
+      @cfg = cfg
+      @cfg['*'] ||= {}
+    end
+
+    ## Returns a deep copy of this object.
+    def clone
+      self.class.new.send(:initialize_copy, self)
+    end
+
+    ## Merges a given Configuration with this one.  Deep-merges config
+    ## attributes correctly.
+    def merge(new)
+      merged_cfg = {}
+      new_cfg = new.send(:cfg)
+
+      (new_cfg.keys | cfg.keys).each do |mask|
+        new_cfg_attrs = new_cfg[mask] || {}
+        cfg_attrs = cfg[mask] || {}
+        merged_cfg[mask] = {}
+
+        ## Do a hash merge when it makes sense, except when it doesn't.
+        (new_cfg_attrs.keys | cfg_attrs.keys).each do |attr|
+          if !(%w(namespace adapter).include?(attr)) &&
+             ((!cfg_attrs[attr] || cfg_attrs[attr].kind_of?(Hash)) &&
+              (!new_cfg_attrs[attr] || new_cfg_attrs[attr].kind_of?(Hash)))
+            merged_cfg[mask][attr] =
+              (cfg_attrs[attr] || {}).merge(new_cfg_attrs[attr] || {})
+          else
+            merged_cfg[mask][attr] = new_cfg_attrs[attr] || cfg_attrs[attr]
+          end
+        end
+      end
+      self.class.new(merged_cfg)
+    end
+
+    ## Applies a given Configuration on top of this one.
+    def merge!(new)
+      initialize_copy(merge(new))
+    end
+
+    ## Applies a given Hash of configurations on top of this one.
+    def config(hash)
+      merge!(self.class.new(hash))
+    end
+
+    ## Returns this object as a Hash.
+    def as_hash
+      clone.send(:cfg)
+    end
+
+    ## Returns the value for a particular hostmask and key, or nil if not
+    ## present.
+    def get(mask, key)
+      cfg[mask] ||= {}
+      cfg[mask][key.to_s]
+    end
+
+    ## Sets a key and value pair for the given hostmask.
+    def set(mask, key, value)
+      cfg[mask] ||= {}
+      cfg[mask][key.to_s] = value
+    end
+
+    ## Returns the best matching value for the given URL and key, or nil
+    ## otherwise.
+    def get_for_url(url, key)
+      subconfig_for_url(url)[key.to_s]
+    end
+
+    ## Sets a key and value pair, using the given URL as the basis of the
+    ## hostmask.  Path, query, and fragment are ignored.
+    def set_for_url(url, key, value)
+      furl = FuzzyURL.new(url || '*')
+      furl.path = nil
+      furl.query = nil
+      furl.fragment = nil
+      set(furl.to_s, key, value)
+    end
+
+
+    ## Returns hostmasks from our config which match the given url.
+    def matching_masks_for_url(url)
+      url = url.to_s
+      return ['*'] if !url || cfg.keys.count == 1
+      @masks ||= {} ## key = mask string, value = FuzzyURL
+      cfg.keys.each {|key| @masks[key] ||= FuzzyURL.new(key) }
+
+      ## Test for matches, and sort by score.
+      scores = {}
+      cfg.keys.each {|key| scores[key] = @masks[key].match(url) }
+      scores = Hash[ scores.select{|k,v| v} ] # remove nils
+      scores.keys.sort_by{|k| [-scores[k], -k.length]} ## TODO length is cheesy
+    end
+
+  private
+
+    def cfg
+      @cfg
+    end
+
+    ## Performs a two-level-deep copy of old @cfg.
+    def initialize_copy(old)
+      old.send(:cfg).each do |mask, old_subcfg|
+        new_subcfg = {}
+        old_subcfg.each do |key, value|
+          if value.kind_of?(Array) || value.kind_of?(Hash)
+            value = value.clone
+          end
+          new_subcfg[key] = value
+        end
+        @cfg[mask] = new_subcfg
+      end
+      self
+    end
+
+
+    ## Returns a merged subconfig consisting of all matching hostmask
+    ## subconfigs, giving priority to more specific hostmasks.
+    def subconfig_for_url(url)
+      matching_masks_for_url(url).inject({}) do |subcfg, mask|
+        (cfg[mask] || {}).merge(subcfg)
+      end
+    end
+
+    ## Returns the hostmasks which match the given url, sorted best match
+    ## first.
+    def get_possible_masks_for_host(host, port=80, masks=nil)
+      masks ||= ["#{host}:#{port}", host]  ## exact matches first
+      host_parts = host.split('.')
+
+      if host_parts.count < 2
+        masks << '*' ## wildcard match last
+      else
+        parent_domain = host_parts[1..-1].join('.')
+        masks << '*.' + parent_domain
+        get_possible_masks_for_host(parent_domain, port, masks)
+      end
+    end
+
+  end
+end
+

data/lib/hyper_resource/exceptions.rb

@@ -3,7 +3,8 @@ class HyperResource
     ## The internal exception which led to this one, if any.
     attr_accessor :cause
 
-    def initialize(message, attrs={}) # @private
+    # @private
+    def initialize(message, attrs={})
       self.cause = attrs[:cause]
       super(message)
     end
@@ -17,7 +18,8 @@ class HyperResource
     ## May be blank, e.g. in case of deserialization errors.
     attr_accessor :body
 
-    def initialize(message, attrs={}) # @private
+    # @private
+    def initialize(message, attrs={})
       self.response = attrs[:response]
       self.body = attrs[:body]
 

data/lib/hyper_resource/link.rb

@@ -1,59 +1,100 @@
 require 'uri_template'
+require 'hyper_resource/modules/http'
 
-class HyperResource::Link
-  attr_accessor :base_href,
-                :name,
-                :templated,
-                :params,
-                :parent_resource
-
-  ## Returns true if this link is templated.
-  def templated?; templated end
-
-  def initialize(resource=nil, link_spec={})
-    self.parent_resource = resource || HyperResource.new
-    self.base_href = link_spec['href']
-    self.name = link_spec['name']
-    self.templated = !!link_spec['templated']
-    self.params    = link_spec['params'] || {}
-  end
+class HyperResource
+
+  ## HyperResource::Link is an object to represent a hyperlink and its
+  ## URL or body parameters, and to encapsulate HTTP calls involving this
+  ## link.  Links are typically created by HyperResource, not by end users.
+  ##
+  ## HTTP method calls return the response as a HyperResource (or subclass)
+  ## object.  Calling an unrecognized method on a link will automatically
+  ## load the resource pointed to by this link, and repeat the method call
+  ## on the resource object.
+  ##
+  ## A HyperResource::Link requires the resource it is based upon to remain
+  ## in scope.  In practice this is rarely a problem, as links are almost
+  ## always accessed through the resource object.
+
+  class Link
+
+    include HyperResource::Modules::HTTP
+
+    ## The literal href of this link; may be templated.
+    attr_accessor :base_href
+
+    ## An optional name describing this link.
+    attr_accessor :name
+
+    ## `true` if this link's href is a URI Template, `false` otherwise.
+    attr_accessor :templated
+
+    ## A hash of URL or request body parameters.
+    attr_accessor :params
+
+    ## Default HTTP method for implicit loading.
+    attr_accessor :default_method
+
+    ## The resource from which this link originates.
+    attr_accessor :resource
+
+    ## Returns a link based on the given resource and link specification
+    ## hash.  `link_spec` keys are: `href` (string, required), `templated`
+    ## (boolean), `params` (hash), and `default_method` (string, default
+    ## `"get"`).
+    def initialize(resource, link_spec={})
+      unless link_spec.kind_of?(Hash)
+        raise ArgumentError, "link_spec must be a Hash (got #{link_spec.inspect})"
+      end
+      link_spec = Hash[ link_spec.map{|(k,v)| [k.to_s, v]} ] ## stringify keys
 
-  ## Returns this link's href, applying any URI template params.
-  def href
-    if self.templated?
-      filtered_params = self.parent_resource.outgoing_uri_filter(params)
-      URITemplate.new(self.base_href).expand(filtered_params)
-    else
-      self.base_href
+      self.resource = resource
+      self.base_href = link_spec['href']
+      self.name = link_spec['name']
+      self.templated = !!link_spec['templated']
+      self.params = link_spec['params'] || {}
+      self.default_method = link_spec['method'] || 'get'
     end
-  end
 
-  ## Returns a new scope with the given params; that is, returns a copy of
-  ## itself with the given params applied.
-  def where(params)
-    params = Hash[ params.map{|(k,v)| [k.to_s, v]} ]
-    self.class.new(self.parent_resource,
-                   'href' => self.base_href,
-                   'name' => self.name,
-                   'templated' => self.templated,
-                   'params' => self.params.merge(params))
-  end
+    ## Returns this link's href, applying any URI template params.
+    def href
+      if self.templated
+        filtered_params = self.resource.outgoing_uri_filter(params)
+        URITemplate.new(self.base_href).expand(filtered_params)
+      else
+        self.base_href
+      end
+    end
 
-  ## Returns a HyperResource representing this link
-  def resource
-    parent_resource._hr_new_from_link(self.href)
-  end
+    ## Returns this link's fully resolved URL, or nil if `resource.root`
+    ## or `href` are malformed.
+    def url
+      begin
+        URI.join(self.resource.root, self.href.to_s).to_s
+      rescue StandardError
+        nil
+      end
+    end
+
+    ## Returns a new scope with the given params; that is, returns a copy of
+    ## itself with the given params applied.
+    def where(params)
+      params = Hash[ params.map{|(k,v)| [k.to_s, v]} ]
+      self.class.new(self.resource,
+                     'href' => self.base_href,
+                     'name' => self.name,
+                     'templated' => self.templated,
+                     'params' => self.params.merge(params),
+                     'method' => self.default_method)
+    end
+
+    ## Unrecognized methods invoke an implicit load of the resource pointed
+    ## to by this link.  The method call is then repeated on the returned
+    ## resource.
+    def method_missing(method, *args)
+      self.send(default_method || :get).send(method, *args)
+    end
 
-  ## Delegate HTTP methods to the resource.
-  def get(*args);    self.resource.get(*args)    end
-  def post(*args);   self.resource.post(*args)   end
-  def patch(*args);  self.resource.patch(*args)  end
-  def put(*args);    self.resource.put(*args)    end
-  def delete(*args); self.resource.delete(*args) end
-
-  ## If we were called with a method we don't know, load this resource
-  ## and pass the message along.  This achieves implicit loading.
-  def method_missing(method, *args)
-    self.get.send(method, *args)
   end
 end
+

data/lib/hyper_resource/links.rb

@@ -1,52 +1,53 @@
 class HyperResource
+
+  ## HyperResource::Links is a modified Hash that permits lookup
+  ## of a link by its link relation (rel), or an abbreviation thereof.
+  ## It also provides read access through `method_missing`.
+  ## It is typically created by HyperResource, not by end users.
+  ##
+  ## For example, a link with rel `someapi:widgets` is accessible
+  ## by any of `self.widgets`, `self['widgets']`, `self[:widgets]`, and
+  ## `self['someapi:widgets'].
   class Links < Hash
-    attr_accessor :_resource
 
+    # @private
     def initialize(resource=nil)
-     self._resource = resource || HyperResource.new
+      ## We used to store the resource, but we didn't need to.  Now we don't.
     end
 
-    ## Creates accessor methods in self.class and self._resource.class.
-    ## Protects against method creation into HyperResource::Links and
-    ## HyperResource classes.  Just subclasses, please!
-    def _hr_create_methods!(opts={}) # @private
-      return if self.class.to_s == 'HyperResource::Links'
-      return if self._resource.class.to_s == 'HyperResource'
-      return if self.class.send(
-        :class_variable_defined?, :@@_hr_created_links_methods)
-
-      self.keys.each do |attr|
-        attr_sym = attr.to_sym
-        self.class.send(:define_method, attr_sym) do |*args|
-          if args.count > 0
-            self[attr].where(*args)
-          else
-            self[attr]
-          end
-        end
-
-        ## Don't stomp on _resource's methods
-        unless _resource.respond_to?(attr_sym)
-          _resource.class.send(:define_method, attr_sym) do |*args|
-            links.send(attr_sym, *args)
-          end
-        end
+    ## Stores a link for future retrieval by its link rel or abbreviations
+    ## thereof.
+    def []=(rel, link)
+      rel = rel.to_s
+
+      ## Every link must appear under its literal name.
+      names = [rel]
+
+      ## Extract 'foo' from e.g. 'http://example.com/foo',
+      ## 'http://example.com/url#foo', 'somecurie:foo'.
+      if m=rel.match(%r{[:/#](.+)})
+        names << m[1]
       end
 
-      self.class.send(:class_variable_set, :@@_hr_created_links_methods, true)
-    end
+      ## Underscore all non-word characters.
+      underscored_names = names.map{|n| n.gsub(/[^a-zA-Z_]/, '_')}
+      names = (names + underscored_names).uniq
 
-    def []=(attr, value) # @private
-      super(attr.to_s, value)
+      ## Register this link under every name we've come up with.
+      names.each do |name|
+        super(name, link)
+      end
     end
 
-    def [](key) # @private
-      return super(key.to_s) if self.has_key?(key.to_s)
-      return super(key.to_sym) if self.has_key?(key.to_sym)
-      nil
+    ## Retrieves a link by its rel.
+    def [](rel)
+      super(rel.to_s)
     end
 
-    def method_missing(method, *args) # @private
+    ## Provides links.somelink(:a => b) to links.somelink.where(:a => b)
+    ## expansion.
+    # @private
+    def method_missing(method, *args)
       unless self[method]
         raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
       end
@@ -58,6 +59,11 @@ class HyperResource
       end
     end
 
+    # @private
+    def respond_to?(method, *args)
+      return true if self.has_key?(method.to_s)
+      super
+    end
   end
 end
 

data/lib/hyper_resource/modules/config_attributes.rb

@@ -0,0 +1,293 @@
+class HyperResource
+  module Modules
+    module ConfigAttributes
+
+      ATTRS = [:auth, :headers, :namespace, :adapter, :faraday_options]
+
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # @private
+      def hr_config
+        @hr_config ||= self.class::Configuration.new
+      end
+
+      # @private
+      def hr_config=(cfg)
+        @hr_config = cfg
+      end
+
+      ## When called with no arguments, returns this resource's Configuration.
+      ## When called with a hash, applies the given configuration parameters
+      ## to this resource's Configuration.  `hash` must be in the form:
+      ##   {'hostmask' => {'attr1' => {...}, 'attr2' => {...}, ...}}
+      ## Valid attributes are `auth`, `headers`, `namespace`, `adapter`,
+      ## `default_attributes`, and `faraday_options`.
+      def config(hash=nil)
+        return hr_config unless hash
+        hr_config.config(hash)
+      end
+
+
+      ## Returns the auth config hash for this resource.
+      def auth
+        cfg_get(:auth)
+      end
+
+      ## Returns the auth config hash for the given url.
+      def auth_for_url(url)
+        self.hr_config.get_for_url(url, :auth)
+      end
+
+      ## Sets the auth config hash for this resource.
+      ## Currently only the format `{:basic => ['username', 'password']}`
+      ## is supported.
+      def auth=(v)
+        cfg_set(:auth, v)
+      end
+
+
+      ## Returns the headers hash for this resource.
+      ## This is done by merging all applicable header configs.
+      def headers
+        matching_masks = self.hr_config.matching_masks_for_url(self.url)
+        matching_masks.inject({}) do |hash, mask|
+          hash.merge(self.hr_config.get(mask, 'headers') || {})
+        end
+      end
+
+      ## Returns the headers hash for the given url.
+      def headers_for_url(url)
+        self.hr_config.get_for_url(url, :headers)
+      end
+
+      ## Sets the headers hash for this resource.
+      def headers=(v)
+        cfg_set(:headers, v)
+      end
+
+
+      ## Returns the namespace string/class for this resource.
+      def namespace
+        cfg_get(:namespace)
+      end
+
+      ## Returns the namespace string/class for the given url.
+      def namespace_for_url(url)
+        self.hr_config.get_for_url(url, :namespace)
+      end
+
+      ## Sets the namespace string/class for this resource.
+      def namespace=(v)
+        cfg_set(:namespace, v)
+      end
+
+
+      ## Returns the adapter class for this resource.
+      def adapter
+        cfg_get(:adapter) ||
+          HyperResource::Adapter::HAL_JSON
+      end
+
+      ## Returns the adapter class for the given url.
+      def adapter_for_url(url)
+        self.hr_config.get_for_url(url, :adapter) ||
+          HyperResource::Adapter::HAL_JSON
+      end
+
+      ## Sets the adapter class for this resource.
+      def adapter=(v)
+        cfg_set(:adapter, v)
+      end
+
+
+      ## Returns the hash of default attributes for this resource.
+      def default_attributes
+        cfg_get(:default_attributes)
+      end
+
+      ## Returns the hash of default attributes for the given url.
+      def default_attributes_for_url(url)
+        self.hr_config.get_for_url(url, :default_attributes)
+      end
+
+      ## Sets the hash of default attributes for this resource.
+      ## These attributes will be passed along with every HTTP request.
+      def default_attributes=(v)
+        cfg_set(:default_attributes, v)
+      end
+
+
+      ## Returns the Faraday connection options hash for this resource.
+      def faraday_options
+        cfg_get(:faraday_options)
+      end
+
+      ## Returns the Faraday connection options hash for this resource.
+      def faraday_options_for_url(url)
+        self.hr_config.get_for_url(url, :faraday_options)
+      end
+
+      ## Sets the Faraday connection options hash for this resource.
+      ## These options will be used for all HTTP requests.
+      def faraday_options=(v)
+        cfg_set(:faraday_options, v)
+      end
+
+
+    private
+
+      def cfg_get(key)
+        hr_config.get_for_url(self.url, key) ||
+          self.class.hr_config.get_for_url(self.url, key)
+      end
+
+      ## Sets a config key-value pair for this resource.
+      def cfg_set(key, value)
+        hr_config.set_for_url(url.to_s, key, value)
+      end
+
+    public
+
+      module ClassMethods
+
+        def hr_config
+          @hr_config ||= self::Configuration.new
+        end
+
+        ## When called with no arguments, returns this class's Configuration.
+        ## When called with a hash, applies the given configuration parameters
+        ## to this resource's Configuration.  `hash` must be in the form:
+        ##   {'hostmask' => {'key1' => 'value1', 'key2' => 'value2', ...}}
+        ## Valid keys are `auth`, `headers`, `namespace`, `adapter`, and
+        ## `faraday_options`.
+        def config(hash=nil)
+          return hr_config unless hash
+          hr_config.config(hash)
+        end
+
+
+        ## Returns the auth config hash for this resource class.
+        def auth
+          cfg_get(:auth)
+        end
+
+        ## Returns the auth config hash for the given url.
+        def auth_for_url(url)
+          self.hr_config.get_for_url(url, :auth)
+        end
+
+        ## Sets the auth config hash for this resource class.
+        ## Currently only the format `{:basic => ['username', 'password']}`
+        ## is supported.
+        def auth=(v)
+          cfg_set(:auth, v)
+        end
+
+
+        ## Returns the headers hash for this resource class.
+        def headers
+          cfg_get(:headers)
+        end
+
+        ## Returns the headers hash for the given url.
+        def headers_for_url(url)
+          self.hr_config.get_for_url(url, :headers)
+        end
+
+        ## Sets the headers hash for this resource class.
+        def headers=(v)
+          cfg_set(:headers, v)
+        end
+
+
+        ## Returns the namespace string/class for this resource class.
+        def namespace
+          cfg_get(:namespace)
+        end
+
+        ## Returns the namespace string/class for the given url.
+        def namespace_for_url(url)
+          self.hr_config.get_for_url(url, :namespace)
+        end
+
+        ## Sets the namespace string/class for this resource class.
+        def namespace=(v)
+          cfg_set(:namespace, v)
+        end
+
+
+        ## Returns the adapter class for this resource class.
+        def adapter
+          cfg_get(:adapter) || HyperResource::Adapter::HAL_JSON
+        end
+
+        ## Returns the adapter class for the given url.
+        def adapter_for_url(url)
+          self.hr_config.get_for_url(url, :adapter) ||
+            HyperResource::Adapter::HAL_JSON
+        end
+
+        ## Sets the adapter class for this resource class.
+        def adapter=(v)
+          cfg_set(:adapter, v)
+        end
+
+
+        ## Returns the hash of default attributes for this resource class.
+        def default_attributes
+          cfg_get(:default_attributes)
+        end
+
+        ## Returns the hash of default attributes for the given url.
+        def default_attributes_for_url(url)
+          self.hr_config.get_for_url(url, :default_attributes)
+        end
+
+        ## Sets the hash of default attributes for this resource class.
+        ## These attributes will be passed along with every HTTP request.
+        def default_attributes=(v)
+          cfg_set(:default_attributes, v)
+        end
+
+
+        ## Returns the Faraday connection options hash for this resource class.
+        def faraday_options
+          cfg_get(:faraday_options)
+        end
+
+        ## Returns the Faraday connection options hash for this resource class.
+        def faraday_options_for_url(url)
+          self.hr_config.get_for_url(url, :faraday_options)
+        end
+
+        ## Sets the Faraday connection options hash for this resource class.
+        ## These options will be used for all HTTP requests.
+        def faraday_options=(v)
+          cfg_set(:faraday_options, v)
+        end
+
+
+      private
+
+        def cfg_get(key)
+          value = hr_config.get_for_url(self.root, key)
+          if value != nil
+            value
+          elsif superclass.respond_to?(:hr_config)
+            superclass.hr_config.get_for_url(self.root, key)
+          else
+            nil
+          end
+        end
+
+        def cfg_set(key, value)
+          hr_config.set_for_url(self.root, key, value)
+        end
+
+      end
+
+    end
+  end
+end