excon-hypermedia 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cb36e9f12e5909b7e4d4321184f39582882da139
-  data.tar.gz: 3b6c39402e531bd8055c75a032aba0db380c6635
+  metadata.gz: 375d919cb0b7562e0664ae44c30d3bdd7b71acf3
+  data.tar.gz: 5d48e0eff3d6f00c2968bb32a330949833a81745
 SHA512:
-  metadata.gz: 759eedec55a1da3d4aced37c4385dcafb38c44ba1e4636222398251808ac6972b52dc5962d471ee3547032605d204f7c2bff3e12d3395f1f6dfd82b3e41f08dc
-  data.tar.gz: 08371cb0d025c67159f85481d2e2ef61cea5b8cb08e0dbf28917cd434f3fccdfb84ceaa0cef2af56d1a2f818c7b9f426f0fdd005731abb4b6ca66fb6b9b65e97
+  metadata.gz: cc9e8bfd092cef7babc130b59e8debd50eb84680a37d91da238ec84888ebdae22ea9808035cc324a52ba81833eb67daffb4a5cdd68856fe8c4209bb5d0ca5d77
+  data.tar.gz: 080f93835dba3d7648c37377293428dadaf1e60281511f8d014debf4dacb5f65555cb96de919461229c718fa0fa253481275a4beff9f9b383d0888184d9c0c56

data/.rubocop.yml

@@ -5,3 +5,6 @@ AllCops:
 
 Metrics/LineLength:
   Max: 100
+
+Lint/EndAlignment:
+  AlignWith: variable

data/README.md

@@ -30,19 +30,20 @@ relations. It returns raw response bodies in string format.
 
 This gem adds a thin layer on top of [Excon][excon] to make it talk with an
 HyperMedia-enabled API. To let Excon know the connection supports HyperMedia,
-simply add the `hypermedia: true` option.
+simply enable the correct middleware (either globally, or per-connection):
 
 ```ruby
-conn = Excon.new('http://www.example.com/api.json', hypermedia: true)
-conn.class # => Excon::Connection
+Excon.defaults[:middlewares].push(Excon::HyperMedia::Middleware)
+
+api = Excon.get('http://www.example.com/api.json')
+api.class # => Excon::Response
 ```
 
-From that point on, you can use this single connection to make all requests. The
-`hypermedia` option will be passed on to all subsequent connection objects, as
-long as you keep chaining the requests from the original top-level connection.
+Using the `HyperMedia` middleware, the `Excon::Response` object now knows how
+to handle the HyperMedia aspect of the API:
 
 ```ruby
-product = conn.product(expand: { uid: 'hello' })
+product = api.product(expand: { uid: 'hello' })
 product.class # => Excon::Connection
 
 response = product.get
@@ -53,16 +54,9 @@ response.body.class # => String
 As seen above, you can expand URI Template variables using the `expand` option,
 provided by the [`excon-addressable` library][excon-addressable].
 
-You can mark any connection object as hypermedia-aware – not just the top-level
-entrypoint – by passing in the `hypermedia: true` option:
-
-```ruby
-user = Excon.new('http://www.example.com/users/jeanmertz', hypermedia: true)
-user.orders.class # => Excon::Connection
-```
-
-Since each new resource is simply an `Excon::Connection` object, all
-[Excon-provided options][options] are available as well:
+Since each new resource is simply an `Excon::Response` object, accessed through
+the default `Excon::Connection` object, all [Excon-provided options][options]
+are available as well:
 
 ```ruby
 product.get(idempotent: true, retry_limit: 6)
@@ -74,10 +68,8 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## TODO
 
-* use Excon's Middleware system
 * make it easy to access attributes in response objects
 * properly handle curied-links and/or non-valid Ruby method name links
-* work correctly with Excon.get/post/delete shortcut methods
 
 [excon]: https://github.com/excon/excon
 [hypermedia]: https://en.wikipedia.org/wiki/HATEOAS

data/excon-hypermedia.gemspec

@@ -6,7 +6,7 @@ require 'excon/hypermedia/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'excon-hypermedia'
-  spec.version       = Excon::Hypermedia::VERSION
+  spec.version       = Excon::HyperMedia::VERSION
   spec.authors       = %w(Jean Mertz)
   spec.email         = %w(jean@mertz.fm)
 
@@ -22,6 +22,7 @@ Gem::Specification.new do |spec|
   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.0'
 
   spec.add_dependency 'excon', '~> 0.49'
   spec.add_dependency 'excon-addressable', '~> 0.1'

data/lib/excon/hypermedia/ext/response.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Excon
+  module HyperMedia
+    module Ext
+      # Ext::Response
+      #
+      # Overloads the default `Excon::Response` to add a thin HyperMedia layer
+      # on top.
+      #
+      module Response
+        def method_missing(method_name, *params)
+          hypermedia_response.handle(method_name, *params) || super
+        end
+
+        def respond_to_missing?(method_name, include_private = false)
+          hypermedia_response.handle(method_name, *params) != false || super
+        end
+
+        def hypermedia_response
+          @hypermedia_response ||= HyperMedia::Response.new(self)
+        end
+      end
+    end
+  end
+
+  # :nodoc:
+  class Response
+    prepend HyperMedia::Ext::Response
+  end
+end

data/lib/excon/hypermedia/link.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Excon
+  module HyperMedia
+    # Link
+    #
+    # This HyperMedia::Link object encapsulates a link pointing to a resource.
+    #
+    class Link
+      attr_reader :name
+
+      def initialize(name:, hash:)
+        @hash = hash
+        @name = name
+      end
+
+      def valid?
+        link_data.keys.any?
+      end
+
+      def invalid?
+        !valid?
+      end
+
+      def uri
+        ::Addressable::URI.parse(href)
+      end
+
+      def href
+        link_data['href']
+      end
+
+      private
+
+      def link_data
+        @hash.dig('_links', name.to_s) || {}
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/middleware.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+Excon.defaults[:middlewares].unshift(Excon::Addressable::Middleware)
+
+module Excon
+  module HyperMedia
+    # Middleware
+    #
+    # This middleware sets the `hypermedia` datum to `true`, if the returned
+    # `Content-Type` header contains `hal+json`.
+    #
+    # If the `hypermedia` attribute is already set for the connection, it
+    # will be left alone by this middleware.
+    #
+    class Middleware < Excon::Middleware::Base
+      def request_call(datum)
+        return super unless (content_type = datum.dig(:response, :headers, 'Content-Type').to_s)
+
+        datum[:response][:hypermedia] = if datum[:hypermedia].nil?
+          content_type.include?('hal+json')
+        else
+          datum[:hypermedia]
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/resource.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Excon
+  module HyperMedia
+    # Resource
+    #
+    # This HyperMedia::Resource object encapsulates the returned JSON and
+    # makes it easy to access the links and attributes.
+    #
+    class Resource
+      attr_reader :data
+
+      def initialize(body)
+        @body = body
+      end
+
+      def links
+        data.fetch('_links', {}).keys.map { |name| link(name) }
+      end
+
+      def link(link_name)
+        Link.new(name: link_name, hash: data)
+      end
+
+      def attributes
+        attributes = data.reject do |k, _|
+          k == '_links'
+        end
+
+        Struct.new(*attributes.keys.map(&:to_sym)).new(*attributes.values)
+      end
+
+      def type?(name)
+        return :link if link(name).valid?
+        return :attribute if attributes.respond_to?(name.to_s)
+
+        :unknown
+      end
+
+      def data
+        @data ||= JSON.parse(@body)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/response.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'excon/hypermedia/ext/response'
+
+module Excon
+  module HyperMedia
+    # Response
+    #
+    # This HyperMedia::Response object helps determine valid subsequent
+    # requests and attribute values.
+    #
+    class Response
+      attr_reader :response
+
+      def initialize(response)
+        @response = response
+      end
+
+      # handle
+      #
+      # Correctly handle the hypermedia request.
+      #
+      def handle(method_name, *params)
+        return false if disabled?
+
+        case resource.type?(method_name)
+        when :link      then return handle_link(method_name, params)
+        when :attribute then return handle_attribute(method_name)
+        end
+
+        respond_to?(method_name) ? send(method_name) : false
+      end
+
+      def links
+        resource.links
+      end
+
+      def attributes
+        resource.attributes
+      end
+
+      def resource
+        @resource ||= Resource.new(response.body)
+      end
+
+      def enabled?
+        response.data[:hypermedia] == true
+      end
+
+      def disabled?
+        !enabled?
+      end
+
+      private
+
+      def handle_link(name, params)
+        Excon.new(resource.link(name).href, params.first.to_h.merge(hypermedia: true))
+      end
+
+      def handle_attribute(name)
+        attributes[name.to_s]
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/version.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
+
 module Excon
-  module Hypermedia
-    VERSION = '0.1.0'
+  module HyperMedia
+    VERSION = '0.2.0'
   end
 end

data/lib/excon/hypermedia.rb

@@ -1,17 +1,9 @@
 # frozen_string_literal: true
+
 require 'excon'
 require 'excon/addressable'
-require 'excon/hypermedia/hyper_media'
-
-# :nodoc:
-module Excon
-  # HyperMedia addition to Excon.
-  #
-  module Hypermedia
-    def new(url, params = {})
-      params[:hypermedia] ? super.extend(HyperMedia) : super
-    end
-  end
-
-  singleton_class.prepend Hypermedia
-end
+require 'excon/hypermedia/link'
+require 'excon/hypermedia/middleware'
+require 'excon/hypermedia/resource'
+require 'excon/hypermedia/response'
+require 'excon/hypermedia/version'

data/test/excon/hypermedia_test.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# rubocop:disable Metrics/AbcSize, Metrics/LineLength
+# rubocop:disable Metrics/LineLength
 require_relative '../test_helper'
 
 module Excon
@@ -9,75 +9,81 @@ module Excon
   #
   class HypermediaTest < Minitest::Test
     def entrypoint
-      <<~EOF
-        {
-          "_links": {
-            "hello": {
-              "href":"http://www.example.com/hello/{location}"
-            }
-          }
-        }
-      EOF
+      '{ "_links": { "hello": { "href":"http://www.example.com/hello/{location}" } } }'
     end
 
-    def hello_world
+    def hello_world # rubocop:disable Metrics/MethodLength
       <<~EOF
         {
           "_links": {
             "goodbye": {
               "href":"http://www.example.com/hello/world/goodbye{?message}"
             }
-          }
-        }
-      EOF
-    end
-
-    def hello_universe
-      <<~EOF
-        {
-          "_links": {
-            "goodbye": {
-              "href":"http://www.example.com/hello/universe/goodbye{?message}"
-            }
-          }
+          },
+          "uid": "hello",
+          "message": "goodbye!"
         }
-      EOF
+        EOF
     end
 
     def setup
       Excon.defaults[:mock] = true
+      Excon.defaults[:middlewares].push(Excon::HyperMedia::Middleware)
+
+      response = { headers: { 'Content-Type' => 'application/hal+json' } }
+      Excon.stub({ method: :get, path: '/api' }, response.merge(body: entrypoint))
+      Excon.stub({ method: :get, path: '/hello/world' }, response.merge(body: hello_world))
+      Excon.stub({ method: :get, path: '/hello/world/goodbye', query: nil }, response.merge(body: 'bye!'))
+      Excon.stub({ method: :get, path: '/hello/world/goodbye', query: 'message=farewell' }, response.merge(body: 'farewell'))
+    end
+
+    def client
+      Excon.get('http://www.example.com/api')
+    end
+
+    def test_request
+      response = client.hello(expand: { location: 'world' }).get
+
+      assert response.body.include?('http://www.example.com/hello/world/goodbye{?message}')
+    end
+
+    def test_nested_request
+      hello    = client.hello(expand: { location: 'world' })
+      response = hello.get.goodbye.get
 
-      Excon.stub({ method: :get, path: '/api' }, body: entrypoint, status: 200)
-      Excon.stub({ method: :get, path: '/hello/world' }, body: hello_world, status: 200)
-      Excon.stub({ method: :get, path: '/hello/world/goodbye', query: nil }, body: 'bye!', status: 200)
-      Excon.stub({ method: :get, path: '/hello/world/goodbye', query: 'message=farewell' }, body: 'farewell', status: 200)
-      Excon.stub({ method: :get, path: '/hello/universe' }, body: hello_universe, status: 200)
+      assert_equal 'bye!', response.body
     end
 
-    def test_hypermedia_request
-      conn = Excon.new('http://www.example.com/api', hypermedia: true)
-      conn2 = conn.hello(expand: { location: 'world' })
-      conn3 = conn.hello(expand: { location: 'universe' })
+    def test_nested_query_parameters
+      hello    = client.hello(expand: { location: 'world' })
+      response = hello.get.goodbye(expand: { message: 'farewell' }).get
 
-      assert_equal '/hello/world', conn2.data[:path]
-      assert conn2.get.body.include?('http://www.example.com/hello/world/goodbye{?message}')
+      assert_equal 'farewell', response.body
+    end
+
+    def test_expand_in_get
+      response = client.hello.get(expand: { location: 'world' })
 
-      assert_equal '/hello/universe', conn3.data[:path]
-      assert conn3.get.body.include?('http://www.example.com/hello/universe/goodbye{?message}')
+      assert response.body.include?('http://www.example.com/hello/world/goodbye{?message}')
     end
 
-    def test_nested_hypermedia_request
-      conn = Excon.new('http://www.example.com/api', hypermedia: true)
-      conn2 = conn.hello(expand: { location: 'world' }).goodbye
-      conn3 = conn.hello(expand: { location: 'world' }).goodbye(expand: { message: 'farewell' })
+    def test_attribute
+      response = client.hello(expand: { location: 'world' }).get
+
+      assert_equal response.uid, 'hello'
+      assert_equal response.message, 'goodbye!'
+    end
+
+    def test_links
+      response = client.hello(expand: { location: 'world' }).get
+
+      assert_equal response.links.first.name, 'goodbye'
+    end
 
-      assert_equal '/hello/world/goodbye', conn2.data[:path]
-      assert_nil conn2.data[:query]
-      assert_equal 'bye!', conn2.get.body
+    def test_attributes
+      response = client.hello(expand: { location: 'world' }).get
 
-      assert_equal '/hello/world/goodbye', conn3.data[:path]
-      assert_equal 'message=farewell', conn3.data[:query]
-      assert_equal 'farewell', conn3.get.body
+      assert_equal response.attributes.uid, 'hello'
     end
 
     def teardown

data/test/excon/link_test.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+require_relative '../test_helper'
+
+module Excon
+  # LinkTest
+  #
+  # Validate the workings of `Excon::HyperResource::Link`.
+  #
+  class LinkTest < Minitest::Test
+    def body # rubocop:disable Metrics/MethodLength
+      <<~EOF
+        {
+          "_links": {
+            "hello": {
+              "href": "http://www.example.com/hello/{location}"
+            }
+          },
+          "uid": "universe",
+          "hello": "world"
+        }
+      EOF
+    end
+
+    def data
+      JSON.parse(body)
+    end
+
+    def link
+      @link ||= Excon::HyperMedia::Link.new(name: 'hello', hash: data)
+    end
+
+    def invalid_link
+      @invalid_link ||= Excon::HyperMedia::Link.new(name: 'goodbye', hash: data)
+    end
+
+    def test_link
+      assert_equal link.name, 'hello'
+    end
+
+    def test_valid_link
+      assert link.valid?
+    end
+
+    def test_invalid_link
+      refute invalid_link.valid?
+    end
+
+    def test_uri
+      assert_equal link.uri.to_s, data['_links']['hello']['href']
+    end
+
+    def test_href
+      assert_equal link.href, data['_links']['hello']['href']
+    end
+  end
+end

data/test/excon/resource_test.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+require_relative '../test_helper'
+
+module Excon
+  # ResourceTest
+  #
+  # Validate the workings of `Excon::HyperResource::Resource`.
+  #
+  class ResourceTest < Minitest::Test
+    def body # rubocop:disable Metrics/MethodLength
+      <<~EOF
+        {
+          "_links": {
+            "hello": {
+              "href": "http://www.example.com/hello/{location}"
+            }
+          },
+          "uid": "universe",
+          "hello": "world"
+        }
+      EOF
+    end
+
+    def data
+      @data ||= JSON.parse(body)
+    end
+
+    def resource
+      @resource ||= Excon::HyperMedia::Resource.new(body)
+    end
+
+    def test_resource
+      assert_equal data, resource.data
+    end
+
+    def test_links
+      assert_equal data['_links']['hello']['href'], resource.links.first.href
+    end
+
+    def test_attributes
+      assert_equal resource.attributes.uid, 'universe'
+      assert_equal resource.attributes.hello, 'world'
+
+      refute resource.attributes.respond_to?('_links')
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: excon-hypermedia
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jean
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-17 00:00:00.000000000 Z
+date: 2016-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -81,6 +81,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: m
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
 - !ruby/object:Gem::Dependency
   name: excon
   requirement: !ruby/object:Gem::Requirement
@@ -126,9 +140,15 @@ files:
 - Rakefile
 - excon-hypermedia.gemspec
 - lib/excon/hypermedia.rb
-- lib/excon/hypermedia/hyper_media.rb
+- lib/excon/hypermedia/ext/response.rb
+- lib/excon/hypermedia/link.rb
+- lib/excon/hypermedia/middleware.rb
+- lib/excon/hypermedia/resource.rb
+- lib/excon/hypermedia/response.rb
 - lib/excon/hypermedia/version.rb
 - test/excon/hypermedia_test.rb
+- test/excon/link_test.rb
+- test/excon/resource_test.rb
 - test/test_helper.rb
 homepage: https://github.com/JeanMertz/excon-hypermedia
 licenses:
@@ -155,4 +175,3 @@ signing_key:
 specification_version: 4
 summary: Excon, with Hypermedia traversing baked in.
 test_files: []
-has_rdoc: 

data/lib/excon/hypermedia/hyper_media.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-require 'json'
-
-module Excon
-  # HyperMedia
-  #
-  module HyperMedia
-    def method_missing(method_name, *params)
-      return super unless (url = entrypoint.dig('_links', method_name.to_s, 'href'))
-
-      Excon.new(url, params.first.to_h.merge(hypermedia: true))
-    end
-
-    def respond_to_missing?(method_name, include_private = false)
-      entrypoint.dig('_links', method_name.to_s, 'href') ? true : super
-    end
-
-    private
-
-    def entrypoint
-      @entrypoint ||= JSON.parse(get.body)
-    rescue JSON::ParserError
-      {}
-    end
-  end
-end