activeresource 5.1.1 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e0cde8f42f06f37aa13a7098b9a1e828aac34c90971a62f4c9a1a7fcf529ce7
-  data.tar.gz: 11e7f85a7c565de83cb5248d8ee35783b343b8714e8ed9adcf08462f8aaceeda
+  metadata.gz: f2a0c925e2619c4a4204eebdaea70776a57fec944e9eefeb98982ed8cf425bbc
+  data.tar.gz: b77c66a74c3fe0d32e16d0ce4eaaec1c772200bda9ea36b2bfba1a3cc4f58b5d
 SHA512:
-  metadata.gz: 133f4a82c31d9c925bc1c04a304c63e03982d45aa51b97d7e9ba580a433579802fb811a32009d40ebb7fc84e947fe65c60fd658b2cebb2f2f4c724efc536f528
-  data.tar.gz: 0f0042b3b644fe8584d34403913f2e11363a684fe438d536303871baaed2a98f26319b0e1dcd036364b42597b48e76c5713a627ea4431a2b2ec9263fce98b3a6
+  metadata.gz: 9116078833a262f5a4d184a9cd080f3a29bfc5c07481cf352dd87baa735ba0dfae6159a35ac37ea1ad2e121348a33d958151a048af8dbb6e85e3a387076de3b5
+  data.tar.gz: 02e8b7e3aa1fd89f70f67b2696d778bf0c4a5d89c4b6f779ec3ecffc6a099374c06515ec2bfcb4e7175a518f00543f16b1b691670378c2533fcf353ce82cb96f

data/README.md

@@ -0,0 +1,324 @@
+# Active Resource
+
+Active Resource (ARes) connects business objects and Representational State Transfer (REST)
+web services. It implements object-relational mapping for REST web services to provide transparent
+proxying capabilities between a client (Active Resource) and a RESTful service (which is provided by
+Simply RESTful routing in `ActionController::Resources`).
+
+## Philosophy
+
+Active Resource attempts to provide a coherent wrapper object-relational mapping for REST
+web services. It follows the same philosophy as Active Record, in that one of its prime aims
+is to reduce the amount of code needed to map to these resources.  This is made possible
+by relying on a number of code- and protocol-based conventions that make it easy for Active Resource
+to infer complex relations and structures. These conventions are outlined in detail in the documentation
+for `ActiveResource::Base`.
+
+## Overview
+
+Model classes are mapped to remote REST resources by Active Resource much the same way Active Record maps
+model classes to database tables. When a request is made to a remote resource, a REST JSON request is
+generated, transmitted, and the result received and serialized into a usable Ruby object.
+
+## Download and installation
+
+The latest version of Active Resource can be installed with RubyGems:
+
+```
+gem install activeresource
+```
+
+Or added to a Gemfile:
+
+```ruby
+gem 'activeresource'
+```
+
+Source code can be downloaded on GitHub
+
+* https://github.com/rails/activeresource/tree/main
+
+### Configuration and Usage
+
+Putting Active Resource to use is very similar to Active Record. It's as simple as creating a model class
+that inherits from `ActiveResource::Base` and providing a `site` class variable to it:
+
+```ruby
+class Person < ActiveResource::Base
+  self.site = "http://api.people.com:3000"
+end
+```
+
+Now the Person class is REST enabled and can invoke REST services very similarly to how Active Record invokes
+life cycle methods that operate against a persistent store.
+
+```ruby
+# Find a person with id = 1
+tyler = Person.find(1)
+Person.exists?(1)  # => true
+```
+
+As you can see, the methods are quite similar to Active Record's methods for dealing with database
+records. But rather than dealing directly with a database record, you're dealing with HTTP resources
+(which may or may not be database records).
+
+Connection settings (`site`, `headers`, `user`, `password`, `bearer_token`, `proxy`) and the connections
+themselves are store in thread-local variables to make them thread-safe, so you can also set these
+dynamically, even in a multi-threaded environment, for instance:
+
+```ruby
+ActiveResource::Base.site = api_site_for(request)
+```
+### Authentication
+
+Active Resource supports the token based authentication provided by Rails through the
+`ActionController::HttpAuthentication::Token` class using custom headers.
+
+```ruby
+class Person < ActiveResource::Base
+  self.headers['Authorization'] = 'Token token="abcd"'
+end
+```
+
+You can also set any specific HTTP header using the same way.  As mentioned above, headers are
+thread-safe, so you can set headers dynamically, even in a multi-threaded environment:
+
+```ruby
+ActiveResource::Base.headers['Authorization'] = current_session_api_token
+```
+
+Active Resource supports 2 options for HTTP authentication today.
+
+1. Basic
+```ruby
+class Person < ActiveResource::Base
+  self.user = 'my@email.com'
+  self.password = '123'
+end
+# username: my@email.com password: 123
+```
+
+2. Bearer Token
+```ruby
+class Person < ActiveResource::Base
+  self.auth_type = :bearer
+  self.bearer_token = 'my-token123'
+end
+# Bearer my-token123
+```
+
+### Protocol
+
+Active Resource is built on a standard JSON or XML format for requesting and submitting resources
+over HTTP. It mirrors the RESTful routing built into Action Controller but will also work with any
+other REST service that properly implements the protocol. REST uses HTTP, but unlike "typical" web
+applications, it makes use of all the verubys available in the HTTP specification:
+
+* GET requests are used for finding and retrieving resources.
+* POST requests are used to create new resources.
+* PUT requests are used to update existing resources.
+* DELETE requests are used to delete resources.
+
+For more information on how this protocol works with Active Resource, see the `ActiveResource::Base` documentation;
+for more general information on REST web services, see the article
+[here](http://en.wikipedia.org/wiki/Representational_State_Transfer).
+
+### Find
+
+Find requests use the GET method and expect the JSON form of whatever resource/resources is/are
+being requested. So, for a request for a single element, the JSON of that item is expected in
+response:
+
+```ruby
+# Expects a response of
+#
+# {"id":1,"first":"Tyler","last":"Durden"}
+#
+# for GET http://api.people.com:3000/people/1.json
+#
+tyler = Person.find(1)
+```
+
+The JSON document that is received is used to build a new object of type Person, with each
+JSON element becoming an attribute on the object.
+
+```ruby
+tyler.is_a? Person  # => true
+tyler.last  # => 'Durden'
+```
+
+Any complex element (one that contains other elements) becomes its own object:
+
+```ruby
+# With this response:
+# {"id":1,"first":"Tyler","address":{"street":"Paper St.","state":"CA"}}
+#
+# for GET http://api.people.com:3000/people/1.json
+#
+tyler = Person.find(1)
+tyler.address  # => <Person::Address::xxxxx>
+tyler.address.street  # => 'Paper St.'
+```
+
+Collections can also be requested in a similar fashion
+
+```ruby
+# Expects a response of
+#
+# [
+#   {"id":1,"first":"Tyler","last":"Durden"},
+#   {"id":2,"first":"Tony","last":"Stark",}
+# ]
+#
+# for GET http://api.people.com:3000/people.json
+#
+people = Person.all
+people.first  # => <Person::xxx 'first' => 'Tyler' ...>
+people.last  # => <Person::xxx 'first' => 'Tony' ...>
+```
+
+### Create
+
+Creating a new resource submits the JSON form of the resource as the body of the request and expects
+a 'Location' header in the response with the RESTful URL location of the newly created resource. The
+id of the newly created resource is parsed out of the Location response header and automatically set
+as the id of the ARes object.
+
+```ruby
+# {"first":"Tyler","last":"Durden"}
+#
+# is submitted as the body on
+#
+# if include_root_in_json is not set or set to false => {"first":"Tyler"}
+# if include_root_in_json is set to true => {"person":{"first":"Tyler"}}
+#
+# POST http://api.people.com:3000/people.json
+#
+# when save is called on a new Person object.  An empty response is
+# is expected with a 'Location' header value:
+#
+# Response (201): Location: http://api.people.com:3000/people/2
+#
+tyler = Person.new(:first => 'Tyler')
+tyler.new?  # => true
+tyler.save  # => true
+tyler.new?  # => false
+tyler.id    # => 2
+```
+
+### Update
+
+'save' is also used to update an existing resource and follows the same protocol as creating a resource
+with the exception that no response headers are needed -- just an empty response when the update on the
+server side was successful.
+
+```ruby
+# {"first":"Tyler"}
+#
+# is submitted as the body on
+#
+# if include_root_in_json is not set or set to false => {"first":"Tyler"}
+# if include_root_in_json is set to true => {"person":{"first":"Tyler"}}
+#
+# PUT http://api.people.com:3000/people/1.json
+#
+# when save is called on an existing Person object.  An empty response is
+# is expected with code (204)
+#
+tyler = Person.find(1)
+tyler.first # => 'Tyler'
+tyler.first = 'Tyson'
+tyler.save  # => true
+```
+
+### Delete
+
+Destruction of a resource can be invoked as a class and instance method of the resource.
+
+```ruby
+# A request is made to
+#
+# DELETE http://api.people.com:3000/people/1.json
+#
+# for both of these forms.  An empty response with
+# is expected with response code (200)
+#
+tyler = Person.find(1)
+tyler.destroy  # => true
+tyler.exists?  # => false
+Person.delete(2)  # => true
+Person.exists?(2) # => false
+```
+
+### Associations
+
+Relationships between resources can be declared using the standard association syntax
+that should be familiar to anyone who uses Active Record. For example, using the
+class definition below:
+
+```ruby
+class Post < ActiveResource::Base
+  self.site = "http://blog.io"
+  has_many :comments
+end
+
+post = Post.find(1)      # issues GET http://blog.io/posts/1.json
+comments = post.comments # issues GET http://blog.io/comments.json?post_id=1
+```
+
+In this case, the `Comment` model would have to be implemented as Active Resource, too.
+
+If you control the server, you may wish to include nested resources thus avoiding a
+second network request. Given the resource above, if the response includes comments
+in the response, they will be automatically loaded into the Active Resource object.
+The server-side model can be adjusted as follows to include comments in the response.
+
+```ruby
+class Post < ActiveRecord::Base
+  has_many :comments
+
+  def as_json(options)
+    super.merge(:include=>[:comments])
+  end
+end
+```
+
+### Logging
+
+Active Resource instruments the event `request.active_resource` when doing a request
+to the remote service. You can subscribe to it by doing:
+
+```ruby
+ActiveSupport::Notifications.subscribe('request.active_resource')  do |name, start, finish, id, payload|
+```
+
+The `payload` is a `Hash` with the following keys:
+
+* `method` as a `Symbol`
+* `request_uri` as a `String`
+* `result` as an `Net::HTTPResponse`
+
+## License
+
+Active Resource is released under the MIT license:
+
+* http://www.opensource.org/licenses/MIT
+
+## Contributing to Active Resource
+
+Active Resource is work of many contributors. You're encouraged to submit pull requests, propose
+features and discuss issues.
+
+See [CONTRIBUTING](https://github.com/rails/activeresource/blob/main/CONTRIBUTING.md).
+
+## Support
+
+Full API documentation is available at
+
+* http://rubydoc.info/gems/activeresource
+
+Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
+
+* https://github.com/rails/activeresource/issues
+
+You can find more usage information in the ActiveResource::Base documentation.

data/lib/active_resource/associations/builder/association.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveResource::Associations::Builder
-  class Association #:nodoc:
+  class Association # :nodoc:
     # providing a Class-Variable, which will have a different store of subclasses
     class_attribute :valid_options
     self.valid_options = [:class_name]
@@ -25,7 +25,6 @@ module ActiveResource::Associations::Builder
     end
 
     private
-
       def validate_options
         options.assert_valid_keys(self.class.valid_options)
       end

data/lib/active_resource/associations.rb

@@ -148,7 +148,7 @@ module ActiveResource::Associations
       elsif attributes.include?(method_name)
         attributes[method_name]
       elsif !new_record?
-        instance_variable_set(ivar_name, reflection.klass.find(:all, params: { :"#{self.class.element_name}_id" => self.id }))
+        instance_variable_set(ivar_name, reflection.klass.find(:all, params: { "#{self.class.element_name}_id": self.id }))
       else
         instance_variable_set(ivar_name, self.class.collection_parser.new)
       end
@@ -166,7 +166,7 @@ module ActiveResource::Associations
       elsif attributes.include?(method_name)
         attributes[method_name]
       elsif reflection.klass.respond_to?(:singleton_name)
-        instance_variable_set(ivar_name, reflection.klass.find(params: { :"#{self.class.element_name}_id" => self.id }))
+        instance_variable_set(ivar_name, reflection.klass.find(params: { "#{self.class.element_name}_id": self.id }))
       else
         instance_variable_set(ivar_name, reflection.klass.find(:one, from: "/#{self.class.collection_name}/#{self.id}/#{method_name}#{self.class.format_extension}"))
       end

data/lib/active_resource/base.rb

@@ -13,7 +13,6 @@ require "active_support/core_ext/object/duplicable"
 require "set"
 require "uri"
 
-require "active_support/core_ext/uri"
 require "active_resource/connection"
 require "active_resource/formats"
 require "active_resource/schema"
@@ -127,18 +126,25 @@ module ActiveResource
   # requests. These sensitive credentials are sent unencrypted, visible to
   # any onlooker, so this scheme should only be used with SSL.
   #
-  # Digest authentication sends a crytographic hash of the username, password,
+  # Digest authentication sends a cryptographic hash of the username, password,
   # HTTP method, URI, and a single-use secret key provided by the server.
   # Sensitive credentials aren't visible to onlookers, so digest authentication
   # doesn't require SSL. However, this doesn't mean the connection is secure!
   # Just the username and password.
   #
+  # Another common way to authenticate requests is via bearer tokens, a scheme
+  # originally created as part of the OAuth 2.0 protocol (see RFC 6750).
+  #
+  # Bearer authentication sends a token, that can maybe only be a short string
+  # of hexadecimal characters or even a JWT Token. Similarly to the Basic
+  # authentication, this scheme should only be used with SSL.
+  #
   # (You really, really want to use SSL. There's little reason not to.)
   #
   # === Picking an authentication scheme
   #
-  # Basic authentication is the default. To switch to digest authentication,
-  # set +auth_type+ to +:digest+:
+  # Basic authentication is the default. To switch to digest or bearer token authentication,
+  # set +auth_type+ to +:digest+ or +:bearer+:
   #
   #    class Person < ActiveResource::Base
   #      self.auth_type = :digest
@@ -157,6 +163,16 @@ module ActiveResource
   #      self.site = "https://ryan:password@api.people.com"
   #    end
   #
+  # === Setting the bearer token
+  #
+  # Set +bearer_token+ on the class:
+  #
+  #    class Person < ActiveResource::Base
+  #      # Set bearer token directly:
+  #      self.auth_type = :bearer
+  #      self.bearer_token = "my-bearer-token"
+  #    end
+  #
   # === Certificate Authentication
   #
   # You can also authenticate using an X509 certificate. <tt>See ssl_options=</tt> for all options.
@@ -202,7 +218,9 @@ module ActiveResource
   # * 405 - ActiveResource::MethodNotAllowed
   # * 409 - ActiveResource::ResourceConflict
   # * 410 - ActiveResource::ResourceGone
+  # * 412 - ActiveResource::PreconditionFailed
   # * 422 - ActiveResource::ResourceInvalid (rescued by save as validation errors)
+  # * 429 - ActiveResource::TooManyRequests
   # * 401..499 - ActiveResource::ClientError
   # * 500..599 - ActiveResource::ServerError
   # * Other - ActiveResource::ConnectionError
@@ -319,7 +337,7 @@ module ActiveResource
 
     class << self
       include ThreadsafeAttributes
-      threadsafe_attribute :_headers, :_connection, :_user, :_password, :_site, :_proxy
+      threadsafe_attribute :_headers, :_connection, :_user, :_password, :_bearer_token, :_site, :_proxy
 
       # Creates a schema for this resource - setting the attributes that are
       # known prior to fetching an instance from the remote system.
@@ -407,7 +425,7 @@ module ActiveResource
       # example:
       #
       #   class Person < ActiveResource::Base
-      #     schema = {'name' => :string, 'age' => :integer }
+      #     self.schema = {'name' => :string, 'age' => :integer }
       #   end
       #
       # The keys/values can be strings or symbols. They will be converted to
@@ -472,8 +490,8 @@ module ActiveResource
           self._site = nil
         else
           self._site = create_site_uri_from(site)
-          self._user = URI.parser.unescape(_site.user) if _site.user
-          self._password = URI.parser.unescape(_site.password) if _site.password
+          self._user = URI::DEFAULT_PARSER.unescape(_site.user) if _site.user
+          self._password = URI::DEFAULT_PARSER.unescape(_site.password) if _site.password
         end
       end
 
@@ -525,6 +543,22 @@ module ActiveResource
         self._password = password
       end
 
+      # Gets the \bearer_token for REST HTTP authentication.
+      def bearer_token
+        # Not using superclass_delegating_reader. See +site+ for explanation
+        if _bearer_token_defined?
+          _bearer_token
+        elsif superclass != Object && superclass.bearer_token
+          superclass.bearer_token.dup.freeze
+        end
+      end
+
+      # Sets the \bearer_token for REST HTTP authentication.
+      def bearer_token=(bearer_token)
+        self._connection = nil
+        self._bearer_token = bearer_token
+      end
+
       def auth_type
         if defined?(@auth_type)
           @auth_type
@@ -649,6 +683,7 @@ module ActiveResource
           _connection.proxy = proxy if proxy
           _connection.user = user if user
           _connection.password = password if password
+          _connection.bearer_token = bearer_token if bearer_token
           _connection.auth_type = auth_type if auth_type
           _connection.timeout = timeout if timeout
           _connection.open_timeout = open_timeout if open_timeout
@@ -661,11 +696,10 @@ module ActiveResource
       end
 
       def headers
-        headers_state = self._headers || {}
-        if superclass != Object
-          self._headers = superclass.headers.merge(headers_state)
+        self._headers ||= if superclass != Object
+          InheritingHash.new(superclass.headers)
         else
-          headers_state
+          {}
         end
       end
 
@@ -716,7 +750,7 @@ module ActiveResource
       # Default value is <tt>site.path</tt>.
       def prefix=(value = "/")
         # Replace :placeholders with '#{embedded options[:lookups]}'
-        prefix_call = value.gsub(/:\w+/) { |key| "\#{URI.parser.escape options[#{key}].to_s}" }
+        prefix_call = value.gsub(/:\w+/) { |key| "\#{URI::DEFAULT_PARSER.escape options[#{key}].to_s}" }
 
         # Clear prefix parameters in case they have been cached
         @prefix_parameters = nil
@@ -733,10 +767,10 @@ module ActiveResource
         raise
       end
 
-      alias_method :set_prefix, :prefix=  #:nodoc:
+      alias_method :set_prefix, :prefix=  # :nodoc:
 
-      alias_method :set_element_name, :element_name=  #:nodoc:
-      alias_method :set_collection_name, :collection_name=  #:nodoc:
+      alias_method :set_element_name, :element_name=  # :nodoc:
+      alias_method :set_collection_name, :collection_name=  # :nodoc:
 
       def format_extension
         include_format_in_path ? ".#{format.extension}" : ""
@@ -852,7 +886,7 @@ module ActiveResource
         "#{prefix(prefix_options)}#{collection_name}#{format_extension}#{query_string(query_options)}"
       end
 
-      alias_method :set_primary_key, :primary_key=  #:nodoc:
+      alias_method :set_primary_key, :primary_key=  # :nodoc:
 
       # Builds a new, unsaved record using the default values from the remote server so
       # that it can be used with RESTful forms.
@@ -1050,7 +1084,6 @@ module ActiveResource
       end
 
       private
-
         def check_prefix_options(prefix_options)
           p_options = HashWithIndifferentAccess.new(prefix_options)
           prefix_parameters.each do |p|
@@ -1060,23 +1093,26 @@ module ActiveResource
 
         # Find every resource
         def find_every(options)
-          begin
+          params = options[:params]
+          prefix_options, query_options = split_options(params)
+
+          response =
             case from = options[:from]
             when Symbol
-              instantiate_collection(get(from, options[:params]), options[:params])
+              get(from, params)
             when String
-              path = "#{from}#{query_string(options[:params])}"
-              instantiate_collection(format.decode(connection.get(path, headers).body) || [], options[:params])
+              path = "#{from}#{query_string(query_options)}"
+              format.decode(connection.get(path, headers).body)
             else
-              prefix_options, query_options = split_options(options[:params])
               path = collection_path(prefix_options, query_options)
-              instantiate_collection((format.decode(connection.get(path, headers).body) || []), query_options, prefix_options)
+              format.decode(connection.get(path, headers).body)
             end
-          rescue ActiveResource::ResourceNotFound
-            # Swallowing ResourceNotFound exceptions and return nil - as per
-            # ActiveRecord.
-            nil
-          end
+
+          instantiate_collection(response || [], query_options, prefix_options)
+        rescue ActiveResource::ResourceNotFound
+          # Swallowing ResourceNotFound exceptions and return nil - as per
+          # ActiveRecord.
+          nil
         end
 
         # Find a single resource from a one-off URL
@@ -1145,8 +1181,8 @@ module ActiveResource
         end
     end
 
-    attr_accessor :attributes #:nodoc:
-    attr_accessor :prefix_options #:nodoc:
+    attr_accessor :attributes # :nodoc:
+    attr_accessor :prefix_options # :nodoc:
 
     # If no schema has been defined for the class (see
     # <tt>ActiveResource::schema=</tt>), the default automatic schema is
@@ -1203,7 +1239,7 @@ module ActiveResource
     #   not_ryan.hash            # => {:not => "an ARes instance"}
     def clone
       # Clone all attributes except the pk and any nested ARes
-      cloned = Hash[attributes.reject { |k, v| k == self.class.primary_key || v.is_a?(ActiveResource::Base) }.map { |k, v| [k, v.clone] }]
+      cloned = attributes.reject { |k, v| k == self.class.primary_key || v.is_a?(ActiveResource::Base) }.transform_values { |v| v.clone }
       # Form the new resource - bypass initialize of resource with 'new' as that will call 'load' which
       # attempts to convert hashes into member objects and arrays into collections of objects. We want
       # the raw objects to be cloned so we bypass load by directly setting the attributes hash.
@@ -1589,7 +1625,6 @@ module ActiveResource
       end
 
     private
-
       # Determine whether the response is allowed to have a body per HTTP 1.1 spec section 4.4.1
       def response_code_allows_body?(c)
         !((100..199).include?(c) || [204, 304].include?(c))
@@ -1651,9 +1686,11 @@ module ActiveResource
 
       # Create and return a class definition for a resource inside the current resource
       def create_resource_for(resource_name)
-        resource = self.class.const_set(resource_name, Class.new(ActiveResource::Base))
+        resource = Class.new(ActiveResource::Base)
         resource.prefix = self.class.prefix
-        resource.site   = self.class.site
+        resource.site = self.class.site
+        self.class.const_set(resource_name, resource)
+
         resource
       end
 
@@ -1661,7 +1698,7 @@ module ActiveResource
         self.class.__send__(:split_options, options)
       end
 
-      def method_missing(method_symbol, *arguments) #:nodoc:
+      def method_missing(method_symbol, *arguments) # :nodoc:
         method_name = method_symbol.to_s
 
         if method_name =~ /(=|\?)$/

data/lib/active_resource/collection.rb

@@ -5,7 +5,7 @@ require "active_support/inflector"
 
 module ActiveResource # :nodoc:
   class Collection # :nodoc:
-    SELF_DEFINE_METHODS = [:to_a, :collect!, :map!]
+    SELF_DEFINE_METHODS = [:to_a, :collect!, :map!, :all?]
     include Enumerable
     delegate :to_yaml, :all?, *(Array.instance_methods(false) - SELF_DEFINE_METHODS), to: :to_a
 
@@ -15,7 +15,7 @@ module ActiveResource # :nodoc:
     # ActiveResource::Collection is a wrapper to handle parsing index responses that
     # do not directly map to Rails conventions.
     #
-    # You can define a custom class that inherets from ActiveResource::Collection
+    # You can define a custom class that inherits from ActiveResource::Collection
     # in order to to set the elements instance.
     #
     # GET /posts.json delivers following response body: