hal-client 3.18.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 822989741d47ce52f9dcc8ff158a16248c8236fc
-  data.tar.gz: 7466b6387ebcd3afeb1ec161854a8f992b0e3552
+  metadata.gz: 8bfaa5d8d4e7d292a1451a99fc57242f11bdea8a
+  data.tar.gz: 5d94cd3f5b0dbfadd72fb69500961bc3ae7de871
 SHA512:
-  metadata.gz: 35cd57faa426d38a11f0a8d0019a9c23349517fdb2c34455e4b2b27eef3e992d2fdafc8519914e9686033d789ba296831a1bb8371e8987555c78301b666fcd2d
-  data.tar.gz: 7884c47f72801c74d420b12f0a2ad10f7b53efe962a66e17d599878df37fd619d8e21c41cf6374b1e12def7ff6a9b9adaee7975fab3a39a7ff31490d58aa255a
+  metadata.gz: 509d532e384249bfc7a2c1be053cf52c71dc04bec2d5328520cdbda229a6e637a0ce094b50f7e4e9e8fcbf064ac661c543be8ea51cd48a93fabe1a48c0322d98
+  data.tar.gz: b2421ace2e732764564dade36b67ebf83459877f3c001bb6afe2032c05c9a6ab290e00669f31b82e79c87d40c93938b658d142d658a8ab74bcf0e7f44190221c

data/.travis.yml

@@ -8,10 +8,9 @@ before_install:
   - gem install bundler
 
 rvm:
-  - 2.0
   - 2.1
-  - 2.2.6
-  - 2.3.2
+  - 2.2
+  - 2.3
   - jruby-9.1.6.0
   - rbx-2.7
 
@@ -20,3 +19,7 @@ gemfile:
   - Gemfile-http-0.8
   - Gemfile-http-0.9
   - Gemfile-http-1.0
+
+matrix:
+  allow_failures:
+  - rvm: rbx-2.7

data/README.md

@@ -173,6 +173,10 @@ Or install it yourself as:
 
     $ gem install hal-client
 
+## Upgrading from 3.x to 4.x
+
+Support for ruby 2.0 has been removed. Please upgrade to ruby 2.1 or later. No other breaking changes were made.
+
 ## Upgrading from 2.x to 3.x
 
 For most uses no change to client code is required. At 3.0 the underlying HTTP library changed to <https://rubygems.org/gems/http> to better support our parallelism needs. This changes the interface of `#get` and `#post` on `HalClient` and `HalClient::Representation` in the situation where the response is not a valid HAL document. In those situations the return value is now a `HTTP::Response` object, rather than a `RestClient::Response`.

data/lib/hal_client/anonymous_resource_locator.rb

@@ -0,0 +1,12 @@
+class HalClient
+  class AnonymousResourceLocator
+    def to_s
+      "ANONYMOUS(#{object_id})"
+    end
+    alias_method :to_str, :to_s
+
+    def anonymous?
+      true
+    end
+  end
+end

data/lib/hal_client/collection.rb

@@ -20,7 +20,6 @@ class HalClient
     # Raises ArgumentError if `first_page` is some page other than 
     #   the first of the collection.
     def initialize(first_page)
-      (fail NotACollectionError) unless first_page.has_related? "item"
       (fail ArgumentError, "Not the first page of the collection") if first_page.has_related? "prev"
 
       @first_page = first_page

data/lib/hal_client/interpreter.rb

@@ -0,0 +1,147 @@
+require 'forwardable'
+require 'addressable/template'
+require 'hal_client/representation'
+require 'hal_client/link'
+require 'hal_client/curie_resolver'
+
+class HalClient
+  # Interprets parsed JSON
+  class Interpreter
+    extend Forwardable
+
+    # Collection of reserved properties
+    # https://tools.ietf.org/html/draft-kelly-json-hal-07#section-4.1
+    RESERVED_PROPERTIES = ['_links', '_embedded'].freeze
+
+    def initialize(parsed_json, hal_client)
+      (fail InvalidRepresentationError,
+            "Invalid HAL representation: #{parsed_json.inspect}") unless
+        hashish?(parsed_json)
+
+      @raw = parsed_json
+      @hal_client = hal_client
+    end
+
+    # Returns hash of properties from `parsed_json`
+    def extract_props()
+      raw.reject{|k,_| RESERVED_PROPERTIES.include?(k) }
+    end
+
+    def extract_links()
+      extract_embedded_links +  extract_basic_links
+    end
+
+    protected
+
+    attr_reader :raw, :hal_client
+
+    def hashish?(obj)
+      obj.respond_to?(:[]) &&
+        obj.respond_to?(:map)
+    end
+
+    def extract_basic_links
+      raw
+        .fetch("_links") { Hash.new }
+        .flat_map { |rel, target_info|
+          build_links(rel, target_info)
+        }
+        .compact
+        .to_set
+    end
+
+    def extract_embedded_links
+      raw
+        .fetch("_embedded") { Hash.new }
+        .flat_map { |rel, embedded_json|
+          build_embedded_links(rel, embedded_json)
+      }
+        .compact
+        .to_set
+    end
+
+    def build_links(rel, target_info)
+      arrayify(target_info)
+        .map { |info|
+          if info["templated"]
+            build_templated_link(rel, info)
+          else
+            build_direct_link(rel, info)
+          end
+        }
+        .compact
+    end
+
+    def build_embedded_links(rel, targets_json)
+      arrayify(targets_json)
+        .map{ |target_json|
+          target_repr = Representation.new(parsed_json: target_json, hal_client: hal_client)
+
+          SimpleLink.new(rel: rel,
+                         target: target_repr,
+                         curie_resolver: curie_resolver)
+        }
+
+    rescue InvalidRepresentationError
+      MalformedLink.new(rel: rel,
+                        msg: "/_embedded/#{jpointer_esc(rel)} is invalid",
+                        curie_resolver: curie_resolver)
+    end
+
+    def build_templated_link(rel, info)
+      fail(InvalidRepresentationError) unless hashish?(info)
+
+      target_pattern = info.fetch("href") { fail InvalidRepresentationError }
+
+      TemplatedLink.new(rel: rel,
+                        template: Addressable::Template.new(target_pattern),
+                        curie_resolver: curie_resolver,
+                        hal_client: hal_client)
+
+    rescue InvalidRepresentationError
+      MalformedLink.new(rel: rel,
+                        msg: "/_links/#{jpointer_esc(rel)} is invalid",
+                        curie_resolver: curie_resolver)
+    end
+
+    def build_direct_link(rel, info)
+      fail InvalidRepresentationError unless hashish?(info)
+
+      target_url = info.fetch("href") { fail InvalidRepresentationError }
+      return nil unless target_url
+
+      target_repr = Representation.new(href: target_url, hal_client: hal_client)
+
+      SimpleLink.new(rel: rel,
+                     target: target_repr,
+                     curie_resolver: curie_resolver)
+
+    rescue InvalidRepresentationError
+      MalformedLink.new(rel: rel,
+                        msg: "/_links/#{jpointer_esc(rel)} is invalid",
+                        curie_resolver: curie_resolver)
+    end
+
+    def curie_resolver
+      @curie_resolver ||= CurieResolver.new(raw.fetch("_links", {}).fetch("curies", []))
+    end
+
+    def hashish?(thing)
+      thing.kind_of?(Hash) ||
+        thing.respond_to?(:fetch) && thing.respond_to?(:key?)
+    end
+
+    def arrayify(obj)
+      if Array === obj
+        obj
+      else
+        [obj]
+      end
+    end
+
+    def jpointer_esc(str)
+      str.gsub "/", "~1"
+    end
+
+  end
+end

data/lib/hal_client/link.rb

@@ -4,144 +4,162 @@ class HalClient
 
   # HAL representation of a single link. Provides access to an embedded representation.
   class Link
+    protected def initialize(rel:, curie_resolver: CurieResolver.new([]), **opts)
+      @literal_rel = rel
+      @curie_resolver = curie_resolver
+
+      post_initialize(opts)
+    end
 
-    # Create a new Link
-    #
-    # options - name parameters
-    #   :rel - This Link's rel property
-    #   :target - An instance of Representation
-    #   :template - A URI template ( https://www.rfc-editor.org/rfc/rfc6570.txt )
-    #   :curie_resolver - An instance of CurieResolver (used to resolve curied rels)
-    def initialize(options)
-      @literal_rel = options[:rel]
-      @target = options[:target]
-      @template = options[:template]
-      @curie_resolver = options[:curie_resolver] || CurieResolver.new([])
-
-      (fail ArgumentError, "A rel must be provided") if @literal_rel.nil?
-
-      if @target.nil? && @template.nil?
-        (fail ArgumentError, "A target or template must be provided")
-      end
-
-      if @target && @template
-        (fail ArgumentError, "Cannot provide both a target and a template")
-      end
-
-      if @target && !@target.kind_of?(Representation)
-        (fail ArgumentError, "Invalid HAL representation: #{target.inspect}")
-      end
-
-      if @template && !@template.kind_of?(Addressable::Template)
-        (fail ArgumentError, "Invalid Addressable::Template: #{template.inspect}")
-      end
-    end
-
-    attr_accessor :literal_rel, :target, :template, :curie_resolver
-
-
-    # Create a new Link using an entry from the '_links' section of a HAL document
-    #
-    # options - name parameters
-    #   :hash_entry - a hash containing keys :rel (string) and :data (hash from a '_links' entry)
-    #   :hal_client - an instance of HalClient
-    #   :curie_resolver - An instance of CurieResolver (used to resolve curied rels)
-    #   :base_url - Base url for resolving relative links in hash_entry (probably the parent
-    # document's "self" link)
-    def self.new_from_link_entry(options)
-      hash_entry = options[:hash_entry]
-      hal_client = options[:hal_client]
-      curie_resolver = options[:curie_resolver]
-      base_url = options[:base_url]
-
-      rel = hash_entry[:rel]
-      hash_data = hash_entry[:data]
-      return nil unless hash_data['href']
-      href = (base_url + hash_data['href']).to_s
-
-      if hash_data['templated']
-        Link.new(rel: rel,
-                 template: Addressable::Template.new(href),
-                 curie_resolver: curie_resolver)
-      else
-        Link.new(rel: rel,
-                 target: Representation.new(hal_client: hal_client, href: href),
-                 curie_resolver: curie_resolver)
-      end
-    end
-
-
-    # Create a new Link using an entry from the '_embedded' section of a HAL document
-    #
-    # options - name parameters
-    #   :hash_entry - a hash containing keys :rel (string) and :data (hash from a '_embedded' entry)
-    #   :hal_client - an instance of HalClient
-    #   :curie_resolver - An instance of CurieResolver (used to resolve curied rels)
-    #   :base_url - Base url for resolving relative links in hash_entry (probably the parent
-    # document's "self" link)
-    def self.new_from_embedded_entry(options)
-      hash_entry = options[:hash_entry]
-      hal_client = options[:hal_client]
-      curie_resolver = options[:curie_resolver]
-      base_url = options[:base_url]
-
-      rel = hash_entry[:rel]
-      hash_data = hash_entry[:data]
-
-      explicit_url = self_href(hash_data)
-      hash_data['_links']['self']['href'] = (base_url + explicit_url).to_s if explicit_url
-
-      Link.new(rel: rel,
-               target: Representation.new(hal_client: hal_client, parsed_json: hash_data),
-               curie_resolver: curie_resolver)
-    end
-
-
-    # Returns the URL of the resource this link references.
-    # In the case of a templated link, this is the unresolved url template pattern.
     def raw_href
-      templated? ? template.pattern : target.href
+      raise NotImplementedError
     end
 
-    def fully_qualified_rel
-      curie_resolver.resolve(literal_rel)
+    def target_url(vars = {})
+      raise NotImplementedError
+    end
+
+    def target(vars = {})
+      raise NotImplementedError
     end
 
-    # Returns true for a templated link, false for an ordinary (non-templated) link
     def templated?
-      !template.nil?
+      raise NotImplementedError
     end
 
-    # Links with the same href, same rel value, and the same 'templated' value are considered equal
-    # Otherwise, they are considered unequal
+    attr_reader :literal_rel, :curie_resolver
+
+    def fully_qualified_rel
+      curie_resolver.resolve(literal_rel)
+    end
+
+    # Links with the same href, same rel value, and the same 'templated' value
+    # are considered equal. Otherwise, they are considered unequal. Links
+    # without a href (for example anonymous embedded links, are never equal to
+    # one another.
     def ==(other)
-      if other.respond_to?(:raw_href) &&
-         other.respond_to?(:fully_qualified_rel) &&
-         other.respond_to?(:templated?)
-        (raw_href == other.raw_href) &&
-          (fully_qualified_rel == other.fully_qualified_rel) &&
-          (templated? == other.templated?)
-      else
-        false
-      end
+      return false if raw_href.nil?
+
+      return false unless other.respond_to?(:raw_href) &&
+                          other.respond_to?(:fully_qualified_rel) &&
+                          other.respond_to?(:templated?)
+
+
+      (raw_href == other.raw_href) &&
+        (fully_qualified_rel == other.fully_qualified_rel) &&
+        (templated? == other.templated?)
     end
     alias :eql? :==
 
-
-    # Differing Representations or Addressable::Templates with matching hrefs will get matching hash
-    # values, since we are using raw_href and not the objects themselves when computing hash
+    # Differing Representations or Addressable::Templates with matching hrefs
+    # will get matching hash values, since we are using raw_href and not the
+    # objects themselves when computing hash
     def hash
-      [fully_qualified_rel, raw_href, templated?].hash
+      [fully_qualified_rel,
+       raw_href,
+       templated?].hash
+    end
+
+    protected
+
+    def post_initialize(opts)
+    end
+
+  end
+
+  # Links that are not templated.
+  class SimpleLink < Link
+
+    protected def post_initialize(target:)
+      fail(ArgumentError) unless target.kind_of?(HalClient::Representation)
+
+      @target = target
+    end
+
+    def raw_href
+      target.href
+    end
+
+    def templated?
+      false
+    end
+
+    def target_url(_vars = {})
+      target.href
     end
 
+    def target(_vars = {})
+      @target
+    end
+
+  end
+
+  # Links that are templated.
+  class TemplatedLink < Link
+
+    protected def post_initialize(template:, hal_client:)
+      fail(ArgumentError) unless template.kind_of? Addressable::Template
+      @tmpl = template
+      @hal_client = hal_client
+    end
+
+    def raw_href
+      tmpl
+    end
+
+    def templated?
+      true
+    end
+
+    def target_url(vars = {})
+      tmpl.expand(vars)
+    end
+
+    def target(vars = {})
+      hal_client.get(target_url(vars))
+    end
+
+    # Differing Representations or Addressable::Templates with matching hrefs
+    # will get matching hash values, since we are using raw_href and not the
+    # objects themselves when computing hash
+    def hash
+      [fully_qualified_rel,
+       tmpl.pattern,
+       templated?].hash
+    end
 
     protected
 
-    def self.self_href(embedded_repr)
-      embedded_repr
-        .fetch('_links', {})
-        .fetch('self', {})
-        .fetch('href', nil)
+    attr_reader :tmpl, :hal_client
+  end
+
+  # A link that was malformed in the JSON. This class is used to delay
+  # presenting interpretation errors so that consumers can ignore malformedness
+  # that does not block their goal. For example, busted links that they will not
+  # use anyway.
+  class MalformedLink < Link
+
+    protected def post_initialize(msg:)
+      @msg = msg
+    end
+
+    def raise_invalid(**)
+      raise InvalidRepresentationError, msg
+    end
+
+    alias_method :raw_href, :raise_invalid
+    alias_method :target_url, :raise_invalid
+    alias_method :target, :raise_invalid
+    alias_method :templated?, :raise_invalid
+
+    def hash
+      fully_qualified_rel.hash
     end
+
+    protected
+
+    attr_reader :msg
   end
+
+
 end

data/lib/hal_client/representation.rb

@@ -3,18 +3,19 @@ require 'addressable/template'
 
 require 'hal_client'
 require 'hal_client/representation_set'
+require 'hal_client/interpreter'
+require 'hal_client/anonymous_resource_locator'
 
 class HalClient
-
   # HAL representation of a single resource. Provides access to
   # properties, links and embedded representations.
+  #
+  # Operations on a representation are not thread-safe.  If you'd like to
+  # use representations in a threaded environment, consider using the method
+  # #clone_for_use_in_different_thread to create a copy for each new thread
   class Representation
     extend Forwardable
 
-    # Collection of reserved properties
-    # https://tools.ietf.org/html/draft-kelly-json-hal-07#section-4.1
-    RESERVED_PROPERTIES = ['_links', '_embedded'].freeze
-
     NO_RELATED_RESOURCE = ->(link_rel) {
       raise KeyError, "No resources are related via `#{link_rel}`"
     }
@@ -37,15 +38,21 @@ class HalClient
     #   :href - The href of this representation.
     #   :hal_client - The HalClient instance to use when navigating.
     def initialize(options)
-      @raw = options[:parsed_json]
       @hal_client = options[:hal_client]
       @href = options[:href]
 
+      interpret options[:parsed_json] if options[:parsed_json]
+
       (fail ArgumentError, "Either parsed_json or href must be provided") if
         @raw.nil? && @href.nil?
+    end
 
-      (fail InvalidRepresentationError, "Invalid HAL representation: #{raw.inspect}") if
-        @raw && ! hashish?(@raw)
+    # Returns a copy of this instance that is safe to use in threaded
+    # environments
+    def clone_for_use_in_different_thread
+      clone.tap do |c|
+        c.hal_client = c.hal_client.clone_for_use_in_different_thread
+      end
     end
 
     # Posts a `Representation` or `String` to this resource. Causes
@@ -86,7 +93,8 @@ class HalClient
     #
     # name - the name of the property to check
     def property?(name)
-      raw.key? name
+      ensure_reified
+      properties.key? name
     end
     alias_method :has_property?, :property?
 
@@ -103,24 +111,24 @@ class HalClient
     # Raises KeyError if the specified property does not exist
     #   and no default nor default_proc is provided.
     def property(name, default=MISSING, &default_proc)
+      ensure_reified
+
       default_proc ||= ->(_){ default} if default != MISSING
 
-      raw.fetch(name.to_s, &default_proc)
+      properties.fetch(name.to_s, &default_proc)
     end
 
     # Returns a Hash including the key-value pairs of all the properties
     #   in the resource. It does not include HAL's reserved
     #   properties (`_links` and `_embedded`).
-    def properties
-      raw.reject { |k, _| RESERVED_PROPERTIES.include? k }
-    end
+    attr_reader :properties
 
     # Returns the URL of the resource this representation represents.
     def href
       @href ||= raw
               .fetch("_links",{})
               .fetch("self",{})
-              .fetch("href",nil)
+              .fetch("href", AnonymousResourceLocator.new)
     end
 
     # Returns the value of the specified property or representations
@@ -159,7 +167,7 @@ class HalClient
     #
     # link_rel - The link rel of interest
     def related?(link_rel)
-      !!(linked(link_rel) { false } || embedded(link_rel) { false })
+      links_by_rel.key?(link_rel)
     end
     alias_method :has_related?, :related?
 
@@ -178,33 +186,13 @@ class HalClient
     def related(link_rel, options = {}, &default_proc)
       default_proc ||= NO_RELATED_RESOURCE
 
-      embedded = embedded(link_rel) { nil }
-      linked = linked(link_rel, options) { nil }
-      return default_proc.call(link_rel) if embedded.nil? and linked.nil?
+      ensure_reified
 
-      RepresentationSet.new (Array(embedded) + Array(linked))
-    end
+      related = links_by_rel
+                .fetch(link_rel) { return default_proc.call(link_rel) }
+                .map { |l| l.target(options) }
 
-    def all_links
-      result = Set.new
-      base_url = Addressable::URI.parse(href || "")
-
-      embedded_entries = flatten_section(raw.fetch("_embedded", {}))
-      result.merge(embedded_entries.map do |entry|
-        Link.new_from_embedded_entry(hash_entry: entry,
-                                     hal_client: hal_client,
-                                     curie_resolver: namespaces,
-                                     base_url: base_url)
-      end)
-
-      link_entries = flatten_section(raw.fetch("_links", {}))
-      result.merge(link_entries.map { |entry|
-        Link.new_from_link_entry(hash_entry: entry,
-                                 hal_client: hal_client,
-                                 curie_resolver: namespaces,
-                                 base_url: base_url) })
-
-      result
+      RepresentationSet.new(related)
     end
 
     # Returns urls of resources related via the specified
@@ -241,11 +229,11 @@ class HalClient
     def raw_related_hrefs(link_rel, &default_proc)
       default_proc ||= NO_RELATED_RESOURCE
 
-      embedded = embedded(link_rel) { nil }
-      linked = links.hrefs(link_rel) { nil }
-      return default_proc.call(link_rel) if embedded.nil? and linked.nil?
+      ensure_reified
 
-      Array(linked) + Array(embedded).map(&:href)
+      links_by_rel
+        .fetch(link_rel) { return default_proc.call(link_rel) }
+        .map { |l| l.raw_href }
     end
 
     # Returns an Enumerable of the items in this collection resource
@@ -266,6 +254,16 @@ class HalClient
       as_enum.to_enum(method, *args, &blk)
     end
 
+    # Returns set of all links in this representation.
+    def all_links
+      links_by_rel
+        .reduce(Set.new) { |result, kv|
+          _,links = *kv
+          links.each { |l| result << l }
+          result
+        }
+    end
+
     # Resets this representation such that it will be requested from
     # the upstream on it's next use.
     def reset
@@ -276,7 +274,7 @@ class HalClient
     # Returns a short human readable description of this
     # representation.
     def to_s
-      "#<" + self.class.name + ": " + (href || "ANONYMOUS")  + ">"
+      "#<" + self.class.name + ": " + href.to_s  + ">"
     end
 
     # Returns the raw json representation of this representation
@@ -304,109 +302,56 @@ class HalClient
     end
     alias :eql? :==
 
-    # Internal: Returns parsed json document
+    # Returns raw parsed json.
     def raw
-      if @raw.nil? && @href
-        (fail "unable to make requests due to missing hal client") unless hal_client
-
-        response = hal_client.get(@href)
-
-        unless response.is_a?(Representation)
-          error_message = "Response body wasn't a valid HAL document:\n\n"
-          error_message += response.body
-          raise InvalidRepresentationError.new(error_message)
-        end
-
-        @raw ||= response.raw
-      end
+      ensure_reified
 
       @raw
     end
 
-    # Internal: Returns the HalClient used to retrieve this
-    # representation
+    # Return the HalClient used to retrieve this representation
     attr_reader :hal_client
 
     protected
 
-    MISSING = Object.new
+    attr_reader :links_by_rel
+    attr_writer :hal_client
 
-    def flatten_section(section_hash)
-      section_hash
-        .each_pair
-        .flat_map { |rel, some_link_info|
-          [some_link_info].flatten
-          .map { |a_link_info| { rel: rel, data: a_link_info } }
-      }
-    end
-
-    def links
-      @links ||= LinksSection.new((raw.fetch("_links"){{}}),
-                                  base_url: Addressable::URI.parse(href || ""))
-    end
-
-    def embedded_section
-      embedded = raw.fetch("_embedded", {})
-
-      @embedded_section ||= embedded.merge fully_qualified(embedded)
-    end
-
-    def embedded(link_rel, &default_proc)
-      default_proc ||= NO_EMBED_FOUND
-
-      relations = embedded_section.fetch(link_rel) { MISSING }
-      return default_proc.call(link_rel) if relations == MISSING
-
-      (boxed relations).map{|it| Representation.new hal_client: hal_client, parsed_json: it}
-
-    rescue InvalidRepresentationError
-      fail InvalidRepresentationError, "/_embedded/#{jpointer_esc(link_rel)} is not a valid representation"
-    end
+    MISSING = Object.new
 
-    def linked(link_rel, options = {}, &default_proc)
-      default_proc ||= NO_LINK_FOUND
+    # Fetch the representation from origin server if that has not already
+    # happened.
+    def ensure_reified
+      return if @raw
+      (fail "unable to make requests due to missing hal client") unless hal_client
+      (fail "unable to make requests due to missing href") unless @href
 
-      relations = links.hrefs(link_rel) { MISSING }
-      return default_proc.call(link_rel, options) if relations == MISSING || relations.compact.empty?
+      response = hal_client.get(@href)
 
-      relations
-        .map {|url_or_tmpl|
-          if url_or_tmpl.respond_to? :expand
-            url_or_tmpl.expand(options).to_s
-          else
-            url_or_tmpl
-          end }
-        .map {|href| Representation.new href: href, hal_client: hal_client }
+      unless response.is_a?(Representation)
+        error_message = "Response body wasn't a valid HAL document:\n\n"
+        error_message += response.body
+        raise InvalidRepresentationError.new(error_message)
+      end
 
-    rescue InvalidRepresentationError
-      fail InvalidRepresentationError, "/_links/#{jpointer_esc(link_rel)} is not a valid link"
+      interpret response.raw
     end
 
-    def jpointer_esc(str)
-      str.gsub "/", "~1"
-    end
+    def interpret(parsed_json)
+      @raw = parsed_json
 
-    def boxed(list_hash_or_nil)
-      if hashish? list_hash_or_nil
-        [list_hash_or_nil]
-      elsif list_hash_or_nil.respond_to? :map
-        list_hash_or_nil
-      else
-        # The only valid values for a link/embedded set are hashes or
-        # array-ish things.
+      interpreter = HalClient::Interpreter.new(parsed_json, hal_client)
 
-        fail InvalidRepresentationError
-      end
-    end
-
-    def fully_qualified(relations_section)
-      Hash[relations_section.map {|rel, link_info|
-        [(namespaces.resolve rel), link_info]
-      }]
-    end
+      @properties = interpreter.extract_props
 
-    def hashish?(thing)
-      thing.respond_to?(:fetch) && thing.respond_to?(:key?)
+      @links_by_rel =
+        interpreter
+        .extract_links
+        .reduce(Hash.new { |h,k| h[k] = Set.new }) { |links_tab, link|
+          links_tab[link.literal_rel] << link
+          links_tab[link.fully_qualified_rel] << link
+          links_tab
+        }
     end
 
     def_delegators :links, :namespaces

data/lib/hal_client/representation_editor.rb

@@ -35,11 +35,17 @@ class HalClient
 
     # Returns true if this, or any previous, editor actually changed the hal
     # representation.
+    #
+    # ---
+    #
+    # Anonymous entries are hard to deal with in a logically clean way. We fudge
+    # it a bit by treating anonymous resources with the same raw value as equal.
     def dirty?
       new_repr = Representation.new(parsed_json: raw)
 
       orig_repr.properties != new_repr.properties ||
-        orig_repr.all_links != new_repr.all_links
+        sans_anon(orig_repr.all_links) != sans_anon(new_repr.all_links) ||
+        raw_anons(orig_repr.all_links) != raw_anons(new_repr.all_links)
     end
 
     # Returns the raw json representation of this representation
@@ -140,6 +146,18 @@ class HalClient
 
     attr_reader :orig_repr
 
+    def sans_anon(links)
+      links.reject { |l| AnonymousResourceLocator === l.raw_href}
+        .to_set
+    end
+
+    def raw_anons(links)
+      links
+        .select { |l| AnonymousResourceLocator === l.raw_href}
+        .map!{ |l| l.target.raw }
+        .to_set
+    end
+
     def Array(thing)
       if Hash === thing
         [thing]

data/lib/hal_client/version.rb

@@ -1,3 +1,3 @@
 class HalClient
-  VERSION = "3.18.0"
+  VERSION = "4.1.0"
 end

data/lib/hal_client.rb

@@ -4,6 +4,11 @@ require 'multi_json'
 require 'benchmark'
 
 # Adapter used to access resources.
+#
+# Operations on a HalClient instance are not thread-safe.  If you'd like to
+# use a HalClient instance in a threaded environment, consider using the
+# method #clone_for_use_in_different_thread to create a copy for each new
+# thread
 class HalClient
   autoload :Representation, 'hal_client/representation'
   autoload :RepresentationSet, 'hal_client/representation_set'
@@ -76,6 +81,11 @@ class HalClient
   end
   protected :initialize
 
+  # Returns a copy of this instance that is safe to use in threaded environments
+  def clone_for_use_in_different_thread
+    clone.tap { |c| c.clear_clients! }
+  end
+
   # Returns a `Representation` of the resource identified by `url`.
   #
   # url - The URL of the resource of interest.
@@ -229,6 +239,12 @@ class HalClient
     base_client_with_headers(headers)
   end
 
+  # Resets memoized HTTP clients
+  def clear_clients!
+    @base_client = nil
+    @base_client_with_headers = {}
+  end
+
   # Returns an HTTP client.
   def base_client
     @base_client ||= begin

data/spec/hal_client/collection_spec.rb

@@ -37,17 +37,11 @@ RSpec.describe HalClient::Collection do
         .not_to raise_error
     end
 
-    specify do
-      expect { described_class.new(non_collection_repr) }
-        .to raise_error HalClient::NotACollectionError
-    end
-
     specify do
       expect { described_class.new(non_first_page) }
         .to raise_error ArgumentError, /first page/
     end
 
-    let(:non_collection_repr) { repr({}) }
     let(:non_first_page) { collection_page(prev_href: "http://example.com/p1") }
   end
 

data/spec/hal_client/interpreter_spec.rb

@@ -0,0 +1,117 @@
+require 'hal_client/interpreter'
+
+RSpec.describe HalClient::Interpreter do
+  let(:hal_client) { HalClient.new }
+
+  describe ".new" do
+    specify { expect(described_class.new({}, hal_client)).to be_kind_of described_class }
+  end
+
+
+  describe "#extract_props" do
+    subject { described_class.new(parsed_json, hal_client) }
+    let(:parsed_json) { {"num" => 1,
+                         "_links" => {},
+                         "_embedded" => {}
+                        } }
+
+    specify { expect(subject.extract_props).to be_kind_of Hash }
+    specify { expect(subject.extract_props).to include("num") }
+    specify { expect(subject.extract_props).not_to include("_links") }
+    specify { expect(subject.extract_props).not_to include("_embedded") }
+  end
+
+
+  describe "#extract_links" do
+    subject { described_class.new({}, hal_client) }
+
+    specify { expect(subject.extract_links).to be_kind_of Enumerable }
+
+    context "with out links" do
+      subject { described_class.new({}, hal_client) }
+
+      specify { expect(subject.extract_links).to be_empty }
+    end
+
+    context "with links" do
+      subject { described_class.new(links_json, hal_client) }
+      let(:links_json) { {"_links" => {
+                            "foo" => { "href" => "http://example.com/foo" },
+                            "bar" => [ { "href" => "http://example.com/bar1" },
+                                       { "href" => "http://example.com/bar2" } ],
+                            "tmpl" =>  { "href" => "http://example.com/foo{?q}",
+                                         "templated" => true},
+                            "mixed" => [ { "href" => "http://example.com/foo" },
+                                         { "href" => "http://example.com/foo{?q}",
+                                           "templated" => true } ]
+                          } } }
+
+      specify { expect(subject.extract_links).not_to be_empty }
+      specify { expect(subject.extract_links)
+                .to include link_matching("foo", "http://example.com/foo") }
+      specify { expect(subject.extract_links)
+                .to include link_matching("bar", "http://example.com/bar1") }
+      specify { expect(subject.extract_links)
+                .to include link_matching("bar", "http://example.com/bar2") }
+      specify { expect(subject.extract_links)
+                .to include link_matching("mixed", "http://example.com/foo") }
+
+      specify { expect(subject.extract_links)
+                .to include templated_link_matching("tmpl", "http://example.com/foo{?q}") }
+      specify { expect(subject.extract_links)
+                .to include templated_link_matching("mixed", "http://example.com/foo{?q}") }
+    end
+
+    context "with embedded" do
+      subject { described_class.new(embedded_json, hal_client) }
+      let(:embedded_json) { {"_links" => {
+                               "foo" => { "href" => "http://example.com/foo" }
+                             },
+                             "_embedded" => {
+                               "bar" => { "_links" => { "self" => { "href" => "http://example.com/bar" } } },
+                               "baz" => [ { "_links" => { "self" => { "href" => "http://example.com/baz1" } } },
+                                          { "_links" => { "self" => { "href" => "http://example.com/baz2" } } } ]
+                             }
+                            } }
+
+      specify { expect(subject.extract_links).not_to be_empty }
+      specify { expect(subject.extract_links).to include link_matching("foo", "http://example.com/foo") }
+      specify { expect(subject.extract_links).to include link_matching("bar", "http://example.com/bar") }
+      specify { expect(subject.extract_links).to include link_matching("baz", "http://example.com/baz1") }
+      specify { expect(subject.extract_links).to include link_matching("baz", "http://example.com/baz2") }
+    end
+
+    context "curies" do
+      let(:raw_repr) { <<-HAL }
+{ "_links": {
+    "self": { "href": "http://example.com/foo" }
+    ,"ex:bar": { "href": "http://example.com/bar" }
+    ,"curies": [{"name": "ex", "href": "http://example.com/rels/{rel}", "templated": true}]
+  }
+}
+HAL
+
+      subject { described_class.new(MultiJson.load(raw_repr), hal_client) }
+
+      specify { expect(subject.extract_links).to include link_matching("ex:bar", "http://example.com/bar") }
+      specify { expect(subject.extract_links).to include link_matching("http://example.com/rels/bar", "http://example.com/bar") }
+
+    end
+  end
+
+  matcher :link_matching do |rel, target_url|
+    match { |actual_link|
+      (actual_link.literal_rel == rel || actual_link.fully_qualified_rel == rel) &&
+            actual_link.target_url == target_url
+    }
+  end
+
+  matcher :templated_link_matching do |rel, target_url|
+    match { |actual_link|
+      (actual_link.literal_rel == rel || actual_link.fully_qualified_rel == rel) &&
+        actual_link.raw_href == Addressable::Template.new(target_url) &&
+        actual_link.templated?
+    }
+  end
+
+end

data/spec/hal_client/link_spec.rb

@@ -4,89 +4,37 @@ require "hal_client/link"
 
 RSpec.describe HalClient::Link do
 
-  subject(:link) { described_class.new(rel: rel_1, target: repr_1) }
+  subject(:link) { HalClient::SimpleLink.new(rel: rel_1, target: repr_1) }
 
   describe "#initialize" do
     it "requires a target" do
-      expect { HalClient::Link.new(rel: rel_1) }.to raise_error(ArgumentError)
+      expect { HalClient::SimpleLink.new(rel: rel_1) }.to raise_error(ArgumentError)
     end
 
     it "doesn't allow both target and template" do
       expect {
-        HalClient::Link.new(rel: rel_1, target: repr_1, template: template_1)
+        HalClient::SimpleLink.new(rel: rel_1, target: repr_1, template: template_1)
       }.to raise_error(ArgumentError)
     end
 
     it "requires target to be a Representation" do
       expect {
-        HalClient::Link.new(rel: rel_1, target: template_1)
+        HalClient::SimpleLink.new(rel: rel_1, target: template_1)
       }.to raise_error(ArgumentError)
     end
 
     it "requires template to be an Addressable::Template" do
       expect {
-        HalClient::Link.new(rel: rel_1, template: repr_1)
+        HalClient::TemplatedLink.new(rel: rel_1, template: repr_1)
       }.to raise_error(ArgumentError)
     end
   end
 
-  describe ".new_from_link_entry" do
-    it "creates an instance of Link" do
-      my_link = described_class.new_from_link_entry(hash_entry: link_entry_hash(href: href_1),
-                                                    hal_client: a_client,
-                                                    curie_resolver: curie_resolver,
-                                                    base_url: href_1)
-      expect(my_link).to be_a(HalClient::Link)
-    end
-
-    it "handles relative hrefs" do
-      input_hash = link_entry_hash(href: relative_href_1)
-      base_url = Addressable::URI.parse(href_1)
-
-      my_link = described_class.new_from_link_entry(hash_entry: input_hash,
-                                                    hal_client: a_client,
-                                                    curie_resolver: curie_resolver,
-                                                    base_url: base_url)
-      expect(my_link.raw_href).to eq((base_url + relative_href_1).to_s)
-    end
-
-    it "handles hrefs with a nil value" do
-      input_hash = link_entry_hash(href: nil)
-      base_url = Addressable::URI.parse(href_1)
-
-      my_link = described_class.new_from_link_entry(hash_entry: input_hash,
-                                                    hal_client: a_client,
-                                                    curie_resolver: curie_resolver,
-                                                    base_url: base_url)
-
-      expect(my_link.raw_href).to eq(base_url.to_s)
-    end
-  end
-
-  describe ".new_from_embedded_entry" do
-    it "creates an instance of Link" do
-      my_link = described_class.new_from_embedded_entry(hash_entry: embedded_entry_hash,
-                                                        hal_client: a_client,
-                                                        curie_resolver: curie_resolver,
-                                                        base_url: href_1)
-      expect(my_link).to be_a(HalClient::Link)
-    end
-
-    it "handles relative hrefs" do
-      input_hash = embedded_entry_hash(href: relative_href_1)
-      base_url = Addressable::URI.parse(href_1)
-
-      my_link = described_class.new_from_embedded_entry(hash_entry: input_hash,
-                                                        hal_client: a_client,
-                                                        curie_resolver: curie_resolver,
-                                                        base_url: base_url)
-      expect(my_link.raw_href).to eq((base_url + relative_href_1).to_s)
-    end
-  end
 
   describe "#href" do
     specify { expect(link.raw_href).to eq('http://example.com/href_1') }
-    specify { expect(templated_link1.raw_href).to eq('http://example.com/people{?name}') }
+    specify { expect(templated_link1.raw_href)
+              .to eq Addressable::Template.new('http://example.com/people{?name}') }
   end
 
   describe "#templated?" do
@@ -95,27 +43,33 @@ RSpec.describe HalClient::Link do
   end
 
   context "equality and hash" do
-    let(:link_same_target_same_rel) { HalClient::Link.new(target: repr_1, rel: rel_1) }
+    let(:link_same_target_same_rel) { HalClient::SimpleLink.new(target: repr_1, rel: rel_1) }
 
-    let(:link_same_target_diff_rel) { HalClient::Link.new(target: repr_1, rel: rel_2) }
-    let(:link_diff_target_same_rel) { HalClient::Link.new(target: repr_2, rel: rel_1) }
-    let(:link_diff_target_diff_rel) { HalClient::Link.new(target: repr_2, rel: rel_2) }
+    let(:link_same_target_diff_rel) { HalClient::SimpleLink.new(target: repr_1, rel: rel_2) }
+    let(:link_diff_target_same_rel) { HalClient::SimpleLink.new(target: repr_2, rel: rel_1) }
+    let(:link_diff_target_diff_rel) { HalClient::SimpleLink.new(target: repr_2, rel: rel_2) }
 
-    let(:link_same_non_fetched) { HalClient::Link.new(target: href_only_repr, rel: rel_1) }
+    let(:link_same_non_fetched) { HalClient::SimpleLink.new(target: href_only_repr, rel: rel_1) }
 
     let(:same_as_templated_link1) do
-      HalClient::Link.new(rel: 'templated_link',
-                          template: Addressable::Template.new('http://example.com/people{?name}'))
+      HalClient::TemplatedLink
+        .new(rel: 'templated_link',
+             template: Addressable::Template.new('http://example.com/people{?name}'),
+             hal_client: a_client)
     end
 
     let(:templated_link2) do
-      HalClient::Link.new(rel: 'templated_link',
-                          template: Addressable::Template.new('http://example.com/places{?name}'))
+      HalClient::TemplatedLink
+        .new(rel: 'templated_link',
+             template: Addressable::Template.new('http://example.com/places{?name}'),
+             hal_client: a_client)
     end
 
     let(:template_but_not_a_template) do
-      HalClient::Link.new(rel: 'rel_1',
-                          template: Addressable::Template.new('http://example.com/href_1'))
+      HalClient::TemplatedLink
+        .new(rel: 'rel_1',
+             template: Addressable::Template.new('http://example.com/href_1'),
+             hal_client: a_client)
     end
 
     describe "#==" do
@@ -181,7 +135,7 @@ RSpec.describe HalClient::Link do
   let(:rel_2) { 'rel_2' }
 
   let(:full_uri_rel_1) { 'http://example.com/rels/rel_1' }
-  let(:full_uri_link_1) { HalClient::Link.new(rel: full_uri_rel_1, target: repr_1) }
+  let(:full_uri_link_1) { HalClient::SimpleLink.new(rel: full_uri_rel_1, target: repr_1) }
 
   let(:curie_resolver) do
     HalClient::CurieResolver.new({
@@ -194,7 +148,7 @@ RSpec.describe HalClient::Link do
   let(:curied_rel_1) { 'ex:rel_1' }
 
   let(:curied_link_1) do
-    HalClient::Link.new(rel: curied_rel_1, target: repr_1, curie_resolver: curie_resolver)
+    HalClient::SimpleLink.new(rel: curied_rel_1, target: repr_1, curie_resolver: curie_resolver)
   end
 
   let(:href_1) { 'http://example.com/href_1' }
@@ -281,6 +235,7 @@ RSpec.describe HalClient::Link do
 
   let(:template_1) { Addressable::Template.new('http://example.com/people{?name}') }
 
-  let(:templated_link1) { HalClient::Link.new(rel: 'templated_link', template: template_1) }
+  let(:templated_link1) { HalClient::TemplatedLink.new(rel: 'templated_link', template: template_1, hal_client: a_client) }
 
+  let(:a_client) { HalClient.new }
 end

data/spec/hal_client/representation_spec.rb

@@ -107,13 +107,15 @@ HAL
   describe "#to_s" do
     subject(:return_val) { repr.to_s }
 
-    it { is_expected.to eq "#<HalClient::Representation: http://example.com/foo>" }
+    it { is_expected.to match %{#<HalClient::Representation:} }
+    it { is_expected.to match %r{http://example.com/foo} }
 
     context "anonymous" do
       let(:repr) {  described_class.new(hal_client: a_client,
                                         parsed_json: MultiJson.load("{}")) }
 
-      it { is_expected.to eq "#<HalClient::Representation: ANONYMOUS>" }
+      it { is_expected.to match %{#<HalClient::Representation:} }
+      it { is_expected.to match /ANONYMOUS/i }
     end
   end
 
@@ -152,7 +154,7 @@ HAL
 
     describe "hash" do
       specify{ expect(repr.hash).to eq repr.href.hash }
-      specify{ expect(repr_no_href.hash).to eq repr_no_href.raw.hash }
+      specify{ expect(repr_no_href.hash).not_to eq repr_no_href.raw.hash }
     end
   end
 
@@ -279,7 +281,10 @@ HAL
     specify { expect(subject).to include(link3a_link) }
     specify { expect(subject).to include(link3b_link) }
 
-    specify { expect(subject.any? { |item| item.target['dupProperty'] == 'foo' }).to be true }
+    specify { expect(subject
+                      .find { |l| l.literal_rel == "dup" }
+                      .target['dupProperty'])
+              .to eq "foo" }
   end
 
   specify { expect(repr.related_hrefs "link1")
@@ -408,11 +413,6 @@ HAL
     specify { expect( repr.to_enum ).to have(2).items }
   end
 
-  context "non-collection" do
-    specify { expect{repr.as_enum}.to raise_error(HalClient::NotACollectionError) }
-    specify { expect{repr.to_enum}.to raise_error(HalClient::NotACollectionError) }
-  end
-
   # Background
 
   let(:link1_repr) do
@@ -429,24 +429,25 @@ HAL
 
 
   let(:link1_link) do
-    HalClient::Link.new(rel: 'link1', target: link1_repr)
+    HalClient::SimpleLink.new(rel: 'link1', target: link1_repr)
   end
 
   let(:link2_link) do
-    HalClient::Link.new(rel: 'link2', target: link1_repr)
+    HalClient::SimpleLink.new(rel: 'link2', target: link1_repr)
   end
 
   let(:templated_link) do
-    HalClient::Link.new(rel: 'templated',
-                        template: Addressable::Template.new('http://example.com/people{?name}'))
+    HalClient::TemplatedLink.new(rel: 'templated',
+                                 template: Addressable::Template.new('http://example.com/people{?name}'),
+                                 hal_client: a_client)
   end
 
   let(:link3a_link) do
-    HalClient::Link.new(rel: 'link3', target: link3a_repr)
+    HalClient::SimpleLink.new(rel: 'link3', target: link3a_repr)
   end
 
   let(:link3b_link) do
-    HalClient::Link.new(rel: 'link3', target: link3b_repr)
+    HalClient::SimpleLink.new(rel: 'link3', target: link3b_repr)
   end
 
 

data/spec/spec_helper.rb

@@ -39,7 +39,7 @@ RSpec.configure do |config|
 
   # This setting enables warnings. It's recommended, but in some cases may
   # be too noisy due to issues in dependencies.
-  config.warnings = true
+  config.warnings = false
 
   # Many RSpec users commonly either run the entire suite or an individual
   # file, and it's useful to allow more verbose output when running an

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hal-client
 version: !ruby/object:Gem::Version
-  version: 3.18.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Peter Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-11-22 00:00:00.000000000 Z
+date: 2017-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -168,9 +168,11 @@ files:
 - hal-client.gemspec
 - lib/hal-client.rb
 - lib/hal_client.rb
+- lib/hal_client/anonymous_resource_locator.rb
 - lib/hal_client/collection.rb
 - lib/hal_client/curie_resolver.rb
 - lib/hal_client/errors.rb
+- lib/hal_client/interpreter.rb
 - lib/hal_client/link.rb
 - lib/hal_client/links_section.rb
 - lib/hal_client/representation.rb
@@ -179,6 +181,7 @@ files:
 - lib/hal_client/version.rb
 - spec/hal_client/collection_spec.rb
 - spec/hal_client/curie_resolver_spec.rb
+- spec/hal_client/interpreter_spec.rb
 - spec/hal_client/link_spec.rb
 - spec/hal_client/links_section_spec.rb
 - spec/hal_client/representation_editor_spec.rb
@@ -214,6 +217,7 @@ summary: Use HAL APIs easily
 test_files:
 - spec/hal_client/collection_spec.rb
 - spec/hal_client/curie_resolver_spec.rb
+- spec/hal_client/interpreter_spec.rb
 - spec/hal_client/link_spec.rb
 - spec/hal_client/links_section_spec.rb
 - spec/hal_client/representation_editor_spec.rb