hyperclient 1.0.1 → 2.1.0

data/test/hyperclient/link_collection_test.rb

@@ -32,6 +32,7 @@ module Hyperclient
 
     describe 'plain link' do
       let(:plain_link) { links.self }
+
       it 'must be correct' do
         _(plain_link._url).must_equal '/productions/1'
       end
@@ -39,6 +40,7 @@ module Hyperclient
 
     describe 'templated link' do
       let(:templated_link) { links.search }
+
       it 'must expand' do
         _(templated_link._expand(search: 'gizmos')._url).must_equal '/productions/1?categories=gizmos'
       end
@@ -47,6 +49,7 @@ module Hyperclient
     describe 'curied link collection' do
       let(:curied_link) { links['image:thumbnail'] }
       let(:curie) { links._curies['image'] }
+
       it 'must expand' do
         _(curied_link._expand(version: 'small')._url).must_equal '/images/thumbnails/small.jpg'
       end
@@ -71,9 +74,16 @@ module Hyperclient
 
     describe 'null link value' do
       let(:null_link) { links.null_link }
+
       it 'must be nil' do
         _(null_link).must_be_nil
       end
     end
+
+    describe 'invalid collection' do
+      it 'raises an error when the collection does not respond to collect' do
+        _(proc { LinkCollection.new('invalid', {}, entry_point) }).must_raise RuntimeError
+      end
+    end
   end
 end

data/test/hyperclient/link_test.rb

@@ -11,11 +11,13 @@ module Hyperclient
       describe prop do
         it 'returns the property value' do
           link = Link.new('key', { prop => 'value' }, entry_point)
+
           _(link.send("_#{prop}")).must_equal 'value'
         end
 
         it 'returns nil if the property is not present' do
           link = Link.new('key', {}, entry_point)
+
           _(link.send("_#{prop}")).must_be_nil
         end
       end
@@ -53,11 +55,13 @@ module Hyperclient
       describe 'required argument' do
         it 'builds a Link with the templated URI representation' do
           link = Link.new('key', { 'href' => '/orders/{id}', 'templated' => true }, entry_point)
+
           _(link._expand(id: '1')._url).must_equal '/orders/1'
         end
 
         it 'expands an uri template without variables' do
           link = Link.new('key', { 'href' => '/orders/{id}', 'templated' => true }, entry_point)
+
           _(link._expand._url).must_equal '/orders/'
           _(link._url).must_equal '/orders/'
         end
@@ -66,27 +70,32 @@ module Hyperclient
       describe 'query string argument' do
         it 'builds a Link with the templated URI representation' do
           link = Link.new('key', { 'href' => '/orders{?id}', 'templated' => true }, entry_point)
+
           _(link._expand(id: '1')._url).must_equal '/orders?id=1'
         end
 
         it 'expands an uri template without variables' do
           link = Link.new('key', { 'href' => '/orders{?id}', 'templated' => true }, entry_point)
+
           _(link._expand._url).must_equal '/orders'
           _(link._url).must_equal '/orders'
         end
 
         it 'does not expand unknown variables' do
           link = Link.new('key', { 'href' => '/orders{?id}', 'templated' => true }, entry_point)
+
           _(link._expand(unknown: '1')._url).must_equal '/orders'
         end
 
         it 'only expands known variables' do
           link = Link.new('key', { 'href' => '/orders{?id}', 'templated' => true }, entry_point)
+
           _(link._expand(unknown: '1', id: '2')._url).must_equal '/orders?id=2'
         end
 
         it 'only expands templated links' do
           link = Link.new('key', { 'href' => '/orders{?id}', 'templated' => false }, entry_point)
+
           _(link._expand(id: '1')._url).must_equal '/orders{?id}'
         end
       end
@@ -119,6 +128,7 @@ module Hyperclient
 
       it 'returns the link when no uri template' do
         link = Link.new('key', { 'href' => '/orders' }, entry_point)
+
         _(link._url).must_equal '/orders'
       end
 
@@ -141,9 +151,53 @@ module Hyperclient
 
         link._resource
       end
+
+      it 'fetches a fresh resource after a mutating request instead of returning the cached response (#107)' do
+        link = Link.new('key', { 'href' => '/productions/1' }, entry_point)
+
+        stub_request(entry_point.connection) do |stub|
+          stub.post('http://api.example.org/productions/1') { [201, {}, { 'status' => 'created' }] }
+          stub.get('http://api.example.org/productions/1') { [200, {}, { 'status' => 'fetched' }] }
+        end
+
+        link._post('foo' => 'bar')
+
+        _(link._resource.status).must_equal 'fetched'
+      end
     end
 
     describe 'get' do
+      %w[application/hal+json application/json].each do |content_type|
+        it "parses a #{content_type} response into a resource" do
+          link = Link.new('key', { 'href' => '/productions/1' }, entry_point)
+
+          stub_request(entry_point.connection) do |stub|
+            stub.get('http://api.example.org/productions/1') do
+              [200, { 'Content-Type' => content_type },
+               '{"title":"Production","_links":{"self":{"href":"/productions/1"}}}']
+            end
+          end
+
+          resource = link._get
+
+          _(resource.title).must_equal 'Production'
+          _(resource._links.self._url).must_equal '/productions/1'
+          _(resource._response.body).must_be_kind_of Hash
+        end
+      end
+
+      it 'raises a parsing error for an invalid JSON response' do
+        link = Link.new('key', { 'href' => '/productions/1' }, entry_point)
+
+        stub_request(entry_point.connection) do |stub|
+          stub.get('http://api.example.org/productions/1') do
+            [200, { 'Content-Type' => 'application/hal+json' }, '{"title":']
+          end
+        end
+
+        _(-> { link._get }).must_raise Faraday::ParsingError
+      end
+
       it 'sends a GET request with the link url' do
         link = Link.new('key', { 'href' => '/productions/1' }, entry_point)
 
@@ -266,7 +320,7 @@ module Hyperclient
         link = Link.new('key', { 'href' => '/productions/1' }, 'foo')
 
         _(link.inspect).must_include 'Link'
-        _(link.inspect).must_include '"href"=>"/productions/1"'
+        _(link.inspect).must_include({ 'href' => '/productions/1' }.inspect)
       end
     end
 
@@ -313,6 +367,37 @@ module Hyperclient
 
           _(resource.next._links.next._url).must_equal 'http://api.example.org/page3'
         end
+
+        it 'iterates over paginated, embedded items across pages' do
+          resource = Resource.new({ '_links' => { 'orders' => { 'href' => '/orders' } } }, entry_point)
+
+          stub_request(entry_point.connection) do |stub|
+            stub.get('http://api.example.org/orders') do
+              [200, {}, { '_links' => { 'next' => { 'href' => 'http://api.example.org/orders?page=2' } },
+                          '_embedded' => { 'orders' => [{ 'id' => 1 }] } }]
+            end
+            stub.get('http://api.example.org/orders?page=2') do
+              [200, {}, { '_embedded' => { 'orders' => [{ 'id' => 2 }] } }]
+            end
+          end
+
+          ids = resource._links.orders.map(&:id)
+
+          _(ids).must_equal [1, 2]
+        end
+
+        it 'returns an Enumerator when called without a block' do
+          resource = Resource.new({ '_links' => { 'orders' => { 'href' => '/orders' } } }, entry_point)
+
+          stub_request(entry_point.connection) do |stub|
+            stub.get('http://api.example.org/orders') { [200, {}, { '_embedded' => { 'orders' => [{ 'id' => 1 }] } }] }
+          end
+
+          enum = resource._links.orders.each
+
+          _(enum).must_be_kind_of Enumerator
+          _(enum.to_a.first.id).must_equal 1
+        end
       end
 
       describe 'resource' do
@@ -341,13 +426,55 @@ module Hyperclient
         it 'responds to missing methods' do
           resource.expects(:respond_to?).with('orders').returns(false)
           resource.expects(:respond_to?).with('embedded').returns(true)
+
           _(link.respond_to?(:embedded)).must_equal true
         end
 
+        it 'responds to missing methods that delegate to another resource' do
+          delegate = mock('Delegate')
+          resource.expects(:respond_to?).with('orders').returns(true)
+          resource.expects(:send).with('orders').returns(delegate)
+          delegate.expects(:respond_to?).with('foo').returns(true)
+
+          _(link.respond_to?(:foo)).must_equal true
+        end
+
         it 'does not delegate to_ary to resource' do
           resource.expects(:to_ary).never
+
           _([[link, link]].flatten).must_equal [link, link]
         end
+
+        it 'delegates through delegate_method when the resource responds but returns nil' do
+          delegate = mock('Delegate')
+          resource.expects(:respond_to?).with('foo').returns(true)
+          resource.expects(:send).with(:foo).returns(nil)
+          resource.expects(:respond_to?).with('orders').returns(true)
+          resource.expects(:send).with('orders').returns(delegate)
+          delegate.expects(:respond_to?).with('foo').returns(true)
+          delegate.expects(:send).with(:foo).returns('delegated result')
+
+          _(link.foo).must_equal 'delegated result'
+        end
+
+        it 'returns nil from delegate_method when the resource has no matching key' do
+          keyless_link = Link.new(nil, { 'href' => 'http://myapi.org/orders' }, entry_point)
+          resource.expects(:respond_to?).with('foo').returns(true)
+          resource.expects(:send).with(:foo).returns(nil)
+
+          _(keyless_link.foo).must_be_nil
+        end
+
+        it 'returns nil from delegate_method when the delegate does not respond to the method' do
+          delegate = mock('Delegate')
+          resource.expects(:respond_to?).with('foo').returns(true)
+          resource.expects(:send).with(:foo).returns(nil)
+          resource.expects(:respond_to?).with('orders').returns(true)
+          resource.expects(:send).with('orders').returns(delegate)
+          delegate.expects(:respond_to?).with('foo').returns(false)
+
+          _(link.foo).must_be_nil
+        end
       end
     end
   end

data/test/hyperclient/resource_test.rb

@@ -13,7 +13,7 @@ module Hyperclient
       end
 
       it 'initializes its attributes' do
-        Attributes.expects(:new).with(foo: :bar)
+        Attributes.expects(:new).with({ foo: :bar })
 
         Resource.new({ foo: :bar }, entry_point)
       end
@@ -60,7 +60,9 @@ module Hyperclient
 
     describe '_links' do
       it '_expand' do
-        resource = Resource.new({ '_links' => { 'orders' => { 'href' => '/orders/{id}', 'templated' => true } } }, entry_point)
+        resource = Resource.new({ '_links' => { 'orders' => { 'href' => '/orders/{id}', 'templated' => true } } },
+                                entry_point)
+
         _(resource._links.orders._expand(id: 1)._url).must_equal '/orders/1'
         _(resource.orders._expand(id: 1)._url).must_equal '/orders/1'
         _(resource.orders(id: 1)._url).must_equal '/orders/1'
@@ -93,16 +95,19 @@ module Hyperclient
       describe 'method_missing' do
         it 'delegates to attributes' do
           resource._attributes.expects(:foo).returns('bar')
+
           _(resource.foo).must_equal 'bar'
         end
 
         it 'delegates to links' do
           resource._links.expects(:foo).returns('bar')
+
           _(resource.foo).must_equal 'bar'
         end
 
         it 'delegates to embedded' do
           resource._embedded.expects(:foo).returns('bar')
+
           _(resource.foo).must_equal 'bar'
         end
 
@@ -110,11 +115,13 @@ module Hyperclient
           resource._attributes.expects('respond_to?').with('foo').returns(false)
           resource._links.expects('respond_to?').with('foo').returns(false)
           resource._embedded.expects('respond_to?').with('foo').returns(false)
+
           _(-> { resource.foo }).must_raise NoMethodError
         end
 
         it 'delegates []' do
           resource._attributes.expects(:foo).returns('bar')
+
           _(resource['foo']).must_equal 'bar'
         end
 
@@ -132,6 +139,7 @@ module Hyperclient
           describe 'with a default value' do
             it 'returns the value for keys that exist' do
               resource._attributes.expects(:foo).returns('bar')
+
               _(resource.fetch('foo', 'default value')).must_equal 'bar'
             end
 
@@ -143,6 +151,7 @@ module Hyperclient
           describe 'with a block' do
             it 'returns the value for keys that exist' do
               resource._attributes.expects(:foo).returns('bar')
+
               _(resource.fetch('foo') { 'default value' }).must_equal 'bar'
             end
 
@@ -219,5 +228,30 @@ module Hyperclient
         end
       end
     end
+
+    describe 'inspect' do
+      it 'outputs a custom-friendly output' do
+        resource = Resource.new({ '_links' => { 'self' => { 'href' => '/orders/523' } }, 'title' => 'Order' },
+                                entry_point)
+
+        _(resource.inspect).must_include 'Resource'
+        _(resource.inspect).must_include 'self_link:'
+        _(resource.inspect).must_include 'attributes:'
+      end
+    end
+
+    describe '#to_h and #to_hash' do
+      let(:resource) do
+        Resource.new({ '_links' => {}, 'title' => 'Order', 'total' => 42 }, entry_point)
+      end
+
+      it 'returns the attributes as a Hash from #to_hash' do
+        _(resource.to_hash).must_equal('title' => 'Order', 'total' => 42)
+      end
+
+      it 'returns the same result from #to_h as #to_hash' do
+        _(resource.to_h).must_equal(resource.to_hash)
+      end
+    end
   end
 end

data/test/hyperclient_test.rb

@@ -13,7 +13,7 @@ describe Hyperclient do
       let(:client) do
         Hyperclient.new('http://api.example.org') do |client|
           client.connection(default: true) do |conn|
-            conn.use Faraday::Request::OAuth
+            conn.use Faraday::Request::Instrumentation
           end
           client.headers['Access-Token'] = 'token'
         end
@@ -31,11 +31,12 @@ describe Hyperclient do
 
       it 'creates a Faraday connection with the default block plus any additional handlers' do
         handlers = client.connection.builder.handlers
-        _(handlers).must_include Faraday::Request::OAuth
+
+        _(handlers).must_include Faraday::Request::Instrumentation
         _(handlers).must_include Faraday::Response::RaiseError
-        _(handlers).must_include FaradayMiddleware::FollowRedirects
-        _(handlers).must_include FaradayMiddleware::EncodeHalJson
-        _(handlers).must_include FaradayMiddleware::ParseHalJson
+        _(handlers).must_include Faraday::FollowRedirects::Middleware
+        _(handlers).must_include Faraday::HalJson::Request
+        _(handlers).must_include Faraday::HalJson::Response
       end
     end
   end

data/test/oxford_example_test.rb

@@ -0,0 +1,52 @@
+require 'test_helper'
+require 'hyperclient'
+require 'webmock'
+require 'stringio'
+require_relative '../examples/oxford/app'
+
+describe OxfordExample::App do
+  let(:app) { OxfordExample::App.new }
+
+  before do
+    WebMock.enable!
+    WebMock.stub_request(:any, %r{\Ahttp://127\.0\.0\.1:9292/}).to_return do |request|
+      status, headers, body = app.call('REQUEST_METHOD' => request.method.to_s.upcase,
+                                       'PATH_INFO' => request.uri.path)
+      { status: status, headers: headers, body: body.join }
+    end
+  end
+
+  after do
+    WebMock.reset!
+    WebMock.disable!
+  end
+
+  it 'runs the documented client without external requests' do
+    output, = capture_io { load File.expand_path('../examples/oxford/client.rb', __dir__) }
+
+    _(output).must_include 'Balliol College: Broad Street OX1 3BJ'
+    _(output).must_include 'Followed primary_place: Balliol College'
+    _(output).must_include 'Archived depiction URL (not fetched):'
+    _(output).must_include 'CURIE: /docs/places'
+  end
+
+  it 'supports explicit navigation, hash attributes, and embedded resources' do
+    api = Hyperclient.new('http://127.0.0.1:9292/')
+    place = api._links.places._embedded.places.first
+
+    _(place[:name]).must_equal 'Balliol College'
+    _(place.to_h['id']).must_equal 'oxpoints:23232339'
+    _(place._embedded.files.first.type).must_equal 'depiction'
+    _(api._links['oxford:places']._embedded.places.first.name).must_equal 'Balliol College'
+  end
+
+  it 'serves HAL, rejects writes, and reports missing resources' do
+    status, headers, = app.call('REQUEST_METHOD' => 'GET', 'PATH_INFO' => '/')
+
+    _(status).must_equal 200
+    _(headers['content-type']).must_equal 'application/hal+json'
+    _(app.call('REQUEST_METHOD' => 'POST', 'PATH_INFO' => '/').first).must_equal 405
+    _(app.call('REQUEST_METHOD' => 'GET', 'PATH_INFO' => '/missing').first).must_equal 404
+    _(app.call('REQUEST_METHOD' => 'HEAD', 'PATH_INFO' => '/').last).must_equal []
+  end
+end

data/test/test_helper.rb

@@ -1,11 +1,29 @@
 $LOAD_PATH << 'lib'
 
+if ENV['COVERAGE']
+  require 'simplecov'
+  require 'simplecov-lcov'
+  SimpleCov.formatter = SimpleCov::Formatter::LcovFormatter
+  SimpleCov::Formatter::LcovFormatter.config do |c|
+    c.report_with_single_file = true
+    c.lcov_file_name = 'lcov.info'
+    c.single_report_path = 'coverage/lcov.info'
+  end
+  SimpleCov.start do
+    add_filter '/test/'
+    add_filter '/features/'
+  end
+end
+
 require 'minitest/autorun'
 require 'minitest/pride'
 require 'mocha/minitest'
 require 'json'
 
-MiniTest::Test.class_eval do
+require 'faraday'
+require 'faraday/request/instrumentation'
+
+Minitest::Assertions.class_eval do
   def stub_request(conn, adapter_class = Faraday::Adapter::Test, &stubs_block)
     adapter_handler = conn.builder.handlers.find { |h| h.klass < Faraday::Adapter }
     if adapter_handler

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hyperclient
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Oriol Gual
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-02 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -30,16 +30,16 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '2'
 - !ruby/object:Gem::Dependency
-  name: faraday_hal_middleware
+  name: faraday-follow_redirects
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,19 +53,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: faraday_middleware
+  name: faraday_hal_middleware
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
 description: Hyperclient is a Ruby Hypermedia API client.
 email:
 - oriol.gual@gmail.com
@@ -73,11 +73,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
+- ".github/workflows/coverage.yml"
+- ".github/workflows/danger-comment.yml"
+- ".github/workflows/danger.yml"
+- ".github/workflows/lint.yml"
+- ".github/workflows/test.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
-- ".travis.yml"
 - ".yardopts"
+- AGENTS.md
 - CHANGELOG.md
 - CONTRIBUTING.md
 - Dangerfile
@@ -88,7 +94,11 @@ files:
 - RELEASING.md
 - Rakefile
 - UPGRADING.md
-- examples/splines_api.rb
+- examples/oxford/README.md
+- examples/oxford/app.rb
+- examples/oxford/client.rb
+- examples/oxford/places.json
+- examples/oxford/server.rb
 - features/api_navigation.feature
 - features/default_config.feature
 - features/steps/api_navigation.rb
@@ -119,10 +129,12 @@ files:
 - test/hyperclient/resource_collection_test.rb
 - test/hyperclient/resource_test.rb
 - test/hyperclient_test.rb
+- test/oxford_example_test.rb
 - test/test_helper.rb
 homepage: https://github.com/codegram/hyperclient/
 licenses: []
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -138,28 +150,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.3
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: ''
-test_files:
-- features/api_navigation.feature
-- features/default_config.feature
-- features/steps/api_navigation.rb
-- features/steps/default_config.rb
-- features/support/api.rb
-- features/support/env.rb
-- features/support/fixtures.rb
-- test/fixtures/collection.json
-- test/fixtures/element.json
-- test/fixtures/root.json
-- test/hyperclient/attributes_test.rb
-- test/hyperclient/collection_test.rb
-- test/hyperclient/curie_test.rb
-- test/hyperclient/entry_point_test.rb
-- test/hyperclient/link_collection_test.rb
-- test/hyperclient/link_test.rb
-- test/hyperclient/resource_collection_test.rb
-- test/hyperclient/resource_test.rb
-- test/hyperclient_test.rb
-- test/test_helper.rb
+test_files: []

data/.travis.yml

@@ -1,24 +0,0 @@
-language: ruby
-
-sudo: false
-
-matrix:
-  include:
-    - rvm: 2.6.6
-      env: FARADAY_VERSION=0.9.0
-    - rvm: 2.6.6
-      env: FARADAY_VERSION=0.17.0
-    - rvm: 2.6.6
-      env: FARADAY_VERSION="~> 1.0"
-    - rvm: 2.6.6
-      script:
-        - bundle exec danger
-    - rvm: 2.3.8
-    - rvm: jruby-9.2.7.0
-    - rvm: jruby-head
-    - rvm: ruby-head
-  allow_failures:
-    - rvm: ruby-head
-    - rvm: jruby-head
-
-bundler_args: --without development

data/examples/splines_api.rb

@@ -1,39 +0,0 @@
-require 'hyperclient'
-
-puts "Using Hyperclient #{Hyperclient::VERSION} ..."
-
-# create a new client
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api')
-
-# enumerate splines
-api.splines.each do |spline|
-  puts spline.uuid.to_s
-  puts " reticulated: #{spline.reticulated ? 'yes' : 'no'}"
-  puts " thumbnail: #{spline['images:thumbnail']}"
-end
-
-api._links.splines._embedded.splines.each do |_spline|
-  # ... equivalent to the above
-end
-
-puts '*' * 10
-
-# retrieve an existing spline
-spline = api.spline(uuid: 123)
-puts "Spline #{spline.uuid} is #{spline.reticulated ? 'reticulated' : 'not reticulated'}."
-
-# puts api._links.spline._expand(uuid: 'uuid')._resource._attributes.reticulated
-
-# spline.to_h
-
-# create a new spline
-spline = api.splines._post(spline: { reticulated: true })
-puts "Created a #{spline.reticulated ? 'reticulated' : 'unreticulated'} spline #{spline.uuid}."
-
-# update an existing spline
-spline = api.spline(uuid: 123)._put(spline: { reticulated: true })
-puts "Updated spline #{spline.uuid}, now #{spline.reticulated ? 'reticulated' : 'not reticulated'}."
-
-# delete an existing spline
-spline = api.spline(uuid: 123)._delete
-puts "Deleted spline #{spline.uuid}."