active_cached_resource 0.0.1.pre

data/lib/activeresource/README.md

@@ -0,0 +1,283 @@
+# Active Resource
+
+**A vendored fork of [rails/activersource](https://github.com/rails/activeresource) packaged with `ActiveCachedResource`**
+
+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.
+
+### 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 verbs 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`

data/lib/activeresource/examples/performance.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "active_resource"
+require "benchmark"
+
+TIMES = (ENV["N"] || 10_000).to_i
+
+# deep nested resource
+attrs = {
+  id: 1,
+  name: "Luis",
+  age: 21,
+  friends: [
+    {
+      name: "JK",
+      age: 24,
+      colors: ["red", "green", "blue"],
+      brothers: [
+        {
+          name: "Mateo",
+          age: 35,
+          children: [{ name: "Edith", age: 5 }, { name: "Martha", age: 4 }]
+        },
+        {
+          name: "Felipe",
+          age: 33,
+          children: [{ name: "Bryan", age: 1 }, { name: "Luke", age: 0 }]
+        }
+      ]
+    },
+    {
+      name: "Eduardo",
+      age: 20,
+      colors: [],
+      brothers: [
+        {
+          name: "Sebas",
+          age: 23,
+          children: [{ name: "Andres", age: 0 }, { name: "Jorge", age: 2 }]
+        },
+        {
+          name: "Elsa",
+          age: 19,
+          children: [{ name: "Natacha", age: 1 }]
+        },
+        {
+          name: "Milena",
+          age: 16,
+          children: []
+        }
+      ]
+    }
+  ]
+}
+
+class Customer < ActiveResource::Base
+  self.site = "http://37s.sunrise.i:3000"
+end
+
+module Nested
+  class Customer < ActiveResource::Base
+    self.site = "http://37s.sunrise.i:3000"
+  end
+end
+
+Benchmark.bm(40) do |x|
+  x.report("Model.new (instantiation)")              { TIMES.times { Customer.new } }
+  x.report("Nested::Model.new (instantiation)")      { TIMES.times { Nested::Customer.new } }
+  x.report("Model.new (setting attributes)")         { TIMES.times { Customer.new attrs } }
+  x.report("Nested::Model.new (setting attributes)") { TIMES.times { Nested::Customer.new attrs } }
+end

data/lib/activeresource/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/activeresource/lib/active_resource/associations/builder/association.rb

@@ -0,0 +1,32 @@
+# 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]
+
+    # would identify subclasses of association
+    class_attribute :macro
+
+    attr_reader :model, :name, :options, :klass
+
+    def self.build(model, name, options)
+      new(model, name, options).build
+    end
+
+    def initialize(model, name, options)
+      @model, @name, @options = model, name, options
+    end
+
+    def build
+      validate_options
+      model.create_reflection(self.class.macro, name, options)
+    end
+
+    private
+      def validate_options
+        options.assert_valid_keys(self.class.valid_options)
+      end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveResource::Associations::Builder
+  class BelongsTo < Association
+    self.valid_options += [:foreign_key]
+
+    self.macro = :belongs_to
+
+    def build
+      validate_options
+      reflection = model.create_reflection(self.class.macro, name, options)
+      model.defines_belongs_to_finder_method(reflection)
+      reflection
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# 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)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# 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)
+      end
+    end
+  end
+end

data/lib/activeresource/lib/active_resource/associations.rb

@@ -0,0 +1,175 @@
+# 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"
+  end
+
+
+
+  # Specifies a one-to-many association.
+  #
+  # === Options
+  # [:class_name]
+  #   Specify the class name of the association. This class name would
+  #   be used for resolving the association class.
+  #
+  # ==== Example for [:class_name] - option
+  # GET /posts/123.json delivers following response body:
+  #   {
+  #     title: "ActiveResource now has associations",
+  #     body: "Lorem Ipsum"
+  #     comments: [
+  #       {
+  #         content: "..."
+  #       },
+  #       {
+  #         content: "..."
+  #       }
+  #     ]
+  #   }
+  # ====
+  #
+  # <tt>has_many :comments, :class_name => 'myblog/comment'</tt>
+  # Would resolve those comments into the <tt>Myblog::Comment</tt> class.
+  #
+  # If the response body does not contain an attribute matching the association name
+  # a request sent to the index action under the current resource.
+  # For the example above, if the comments are not present the requested path would be:
+  # GET /posts/123/comments.xml
+  def has_many(name, options = {})
+    Builder::HasMany.build(self, name, options)
+  end
+
+  # Specifies a one-to-one association.
+  #
+  # === Options
+  # [:class_name]
+  #   Specify the class name of the association. This class name would
+  #   be used for resolving the association class.
+  #
+  # ==== Example for [:class_name] - option
+  # GET /posts/1.json delivers following response body:
+  #   {
+  #     title: "ActiveResource now has associations",
+  #     body: "Lorem Ipsum",
+  #     author: {
+  #       name: "Gabby Blogger",
+  #     }
+  #   }
+  # ====
+  #
+  # <tt>has_one :author, :class_name => 'myblog/author'</tt>
+  # 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 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.
+  #
+  def has_one(name, options = {})
+    Builder::HasOne.build(self, name, options)
+  end
+
+  # Specifies a one-to-one association with another class. This class should only be used
+  # if this class contains the foreign key.
+  #
+  # Methods will be added for retrieval and query for a single associated object, for which
+  # this object holds an id:
+  #
+  # [association(force_reload = false)]
+  #   Returns the associated object. +nil+ is returned if the foreign key is +nil+.
+  #   Throws a ActiveResource::ResourceNotFound exception if the foreign key is not +nil+
+  #   and the resource is not found.
+  #
+  # (+association+ is replaced with the symbol passed as the first argument, so
+  # <tt>belongs_to :post</tt> would add among others <tt>post.nil?</tt>.
+  #
+  # === Example
+  #
+  # 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.
+  #   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 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>
+  #   association will use "post_id" as the default <tt>:foreign_key</tt>. Similarly,
+  #   <tt>belongs_to :article, :class_name => "Post"</tt> will use a foreign key
+  #   of "article_id".
+  #
+  # Option examples:
+  # <tt>belongs_to :customer, :class_name => 'User'</tt>
+  # Creates a belongs_to association called customer which is represented through the <tt>User</tt> class.
+  #
+  # <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 = {})
+    Builder::BelongsTo.build(self, name, options)
+  end
+
+  # Defines the belongs_to association finder method
+  def defines_belongs_to_finder_method(reflection)
+    method_name = reflection.name
+    ivar_name = :"@#{method_name}"
+
+    if method_defined?(method_name)
+      instance_variable_set(ivar_name, nil)
+      remove_method(method_name)
+    end
+
+    define_method(method_name) do
+      if instance_variable_defined?(ivar_name)
+        instance_variable_get(ivar_name)
+      elsif attributes.include?(method_name)
+        attributes[method_name]
+      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(reflection)
+    method_name = reflection.name
+    ivar_name = :"@#{method_name}"
+
+    define_method(method_name) do
+      if instance_variable_defined?(ivar_name)
+        instance_variable_get(ivar_name)
+      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 }))
+      else
+        instance_variable_set(ivar_name, reflection.klass.find(:all))
+      end
+    end
+  end
+
+  # Defines the has_one association
+  def defines_has_one_finder_method(reflection)
+    method_name = reflection.name
+    ivar_name = :"@#{method_name}"
+
+    define_method(method_name) do
+      if instance_variable_defined?(ivar_name)
+        instance_variable_get(ivar_name)
+      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 }))
+      else
+        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