excon-hypermedia 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 912319706191a6c2866f3c5e8a7f9d6c16631149
-  data.tar.gz: 5309fb839091943003bb4dfe9be37c908fc0410d
+  metadata.gz: 6bc648cfd5761dfb1236aada3be47b061620a3ad
+  data.tar.gz: f0fc534b110a5de92cbe548a4dbe5eb4bcb6f5e6
 SHA512:
-  metadata.gz: 0d196a5a238fba1fcfae2ed1cf3287c2f5b42f1ee9bd837c5e4b93c13407a511b2566cc1bcec76524752121ef464427737cdad05c69d2dbdc76292e36fb924b5
-  data.tar.gz: b6f03792762adcc3e2d41af35bbdb8f6a2c21afbe3c09f72df20f7cc8ae29285777a726f0cca10dbdf373f73ebdcaf3824c342ad57f4489fe232d2c5f5289fa7
+  metadata.gz: 83c3ec47d43ce609a789f2bf0ae0281822ae0b4ba25b00596516ef7ed54e9ecc8ab4f3e834e642172b4a1560da4c8184aa4f6a6ac611f63dc84f22e19b4ee226
+  data.tar.gz: 74fb5d0362acce99b511533c487d18612c81f0c8b455d62633c6fd52e74eb8a262429e6873913e5a5f60e5efae9fdda15132c1602b38a3597e02e0573bf929ea

data/.wercker.yml

@@ -1,5 +1,29 @@
-box: ruby:2.3
-build:
+ruby-latest:
+  box: ruby:latest
+  steps:
+  - bundle-install
+  - script:
+    name: tests
+    code: bundle exec rake
+
+ruby-23:
+  box: ruby:2.3
+  steps:
+  - bundle-install
+  - script:
+    name: tests
+    code: bundle exec rake
+
+ruby-22:
+  box: ruby:2.2
+  steps:
+  - bundle-install
+  - script:
+    name: tests
+    code: bundle exec rake
+
+ruby-21:
+  box: ruby:2.1
   steps:
   - bundle-install
   - script:

data/README.md

@@ -10,6 +10,8 @@ Teaches [Excon][] how to talk to [HyperMedia APIs][hypermedia].
   * [relations](#relations)
   * [properties](#properties)
   * [embedded](#embedded)
+  * [Hypertext Cache Pattern](#hypertext-cache-pattern)
+  * [shortcuts](#shortcuts)
 * [License](#license)
 
 ## Installation
@@ -254,8 +256,51 @@ For more information on this concept, see the [formal specification][_embedded].
 Embedded resources work the same as the top-level resource:
 
 ```ruby
-product._embedded.pump.class # => Excon::HyperMedia::ResourceObject
-product._embedded.pump.weight # => '2kg'
+product.resource._embedded.pump.class # => Excon::HyperMedia::ResourceObject
+product.resource._embedded.pump.weight # => '2kg'
+```
+
+### Hypertext Cache Pattern
+
+You can leverage embedded resources to dynamically reduce the number of requests
+you have to make to get the desired results, improving the efficiency and
+performance of the application. This technique is called
+"[Hypertext Cache Pattern][hcp]".
+
+When you enable `hcp`, the library detects if a requested resource is already
+embedded, and will use that resource as a mocked response, eliminating any extra
+request to get the resource:
+
+```ruby
+pump = product.rel('pump', hcp: true).get
+
+pump[:hcp] # => true
+pump.remote_ip # => '127.0.0.1'
+pump.resource.weight # => '2kg'
+```
+
+This feature only works if you are sure the embedded resource is equal to the
+resource returned by the link relation. Because of this requirement, the default
+configuration has `hcp` disabled, you can either enable it per request (which
+also enables it for future requests in the chain), or enable it globally:
+
+```ruby
+Excon.defaults[:hcp] = true
+```
+
+### shortcuts
+
+While the above examples shows the clean separation between the different
+concepts like `response`, `resource`, `links`, `properties` and `emeds`.
+
+Traversing these objects always starts from the response object. To make moving
+around a bit faster, there are several methods available on the
+`Excon::Response` object for ease-of-use:
+
+```ruby
+product.links.class # => Excon::HyperMedia::ResourceObject::Links
+product.properties.class # => Excon::HyperMedia::ResourceObject::Properties
+product.embedded.class # => Excon::HyperMedia::ResourceObject::Embedded
 ```
 
 ## License
@@ -267,3 +312,4 @@ The gem is available as open source under the terms of the [MIT License](http://
 [excon-addressable]: https://github.com/JeanMertz/excon-addressable
 [options]: https://github.com/excon/excon#options
 [_embedded]: https://tools.ietf.org/html/draft-kelly-json-hal-08#section-4.1.2
+[hcp]: https://tools.ietf.org/html/draft-kelly-json-hal-06#section-8.3

data/excon-hypermedia.gemspec

@@ -17,13 +17,14 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0")
   spec.require_paths = %w(lib)
 
-  spec.add_development_dependency 'bundler', '~> 1.12'
+  spec.add_development_dependency 'bundler', '~> 1.9'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'rubocop', '~> 0.40'
   spec.add_development_dependency 'pry', '~> 0.10'
   spec.add_development_dependency 'm', '~> 1.5'
 
+  spec.add_dependency 'backport_dig' if RUBY_VERSION < '2.3'
   spec.add_dependency 'excon', '~> 0.49'
   spec.add_dependency 'excon-addressable', '~> 0.3'
 end

data/lib/excon/hypermedia/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# :no-doc:
+module Excon
+  module HyperMedia
+    class Error < StandardError; end
+
+    UnknownRelationError = Class.new(Error)
+  end
+end

data/lib/excon/hypermedia/helpers/collection.rb

@@ -12,7 +12,7 @@ module Excon
       include Enumerable
 
       def initialize(collection = {})
-        @collection ||= collection
+        @collection ||= collection.to_h
         to_properties
       end
 
@@ -34,6 +34,21 @@ module Excon
 
       private
 
+      # method_missing
+      #
+      # Collections can be accessed using both the "dot notation" and the hash
+      # notation:
+      #
+      #   collection.hello_world
+      #   collection['hello_world']
+      #
+      # The second notation returns `nil` on missing keys, the first should do
+      # as well.
+      #
+      def method_missing(_)
+        nil
+      end
+
       def to_properties
         collection.each do |key, value|
           key = key.downcase

data/lib/excon/hypermedia/middleware.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'backport_dig' if RUBY_VERSION < '2.3'
+
 Excon.defaults[:middlewares].delete(Excon::Addressable::Middleware)
 Excon.defaults[:middlewares].unshift(Excon::Addressable::Middleware)
 
@@ -14,6 +16,12 @@ module Excon
     # will be left alone by this middleware.
     #
     class Middleware < Excon::Middleware::Base
+      def request_call(datum)
+        orig_stack = @stack
+        @stack = Excon::HyperMedia::Middlewares::HypertextCachePattern.new(orig_stack)
+        super
+      end
+
       def response_call(datum)
         return super unless (content_type = datum.dig(:response, :headers, 'Content-Type').to_s)
 

data/lib/excon/hypermedia/middlewares/hypertext_cache_pattern.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Excon
+  module HyperMedia
+    module Middlewares
+      # HypertextCachePattern
+      #
+      # This middleware handles hcp-enabled requests.
+      #
+      # @see: https://tools.ietf.org/html/draft-kelly-json-hal-06#section-8.3
+      #
+      class HypertextCachePattern < Excon::Middleware::Base
+        attr_reader :datum
+
+        def request_call(datum)
+          @datum = datum
+
+          return super unless datum[:hcp] == true && datum[:method] == :get && find_embedded
+
+          datum[:response] = {
+            body:      @embedded.to_json,
+            hcp:       true,
+            headers:   content_type_header,
+            remote_ip: '127.0.0.1',
+            status:    200
+          }
+
+          super
+        end
+
+        private
+
+        def find_embedded
+          datum.dig(:hcp_params, :embedded).to_h.each do |_, object|
+            break if (@embedded = object_to_embedded(object))
+          end
+
+          @embedded
+        end
+
+        def object_to_embedded(object)
+          uri = ::Addressable::URI.new(datum.tap { |h| h.delete(:port) })
+
+          if object.respond_to?(:to_ary)
+            object.find { |hash| hash.dig('_links', 'self', 'href') == uri.to_s }
+          elsif object.dig('_links', 'self', 'href') == uri.to_s
+            object
+          end
+        end
+
+        def content_type_header
+          return {} unless (header = datum.dig(:hcp_params, :content_type))
+
+          { 'Content-Type' => header }
+        end
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/resource_object.rb

@@ -15,14 +15,6 @@ module Excon
 
       def initialize(data)
         @data = data
-
-        _properties.each do |key, value|
-          key = key.downcase
-          next unless /[@$"]/ !~ key.to_sym.inspect
-
-          singleton_class.class_eval { attr_reader key }
-          instance_variable_set("@#{key}", value.respond_to?(:keys) ? Properties.new(value) : value)
-        end
       end
 
       def _properties
@@ -64,6 +56,10 @@ module Excon
       def [](key)
         _properties[key]
       end
+
+      def method_missing(method_name, *_)
+        _properties.send(method_name)
+      end
     end
   end
 end

data/lib/excon/hypermedia/response.rb

@@ -18,12 +18,15 @@ module Excon
       #
       # Correctly handle the hypermedia request.
       #
-      def handle(method_name, *params)
+      def handle(method_name, *params) # rubocop:disable Metrics/CyclomaticComplexity
         return false unless enabled?
 
         case method_name
-        when :resource then resource
-        when :rel      then rel(params.shift, params)
+        when :resource                 then resource
+        when :_links, :links           then resource._links
+        when :_embedded, :embedded     then resource._embedded
+        when :_properties, :properties then resource._properties
+        when :rel                      then rel(params.shift, params)
         else false
         end
       end
@@ -49,11 +52,27 @@ module Excon
       end
 
       def rel(name, params)
-        link    = resource._links.send(name)
-        options = params.first.to_h.merge(hypermedia: true)
+        raise ArgumentError, 'missing relation name' unless name
+
+        unless (link = resource._links[name])
+          raise UnknownRelationError, "unknown relation: #{name}"
+        end
+
+        options = rel_params(params.first.to_h)
 
         link.respond_to?(:to_ary) ? link.map { |l| l.rel(options) } : link.rel(options)
       end
+
+      def rel_params(params)
+        params.merge(
+          hypermedia: true,
+          hcp: (params[:hcp].nil? ? response.data[:hcp] : params[:hcp]),
+          hcp_params: {
+            content_type: response.headers['Content-Type'],
+            embedded: resource._embedded
+          }
+        )
+      end
     end
   end
 end

data/lib/excon/hypermedia/version.rb

@@ -2,6 +2,6 @@
 
 module Excon
   module HyperMedia
-    VERSION = '0.4.3'
+    VERSION = '0.5.0'
   end
 end

data/lib/excon/hypermedia.rb

@@ -3,9 +3,11 @@
 require 'excon'
 require 'excon/addressable'
 
+require 'excon/hypermedia/errors'
 require 'excon/hypermedia/helpers/collection'
 require 'excon/hypermedia/link_object'
 require 'excon/hypermedia/middleware'
+require 'excon/hypermedia/middlewares/hypertext_cache_pattern'
 require 'excon/hypermedia/resource_object'
 require 'excon/hypermedia/response'
 require 'excon/hypermedia/version'

data/test/excon/edgecase_test.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative '../test_helper'
+
+module Excon
+  # EdgeCaseTest
+  #
+  # Validate edge cases (or: non-happy path)
+  #
+  class EdgeCaseTest < HyperMediaTest
+    def setup
+      Excon.defaults[:mock] = true
+      Excon.defaults[:middlewares].push(Excon::HyperMedia::Middleware)
+
+      response = { headers: { 'Content-Type' => 'application/hal+json' } }
+      Excon.stub({ path: '/api.json' }, response.merge(body: api_body))
+      Excon.stub({ path: '/empty_json' }, response.merge(body: '{}'))
+    end
+
+    def teardown
+      Excon.stubs.clear
+      Excon.defaults[:middlewares].delete(Excon::HyperMedia::Middleware)
+    end
+
+    def api
+      Excon.get('https://www.example.org/api.json')
+    end
+
+    def test_missing_middleware
+      Excon.defaults[:middlewares].delete(Excon::HyperMedia::Middleware)
+
+      assert_raises(NoMethodError) { api.rel }
+    end
+
+    def test_rel_missing_name
+      ex = assert_raises(ArgumentError) { api.rel }
+      assert_equal 'missing relation name', ex.message
+    end
+
+    def test_rel_missing_arguments
+      assert_equal Excon::Connection, api.rel('self').class
+    end
+
+    def test_rel_unknown_relation
+      ex = assert_raises(Excon::HyperMedia::UnknownRelationError) { api.rel('invalid') }
+      assert_equal 'unknown relation: invalid', ex.message
+    end
+
+    def test_missing_links
+      resource = Excon.get('https://www.example.org/empty_json').resource
+
+      assert_equal({}, resource._links.to_h)
+    end
+
+    def test_missing_embedded
+      resource = Excon.get('https://www.example.org/empty_json').resource
+
+      assert_equal({}, resource._embedded.to_h)
+    end
+
+    def test_missing_properties
+      resource = Excon.get('https://www.example.org/empty_json').resource
+
+      assert_equal({}, resource._properties.to_h)
+    end
+
+    def test_unknown_property
+      resource = Excon.get('https://www.example.org/api.json').resource
+
+      assert_equal nil, resource._properties.invalid
+      assert_equal nil, resource._properties['invalid']
+    end
+
+    def test_unknown_link
+      resource = Excon.get('https://www.example.org/empty_json').resource
+
+      assert_equal nil, resource._links.invalid
+      assert_equal nil, resource._links['invalid']
+    end
+
+    def test_unknown_embed
+      resource = Excon.get('https://www.example.org/api.json').resource
+
+      assert_equal nil, resource._embedded.invalid
+      assert_equal nil, resource._embedded['invalid']
+    end
+  end
+end

data/test/excon/hcp_test.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative '../test_helper'
+
+module Excon
+  # HCPTest
+  #
+  # Validate the workings of `Excon::HyperResource::Middlewares::HypertextCachePattern`.
+  #
+  class HCPTest < HyperMediaTest
+    def response
+      @response ||= Excon.get('https://example.org/product/bicycle')
+    end
+
+    def test_non_hcp_response
+      assert_equal nil, response[:hcp]
+    end
+
+    def test_hcp_response
+      assert response.rel('pump', hcp: true).get[:hcp]
+    end
+
+    def test_hcp_response_with_missing_embedding
+      api      = Excon.get('https://www.example.org/api.json')
+      response = api.rel('product', expand: { uid: 'bicycle' }, rel: true).get
+
+      assert_equal nil, response[:hcp]
+    end
+
+    def test_hcp_response_with_embedded_array
+      wheels = response.rel('wheels', hcp: true)
+
+      assert wheels.map(&:get).all? { |res| res[:hcp] }
+    end
+
+    def test_nested_hcp_responses
+      pump = response.rel('pump', hcp: true).get
+      response = pump.rel('parts', expand: { uid: 'bicycle' }).get
+
+      assert response[:hcp]
+    end
+
+    def test_hcp_not_working_for_non_get_requests
+      assert_equal nil, response.rel('pump', hcp: true).post[:hcp]
+    end
+
+    def test_hcp_resource
+      resource = response.rel('pump', hcp: true).get.resource
+
+      assert_equal Excon::HyperMedia::ResourceObject, resource.class
+    end
+
+    def test_hcp_links
+      resource = response.rel('pump', hcp: true).get.resource
+
+      assert_equal data(:parts)['_links']['self']['href'], resource._links.parts.href
+    end
+  end
+end

data/test/excon/integration_test.rb

@@ -48,10 +48,6 @@ module Excon
       assert response.body.include?('https://www.example.org/product/bicycle')
     end
 
-    def test_invalid_relation
-      assert_raises(NoMethodError) { api.rel('invalid') }
-    end
-
     def test_link
       response = api.rel('product', expand: { uid: 'bicycle' }).get
 

data/test/excon/link_object_test.rb

@@ -18,7 +18,7 @@ module Excon
     end
 
     def full
-      <<~EOF
+      <<-EOF
         {
           "href": "https://www.example.org/goodbye/{receiver}",
           "templated": "true",

data/test/excon/links_test.rb

@@ -10,7 +10,7 @@ module Excon
   #
   class LinksTest < Minitest::Test
     def body
-      <<~EOF
+      <<-EOF
         {
           "_links": {
             "self": {

data/test/excon/properties_test.rb

@@ -10,7 +10,7 @@ module Excon
   #
   class PropertiesTest < Minitest::Test
     def body
-      <<~EOF
+      <<-EOF
         {
           "size": "49CM",
           "bike-type": "Mountain Bike",

data/test/excon/resource_object_test.rb

@@ -10,7 +10,7 @@ module Excon
   #
   class ResourceObjectTest < Minitest::Test
     def body
-      <<~EOF
+      <<-EOF
         {
           "_links": {
             "hello": {

data/test/excon/response_test.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../test_helper'
+
+module Excon
+  # ResourceObjectTest
+  #
+  # Validate the workings of `Excon::HyperResource::ResourceObject`.
+  #
+  class ResponseTest < HyperMediaTest
+    def response
+      @response ||= Excon.get('https://example.org/product/bicycle')
+    end
+
+    def test_response
+      assert_equal Excon::Response, response.class
+    end
+
+    def test_links
+      assert_equal response.resource._links, response.links
+      assert_equal response.resource._links, response._links
+    end
+
+    def test_embedded
+      assert_equal response.resource._embedded, response.embedded
+      assert_equal response.resource._embedded, response._embedded
+    end
+
+    def test_properties
+      assert_equal response.resource._properties, response.properties
+      assert_equal response.resource._properties, response._properties
+    end
+  end
+end

data/test/test_helper.rb

@@ -21,7 +21,8 @@ module Excon
       Excon.stub({ method: :get, path: '/product/bicycle' }, response.merge(body: bicycle_body))
       Excon.stub({ method: :get, path: '/product/bicycle/wheels/front' }, response.merge(body: front_wheel_body))
       Excon.stub({ method: :get, path: '/product/bicycle/wheels/rear' }, response.merge(body: rear_wheel_body))
-      Excon.stub({ method: :get, path: '/product/pump' }, response.merge(body: pump_body))
+      Excon.stub({ path: '/product/pump' }, response.merge(body: pump_body))
+      Excon.stub({ method: :get, path: '/product/pump/parts' }, response.merge(body: parts_body))
       Excon.stub({ method: :get, path: '/product/handlebar' }, response.merge(body: handlebar_body))
       Excon.stub({ method: :get, path: '/api_v2.json' }, body: api_body, headers: { 'Content-Type' => 'application/json' })
     end
@@ -37,7 +38,7 @@ module Excon
     end
 
     def api_body
-      <<~EOF
+      <<-EOF
        {
          "_links": {
            "self": {
@@ -53,7 +54,7 @@ module Excon
     end
 
     def bicycle_body
-      <<~EOF
+      <<-EOF
         {
           "_links": {
             "self": {
@@ -90,7 +91,7 @@ module Excon
     end
 
     def handlebar_body
-      <<~EOF
+      <<-EOF
         {
           "_links": {
             "self": {
@@ -105,22 +106,42 @@ module Excon
     end
 
     def pump_body
-      <<~EOF
+      <<-EOF
         {
           "_links": {
             "self": {
               "href": "https://www.example.org/product/pump"
+            },
+            "parts": {
+              "href": "https://www.example.org/product/pump/parts"
             }
           },
           "weight": "2kg",
           "type": "Floor Pump",
-          "valve-type": "Presta"
+          "valve-type": "Presta",
+          "_embedded": {
+            "parts": #{parts_body}
+          }
+
+        }
+      EOF
+    end
+
+    def parts_body
+      <<-EOF
+        {
+          "_links": {
+            "self": {
+              "href": "https://www.example.org/product/pump/parts"
+            }
+          },
+          "count": 47
         }
       EOF
     end
 
     def rear_wheel_body
-      <<~EOF
+      <<-EOF
         {
           "_links": {
             "self": {
@@ -134,7 +155,7 @@ module Excon
     end
 
     def front_wheel_body
-      <<~EOF
+      <<-EOF
         {
           "_links": {
             "self": {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: excon-hypermedia
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Jean
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-27 00:00:00.000000000 Z
+date: 2016-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '1.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -140,21 +140,26 @@ files:
 - Rakefile
 - excon-hypermedia.gemspec
 - lib/excon/hypermedia.rb
+- lib/excon/hypermedia/errors.rb
 - lib/excon/hypermedia/ext/response.rb
 - lib/excon/hypermedia/helpers/collection.rb
 - lib/excon/hypermedia/link_object.rb
 - lib/excon/hypermedia/middleware.rb
+- lib/excon/hypermedia/middlewares/hypertext_cache_pattern.rb
 - lib/excon/hypermedia/resource_object.rb
 - lib/excon/hypermedia/resource_object/embedded.rb
 - lib/excon/hypermedia/resource_object/links.rb
 - lib/excon/hypermedia/resource_object/properties.rb
 - lib/excon/hypermedia/response.rb
 - lib/excon/hypermedia/version.rb
+- test/excon/edgecase_test.rb
+- test/excon/hcp_test.rb
 - test/excon/integration_test.rb
 - test/excon/link_object_test.rb
 - test/excon/links_test.rb
 - test/excon/properties_test.rb
 - test/excon/resource_object_test.rb
+- test/excon/response_test.rb
 - test/test_helper.rb
 homepage: https://github.com/JeanMertz/excon-hypermedia
 licenses: