hyperclient 2.0.0 → 2.1.0

data/RELEASING.md

@@ -1,69 +1,75 @@
-Releasing Hyperclient
-=====================
+# Releasing Hyperclient
 
-There're no particular rules about when to release hyperclient. Release bug fixes frequenty, features not so frequently and breaking API changes rarely.
+Release bug fixes frequently, features less frequently, and breaking API changes rarely.
 
-### Release
+## Prepare the Release
 
-Run tests, check that all tests succeed locally.
+Start with a clean, up-to-date `master` branch. Check that CI has succeeded for all supported platforms.
 
-```
-bundle install
-rake
-```
-
-Check that the last build succeeded in CI for all supported platforms.
-
-Increment the version, modify [lib/hyperclient/version.rb](lib/hyperclient/version.rb).
+Set the release version in [lib/hyperclient/version.rb](lib/hyperclient/version.rb). Use a patch version for backward-compatible fixes, a minor version for backward-compatible features, and a major version for breaking changes.
 
-*  Increment the third number if the release has bug fixes and/or very minor features, only (eg. change `0.5.1` to `0.5.2`).
-*  Increment the second number if the release contains major features or breaking API changes (eg. change `0.5.1` to `0.4.0`).
+Replace the next-version heading in [CHANGELOG.md](CHANGELOG.md) with the release version and date, for example `### 2.1.0 (2026/10/14)`. Remove the "Your contribution here." placeholder from that release.
 
-Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
+Run the full suite, then commit and push the release preparation:
 
-```
-0.4.0 (2014-01-27)
-==================
+```sh
+bundle install
+bundle exec rake
+git add CHANGELOG.md lib/hyperclient/version.rb
+git commit -m "Preparing for release, 2.1.0."
+git push origin master
 ```
 
-Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+Wait for CI on the release preparation commit to succeed before publishing.
 
-Commit your changes.
+## Publish to RubyGems and GitHub
 
+Publish the gem using Bundler's release task. This builds the gem, creates and pushes the version tag, and publishes to RubyGems. Complete RubyGems MFA when prompted.
+
+```sh
+bundle exec rake release
 ```
-git add CHANGELOG.md lib/hyperclient/version.rb
-git commit -m "Preparing for release, 0.4.0."
-git push origin master
+
+Creating a Git tag does **not** create a GitHub release. After confirming that the gem was published successfully, create a GitHub release for the same tag. Put the matching changelog section's entries in a temporary file and use them as the release notes:
+
+```sh
+version=2.1.0
+notes="$(mktemp)"
+awk -v version="$version" '
+  /^### / {
+    if (found) exit
+    if ($2 == version) found = 1
+    next
+  }
+  found { print }
+' CHANGELOG.md > "$notes"
+gh release create "v$version" --repo codegram/hyperclient --verify-tag --title "$version" --notes-file "$notes" --latest
+rm "$notes"
 ```
 
-Release.
+Verify both publications before considering the release complete:
 
+```sh
+curl --fail --silent --show-error "https://rubygems.org/api/v2/rubygems/hyperclient/versions/$version.json"
+gh release view "v$version" --repo codegram/hyperclient
 ```
-$ rake release
 
-hyperclient 0.4.0 built to pkg/hyperclient-0.4.0.gem.
-Tagged v0.4.0.
-Pushed git commits and tags.
-Pushed hyperclient 0.4.0 to rubygems.org.
-```
+If publishing is interrupted, inspect the existing tag, RubyGems version, and GitHub release first. Resume only the missing step; do not move or recreate a published tag.
 
-### Prepare for the Next Version
+## Prepare the Next Version
 
-Add the next release to [CHANGELOG.md](CHANGELOG.md).
+Increment the development patch version in [lib/hyperclient/version.rb](lib/hyperclient/version.rb), for example from `2.1.0` to `2.1.1`. Add the matching unreleased section at the top of [CHANGELOG.md](CHANGELOG.md):
 
-```
-Next Release
-============
+```markdown
+### 2.1.1 (Next)
 
 * Your contribution here.
 ```
 
-Increment the minor version, modify [lib/hyperclient/version.rb](lib/hyperclient/version.rb).
+Commit and push:
 
-Comit your changes.
-
-```
+```sh
 git add CHANGELOG.md lib/hyperclient/version.rb
-git commit -m "Preparing for next release, 0.4.1."
+git commit -m "Preparing for next release, 2.1.1."
 git push origin master
 ```

data/examples/oxford/README.md

@@ -0,0 +1,42 @@
+# Local Oxford HAL Demo
+
+This read-only demo uses a small selection of public place facts from Oxford's retired mobile API. It runs entirely on localhost; neither Oxford nor the Internet Archive is contacted when running the example. The information is historical, not a current directory.
+
+From the repository root, install dependencies and start the server:
+
+```sh
+bundle install
+bundle exec ruby examples/oxford/server.rb
+```
+
+In a second terminal:
+
+```sh
+bundle exec ruby -Ilib examples/oxford/client.rb
+```
+
+The server binds only to `127.0.0.1:9292`. Set `PORT` on the server and `OXFORD_URL` on the client to use another port. Stop the server with Ctrl-C.
+
+The client demonstrates collection traversal, attributes, a templated place link, following `primary_place`, embedded file metadata, and CURIE expansion. It prints image URLs without downloading images. Unknown paths return 404; writes return 405.
+
+## Provenance and Adaptations
+
+The factual fields and original place path in `places.json` were transcribed from [Balliol College's archived response, September 10, 2020](https://web.archive.org/web/20200910141343id_/https://api.m.ox.ac.uk/places/oxpoints:23232339). The record retains the original ID, name, address, coordinates, self/primary-place paths, and one image URL. No image or descriptive prose is redistributed.
+
+The [archived API root, July 12, 2024](https://web.archive.org/web/20240712050404id_/http://api.m.ox.ac.uk/) demonstrates the original HAL-style links. See also [Moxie's OxPoints importer documentation](https://moxie.readthedocs.io/en/latest/places/oxpoints.html).
+
+## Data License
+
+The underlying OxPoints place data is dedicated to the public domain under [CC0](https://creativecommons.org/publicdomain/zero/1.0/). Oxford's own presentation, [*OxPoints and data.ox.ac.uk*, Alexander Dutton, InfoDev, OUCS (2011)](https://old.ictf.ox.ac.uk/conference/2011/presentations/wks11_oxpoints_dataox.pdf), identifies names, coordinates, addresses, and identifiers as OxPoints data (slides 2-5) and explicitly states "Public domain (CC0; no attribution required)" (slide 8). The place facts in `places.json` come from this dataset via the archived mobile API response cited above; the HAL wrappers and local links are demo adaptations.
+
+This is not a license claim for full archived API responses or photographs. The depiction URL is retained only as a reference to an external image; the image itself is not included, fetched, or covered by this notice. Newly authored server code and documentation are under this project's license. Moxie's Apache-2.0 code license is separate from the OxPoints data license.
+
+The root, collection wrapper, templated `place` link, `oxford` CURIE, and local relation documentation are demo additions, not a reconstruction of the original service. Responses use `application/hal+json`; the archived service returned `application/json`. Relative place links retain their original paths and resolve locally. Unavailable child links, images, and unrelated API endpoints are not mirrored.
+
+## Tests
+
+```sh
+bundle exec ruby -Itest test/oxford_example_test.rb
+```
+
+The tests exercise the same app and client using local HTTP stubs, without requiring a running server or external network access. They are also included in `bundle exec rake test`.

data/examples/oxford/app.rb

@@ -0,0 +1,48 @@
+require 'json'
+
+module OxfordExample
+  # A read-only HAL demo, independent of Oxford's retired API.
+  class App
+    def initialize
+      @places = JSON.parse(File.read(File.join(__dir__, 'places.json')))
+    end
+
+    def call(env)
+      return response(405, { 'error' => 'Read-only example' }) unless %w[GET HEAD].include?(env['REQUEST_METHOD'])
+
+      status, body = representation(env['PATH_INFO'])
+      result = response(status, body)
+      result[2] = [] if env['REQUEST_METHOD'] == 'HEAD'
+      result
+    end
+
+    private
+
+    def representation(path)
+      case path
+      when '/'
+        [200, {
+          '_links' => {
+            'self' => { 'href' => '/' },
+            'places' => { 'href' => '/places/' },
+            'place' => { 'href' => '/places/{id}', 'templated' => true },
+            'curies' => [{ 'name' => 'oxford', 'href' => '/docs/{rel}', 'templated' => true }],
+            'oxford:places' => { 'href' => '/places/' }
+          }
+        }]
+      when '/places/'
+        [200, { '_links' => { 'self' => { 'href' => '/places/' } },
+                '_embedded' => { 'places' => @places } }]
+      when '/docs/places'
+        [200, { 'description' => 'Archived Oxford place facts in a local HAL collection.' }]
+      else
+        place = @places.find { |item| item['_links']['self']['href'] == path }
+        place ? [200, place] : [404, { 'error' => 'Not included in this example' }]
+      end
+    end
+
+    def response(status, body)
+      [status, { 'content-type' => 'application/hal+json' }, [JSON.generate(body)]]
+    end
+  end
+end

data/examples/oxford/client.rb

@@ -0,0 +1,13 @@
+require 'hyperclient'
+
+api = Hyperclient.new(ENV.fetch('OXFORD_URL', 'http://127.0.0.1:9292/'))
+api.places.each do |place|
+  puts "#{place.name}: #{place.address}"
+end
+
+place = api.place(id: 'oxpoints:23232339')
+puts "Followed primary_place: #{place.primary_place.name}"
+place._embedded.files.each do |file|
+  puts "Archived #{file.type} URL (not fetched): #{file.url}"
+end
+puts "CURIE: #{api._links._curies['oxford'].expand('places')}"

data/examples/oxford/places.json

@@ -0,0 +1,21 @@
+[
+  {
+    "_links": {
+      "self": { "href": "/places/oxpoints:23232339" },
+      "primary_place": { "href": "/places/oxpoints:23232339" }
+    },
+    "_embedded": {
+      "files": [
+        {
+          "type": "depiction",
+          "url": "//mox-static-files.oucs.ox.ac.uk/oxpoints/23232339/depiction/original/ball.jpg"
+        }
+      ]
+    },
+    "id": "oxpoints:23232339",
+    "name": "Balliol College",
+    "address": "Broad Street OX1 3BJ",
+    "lat": "51.754425",
+    "lon": "-1.257216"
+  }
+]

data/examples/oxford/server.rb

@@ -0,0 +1,13 @@
+require 'webrick'
+require_relative 'app'
+
+app = OxfordExample::App.new
+server = WEBrick::HTTPServer.new(BindAddress: '127.0.0.1', Port: Integer(ENV.fetch('PORT', '9292')))
+server.mount_proc('/') do |request, response|
+  status, headers, body = app.call('REQUEST_METHOD' => request.request_method, 'PATH_INFO' => request.path)
+  response.status = status
+  headers.each { |key, value| response[key] = value }
+  response.body = body.join
+end
+%w[INT TERM].each { |signal| trap(signal) { server.shutdown } }
+server.start

data/features/support/env.rb

@@ -8,10 +8,11 @@ Spinach.config[:failure_exceptions] << Minitest::Assertion
 
 class Spinach::FeatureSteps
   include Minitest::Assertions
+
   attr_accessor :assertions
 
   def initialize(*args)
-    super(*args)
+    super
     self.assertions = 0
   end
 end

data/lib/hyperclient/link.rb

@@ -190,10 +190,19 @@ module Hyperclient
     end
 
     def http_method(method, body = nil)
-      @resource = begin
-        response = @entry_point.connection.run_request(method, _url, body, nil)
-        Resource.new(response.body, @entry_point, response)
-      end
+      response = @entry_point.connection.run_request(method, _url, body, nil)
+      resource = Resource.new(response.body, @entry_point, response)
+
+      # Only cache GET responses. Caching the response of a mutating
+      # request (POST/PUT/PATCH/DELETE) as `@resource` would make
+      # subsequent delegated calls (e.g. `#each`, `method_missing`) see
+      # the stale mutation response instead of fetching a fresh
+      # resource, requiring users to create a new client between a
+      # `_post` and a `_get`. See #107.
+      @resource = resource if method == :get
+      @delegate = nil
+
+      resource
     end
   end
 end

data/lib/hyperclient/resource.rb

@@ -66,6 +66,18 @@ module Hyperclient
       send(name) if respond_to?(name)
     end
 
+    # Public: Returns the attributes of the Resource as a Hash.
+    #
+    # Delegates explicitly (rather than relying on method_missing) since
+    # Array also defines #to_h (but not #to_hash), which meant the
+    # `Array.method_defined?(method)` guard in method_missing let #to_hash
+    # through but silently swallowed #to_h, returning nil instead of the
+    # attributes hash.
+    def to_h
+      _attributes.to_h
+    end
+    alias to_hash to_h
+
     def fetch(key, *args)
       return self[key] if respond_to?(key)
 

data/lib/hyperclient/version.rb

@@ -1,3 +1,3 @@
 module Hyperclient
-  VERSION = '2.0.0'.freeze
+  VERSION = '2.1.0'.freeze
 end

data/test/hyperclient/attributes_test.rb

@@ -36,5 +36,14 @@ module Hyperclient
     it 'is a collection' do
       _(Attributes.ancestors).must_include Collection
     end
+
+    describe 'when the representation is not a Hash' do
+      it 'wraps the representation as-is instead of filtering reserved keys' do
+        representation = 'not a hash'
+        attributes = Attributes.new(representation)
+
+        _(attributes.instance_variable_get(:@collection)).must_equal representation
+      end
+    end
   end
 end

data/test/hyperclient/collection_test.rb

@@ -41,6 +41,28 @@ module Hyperclient
       end
     end
 
+    describe '#to_h' do
+      it 'returns the wrapped collection as a hash' do
+        _(collection.to_h).must_be_kind_of Hash
+      end
+
+      it 'returns the same result as #to_hash' do
+        _(collection.to_h).must_equal(collection.to_hash)
+      end
+    end
+
+    describe '#to_s' do
+      it 'returns the wrapped collection as a hash' do
+        _(collection.to_s).must_be_kind_of Hash
+      end
+    end
+
+    describe '#method_missing' do
+      it 'raises an error for missing keys' do
+        _(proc { collection.missing_key }).must_raise RuntimeError
+      end
+    end
+
     describe 'include?' do
       it 'returns true for keys that exist' do
         _(collection.include?('_links')).must_equal true

data/test/hyperclient/curie_test.rb

@@ -34,5 +34,12 @@ module Hyperclient
         _(curie.expand('thumbnail')).must_equal '/images/thumbnail'
       end
     end
+
+    describe 'inspect' do
+      it 'outputs a custom-friendly output' do
+        _(curie.inspect).must_include 'Curie'
+        _(curie.inspect).must_include({ 'name' => 'image', 'href' => '/images/{rel}', 'templated' => true }.to_s)
+      end
+    end
   end
 end

data/test/hyperclient/entry_point_test.rb

@@ -21,6 +21,7 @@ module Hyperclient
         it 'can update headers after a connection has been constructed' do
           _(entry_point.connection).must_be_kind_of Faraday::Connection
           entry_point.headers.update('Content-Type' => 'application/foobar')
+
           _(entry_point.headers['Content-Type']).must_equal 'application/foobar'
         end
 
@@ -28,6 +29,7 @@ module Hyperclient
           _(entry_point.connection).must_be_kind_of Faraday::Connection
           entry_point.connection.use Faraday::Request::Instrumentation
           handlers = entry_point.connection.builder.handlers
+
           _(handlers).must_include Faraday::Request::Instrumentation
         end
 
@@ -51,6 +53,19 @@ module Hyperclient
           _(entry_point.connection).must_be_kind_of Faraday::Connection
           _(-> { entry_point.connection {} }).must_raise ConnectionAlreadyInitializedError
         end
+
+        it 'can set the faraday block before a connection has been constructed' do
+          block = proc { |conn| conn.use Faraday::Request::Instrumentation }
+          entry_point.faraday_block = block
+
+          _(entry_point.faraday_block).must_equal block
+        end
+
+        it 'raises a ConnectionAlreadyInitializedError if attempting to modify ' \
+           'the faraday block after a connection has been constructed' do
+          _(entry_point.connection).must_be_kind_of Faraday::Connection
+          _(-> { entry_point.faraday_block = proc {} }).must_raise ConnectionAlreadyInitializedError
+        end
       end
 
       describe 'initialize' do
@@ -136,6 +151,7 @@ module Hyperclient
 
         it 'creates a Faraday connection with the default block' do
           handlers = entry_point.connection.builder.handlers
+
           _(handlers).wont_include Faraday::Response::RaiseError
           _(handlers).wont_include Faraday::FollowRedirects
           _(handlers).must_include Faraday::Request::Json
@@ -178,5 +194,11 @@ module Hyperclient
         end
       end
     end
+
+    describe ConnectionAlreadyInitializedError do
+      it 'has a descriptive message' do
+        _(ConnectionAlreadyInitializedError.new.message).must_equal 'The connection has already been initialized.'
+      end
+    end
   end
 end

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