prx_hyperresource 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f915cfe28034820646356966a937d0d0aa356239272d2b4c67c09bf1229fadf
+  data.tar.gz: 67725008931bf8c1333d5f06b3267a3fadeea8540d572973f1f01f31097dd344
+SHA512:
+  metadata.gz: ebe26180a2258b3f037191612663ec06b49f5b17cfba2a33b0222cd565135eeb19f8f4ff075615243e0565be120966705f3d5dfbc6caa307f20b4dda2b039def
+  data.tar.gz: f2ed869789f03947e5ed8863db56515ab9e65308bfadbf0b9b9b0d5aaf9bfce3202d77f200d87d8aa5b50500c121812b290db02271a291088f07594aef8fbbf4

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.0.0
+
+First release as `prx_hyperresource`, PRX's fork of
+[hyperresource](https://github.com/gamache/hyperresource) 0.9.4. The library
+is still loaded as `HyperResource`, and `require "hyperresource"` still works.
+
+- Support Ruby 4: require `cgi`, which is no longer in Ruby's stdlib.
+- Match URL masks without the `fuzzyurl` gem, but with similar logic.
+- Treat URLs without a protocol as `https` (port 443) when matching masks.
+- Support Faraday 2 basic auth, using the authorization middleware.
+- Don't share cached connections between resources with different `faraday_options`.
+- Default to `application/json` unless a Content-Type is configured.
+- Prefer headers from more specific masks over `*`.
+- Require Ruby 3.3 or later.
+- Remove `HyperResource::VERSION_DATE` and the gemspec `date`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright 2013 Pete Gamache, pete@gamache.org.
+Copyright 2025-2026 PRX.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,263 @@
+# HyperResource
+
+PRX's maintained fork of
+[gamache/hyperresource](https://github.com/gamache/hyperresource), published
+as `prx_hyperresource`. See updates in the [CHANGELOG.md](CHANGELOG.md).
+
+HyperResource is a Ruby client library for hypermedia web services.
+
+HyperResource makes using a hypermedia API feel like calling plain old
+methods on plain old objects.
+
+It is usable with no configuration other than API root endpoint, but
+also allows incoming data types to be extended with Ruby code.
+
+HyperResource supports the 
+[HAL+JSON hypermedia format](http://stateless.co/hal_specification.html),
+with support for Siren and other hypermedia formats planned.
+
+For more insight into HyperResource's goals and design,
+[read the paper](http://petegamache.com/wsrest2014-gamache.pdf)!
+
+## Hypermedia in a Nutshell
+
+Hypermedia APIs return a list of hyperlinks with each response.  These
+links, each of which has a relation name or "rel", represent everything
+you can do to, with, or from the given response.  They are URLs which
+can take arguments.  The consumer of the hypermedia API uses these
+links to access the API's entire functionality.
+
+A primary advantage to hypermedia APIs is that a client library can
+write itself based on the hyperlinks coming back with each response.
+This removes both the chore of writing a custom client library in the
+first place, and also the process of pushing client updates to your
+users.
+
+## HyperResource Philosophy
+
+An automatically-generated library can and should feel as comfortable as a
+custom client library.  Hypermedia brings many promises, but this is one
+we can deliver on.
+
+If you're an API user, HyperResource will help you consume a hypermedia
+API with short, direct, elegant code.
+If you're an API designer, HyperResource is a great default client, or a
+smart starting point for a rich SDK.
+
+Link-driven APIs are the future, and proper tooling can make it The Jetsons
+instead of The Road Warrior.
+
+## Install It
+
+Add `gem "prx_hyperresource"` to your Gemfile, or `gem install prx_hyperresource`.
+It is loaded as `HyperResource`, and `require "hyperresource"` still works.
+
+HyperResource requires Ruby 3.3 or later.
+
+HyperResource uses the 
+[uri_template](https://github.com/hannesg/uri_template)
+and [Faraday](https://github.com/lostisland/faraday)
+gems.  
+
+## Use It - Zero Configuration
+
+Set up API connection:
+
+```ruby
+api = HyperResource.new(root: 'https://api.example.com',
+                        headers: {'Accept' => 'application/vnd.example.com.v1+json'},
+                        auth: {basic: ['username', 'password']})
+# => #<HyperResource:0xABCD1234 @root="https://api.example.com" @href="" @namespace=nil ... >
+```
+
+Now we can get the API's root resource, the gateway to everything else
+on the API.
+
+```ruby
+api.get
+# => #<HyperResource:0xABCD1234 @root="https://api.example.com" @href="" @namespace=nil ... >
+```
+
+What'd we get back?
+
+```ruby
+api.body
+# => { 'message' => 'Welcome to the Example.com API',
+#      'version' => 1,
+#      '_links' => {
+#        'curies' => [{
+#          'name' => 'example',
+#          'templated' => true,
+#          'href' => 'https://api.example.com/rels/{rel}'
+#        }],
+#        'self' => {'href' => '/'},
+#        'example:users' => {'href' => '/users{?email,last_name}', 'templated' => true},
+#        'example:forums' => {'href' => '/forums{?title}', 'templated' => true}
+#      }
+#    }
+```
+
+Lovely.  Let's find a user by their email.
+
+```ruby
+jdoe_user = api.users(email: "jdoe@example.com").first
+# => #<HyperResource:0x12312312 ...>
+```
+
+HyperResource has performed some behind-the-scenes expansions here.
+
+First, the `example:users` link was
+added to the `api` object at the time the resource was
+loaded with `api.get`.  And since the link rel has a 
+[CURIE prefix](http://tools.ietf.org/html/draft-kelly-json-hal-06#section-8.2),
+HyperResource will allow a shortened version of its name, `users`.
+
+Then, calling `first` on the `users` link
+followed the link and loaded it automatically.
+
+Finally, calling `first` on the resource containing one set of
+embedded objects -- like this one -- delegates the method to
+`.objects.first`, which returns the first object in the resource.
+
+Here are some equivalent expressions to the above.  HyperResource offers
+a very short, expressive syntax as its primary interface,
+but you can always fall back to explicit syntax if you like or need to.
+
+
+```
+api.users(email: "jdoe@example.com").first
+api.get.users(email: "jdoe@example.com").first
+api.get.links.users(email: "jdoe@example.com").first
+api.get.links['users'].where(email: "jdoe@example.com").first
+api.get.links['users'].where(email: "jdoe@example.com").get.first
+api.get.links['users'].where(email: "jdoe@example.com").get.objects.first[1][0]
+```
+
+## Use It - ActiveResource-style
+
+If an API is returning data type information as part of the response,
+then we can assign those data types to ruby classes so that they can
+be extended.
+
+For example, in our hypothetical Example API above, a user object is
+returned with a custom media type bearing a 'type=User' modifier.  We
+will extend the User class with a few convenience methods.
+
+```ruby
+class ExampleAPI < HyperResource
+  self.root = 'https://api.example.com'
+  self.headers = {'Accept' => 'application/vnd.example.com.v1+json'}
+  self.auth = {basic: ['username', 'password']}
+
+  class User < ExampleAPI
+    def full_name
+      first_name + ' ' + last_name
+    end
+  end
+end
+
+api = ExampleApi.new
+
+user = api.users.where(email: 'jdoe@example.com').first
+# => #<ExampleApi::User:0xffffffff ...>
+
+user.full_name
+# => "John Doe"
+```
+
+Don't worry if your API uses some other mechanism to indicate resource data
+type; you can override the `.get_data_type` method and
+implement your own logic.
+
+## Configuration for Multiple Hosts
+
+HyperResource supports the concept of different APIs connected in one
+ecosystem by providing a mechanism to scope configuration parameters by
+a URL mask.  This allows a simple way to provide separate
+authentication, headers, etc. to different services which link to each
+other.
+
+As a toy example, consider two servers.  `http://localhost:12345/` returns:
+
+```json
+{ "name": "Server One",
+  "_links": {
+    "self":       {"href": "http://localhost:12345/"},
+    "server_two": {"href": "http://localhost:23456/"}
+  }
+}
+```
+
+And `http://localhost:23456/` returns:
+
+```json
+{ "name": "Server Two",
+  "_links": {
+    "self":       {"href": "http://localhost:23456/"},
+    "server_one": {"href": "http://localhost:12345/"}
+  }
+}
+```
+
+The following configuration would ensure proper namespacing of the two
+servers' response objects:
+
+```ruby
+class APIEcosystem < HyperResource
+  self.config(
+    "localhost:12345" => {"namespace" => "ServerOneAPI"},
+    "localhost:23456" => {"namespace" => "ServerTwoAPI"}
+  )
+end
+
+root_one = APIEcosystem.new(root: ‘http://localhost:12345’).get
+root_one.name      # => ‘Server One’
+root_one.url       # => ‘http://localhost:12345’
+root_one.namespace # => ServerOneAPI
+
+root_two = root_one.server_two.get
+root_two.name      # => ‘Server Two’
+root_two.url       # => ‘http://localhost:23456’
+root_two.namespace # => ServerTwoAPI
+```
+
+URL masks are matched by HyperResource itself; it no longer uses the
+[FuzzyURL](https://github.com/gamache/fuzzyurl/) gem.  A mask may include a
+protocol, hostname, and port, e.g. `https://api.example.com:8080`,
+`api.example.com`, `*.example.com`, or `*`.  Omitted parts match anything,
+and more specific masks take priority.  A URL without a protocol is treated
+as `https`, so it matches `https://` and `:443` masks, but not `http://` or
+`:80` masks.
+
+## Error Handling
+
+HyperResource raises a `HyperResource::ClientError` on 4xx responses,
+and `HyperResource::ServerError` on 5xx responses.  Catch one or both
+(`HyperResource::ResponseError`).  The exceptions contain as much of
+`cause` (internal exception which led to this one), `response`
+(`Faraday::Response` object), and `body` (the decoded response
+as a `Hash`) as is possible at the time.
+
+## Contributors
+
+Many thanks to the people who've sent pull requests and improved this code:
+
+* Jean-Charles d'Anthenaise Sisk ([@jasisk](https://github.com/jasisk))
+* Ian Asaff ([@montague](https://github.com/montague))
+* Julien Blanchard ([@julienXX](https://github.com/julienXX))
+* Andrew Rollins ([@andrew311](https://github.com/andrew311))
+* Étienne Barrié ([@etiennebarrie](https://github.com/etiennebarrie))
+* James Martelletti ([@jmartelletti](https://github.com/jmartelletti))
+* Frank Macreery ([@fancyremarker](https://github.com/fancyremarker))
+* Chris Rollock ([@Sastafer](https://github.com/Sastafer))
+* Pieter Vanmeerbeek ([@pvmeerbe](https://github.com/pvmeerbe))
+
+## Authorship and License
+
+Copyright 2013-2015 Pete Gamache, [pete@gamache.org](mailto:pete@gamache.org).
+Fork maintained by [PRX](https://github.com/PRX) since 2025.
+
+Released under the MIT License.  See LICENSE.txt.
+
+If you got this far, you should probably follow @gamache on Twitter.
+[@gamache](https://twitter.com/gamache)

data/lib/hyper_resource/adapter/hal_json.rb

@@ -0,0 +1,105 @@
+require "rubygems" if RUBY_VERSION[0..2] == "1.8"
+require "json"
+
+class HyperResource
+  class Adapter
+    ## HyperResource::Adapter::HAL_JSON provides support for the HAL+JSON
+    ## hypermedia format by implementing the interface defined in
+    ## HyperResource::Adapter.
+
+    class HAL_JSON < Adapter # standard:disable Naming/ClassAndModuleCamelCase
+      class << self
+        def serialize(object)
+          JSON.dump(object)
+        end
+
+        def deserialize(string)
+          JSON.parse(string)
+        end
+
+        def apply(response, resource, opts = {})
+          if !response.is_a?(Hash)
+            raise ArgumentError, "'response' argument must be a Hash (got #{response.inspect})"
+          end
+          if !resource.is_a?(HyperResource)
+            raise ArgumentError, "'resource' argument must be a HyperResource (got #{resource.inspect})"
+          end
+
+          apply_objects(response, resource)
+          apply_links(response, resource)
+          apply_attributes(response, resource)
+          resource.loaded = true
+          new_href = begin
+            response["_links"]["self"]["href"]
+          rescue
+            nil
+          end
+          resource.href = new_href unless new_href.nil? && resource.href
+          resource
+        end
+
+        private
+
+        def apply_objects(resp, rsrc)
+          return unless resp["_embedded"]
+          objs = rsrc.objects
+
+          resp["_embedded"].each do |name, collection|
+            if collection.is_a? Hash
+              href = begin
+                collection["_links"]["self"]["href"]
+              rescue
+                nil
+              end
+              objs[name] =
+                rsrc.new_from(resource: rsrc,
+                  body: collection,
+                  href: href)
+            else
+              objs[name] = collection.map do |obj|
+                href = begin
+                  obj["_links"]["self"]["href"]
+                rescue
+                  nil
+                end
+                rsrc.new_from(resource: rsrc,
+                  body: obj,
+                  href: href)
+              end
+            end
+          end
+        end
+
+        def apply_links(resp, rsrc)
+          return unless resp["_links"]
+          links = rsrc.links
+
+          resp["_links"].each do |rel, link_spec|
+            links[rel] = if link_spec.is_a? Array
+              link_spec.map do |link|
+                new_link_from_spec(rsrc, link)
+              end
+            else
+              new_link_from_spec(rsrc, link_spec)
+            end
+          end
+        end
+
+        def new_link_from_spec(resource, link_spec)
+          resource.class::Link.new(resource, link_spec)
+        end
+
+        def apply_attributes(resp, rsrc)
+          given_attrs = resp.except("_links", "_embedded")
+          filtered_attrs = rsrc.incoming_body_filter(given_attrs)
+
+          filtered_attrs.keys.each do |attr|
+            rsrc.attributes[attr] = filtered_attrs[attr]
+          end
+
+          rsrc.attributes._hr_clear_changed
+        end
+      end
+    end
+  end
+end

data/lib/hyper_resource/adapter.rb

@@ -0,0 +1,28 @@
+class HyperResource
+  ## HyperResource::Adapter is the interface/abstract base class for
+  ## adapters to different hypermedia formats (e.g., HAL+JSON).  New
+  ## adapters must implement the public methods of this class.
+
+  class Adapter
+    class << self
+      ## Serialize the given object into a string.
+      def serialize(object)
+        raise NotImplementedError, "This is an abstract method -- subclasses " \
+          "of HyperResource::Adapter must implement it."
+      end
+
+      ## Deserialize a given string into an object (Hash).
+      def deserialize(string)
+        raise NotImplementedError, "This is an abstract method -- subclasses " \
+          "of HyperResource::Adapter must implement it."
+      end
+
+      ## Use a given deserialized response object (Hash) to update a given
+      ## resource (HyperResource), returning the updated resource.
+      def apply(response, resource, opts = {})
+        raise NotImplementedError, "This is an abstract method -- subclasses " \
+          "of HyperResource::Adapter must implement it."
+      end
+    end
+  end
+end

data/lib/hyper_resource/attributes.rb

@@ -0,0 +1,73 @@
+class HyperResource
+  class Attributes < Hash
+    attr_accessor :_resource # @private
+
+    def initialize(resource = nil)
+      self._resource = resource || HyperResource.new
+    end
+
+    ## Returns +true+ if the given attribute has been changed since creation
+    ## time, +false+ otherwise.
+    ## If no attribute is given, return whether any attributes have been
+    ## changed.
+    def changed?(attr = nil)
+      @_hr_changed ||= Hash.new(false)
+      return @_hr_changed[attr.to_sym] if attr
+      @_hr_changed.keys.count > 0
+    end
+
+    ## Returns a hash of the attributes and values which have been changed
+    ## since creation time.
+    def changed_attributes
+      @_hr_changed.select { |k, v| v }.keys.each_with_object({}) { |k, h|
+        h[k] = self[k]
+      }
+    end
+
+    # @private
+    def []=(attr, value)
+      return if has_key?(attr.to_s) && self[attr] == value
+      _hr_mark_changed(attr)
+      super(attr.to_s, value)
+    end
+
+    # @private
+    def [](key)
+      return super(key.to_s) if has_key?(key.to_s)
+      return super(key.to_sym) if has_key?(key.to_sym)
+      nil
+    end
+
+    # @private
+    def method_missing(method, *args) # standard:disable Style/MissingRespondToMissing
+      method = method.to_s
+      if has_key?(method)
+        self[method]
+      elsif method[-1, 1] == "="
+        self[method[0..-2]] = args.first
+      else
+        raise NoMethodError, "undefined method `#{method}' for #{inspect}"
+      end
+    end
+
+    # @private
+    def respond_to?(method, *args)
+      method = method.to_s
+      return true if has_key?(method)
+      return true if method[-1, 1] == "=" && has_key?(method[0..-2])
+      super
+    end
+
+    # @private
+    def _hr_clear_changed # @private
+      @_hr_changed = nil
+    end
+
+    # @private
+    def _hr_mark_changed(attr, is_changed = true)
+      attr = attr.to_sym
+      @_hr_changed ||= Hash.new(false)
+      @_hr_changed[attr] = is_changed
+    end
+  end
+end