hyperclient 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: f6f97641ae8ac6b8ee5e917bb42885454ccfa4dfbe29f91fbe488266c3d8df1b
4
- data.tar.gz: 1b4da773e4b20cb6e4ba0e4acec481d586b9101d1cbc6010e0072b9366e7e495
3
+ metadata.gz: a8386e0cfaa50b2ee6b593a3adfbd18d510be2f614ac671eea8b10598c6e95eb
4
+ data.tar.gz: 16065c923d08bdeefd62f778052ac587362dd1dafa67f037524ca9c2b5b2c221
5
5
  SHA512:
6
- metadata.gz: 9786c186df822fa748372f4ad8591f949f53ea37625e78946da83e16572bec228e59c0cbfea2bb5f287c6b81f513e2a7b3c46ce98a7c0f8d48dc6ca88d4792ef
7
- data.tar.gz: 8a525a635faa47057352eb5bfb8cde4d65a3d81fd41e9a2c536bc465170249fa0dc8f84d00f8f7e865bb849a076160ce6ec9dc02ba8ac637c2dbc88a8c399e72
6
+ metadata.gz: b0bd84465e74d3eb2b7b9f0e2c5c9141a58c2f107390ca1da5d4742ff6420875abbd3d637ccfd67fc053503868b14e7129a6ba49020457f0715ffd5d92addd60
7
+ data.tar.gz: 0d6e6116a470e3720f0789fdb072b041955685135b667982fa1153a010106b860a2828363cceca09a5f43b66271336d92a90adc6e6395030272d64d32809b8c5
@@ -1,6 +1,13 @@
1
1
  ---
2
2
  name: coverage
3
- on: [push, pull_request]
3
+ on:
4
+ push:
5
+ branches: [master]
6
+ pull_request:
7
+
8
+ concurrency:
9
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
10
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
4
11
 
5
12
  env:
6
13
  COVERAGE: 1
@@ -9,7 +16,7 @@ jobs:
9
16
  build:
10
17
  runs-on: ubuntu-latest
11
18
  steps:
12
- - uses: actions/checkout@v3
19
+ - uses: actions/checkout@v7
13
20
  - uses: ruby/setup-ruby@v1
14
21
  with:
15
22
  ruby-version: '4.0'
@@ -5,7 +5,14 @@ on:
5
5
  workflows: [Danger]
6
6
  types: [completed]
7
7
 
8
+ permissions:
9
+ actions: read # download artifacts
10
+ issues: write # list + create/update comments
11
+ pull-requests: write # PR comment access
12
+
8
13
  jobs:
9
14
  comment:
10
- uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@v0.1.0
15
+ uses: danger/danger-pr-comment/.github/workflows/danger-comment.yml@v0.3.0
11
16
  secrets: inherit
17
+ with:
18
+ comment-empty: false
@@ -6,7 +6,7 @@ on:
6
6
 
7
7
  jobs:
8
8
  danger:
9
- uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0
9
+ uses: danger/danger-pr-comment/.github/workflows/danger-run.yml@v0.3.0
10
10
  secrets: inherit
11
11
  with:
12
12
  ruby-version: '4.0'
@@ -1,12 +1,19 @@
1
1
  name: lint
2
- on: [push, pull_request]
2
+ on:
3
+ push:
4
+ branches: [master]
5
+ pull_request:
6
+
7
+ concurrency:
8
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
9
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
3
10
  jobs:
4
11
  rubocop:
5
12
  name: RuboCop
6
13
  runs-on: ubuntu-latest
7
14
  steps:
8
15
  - name: Checkout
9
- uses: actions/checkout@v3
16
+ uses: actions/checkout@v7
10
17
  - name: Set up Ruby
11
18
  uses: ruby/setup-ruby@v1
12
19
  with:
@@ -0,0 +1,26 @@
1
+ name: Release
2
+
3
+ on:
4
+ workflow_dispatch:
5
+ inputs:
6
+ version:
7
+ description: Optional release version overriding the checked-in version.
8
+ type: string
9
+ required: false
10
+ dry-run:
11
+ description: Check release prerequisites without releasing.
12
+ type: boolean
13
+ default: false
14
+
15
+ permissions:
16
+ contents: write
17
+ id-token: write
18
+
19
+ jobs:
20
+ release:
21
+ uses: dblock/ruby-gem-release/.github/workflows/release.yml@v0.9.0
22
+ with:
23
+ ruby-version: '4.0'
24
+ gemfile: gemfiles/release.gemfile
25
+ version: ${{ inputs.version }}
26
+ dry-run: ${{ inputs.dry-run }}
@@ -1,9 +1,16 @@
1
1
  ---
2
2
  name: test
3
- on: [push, pull_request]
3
+ on:
4
+ push:
5
+ branches: [master]
6
+ pull_request:
7
+
8
+ concurrency:
9
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
10
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
4
11
  jobs:
5
12
  test:
6
- runs-on: ubuntu-latest
13
+ runs-on: ${{ matrix.entry.os || 'ubuntu-latest' }}
7
14
  strategy:
8
15
  fail-fast: false
9
16
  matrix:
@@ -12,17 +19,21 @@ jobs:
12
19
  - { ruby: '3.4' }
13
20
  - { ruby: '3.2', json: '2' }
14
21
  - { ruby: '3.2' }
15
- - { ruby: '2.7', json: '2' }
22
+ - { ruby: '2.7', json: '2', os: 'ubuntu-22.04' }
16
23
  - { ruby: 'ruby-head', allowed-failure: true }
17
24
  - { ruby: 'jruby-head', allowed-failure: true }
18
25
  name: test (Ruby ${{ matrix.entry.ruby }}, JSON ${{ matrix.entry.json || '3' }})
19
26
  env:
20
27
  JSON_VERSION: ${{ matrix.entry.json || '3' }}
28
+ # Speeds up JRuby startup, which dominates its bundle and test steps. CRuby ignores it.
29
+ JRUBY_OPTS: --dev
21
30
  steps:
22
- - uses: actions/checkout@v3
31
+ - uses: actions/checkout@v7
23
32
  - uses: ruby/setup-ruby@v1
24
33
  with:
25
34
  ruby-version: ${{ matrix.entry.ruby }}
26
35
  bundler-cache: true
36
+ # Gemfile.lock isn't committed, so keep JSON 2 and JSON 3 bundles from restoring each other's cache.
37
+ cache-version: json-${{ matrix.entry.json || '3' }}
27
38
  - run: bundle exec rake test spinach
28
39
  continue-on-error: ${{ matrix.entry.allowed-failure || false }}
data/.gitignore CHANGED
@@ -17,3 +17,5 @@ test/version_tmp
17
17
  tmp
18
18
  examples/william.rb
19
19
  Gemfile.lock
20
+ gemfiles/*.lock
21
+ vendor/bundle
data/CHANGELOG.md CHANGED
@@ -1,5 +1,16 @@
1
1
  ## Changelog
2
2
 
3
+ ### 2.2.0 (2026/11/22)
4
+
5
+ * [#333](https://github.com/codegram/hyperclient/pull/333): Updated danger-pr-comment to 0.2.0 and fixed the hash conversion assertion for Minitest 6.1 - [@dblock](https://github.com/dblock).
6
+ * [#334](https://github.com/codegram/hyperclient/pull/334): Added `Link#_query` to send query parameters that a link doesn't declare - [@dblock](https://github.com/dblock).
7
+ * [#336](https://github.com/codegram/hyperclient/pull/336): Fixed `SystemStackError` when iterating a link whose resource links back to itself under the same name, raising `Hyperclient::SelfReferencingLinkError` instead - [@dblock](https://github.com/dblock).
8
+ * [#337](https://github.com/codegram/hyperclient/pull/337): Updated danger-pr-comment to 0.3.0 and stopped posting empty Danger reports - [@dblock](https://github.com/dblock).
9
+ * [#338](https://github.com/codegram/hyperclient/pull/338): Documented link properties, including HAL `profile` via `Link#_profile` - [@dblock](https://github.com/dblock).
10
+ * [#339](https://github.com/codegram/hyperclient/pull/339): Sped up CI by running JRuby with `--dev`, separating JSON 2 and JSON 3 bundler caches, skipping duplicate branch builds, and updating `actions/checkout` to v7 - [@dblock](https://github.com/dblock).
11
+ * [#340](https://github.com/codegram/hyperclient/pull/340): Added `Link#_allow`, `Link#_allow?`, `Resource#_allow` and `Resource#_allow?` to read the `Allow` header, and an opt-in `enforce_allowed_methods` setting that raises `Hyperclient::MethodNotAllowedError` instead of sending a method the link's most recent response disallowed - [@dblock](https://github.com/dblock).
12
+ * [#341](https://github.com/codegram/hyperclient/pull/341): Added a Release workflow using [ruby-gem-release](https://github.com/dblock/ruby-gem-release) and RubyGems Trusted Publishing, and disabled the local `rake release` task - [@dblock](https://github.com/dblock).
13
+
3
14
  ### 2.1.0 (2026/10/14)
4
15
 
5
16
  * [#328](https://github.com/codegram/hyperclient/pull/328): Replaced the retired Splines demo with a local read-only Oxford HAL example using archived place facts - [@dblock](https://github.com/dblock).
data/Gemfile CHANGED
@@ -24,13 +24,19 @@ group :development, :test do
24
24
  end
25
25
 
26
26
  group :test do
27
- gem 'danger', '~> 9.5'
28
- gem 'danger-changelog', '~> 0.8.0'
29
- gem 'danger-pr-comment', '~> 0.1.0'
30
- gem 'danger-toc', '~> 0.2.0'
31
27
  gem 'minitest'
32
28
  gem 'mocha'
33
29
  gem 'rack-test'
34
30
  gem 'spinach'
35
31
  gem 'webmock'
36
32
  end
33
+
34
+ # Danger runs separately on Ruby 4.0; its plugins require Ruby 3.1+.
35
+ if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.1')
36
+ group :danger do
37
+ gem 'danger', '~> 9.5'
38
+ gem 'danger-changelog', '~> 0.10.0'
39
+ gem 'danger-pr-comment', '~> 0.3.0'
40
+ gem 'danger-toc', '~> 0.3.0'
41
+ end
42
+ end
data/README.md CHANGED
@@ -13,9 +13,12 @@ Hyperclient is a Hypermedia API client written in Ruby. It fully supports [JSON
13
13
  - [Resources and Attributes](#resources-and-attributes)
14
14
  - [Links and Embedded Resources](#links-and-embedded-resources)
15
15
  - [Templated Links](#templated-links)
16
+ - [Query Parameters](#query-parameters)
17
+ - [Link Properties](#link-properties)
16
18
  - [Curies](#curies)
17
19
  - [Attributes](#attributes)
18
20
  - [HTTP](#http)
21
+ - [Allowed Methods](#allowed-methods)
19
22
  - [Testing Using Hyperclient](#testing-using-hyperclient)
20
23
  - [Reference](#reference)
21
24
  - [Hyperclient Users](#hyperclient-users)
@@ -156,6 +159,34 @@ Invoking `api.place(id: 'oxpoints:23232339').name` is equivalent to `api._links.
156
159
 
157
160
  The client is responsible for supplying all the necessary parameters. Templated links don't do any strict parameter name checking and don't support required vs. optional parameters. Parameters not declared by the API will be dropped and will not have any effect when passed to `_expand`.
158
161
 
162
+ ## Query Parameters
163
+
164
+ HAL APIs declare the query parameters they accept in templated links, and `_expand` only fills in those. To send query parameters that a link doesn't declare, or to add them to a link that isn't templated, use `_query`. It returns a new link with the parameters appended to its URL, after any existing query string.
165
+
166
+ ```ruby
167
+ api._links.places._query(sort: 'name')._get # GET /places/?sort=name
168
+ api._links.place._expand(id: 'oxpoints:23232339')._query(fields: 'name')._get # GET /places/oxpoints%3A23232339?fields=name
169
+ ```
170
+
171
+ Array values are sent as repeated parameters, and parameters with `nil` values are dropped.
172
+
173
+ ## Link Properties
174
+
175
+ HAL links can carry optional [properties](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-11#section-5) besides `href` and `templated`. Hyperclient exposes them as `_type`, `_deprecation`, `_name`, `_profile`, `_title`, and `_hreflang`, each returning `nil` when the property is absent. The local demo gives its `places` link a `title` and a `profile`.
176
+
177
+ ```ruby
178
+ puts api._links.places._title # => Oxford places
179
+ puts api._links.places._profile # => /docs/places
180
+ ```
181
+
182
+ A [`profile`](https://datatracker.ietf.org/doc/html/rfc6906) is a URI that documents the semantics of the target resource, beyond what the media type describes. Hyperclient returns it as-is and doesn't follow it, since a profile isn't necessarily a HAL resource. Fetch it with the client's Faraday connection if you need it.
183
+
184
+ ```ruby
185
+ puts api.connection.get(api._links.places._profile).body['description'] # => Archived Oxford place facts in a local HAL collection.
186
+ ```
187
+
188
+ A link with a `deprecation` property will be removed in the future, and `_deprecation` returns a URL with more information about the deprecation.
189
+
159
190
  ## Curies
160
191
 
161
192
  Curies provide compact names for relation documentation. The local demo adds an `oxford` CURIE and an `oxford:places` relation.
@@ -214,6 +245,39 @@ place._delete
214
245
 
215
246
  HTTP methods always return a new instance of Resource.
216
247
 
248
+ ## Allowed Methods
249
+
250
+ Hyperclient remembers the `Allow` header of the most recent response on the link that made the request, including a `405 Method Not Allowed` response, whose `Allow` header lists the methods the server supports. Each response replaces what the link knows. Use `_allow` and `_allow?` to check before sending a request.
251
+
252
+ ```ruby
253
+ order = api.order(id: 1) # a server responding with "Allow: GET, HEAD, OPTIONS"
254
+ order._get
255
+ order._allow # => ["GET", "HEAD", "OPTIONS"], or nil without an Allow header
256
+ order._allow?(:delete) # => false
257
+ ```
258
+
259
+ By default, Hyperclient still sends any method and leaves it to the server to refuse it. Set `enforce_allowed_methods` to have links refuse to send a method that their most recent `Allow` header doesn't list, raising `Hyperclient::MethodNotAllowedError` without contacting the server. A response without an `Allow` header lifts the restriction, and `_options` is always sent so you can rediscover the allowed methods.
260
+
261
+ ```ruby
262
+ api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
263
+ client.enforce_allowed_methods = true
264
+ end
265
+
266
+ order = api.order(id: 1) # a server responding with "Allow: GET, HEAD, OPTIONS"
267
+ order._get
268
+
269
+ begin
270
+ order._delete
271
+ rescue Hyperclient::MethodNotAllowedError => e
272
+ e.message # => "DELETE is not allowed on /orders/1, the server allows only GET, HEAD, OPTIONS."
273
+ e.allowed # => ["GET", "HEAD", "OPTIONS"]
274
+ end
275
+ ```
276
+
277
+ Methods are compared case-insensitively, an empty `Allow` header means no methods are allowed, and `HEAD` is only allowed when listed. A resource also exposes the `Allow` header of the response that created it with `_allow` and `_allow?`. Hyperclient never sends extra `OPTIONS` requests.
278
+
279
+ There is no method to clear or override what a link remembers. With `enforce_allowed_methods` on, the remembered `Allow` header is replaced by the link's next response, so call `_options` to ask the server again. Alternatively, use a new link object, which starts without restrictions, such as `link._expand` or a link from a freshly fetched resource.
280
+
217
281
  # Testing Using Hyperclient
218
282
 
219
283
  You can combine RSpec, Faraday::Adapter::Rack and Hyperclient to test your HAL API without having to ever examine the raw JSON response.
data/RELEASING.md CHANGED
@@ -2,74 +2,57 @@
2
2
 
3
3
  Release bug fixes frequently, features less frequently, and breaking API changes rarely.
4
4
 
5
- ## Prepare the Release
5
+ Releases run through the [Release workflow](.github/workflows/release.yml), which uses [ruby-gem-release](https://github.com/dblock/ruby-gem-release/tree/v0.9.0) and RubyGems Trusted Publishing. Merging does not publish anything, and the local Bundler `rake release` task is disabled.
6
6
 
7
- Start with a clean, up-to-date `master` branch. Check that CI has succeeded for all supported platforms.
7
+ ## One-Time Setup
8
8
 
9
- 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.
9
+ Create a GitHub environment named `release` in this repository, for example with `gh api --method PUT repos/codegram/hyperclient/environments/release`. To require a maintainer's approval before publication, add required reviewers and restrict deployment to `master`.
10
10
 
11
- 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.
11
+ On RubyGems, open the [hyperclient trusted publishers](https://rubygems.org/gems/hyperclient/trusted_publishers) page and add a GitHub Actions publisher with repository owner `codegram`, repository name `hyperclient`, workflow filename `release.yml`, and environment `release`. Set the separate workflow repository owner to `dblock` and name to `ruby-gem-release`, because publication runs in that reusable workflow. No RubyGems API key is stored.
12
12
 
13
- Run the full suite, then commit and push the release preparation:
13
+ The workflow needs to push the release commit, the `vVERSION` tag, and the next development commit to `master`. Branch and tag rules must allow that; every release checks them before publishing.
14
14
 
15
- ```sh
16
- bundle install
17
- bundle exec rake
18
- git add CHANGELOG.md lib/hyperclient/version.rb
19
- git commit -m "Preparing for release, 2.1.0."
20
- git push origin master
21
- ```
15
+ ## Prepare the Release
16
+
17
+ Releases publish the version in [lib/hyperclient/version.rb](lib/hyperclient/version.rb) with the notes in its `### VERSION (Next)` section of [CHANGELOG.md](CHANGELOG.md). Use a patch version for backward-compatible fixes, a minor version for backward-compatible features, and a major version for breaking changes. To change it, update both files in a pull request, or pass a different version when starting the release.
22
18
 
23
- Wait for CI on the release preparation commit to succeed before publishing.
19
+ Check that CI has succeeded on `master`, and don't merge anything while a release is running.
24
20
 
25
- ## Publish to RubyGems and GitHub
21
+ ## Release
26
22
 
27
- 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.
23
+ Check the setup without releasing anything:
28
24
 
29
25
  ```sh
30
- bundle exec rake release
26
+ gh workflow run release.yml --repo codegram/hyperclient --ref master -f dry-run=true
31
27
  ```
32
28
 
33
- 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:
29
+ Then release the checked-in version:
34
30
 
35
31
  ```sh
36
- version=2.1.0
37
- notes="$(mktemp)"
38
- awk -v version="$version" '
39
- /^### / {
40
- if (found) exit
41
- if ($2 == version) found = 1
42
- next
43
- }
44
- found { print }
45
- ' CHANGELOG.md > "$notes"
46
- gh release create "v$version" --repo codegram/hyperclient --verify-tag --title "$version" --notes-file "$notes" --latest
47
- rm "$notes"
32
+ gh workflow run release.yml --repo codegram/hyperclient --ref master
48
33
  ```
49
34
 
50
- Verify both publications before considering the release complete:
35
+ To release a different version, pass `-f version=2.3.0`.
36
+
37
+ The workflow runs `bundle exec rake` on Ruby 4.0 with [gemfiles/release.gemfile](gemfiles/release.gemfile), dates the changelog section and removes its "Your contribution here." placeholder, publishes the gem to RubyGems, pushes the release commit and tag, and creates a GitHub Release with the changelog notes. It then increments the patch version and pushes a new `### VERSION (Next)` section to `master`.
38
+
39
+ ## Verify and Recover
40
+
41
+ Check the RubyGems version, the matching tag and GitHub Release, and the next development version on `master`:
51
42
 
52
43
  ```sh
44
+ version=2.2.0
53
45
  curl --fail --silent --show-error "https://rubygems.org/api/v2/rubygems/hyperclient/versions/$version.json"
54
46
  gh release view "v$version" --repo codegram/hyperclient
55
47
  ```
56
48
 
57
- 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.
58
-
59
- ## Prepare the Next Version
49
+ Don't rerun a failed release blindly: RubyGems may have accepted the gem. Inspect the existing tag, RubyGems version, and GitHub Release first, and never republish a version or move its tag. Follow the [ruby-gem-release recovery instructions](https://github.com/dblock/ruby-gem-release/blob/v0.9.0/docs/actions/release.md#recovery-artifacts) to complete only the missing steps.
60
50
 
61
- 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):
62
-
63
- ```markdown
64
- ### 2.1.1 (Next)
65
-
66
- * Your contribution here.
67
- ```
51
+ ## Run the Release Tasks Locally
68
52
 
69
- Commit and push:
53
+ The release tasks need Ruby 3.3+ and the release bundle:
70
54
 
71
55
  ```sh
72
- git add CHANGELOG.md lib/hyperclient/version.rb
73
- git commit -m "Preparing for next release, 2.1.1."
74
- git push origin master
56
+ BUNDLE_GEMFILE=gemfiles/release.gemfile bundle install
57
+ BUNDLE_GEMFILE=gemfiles/release.gemfile bundle exec rake -T release
75
58
  ```
data/Rakefile CHANGED
@@ -6,6 +6,24 @@ Bundler.setup :default, :test, :development
6
6
 
7
7
  Bundler::GemHelper.install_tasks
8
8
 
9
+ # Releases run through the Release workflow, see RELEASING.md.
10
+ %w[release release:rubygem_push release:source_control_push].each do |name|
11
+ Rake::Task[name].clear
12
+ desc 'Disabled, releases run through the Release workflow (see RELEASING.md)'
13
+ task(name) { abort "#{name} is disabled; releases run through GitHub Actions, see RELEASING.md" }
14
+ end
15
+
16
+ # The release tasks are only installed with BUNDLE_GEMFILE=gemfiles/release.gemfile.
17
+ if Gem.loaded_specs.key?('ruby-gem-release')
18
+ require 'ruby-gem-release/workflow/ruby_gem'
19
+ require 'ruby-gem-release/changelog'
20
+
21
+ RubyGemRelease::Workflow::RubyGem.new(
22
+ version: RubyGemRelease::Version::RubyConstant.new(path: 'lib/hyperclient/version.rb', constant: 'VERSION'),
23
+ changelog: RubyGemRelease::Changelog::Intridea.new(placeholder: '* Your contribution here.')
24
+ ).install_tasks
25
+ end
26
+
9
27
  require 'rake/testtask'
10
28
 
11
29
  Rake::TestTask.new(:test) do |t|
@@ -24,7 +24,7 @@ module OxfordExample
24
24
  [200, {
25
25
  '_links' => {
26
26
  'self' => { 'href' => '/' },
27
- 'places' => { 'href' => '/places/' },
27
+ 'places' => { 'href' => '/places/', 'title' => 'Oxford places', 'profile' => '/docs/places' },
28
28
  'place' => { 'href' => '/places/{id}', 'templated' => true },
29
29
  'curies' => [{ 'name' => 'oxford', 'href' => '/docs/{rel}', 'templated' => true }],
30
30
  'oxford:places' => { 'href' => '/places/' }
@@ -11,3 +11,4 @@ place._embedded.files.each do |file|
11
11
  puts "Archived #{file.type} URL (not fetched): #{file.url}"
12
12
  end
13
13
  puts "CURIE: #{api._links._curies['oxford'].expand('places')}"
14
+ puts "Places profile: #{api._links.places._profile}"
@@ -0,0 +1,6 @@
1
+ # Bundle used by the Release workflow, see RELEASING.md.
2
+ # ruby-gem-release requires Ruby 3.3+, so it is kept out of the main Gemfile.
3
+ eval_gemfile '../Gemfile'
4
+
5
+ gem 'commonmarker', '~> 2.10', require: false
6
+ gem 'ruby-gem-release', '0.9.0', require: false
@@ -42,6 +42,7 @@ module Hyperclient
42
42
  @resource = nil
43
43
  @key = nil
44
44
  @uri_variables = nil
45
+ @enforce_allowed_methods = false
45
46
  yield self if block_given?
46
47
  end
47
48
 
@@ -124,6 +125,19 @@ module Hyperclient
124
125
  # value - A Hash containing the client options.
125
126
  attr_accessor :options
126
127
 
128
+ # Public: Set whether links refuse to send a method that the Allow header
129
+ # of their most recent response doesn't list, raising
130
+ # MethodNotAllowedError instead. Defaults to false.
131
+ attr_writer :enforce_allowed_methods
132
+
133
+ # Public: Indicates if links enforce the methods allowed by the Allow
134
+ # header.
135
+ #
136
+ # Returns true if enabled, false otherwise.
137
+ def enforce_allowed_methods?
138
+ @enforce_allowed_methods == true
139
+ end
140
+
127
141
  private
128
142
 
129
143
  # Internal: Returns a block to initialize the Faraday connection. The
@@ -1,6 +1,38 @@
1
1
  require 'addressable'
2
2
 
3
3
  module Hyperclient
4
+ # Public: Exception that is raised when iterating a link whose resource
5
+ # links back to itself under the same name, which would otherwise recurse
6
+ # forever.
7
+ class SelfReferencingLinkError < StandardError
8
+ def initialize(key, url)
9
+ super("The #{key} link at #{url} links back to itself, use _embedded to iterate over embedded items.")
10
+ end
11
+ end
12
+
13
+ # Public: Exception that is raised before sending a request with a method
14
+ # that the most recent response for the same Link excluded from its Allow
15
+ # header.
16
+ class MethodNotAllowedError < StandardError
17
+ # Public: Returns the upper-case String HTTP method that was refused.
18
+ attr_reader :http_method
19
+
20
+ # Public: Returns the String url of the Link.
21
+ attr_reader :url
22
+
23
+ # Public: Returns the Array of upper-case String methods that the server
24
+ # allows.
25
+ attr_reader :allowed
26
+
27
+ def initialize(http_method, url, allowed)
28
+ @http_method = http_method
29
+ @url = url
30
+ @allowed = allowed
31
+ allows = allowed.empty? ? 'no methods' : "only #{allowed.join(', ')}"
32
+ super("#{http_method} is not allowed on #{url}, the server allows #{allows}.")
33
+ end
34
+ end
35
+
4
36
  # Internal: The Link is used to let a Resource interact with the API.
5
37
  #
6
38
  class Link
@@ -13,12 +45,29 @@ module Hyperclient
13
45
  # entry_point - The EntryPoint object to inject the configuration.
14
46
  # uri_variables - The optional Hash with the variables to expand the link
15
47
  # if it is templated.
16
- def initialize(key, link, entry_point, uri_variables = nil)
48
+ # query_params - The optional Hash with query parameters to add to the
49
+ # link's URL.
50
+ def initialize(key, link, entry_point, uri_variables = nil, query_params = nil)
17
51
  @key = key
18
52
  @link = link
19
53
  @entry_point = entry_point
20
54
  @uri_variables = uri_variables
55
+ @query_params = query_params
21
56
  @resource = nil
57
+ @allow = nil
58
+ end
59
+
60
+ # Internal: Parses the Allow header from response headers.
61
+ #
62
+ # headers - The Hash-like response headers, or nil.
63
+ #
64
+ # Returns nil when there is no Allow header, otherwise an Array of
65
+ # upper-case String methods, which is empty when the header is empty.
66
+ def self.parse_allow(headers)
67
+ value = headers && (headers['Allow'] || headers['allow'])
68
+ return if value.nil?
69
+
70
+ Array(value).join(',').split(',').map { |m| m.strip.upcase }.reject(&:empty?).uniq
22
71
  end
23
72
 
24
73
  # Public: Each implementation to allow the class to use the Enumerable
@@ -30,6 +79,8 @@ module Hyperclient
30
79
  current = self
31
80
  while current
32
81
  coll = current.respond_to?(@key) ? current.send(@key) : _resource
82
+ raise SelfReferencingLinkError.new(@key, current._url) if current.self_referencing?(coll)
83
+
33
84
  coll.each(&block)
34
85
  break unless current._links[:next]
35
86
 
@@ -54,14 +105,22 @@ module Hyperclient
54
105
  #
55
106
  # Returns a new Link with the expanded variables.
56
107
  def _expand(uri_variables = {})
57
- self.class.new(@key, @link, @entry_point, uri_variables)
108
+ self.class.new(@key, @link, @entry_point, uri_variables, @query_params)
109
+ end
110
+
111
+ # Public: Adds query parameters to the Link's URL, whether or not the link
112
+ # is templated or declares them. Parameters with nil values are dropped.
113
+ #
114
+ # query_params - The Hash with the query parameters to add.
115
+ #
116
+ # Returns a new Link with the query parameters.
117
+ def _query(query_params = {})
118
+ self.class.new(@key, @link, @entry_point, @uri_variables, (@query_params || {}).merge(query_params))
58
119
  end
59
120
 
60
121
  # Public: Returns the url of the Link.
61
122
  def _url
62
- return @link['href'] unless _templated?
63
-
64
- @url ||= _uri_template.expand(@uri_variables || {}).to_s
123
+ @url ||= _add_query_params(_templated? ? _uri_template.expand(@uri_variables || {}).to_s : @link['href'])
65
124
  end
66
125
 
67
126
  # Public: Returns an array of variables from the URITemplate.
@@ -101,6 +160,25 @@ module Hyperclient
101
160
  @link['hreflang']
102
161
  end
103
162
 
163
+ # Public: Returns the methods listed in the Allow header of the most
164
+ # recent response for this Link, as upper-case Strings.
165
+ #
166
+ # Returns nil if no response has been received yet or the most recent
167
+ # response did not carry an Allow header.
168
+ def _allow
169
+ @allow&.dup
170
+ end
171
+
172
+ # Public: Indicates if the server allows the given method on this Link,
173
+ # according to the Allow header of the most recent response.
174
+ #
175
+ # method - A Symbol or String HTTP method, case-insensitive.
176
+ #
177
+ # Returns true if the method is allowed or no Allow header was received.
178
+ def _allow?(method)
179
+ @allow.nil? || @allow.include?(method.to_s.upcase)
180
+ end
181
+
104
182
  def _resource
105
183
  @resource || _get
106
184
  end
@@ -161,6 +239,7 @@ module Hyperclient
161
239
  return unless @key && _resource.respond_to?(@key)
162
240
 
163
241
  @delegate ||= _resource.send(@key)
242
+ return if self_referencing?(@delegate)
164
243
  return unless @delegate&.respond_to?(method.to_s)
165
244
 
166
245
  @delegate.send(method, *args, &block)
@@ -169,13 +248,21 @@ module Hyperclient
169
248
  # Internal: Accessory method to allow the link respond to the
170
249
  # methods that will hit method_missing.
171
250
  def respond_to_missing?(method, _include_private = false)
172
- if @key && _resource.respond_to?(@key) && (delegate = _resource.send(@key)) && delegate.respond_to?(method.to_s)
251
+ if @key && _resource.respond_to?(@key) && (delegate = _resource.send(@key)) &&
252
+ !self_referencing?(delegate) && delegate.respond_to?(method.to_s)
173
253
  true
174
254
  else
175
255
  _resource.respond_to?(method.to_s)
176
256
  end
177
257
  end
178
258
 
259
+ # Internal: Indicates if the given object is a Link to this same URL,
260
+ # following which would recurse forever.
261
+ def self_referencing?(other)
262
+ other.is_a?(Link) && other._url == _url
263
+ end
264
+ protected :self_referencing?
265
+
179
266
  # Internal: avoid delegating to resource
180
267
  #
181
268
  # #to_ary is called for implicit array coercion (such as parallel assignment
@@ -189,8 +276,37 @@ module Hyperclient
189
276
  @uri_template ||= Addressable::Template.new(@link['href'])
190
277
  end
191
278
 
279
+ # Internal: Appends the query parameters to the URL, keeping its existing
280
+ # query string and fragment.
281
+ def _add_query_params(url)
282
+ params = (@query_params || {}).compact
283
+ return url if params.empty?
284
+
285
+ uri = Addressable::URI.parse(url)
286
+ uri.query = [uri.query, Addressable::URI.form_encode(params)].compact.reject(&:empty?).join('&')
287
+ uri.to_s
288
+ end
289
+
290
+ # Internal: Raises MethodNotAllowedError if the most recent response for
291
+ # this Link excluded the method from its Allow header. OPTIONS is always
292
+ # sent, so that callers can rediscover the allowed methods.
293
+ def ensure_allowed!(method)
294
+ return if method == :options || _allow?(method) || !@entry_point.enforce_allowed_methods?
295
+
296
+ raise MethodNotAllowedError.new(method.to_s.upcase, _url, @allow.dup)
297
+ end
298
+
192
299
  def http_method(method, body = nil)
193
- response = @entry_point.connection.run_request(method, _url, body, nil)
300
+ ensure_allowed!(method)
301
+
302
+ begin
303
+ response = @entry_point.connection.run_request(method, _url, body, nil)
304
+ rescue Faraday::Error => e
305
+ @allow = Link.parse_allow(e.response_headers) if e.response
306
+ raise
307
+ end
308
+
309
+ @allow = Link.parse_allow(response.headers)
194
310
  resource = Resource.new(response.body, @entry_point, response)
195
311
 
196
312
  # Only cache GET responses. Caching the response of a mutating
@@ -62,6 +62,21 @@ module Hyperclient
62
62
  _response&.status
63
63
  end
64
64
 
65
+ # Public: Returns the methods listed in the Allow header of the response
66
+ # that created this resource, as upper-case Strings, or nil if there is no
67
+ # response or it did not carry an Allow header.
68
+ def _allow
69
+ Link.parse_allow(_response&.headers)
70
+ end
71
+
72
+ # Public: Indicates if the response that created this resource allows the
73
+ # given Symbol or String HTTP method, case-insensitive. Returns true if
74
+ # there is no Allow header.
75
+ def _allow?(method)
76
+ allow = _allow
77
+ allow.nil? || allow.include?(method.to_s.upcase)
78
+ end
79
+
65
80
  def [](name)
66
81
  send(name) if respond_to?(name)
67
82
  end
@@ -1,3 +1,3 @@
1
1
  module Hyperclient
2
- VERSION = '2.1.0'.freeze
2
+ VERSION = '2.2.0'.freeze
3
3
  end
@@ -123,6 +123,20 @@ module Hyperclient
123
123
  end
124
124
  end
125
125
 
126
+ describe 'enforce_allowed_methods' do
127
+ it 'is disabled by default' do
128
+ _(EntryPoint.new('http://my.api.org').enforce_allowed_methods?).must_equal false
129
+ end
130
+
131
+ it 'can be enabled in the block' do
132
+ entry_point = EntryPoint.new('http://my.api.org') do |client|
133
+ client.enforce_allowed_methods = true
134
+ end
135
+
136
+ _(entry_point.enforce_allowed_methods?).must_equal true
137
+ end
138
+ end
139
+
126
140
  describe 'custom' do
127
141
  let(:entry_point) do
128
142
  EntryPoint.new 'http://my.api.org' do |entry_point|
@@ -101,6 +101,68 @@ module Hyperclient
101
101
  end
102
102
  end
103
103
 
104
+ describe '_query' do
105
+ it 'adds query parameters to a link that is not templated' do
106
+ link = Link.new('key', { 'href' => '/orders' }, entry_point)
107
+
108
+ _(link._query(sort: 'name')._url).must_equal '/orders?sort=name'
109
+ end
110
+
111
+ it 'adds query parameters a templated link does not declare' do
112
+ link = Link.new('key', { 'href' => '/orders{?id}', 'templated' => true }, entry_point)
113
+
114
+ _(link._expand(id: '1')._query(sort: 'name')._url).must_equal '/orders?id=1&sort=name'
115
+ end
116
+
117
+ it 'keeps query parameters when expanded afterwards' do
118
+ link = Link.new('key', { 'href' => '/orders{?id}', 'templated' => true }, entry_point)
119
+
120
+ _(link._query(sort: 'name')._expand(id: '1')._url).must_equal '/orders?id=1&sort=name'
121
+ end
122
+
123
+ it 'keeps the existing query string and fragment' do
124
+ link = Link.new('key', { 'href' => '/orders?status=open&status=paid#top' }, entry_point)
125
+
126
+ _(link._query(sort: 'name')._url).must_equal '/orders?status=open&status=paid&sort=name#top'
127
+ end
128
+
129
+ it 'combines chained query parameters' do
130
+ link = Link.new('key', { 'href' => '/orders' }, entry_point)
131
+
132
+ _(link._query(sort: 'name')._query(page: 2, sort: 'date')._url).must_equal '/orders?sort=date&page=2'
133
+ end
134
+
135
+ it 'encodes values and repeats array parameters' do
136
+ link = Link.new('key', { 'href' => '/orders' }, entry_point)
137
+
138
+ _(link._query(q: 'a&b c', ids: [1, 2])._url).must_equal '/orders?q=a%26b+c&ids=1&ids=2'
139
+ end
140
+
141
+ it 'drops nil and empty query parameters' do
142
+ link = Link.new('key', { 'href' => '/orders' }, entry_point)
143
+
144
+ _(link._query(sort: nil)._url).must_equal '/orders'
145
+ _(link._query({})._url).must_equal '/orders'
146
+ end
147
+
148
+ it 'does not change the original link' do
149
+ link = Link.new('key', { 'href' => '/orders' }, entry_point)
150
+ link._query(sort: 'name')
151
+
152
+ _(link._url).must_equal '/orders'
153
+ end
154
+
155
+ it 'sends the query parameters with the request' do
156
+ link = Link.new('key', { 'href' => '/orders' }, entry_point)
157
+
158
+ stub_request(entry_point.connection) do |stub|
159
+ stub.get('http://api.example.org/orders?sort=name') { [200, {}, { 'sorted' => true }] }
160
+ end
161
+
162
+ _(link._query(sort: 'name')._get.sorted).must_equal true
163
+ end
164
+ end
165
+
104
166
  describe '_url' do
105
167
  it 'expands an uri template without variables' do
106
168
  link = Link.new('key', { 'href' => '/orders{?id}', 'templated' => true }, entry_point)
@@ -315,6 +377,209 @@ module Hyperclient
315
377
  end
316
378
  end
317
379
 
380
+ describe 'Allow header' do
381
+ let(:link) { Link.new('key', { 'href' => '/productions/1' }, entry_point) }
382
+ let(:url) { 'http://api.example.org/productions/1' }
383
+
384
+ it 'does not know the allowed methods before a request' do
385
+ _(link._allow).must_be_nil
386
+ _(link._allow?(:delete)).must_equal true
387
+ end
388
+
389
+ it 'sends any method when the response has no Allow header' do
390
+ stub_request(entry_point.connection) do |stub|
391
+ stub.get(url) { [200, {}, nil] }
392
+ stub.delete(url) { [204, {}, nil] }
393
+ end
394
+
395
+ link._get
396
+
397
+ _(link._allow).must_be_nil
398
+ _(link._delete).must_be_kind_of Resource
399
+ end
400
+
401
+ it 'parses methods case-insensitively, ignoring whitespace and empty entries' do
402
+ stub_request(entry_point.connection) do |stub|
403
+ stub.get(url) { [200, { 'allow' => ' get,head ,, Post,get ' }, nil] }
404
+ end
405
+
406
+ link._get
407
+
408
+ _(link._allow).must_equal %w[GET HEAD POST]
409
+ _(link._allow?(:post)).must_equal true
410
+ _(link._allow?('Head')).must_equal true
411
+ _(link._allow?(:delete)).must_equal false
412
+ end
413
+
414
+ it 'sends a method that the Allow header does not list by default' do
415
+ stub_request(entry_point.connection) do |stub|
416
+ stub.get(url) { [200, { 'Allow' => 'GET, HEAD' }, nil] }
417
+ stub.delete(url) { [204, {}, nil] }
418
+ end
419
+
420
+ link._get
421
+
422
+ _(entry_point.enforce_allowed_methods?).must_equal false
423
+ _(link._allow?(:delete)).must_equal false
424
+ _(link._delete).must_be_kind_of Resource
425
+ end
426
+
427
+ it 'repeats a request that returned 405 by default' do
428
+ requests = 0
429
+ stub_request(entry_point.connection) do |stub|
430
+ stub.delete(url) do
431
+ requests += 1
432
+ [405, { 'Allow' => 'GET' }, nil]
433
+ end
434
+ end
435
+
436
+ _(-> { link._delete }).must_raise Faraday::ClientError
437
+ _(link._allow).must_equal %w[GET]
438
+ _(-> { link._delete }).must_raise Faraday::ClientError
439
+ _(requests).must_equal 2
440
+ end
441
+
442
+ it 'returns a copy of the allowed methods' do
443
+ stub_request(entry_point.connection) do |stub|
444
+ stub.get(url) { [200, { 'Allow' => 'GET' }, nil] }
445
+ end
446
+
447
+ link._get
448
+ link._allow << 'DELETE'
449
+
450
+ _(link._allow?(:delete)).must_equal false
451
+ end
452
+
453
+ describe 'with enforce_allowed_methods' do
454
+ before do
455
+ entry_point.enforce_allowed_methods = true
456
+ end
457
+
458
+ it 'sends an allowed method' do
459
+ stub_request(entry_point.connection) do |stub|
460
+ stub.get(url) { [200, { 'Allow' => 'GET, POST' }, nil] }
461
+ stub.post(url) { [201, {}, nil] }
462
+ end
463
+
464
+ link._get
465
+
466
+ _(link._post('foo' => 'bar')).must_be_kind_of Resource
467
+ end
468
+
469
+ it 'raises MethodNotAllowedError without sending a disallowed method' do
470
+ stub_request(entry_point.connection) do |stub|
471
+ stub.get(url) { [200, { 'Allow' => 'GET, HEAD' }, nil] }
472
+ end
473
+
474
+ link._get
475
+ error = _(-> { link._delete }).must_raise MethodNotAllowedError
476
+
477
+ _(error.http_method).must_equal 'DELETE'
478
+ _(error.url).must_equal '/productions/1'
479
+ _(error.allowed).must_equal %w[GET HEAD]
480
+ _(error.message).must_equal 'DELETE is not allowed on /productions/1, the server allows only GET, HEAD.'
481
+ end
482
+
483
+ it 'raises for every method when the Allow header is empty, except OPTIONS' do
484
+ stub_request(entry_point.connection) do |stub|
485
+ stub.head(url) { [200, { 'Allow' => '' }, nil] }
486
+ stub.options(url) { [200, { 'Allow' => 'GET' }, nil] }
487
+ stub.get(url) { [200, {}, nil] }
488
+ end
489
+
490
+ link._head
491
+
492
+ _(link._allow).must_equal []
493
+ error = _(-> { link._get }).must_raise MethodNotAllowedError
494
+ _(error.message).must_equal 'GET is not allowed on /productions/1, the server allows no methods.'
495
+ _(-> { link._head }).must_raise MethodNotAllowedError
496
+
497
+ link._options
498
+
499
+ _(link._allow).must_equal %w[GET]
500
+ _(link._get).must_be_kind_of Resource
501
+ end
502
+
503
+ it 'does not imply HEAD from GET' do
504
+ stub_request(entry_point.connection) do |stub|
505
+ stub.get(url) { [200, { 'Allow' => 'GET' }, nil] }
506
+ end
507
+
508
+ link._get
509
+
510
+ _(-> { link._head }).must_raise MethodNotAllowedError
511
+ end
512
+
513
+ it 'records the Allow header of a 405 response and refuses to repeat the request' do
514
+ requests = 0
515
+ stub_request(entry_point.connection) do |stub|
516
+ stub.delete(url) do
517
+ requests += 1
518
+ [405, { 'Allow' => 'GET, PUT' }, nil]
519
+ end
520
+ stub.put(url) { [200, {}, nil] }
521
+ end
522
+
523
+ _(-> { link._delete }).must_raise Faraday::ClientError
524
+ _(link._allow).must_equal %w[GET PUT]
525
+ _(-> { link._delete }).must_raise MethodNotAllowedError
526
+ _(requests).must_equal 1
527
+ _(link._put('foo' => 'bar')).must_be_kind_of Resource
528
+ end
529
+
530
+ it 'records the Allow header of a 405 response when errors are not raised' do
531
+ entry_point.connection(default: false) do |conn|
532
+ conn.adapter :test do |stub|
533
+ stub.post(url) { [405, { 'Allow' => 'GET' }, nil] }
534
+ end
535
+ end
536
+
537
+ _(link._post._status).must_equal 405
538
+ _(-> { link._post }).must_raise MethodNotAllowedError
539
+ end
540
+
541
+ it 'uses the most recent response' do
542
+ stub_request(entry_point.connection) do |stub|
543
+ stub.get(url) { [200, { 'Allow' => 'GET, PATCH' }, nil] }
544
+ stub.patch(url) { [200, {}, nil] }
545
+ stub.delete(url) { [204, {}, nil] }
546
+ end
547
+
548
+ link._get
549
+
550
+ _(-> { link._delete }).must_raise MethodNotAllowedError
551
+ link._patch('foo' => 'bar')
552
+
553
+ _(link._allow).must_be_nil
554
+ _(link._delete).must_be_kind_of Resource
555
+ end
556
+
557
+ it 'keeps the allowed methods per link' do
558
+ stub_request(entry_point.connection) do |stub|
559
+ stub.get(url) { [200, { 'Allow' => 'GET' }, nil] }
560
+ stub.delete(url) { [204, {}, nil] }
561
+ end
562
+
563
+ link._get
564
+
565
+ _(Link.new('key', { 'href' => '/productions/1' }, entry_point)._delete).must_be_kind_of Resource
566
+ end
567
+
568
+ it 'starts an expanded link without restrictions' do
569
+ stub_request(entry_point.connection) do |stub|
570
+ stub.get(url) { [200, { 'Allow' => 'GET' }, nil] }
571
+ stub.delete(url) { [204, {}, nil] }
572
+ end
573
+
574
+ link._get
575
+
576
+ _(-> { link._delete }).must_raise MethodNotAllowedError
577
+ _(link._expand._allow).must_be_nil
578
+ _(link._expand._delete).must_be_kind_of Resource
579
+ end
580
+ end
581
+ end
582
+
318
583
  describe 'inspect' do
319
584
  it 'outputs a custom-friendly output' do
320
585
  link = Link.new('key', { 'href' => '/productions/1' }, 'foo')
@@ -386,6 +651,47 @@ module Hyperclient
386
651
  _(ids).must_equal [1, 2]
387
652
  end
388
653
 
654
+ it 'raises a clear error when the resource links back to itself under the same name' do
655
+ resource = Resource.new({ '_links' => { 'sub_nodes' => { 'href' => '/sub_nodes' } } }, entry_point)
656
+
657
+ stub_request(entry_point.connection) do |stub|
658
+ stub.get('http://api.example.org/sub_nodes') do
659
+ [200, {}, { '_links' => { 'sub_nodes' => { 'href' => 'http://api.example.org/sub_nodes' } },
660
+ '_embedded' => { 'nodes' => [{ 'name' => 'a' }] } }]
661
+ end
662
+ end
663
+
664
+ error = _(-> { resource._links.sub_nodes.map(&:name) }).must_raise Hyperclient::SelfReferencingLinkError
665
+ _(error.message).must_equal 'The sub_nodes link at http://api.example.org/sub_nodes links back to itself, ' \
666
+ 'use _embedded to iterate over embedded items.'
667
+ _(resource._links.sub_nodes._embedded.nodes.map(&:name)).must_equal ['a']
668
+ end
669
+
670
+ it 'does not follow a link back to itself when checking respond_to? or delegating' do
671
+ resource = Resource.new({ '_links' => { 'sub_nodes' => { 'href' => '/sub_nodes' } } }, entry_point)
672
+
673
+ stub_request(entry_point.connection) do |stub|
674
+ stub.get('http://api.example.org/sub_nodes') do
675
+ [200, {}, { 'name' => nil,
676
+ '_links' => { 'sub_nodes' => { 'href' => 'http://api.example.org/sub_nodes' } } }]
677
+ end
678
+ end
679
+
680
+ _(resource._links.sub_nodes.respond_to?(:unknown)).must_equal false
681
+ _(resource._links.sub_nodes.name).must_be_nil
682
+ end
683
+
684
+ it 'iterates a link that points to a different url with the same name' do
685
+ resource = Resource.new({ '_links' => { 'orders' => { 'href' => '/orders' } } }, entry_point)
686
+
687
+ stub_request(entry_point.connection) do |stub|
688
+ stub.get('http://api.example.org/orders') { [200, {}, { '_links' => { 'orders' => { 'href' => '/all_orders' } } }] }
689
+ stub.get('http://api.example.org/all_orders') { [200, {}, { '_embedded' => { 'orders' => [{ 'id' => 1 }] } }] }
690
+ end
691
+
692
+ _(resource._links.orders.map(&:id)).must_equal [1]
693
+ end
694
+
389
695
  it 'returns an Enumerator when called without a block' do
390
696
  resource = Resource.new({ '_links' => { 'orders' => { 'href' => '/orders' } } }, entry_point)
391
697
 
@@ -229,6 +229,37 @@ module Hyperclient
229
229
  end
230
230
  end
231
231
 
232
+ describe '._allow' do
233
+ it 'returns nil without a response object' do
234
+ resource = Resource.new({}, entry_point)
235
+
236
+ _(resource._allow).must_be_nil
237
+ _(resource._allow?(:delete)).must_equal true
238
+ end
239
+
240
+ it 'returns nil without an Allow header' do
241
+ resource = Resource.new({}, entry_point, stub(headers: {}))
242
+
243
+ _(resource._allow).must_be_nil
244
+ _(resource._allow?(:delete)).must_equal true
245
+ end
246
+
247
+ it 'returns the allowed methods' do
248
+ resource = Resource.new({}, entry_point, stub(headers: Faraday::Utils::Headers.new('allow' => 'get, Head')))
249
+
250
+ _(resource._allow).must_equal %w[GET HEAD]
251
+ _(resource._allow?(:head)).must_equal true
252
+ _(resource._allow?('DELETE')).must_equal false
253
+ end
254
+
255
+ it 'returns an empty list for an empty Allow header' do
256
+ resource = Resource.new({}, entry_point, stub(headers: { 'Allow' => ' ' }))
257
+
258
+ _(resource._allow).must_equal []
259
+ _(resource._allow?(:get)).must_equal false
260
+ end
261
+ end
262
+
232
263
  describe 'inspect' do
233
264
  it 'outputs a custom-friendly output' do
234
265
  resource = Resource.new({ '_links' => { 'self' => { 'href' => '/orders/523' } }, 'title' => 'Order' },
@@ -246,7 +277,7 @@ module Hyperclient
246
277
  end
247
278
 
248
279
  it 'returns the attributes as a Hash from #to_hash' do
249
- _(resource.to_hash).must_equal('title' => 'Order', 'total' => 42)
280
+ _(resource.to_hash).must_equal({ 'title' => 'Order', 'total' => 42 })
250
281
  end
251
282
 
252
283
  it 'returns the same result from #to_h as #to_hash' do
@@ -28,6 +28,7 @@ describe OxfordExample::App do
28
28
  _(output).must_include 'Followed primary_place: Balliol College'
29
29
  _(output).must_include 'Archived depiction URL (not fetched):'
30
30
  _(output).must_include 'CURIE: /docs/places'
31
+ _(output).must_include 'Places profile: /docs/places'
31
32
  end
32
33
 
33
34
  it 'supports explicit navigation, hash attributes, and embedded resources' do
@@ -40,6 +41,16 @@ describe OxfordExample::App do
40
41
  _(api._links['oxford:places']._embedded.places.first.name).must_equal 'Balliol College'
41
42
  end
42
43
 
44
+ it 'exposes link properties, including a profile that can be fetched' do
45
+ api = Hyperclient.new('http://127.0.0.1:9292/')
46
+ places = api._links.places
47
+
48
+ _(places._title).must_equal 'Oxford places'
49
+ _(places._profile).must_equal '/docs/places'
50
+ _(places._deprecation).must_be_nil
51
+ _(api.connection.get(places._profile).body['description']).must_include 'Oxford place facts'
52
+ end
53
+
43
54
  it 'serves HAL, rejects writes, and reports missing resources' do
44
55
  status, headers, = app.call('REQUEST_METHOD' => 'GET', 'PATH_INFO' => '/')
45
56
 
metadata CHANGED
@@ -1,14 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: hyperclient
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.1.0
4
+ version: 2.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Oriol Gual
8
- autorequire:
9
8
  bindir: bin
10
9
  cert_chain: []
11
- date: 2026-10-14 00:00:00.000000000 Z
10
+ date: 2026-11-22 00:00:00.000000000 Z
12
11
  dependencies:
13
12
  - !ruby/object:Gem::Dependency
14
13
  name: addressable
@@ -78,6 +77,7 @@ files:
78
77
  - ".github/workflows/danger-comment.yml"
79
78
  - ".github/workflows/danger.yml"
80
79
  - ".github/workflows/lint.yml"
80
+ - ".github/workflows/release.yml"
81
81
  - ".github/workflows/test.yml"
82
82
  - ".gitignore"
83
83
  - ".rubocop.yml"
@@ -106,6 +106,7 @@ files:
106
106
  - features/support/api.rb
107
107
  - features/support/env.rb
108
108
  - features/support/fixtures.rb
109
+ - gemfiles/release.gemfile
109
110
  - hyperclient.gemspec
110
111
  - lib/hyperclient.rb
111
112
  - lib/hyperclient/attributes.rb
@@ -135,7 +136,6 @@ homepage: https://github.com/codegram/hyperclient/
135
136
  licenses: []
136
137
  metadata:
137
138
  rubygems_mfa_required: 'true'
138
- post_install_message:
139
139
  rdoc_options: []
140
140
  require_paths:
141
141
  - lib
@@ -150,8 +150,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
150
150
  - !ruby/object:Gem::Version
151
151
  version: '0'
152
152
  requirements: []
153
- rubygems_version: 3.5.16
154
- signing_key:
153
+ rubygems_version: 4.0.20
155
154
  specification_version: 4
156
155
  summary: ''
157
156
  test_files: []