prx_hyperresource 1.0.0

data/lib/hyper_resource/configuration.rb

@@ -0,0 +1,194 @@
+require "uri"
+
+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|
+          merged_cfg[mask][attr] = if !%w[namespace adapter].include?(attr) &&
+              (!cfg_attrs[attr] || cfg_attrs[attr].is_a?(Hash)) &&
+              (!new_cfg_attrs[attr] || new_cfg_attrs[attr].is_a?(Hash))
+            (cfg_attrs[attr] || {}).merge(new_cfg_attrs[attr] || {})
+          else
+            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)
+      set(url ? mask_for_url(url) : "*", key, value)
+    end
+
+    ## Returns hostmasks from our config which match the given url, sorted
+    ## best match first.
+    def matching_masks_for_url(url)
+      return ["*"] if cfg.keys.count == 1
+      url_parts = parse_url(url.to_s)
+      scores = {}
+      cfg.keys.each do |mask|
+        score = match_mask(parse_url(mask), url_parts)
+        scores[mask] = score if score
+      end
+      scores.keys.sort_by { |k| [-scores[k], -k.length] }
+    end
+
+    private
+
+    attr_reader :cfg
+
+    ## 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.is_a?(Array) || value.is_a?(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
+
+    ## Adapted from FuzzyURL.url_to_hash in fuzzyurl 0.2.2
+    ## (https://github.com/gamache/fuzzyurl), keeping only protocol, host, and port.
+    URL_PATTERN = %r{\A(?:(\*|[a-z][a-z0-9+.-]*)://)?(?:[^@/]*@)?([a-z0-9.*-]*)(?::(\*|\d+))?}i
+
+    DEFAULT_PORTS = {"http" => "80", "https" => "443"}
+
+    ## Returns the protocol, host, and port of a URL or hostmask.
+    def parse_url(url)
+      m = url.match(URL_PATTERN)
+      {protocol: m[1]&.downcase, host: m[2].downcase, port: m[3]}
+    end
+
+    ## Returns the hostmask for a URL, without path, query, or fragment.
+    def mask_for_url(url)
+      parts = parse_url(url.to_s)
+      mask = parts[:host]
+      mask = "#{parts[:protocol]}://#{mask}" if parts[:protocol]
+      mask = "#{mask}:#{parts[:port]}" if parts[:port]
+      mask
+    end
+
+    ## Returns nil if the mask does not match the url, or a score which is
+    ## higher for more specific matches.
+    def match_mask(mask, url)
+      host_score = match_hosts(mask[:host], url[:host])
+      port_score = match_protocols_and_ports(mask, url)
+      host_score + port_score if host_score && port_score
+    end
+
+    ## Returns nil for no match, 0 for a wildcard match, or 1 for an exact
+    ## match.
+    def match_hosts(mask, host)
+      mask_pieces = mask.split(".").reverse
+      host_pieces = host.split(".").reverse
+      return 1 if !mask.empty? && mask_pieces == host_pieces
+      return nil if mask_pieces.count > host_pieces.count
+      host_pieces.each_with_index do |piece, i|
+        return 0 if mask_pieces[i] == "*"
+        return nil if mask_pieces[i] != piece
+      end
+      0
+    end
+
+    ## Returns nil for no match, or 0-2 for the number of exact matches.
+    ## Protocol defaults to https, and a port matches its protocol's default.
+    def match_protocols_and_ports(mask, url)
+      wildcards = 0
+      protocol = url[:protocol] || "https"
+      if mask[:protocol] && mask[:protocol] != "*"
+        return nil if mask[:protocol] != protocol
+      else
+        wildcards += 1
+      end
+
+      if !mask[:port] || mask[:port] == "*"
+        wildcards += 1
+      elsif !url[:port] && DEFAULT_PORTS[protocol] == mask[:port]
+        wildcards += 1
+      elsif mask[:port] != url[:port]
+        return nil
+      end
+
+      2 - wildcards
+    end
+  end
+end

data/lib/hyper_resource/exceptions.rb

@@ -0,0 +1,41 @@
+class HyperResource
+  class Exception < ::StandardError
+    ## The internal exception which led to this one, if any.
+    attr_accessor :cause
+
+    # @private
+    def initialize(message, attrs = {})
+      self.cause = attrs[:cause]
+      super(message)
+    end
+  end
+
+  class ResponseError < Exception
+    ## The +Faraday::Response+ object which led to this exception.
+    attr_accessor :response
+
+    ## The deserialized response body which led to this exception.
+    ## May be blank, e.g. in case of deserialization errors.
+    attr_accessor :body
+
+    # @private
+    def initialize(message, attrs = {})
+      self.response = attrs[:response]
+      self.body = attrs[:body]
+
+      ## Try to help out with the message
+      if body
+        if (error = body["error"])
+          message = "#{message} (#{error})"
+        end
+      elsif response
+        message = "#{message} (\"#{response.inspect}\")"
+      end
+
+      super
+    end
+  end
+
+  class ClientError < ResponseError; end
+  class ServerError < ResponseError; end
+end

data/lib/hyper_resource/link.rb

@@ -0,0 +1,116 @@
+require "uri_template"
+require "hyper_resource/modules/http"
+
+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.is_a?(Hash)
+        raise ArgumentError, "link_spec must be a Hash (got #{link_spec.inspect})"
+      end
+      link_spec = link_spec.map { |(k, v)| [k.to_s, v] }.to_h ## stringify keys
+
+      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"
+      @headers = link_spec["headers"] || {}
+    end
+
+    ## Returns this link's href, applying any URI template params.
+    def href
+      if templated
+        filtered_params = resource.outgoing_uri_filter(params)
+        URITemplate.new(base_href).expand(filtered_params)
+      else
+        base_href
+      end
+    end
+
+    ## Returns this link's fully resolved URL, or nil if `resource.root`
+    ## or `href` are malformed.
+    def url
+      URI.join(resource.root, href.to_s).to_s
+    rescue
+      nil
+    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 = params.map { |(k, v)| [k.to_s, v] }.to_h
+      self.class.new(resource,
+        "href" => base_href,
+        "name" => name,
+        "templated" => templated,
+        "params" => self.params.merge(params),
+        "method" => default_method,
+        "headers" => @headers)
+    end
+
+    ## When called with a hash, returns a new scope with the given headers;
+    ## that is, returns a copy of itself with the given headers applied.
+    ## These headers will be merged with `resource.headers` at request time.
+    ##
+    ## When called with no arguments, returns the headers for this link.
+    def headers(*args)
+      if args.count == 0
+        @headers
+      else
+        self.class.new(resource,
+          "href" => base_href,
+          "name" => name,
+          "templated" => templated,
+          "params" => params,
+          "method" => default_method,
+          "headers" => @headers.merge(args[0]))
+
+      end
+    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) # standard:disable Style/MissingRespondToMissing
+      send(default_method || :get).send(method, *args)
+    end
+  end
+end

data/lib/hyper_resource/links.rb

@@ -0,0 +1,66 @@
+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
+    # @private
+    def initialize(resource = nil)
+      ## We used to store the resource, but we didn't need to.  Now we don't.
+    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
+
+      ## Underscore all non-word characters.
+      underscored_names = names.map { |n| n.gsub(/[^a-zA-Z_]/, "_") }
+      names = (names + underscored_names).uniq
+
+      ## Register this link under every name we've come up with.
+      names.each do |name|
+        super(name, link)
+      end
+    end
+
+    ## Retrieves a link by its rel.
+    def [](rel)
+      super(rel.to_s)
+    end
+
+    ## Provides links.somelink(:a => b) to links.somelink.where(:a => b)
+    ## expansion.
+    # @private
+    def method_missing(method, *args) # standard:disable Style/MissingRespondToMissing
+      unless self[method]
+        raise NoMethodError, "undefined method `#{method}' for #{inspect}"
+      end
+
+      if args.count > 0
+        self[method].where(*args)
+      else
+        self[method]
+      end
+    end
+
+    # @private
+    def respond_to?(method, *args)
+      return true if has_key?(method.to_s)
+      super
+    end
+  end
+end

data/lib/hyper_resource/modules/config_attributes.rb

@@ -0,0 +1,273 @@
+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)
+        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 = hr_config.matching_masks_for_url(url)
+        matching_masks.inject({}) do |hash, mask|
+          (hr_config.get(mask, "headers") || {}).merge(hash)
+        end
+      end
+
+      ## Returns the headers hash for the given url.
+      def headers_for_url(url)
+        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)
+        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)
+        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)
+        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)
+        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(url, key) ||
+          self.class.hr_config.get_for_url(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)
+          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)
+          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)
+          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)
+          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)
+          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)
+          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(root, key)
+          if !value.nil?
+            value
+          elsif superclass.respond_to?(:hr_config)
+            superclass.hr_config.get_for_url(root, key)
+          end
+        end
+
+        def cfg_set(key, value)
+          hr_config.set_for_url(root, key, value)
+        end
+      end
+    end
+  end
+end