activeresource 4.1.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5ec4c5f35bfca437beeae8e7acb8763bc0ce1f96
-  data.tar.gz: 9ce68f2e6a206530f05c57ce23aaa0f240bc74f8
+SHA256:
+  metadata.gz: f2a0c925e2619c4a4204eebdaea70776a57fec944e9eefeb98982ed8cf425bbc
+  data.tar.gz: b77c66a74c3fe0d32e16d0ce4eaaec1c772200bda9ea36b2bfba1a3cc4f58b5d
 SHA512:
-  metadata.gz: e8faca6d64850e4eb46e54d829c90355b7d18538b618032498e747dd27fc12861fac7e5e0d5ba53f4bf7eb7203f85c2dd092f0ad1a3badc3ed290a958558e820
-  data.tar.gz: 23fd61de41602794182b27df1703ae3e7a82dba3249c285524f6a5d681b792b9ea38ab782d1a4731b8ddf7a09eb3b78acf5ce0ea04cca8bf0f2d573129da1a9f
+  metadata.gz: 9116078833a262f5a4d184a9cd080f3a29bfc5c07481cf352dd87baa735ba0dfae6159a35ac37ea1ad2e121348a33d958151a048af8dbb6e85e3a387076de3b5
+  data.tar.gz: 02e8b7e3aa1fd89f70f67b2696d778bf0c4a5d89c4b6f779ec3ecffc6a099374c06515ec2bfcb4e7175a518f00543f16b1b691670378c2533fcf353ce82cb96f

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2016 David Heinemeier Hansson
+
+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,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/active_job_serializer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActiveResource
+  class ActiveJobSerializer < ActiveJob::Serializers::ObjectSerializer
+    def serialize(resource)
+      super(
+        "class" => resource.class.name,
+        "persisted" => resource.persisted?,
+        "prefix_options" => resource.prefix_options.as_json,
+        "attributes" => resource.attributes.as_json
+      )
+    end
+
+    def deserialize(hash)
+      hash["class"].constantize.new(hash["attributes"]).tap do |resource|
+        resource.persisted      = hash["persisted"]
+        resource.prefix_options = hash["prefix_options"]
+      end
+    end
+
+    private
+      def klass
+        ActiveResource::Base
+      end
+  end
+end

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

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

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

@@ -1,4 +1,6 @@
-module ActiveResource::Associations::Builder 
+# frozen_string_literal: true
+
+module ActiveResource::Associations::Builder
   class BelongsTo < Association
     self.valid_options += [:foreign_key]
 
@@ -7,8 +9,8 @@ module ActiveResource::Associations::Builder
     def build
       validate_options
       reflection = model.create_reflection(self.class.macro, name, options)
-      model.defines_belongs_to_finder_method(reflection.name, reflection.klass, reflection.foreign_key)
-      return reflection
+      model.defines_belongs_to_finder_method(reflection)
+      reflection
     end
   end
 end

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

@@ -1,11 +1,13 @@
-module ActiveResource::Associations::Builder 
+# frozen_string_literal: true
+
+module ActiveResource::Associations::Builder
   class HasMany < Association
     self.macro = :has_many
 
     def build
       validate_options
       model.create_reflection(self.class.macro, name, options).tap do |reflection|
-        model.defines_has_many_finder_method(reflection.name, reflection.klass)
+        model.defines_has_many_finder_method(reflection)
       end
     end
   end

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

@@ -1,11 +1,13 @@
-module ActiveResource::Associations::Builder 
+# frozen_string_literal: true
+
+module ActiveResource::Associations::Builder
   class HasOne < Association
     self.macro = :has_one
-    
+
     def build
       validate_options
       model.create_reflection(self.class.macro, name, options).tap do |reflection|
-        model.defines_has_one_finder_method(reflection.name, reflection.klass)
+        model.defines_has_one_finder_method(reflection)
       end
     end
   end

data/lib/active_resource/associations.rb

@@ -1,10 +1,11 @@
-module ActiveResource::Associations
+# frozen_string_literal: true
 
+module ActiveResource::Associations
   module Builder
-    autoload :Association, 'active_resource/associations/builder/association'
-    autoload :HasMany,     'active_resource/associations/builder/has_many'
-    autoload :HasOne,      'active_resource/associations/builder/has_one'
-    autoload :BelongsTo,   'active_resource/associations/builder/belongs_to'
+    autoload :Association, "active_resource/associations/builder/association"
+    autoload :HasMany,     "active_resource/associations/builder/has_many"
+    autoload :HasOne,      "active_resource/associations/builder/has_one"
+    autoload :BelongsTo,   "active_resource/associations/builder/belongs_to"
   end
 
 
@@ -65,7 +66,7 @@ module ActiveResource::Associations
   # Would resolve this author into the <tt>Myblog::Author</tt> class.
   #
   # If the response body does not contain an attribute matching the association name
-  # a request is sent to a singelton path under the current resource.
+  # a request is sent to a singleton path under the current resource.
   # For example, if a Product class <tt>has_one :inventory</tt> calling <tt>Product#inventory</tt>
   # will generate a request on /products/:product_id/inventory.json.
   #
@@ -89,15 +90,15 @@ module ActiveResource::Associations
   #
   # === Example
   #
-  # A Comment class declaress <tt>belongs_to :post</tt>, which will add:
+  # A Comment class declares <tt>belongs_to :post</tt>, which will add:
   # * <tt>Comment#post</tt> (similar to <tt>Post.find(post_id)</tt>)
   # The declaration can also include an options hash to specialize the behavior of the association.
   #
   # === Options
   # [:class_name]
-  #   Specify the class name for the association. Use it only if that name canÄt be inferred from association name.
+  #   Specify the class name for the association. Use it only if that name can't be inferred from association name.
   #   So <tt>belongs_to :post</tt> will by default be linked to the Post class, but if the real class name is Article,
-  #   you'll have to specify it with whis option.
+  #   you'll have to specify it with this option.
   # [:foreign_key]
   #   Specify the foreign key used for the association. By default this is guessed to be the name
   #   of the association with an "_id" suffix. So a class that defines a <tt>belongs_to :post</tt>
@@ -112,12 +113,13 @@ module ActiveResource::Associations
   # <tt>belongs_to :customer, :foreign_key => 'user_id'</tt>
   # Creates a belongs_to association called customer which would be resolved by the foreign_key <tt>user_id</tt> instead of <tt>customer_id</tt>
   #
-  def belongs_to(name, options={})
+  def belongs_to(name, options = {})
     Builder::BelongsTo.build(self, name, options)
   end
 
   # Defines the belongs_to association finder method
-  def defines_belongs_to_finder_method(method_name, association_model, finder_key)
+  def defines_belongs_to_finder_method(reflection)
+    method_name = reflection.name
     ivar_name = :"@#{method_name}"
 
     if method_defined?(method_name)
@@ -130,13 +132,14 @@ module ActiveResource::Associations
         instance_variable_get(ivar_name)
       elsif attributes.include?(method_name)
         attributes[method_name]
-      elsif association_id = send(finder_key)
-        instance_variable_set(ivar_name, association_model.find(association_id))
+      elsif association_id = send(reflection.foreign_key)
+        instance_variable_set(ivar_name, reflection.klass.find(association_id))
       end
     end
   end
 
-  def defines_has_many_finder_method(method_name, association_model)
+  def defines_has_many_finder_method(reflection)
+    method_name = reflection.name
     ivar_name = :"@#{method_name}"
 
     define_method(method_name) do
@@ -145,7 +148,7 @@ module ActiveResource::Associations
       elsif attributes.include?(method_name)
         attributes[method_name]
       elsif !new_record?
-        instance_variable_set(ivar_name, association_model.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
@@ -153,7 +156,8 @@ module ActiveResource::Associations
   end
 
   # Defines the has_one association
-  def defines_has_one_finder_method(method_name, association_model)
+  def defines_has_one_finder_method(reflection)
+    method_name = reflection.name
     ivar_name = :"@#{method_name}"
 
     define_method(method_name) do
@@ -161,12 +165,11 @@ module ActiveResource::Associations
         instance_variable_get(ivar_name)
       elsif attributes.include?(method_name)
         attributes[method_name]
-      elsif association_model.respond_to?(:singleton_name)
-        instance_variable_set(ivar_name, association_model.find(:params => {:"#{self.class.element_name}_id" => self.id}))
+      elsif reflection.klass.respond_to?(:singleton_name)
+        instance_variable_set(ivar_name, reflection.klass.find(params: { "#{self.class.element_name}_id": self.id }))
       else
-        instance_variable_set(ivar_name, association_model.find(:one, :from => "/#{self.class.collection_name}/#{self.id}/#{method_name}#{self.class.format_extension}"))
+        instance_variable_set(ivar_name, reflection.klass.find(:one, from: "/#{self.class.collection_name}/#{self.id}/#{method_name}#{self.class.format_extension}"))
       end
     end
   end
-
 end