restorm 1.0.0

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2012-2015 Rémi Prévost
+
+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,7 @@
+# Restorm
+
+Restorm is a fork of [Her](https://github.com/remi/her). Project is renamed so
+put it in rubygems.org. We have a special need for this to be in rubygems.org as
+Her was used as a dependency in our gems and we can't add a git repo as a
+dependency in the gemspec.
+

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler"
+require "rake"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+task :default => :spec
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = "spec/**/*_spec.rb"
+end

data/UPGRADE.md

@@ -0,0 +1,101 @@
+# Upgrade Her
+
+Here is a list of notable changes by release. Her follows the [Semantic Versioning](http://semver.org/) system.
+
+## 0.8.1 (Note: 0.8.0 yanked)
+
+- Initial support for JSONAPI [link](https://github.com/remiprev/her/pull/347)
+- Fix for has_one association parsing [link](https://github.com/remiprev/her/pull/352)
+- Fix for escaping path variables HT @marshall-lee [link](https://github.com/remiprev/her/pull/354)
+- Fix syntax highlighting in README HT @tippenein [link](https://github.com/remiprev/her/pull/356)
+- Fix associations with Active Model Serializers HT @minktom [link](https://github.com/remiprev/her/pull/359)
+
+## 0.7.6
+
+- Loosen restrictions on ActiveSupport and ActiveModel to accommodate security fixes [link](https://github.com/remiprev/her/commit/8ff641fcdaf14be7cc9b1a6ee6654f27f7dfa34c)
+
+## 0.7.5
+
+- Performance fix for responses with large number of objects [link](https://github.com/remiprev/her/pull/337)
+- Bugfix for dirty attributes [link](https://github.com/remiprev/her/commit/70285debc6837a33a3a750c7c4a7251439464b42)
+- Add ruby 2.1 and 2.2 to travis test run. We will likely be removing official 1.9.x support in the near future, and 
+will begin to align our support with the official ruby maintenance schedule. 
+- README updates
+
+## 0.6
+
+Associations have been refactored so that calling the association name method doesn’t immediately load or fetch the data.
+
+```ruby
+class User
+  include Her::Model
+  has_many :comments
+end
+
+# This doesn’t fetch the data yet and it’s still chainable
+comments = User.find(1).comments
+
+# This actually fetches the data
+puts comments.inspect
+
+# This is no longer possible in her-0.6
+comments = User.find(1).comments(:approved => 1)
+
+# To pass additional parameters to the HTTP request, we now have to do this
+comments = User.find(1).comments.where(:approved => 1)
+```
+
+## 0.5
+
+Her is now compatible with `ActiveModel` and includes `ActiveModel::Validations`.
+
+Before 0.5, the `errors` method on an object would return an error list received from the server (the `:errors` key defined by the parsing middleware). But now, `errors` returns the error list generated after calling the `valid?` method (or any other similar validation method from `ActiveModel::Validations`). The error list returned from the server is now accessible from the `response_errors` method.
+
+Since 0.5.5, Her provides a `store_response_errors` method, which allows you to choose the method which will return the response errors. You can use it to revert Her back to its original behavior (ie. `errors` returning the response errors):
+
+```ruby
+class User
+  include Her::Model
+  store_response_errors :errors
+end
+
+user = User.create(:email => "foo") # POST /users returns { :errors => ["Email is invalid"] }
+user.errors # => ["Email is invalid"]
+```
+
+## 0.2.4
+
+Her no longer includes default middleware when making HTTP requests. The user has now to define all the needed middleware. Before:
+
+```ruby
+Her::API.setup :url => "https://api.example.com" do |connection|
+  connection.insert(0, FaradayMiddle::OAuth)
+end
+```
+
+Now:
+
+```ruby
+Her::API.setup :url => "https://api.example.com" do |connection|
+  connection.use FaradayMiddle::OAuth
+  connection.use Her::Middleware::FirstLevelParseJSON
+  connection.use Faraday::Request::UrlEncoded
+  connection.use Faraday::Adapter::NetHttp
+end
+```
+
+## 0.2
+
+The default parser middleware has been replaced to treat first-level JSON data as the resource or collection data. Before it expected this:
+
+```json
+{ "data": { "id": 1, "name": "Foo" }, "errors": [] }
+```
+
+Now it expects this (the `errors` key is not treated as resource data):
+  
+```json
+{ "id": 1, "name": "Foo", "errors": [] }
+```
+
+If you still want to get the old behavior, you can use `Her::Middleware::SecondLevelParseJSON` instead of `Her::Middleware::FirstLevelParseJSON` in your middleware stack.

data/gemfiles/Gemfile.activemodel-4.2

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec :path => "../"
+
+gem 'activemodel', '~> 4.2.0'
+gem 'faraday', '~> 0.8.9'

data/gemfiles/Gemfile.activemodel-5.0

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec :path => "../"
+
+gem 'activemodel', '~> 5.0.0'
+gem 'faraday', '~> 0.8.9'

data/gemfiles/Gemfile.activemodel-5.1

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec :path => "../"
+
+gem 'activemodel', '~> 5.1.0'
+gem 'faraday', '~> 0.8.9'

data/gemfiles/Gemfile.activemodel-5.2

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec :path => "../"
+
+gem 'activemodel', '~> 5.2.0'
+gem 'faraday', '~> 0.8.9'

data/gemfiles/Gemfile.faraday-1.0

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec :path => "../"
+
+gem 'activemodel', '~> 4.2.1'
+gem 'faraday', '~> 1.0'

data/lib/restorm/api.rb

@@ -0,0 +1,121 @@
+module Restorm
+  # This class is where all HTTP requests are made. Before using Restorm, you must configure it
+  # so it knows where to make those requests. In Rails, this is usually done in `config/initializers/restorm.rb`:
+  class API
+
+    # @private
+    attr_reader :connection, :options
+
+    # Constants
+    FARADAY_OPTIONS = [:request, :proxy, :ssl, :builder, :url, :parallel_manager, :params, :headers, :builder_class].freeze
+
+    # Setup a default API connection. Accepted arguments and options are the same as {API#setup}.
+    def self.setup(opts = {}, &block)
+      @default_api = new(opts, &block)
+    end
+
+    # Create a new API object. This is useful to create multiple APIs and use them with the `uses_api` method.
+    # If your application uses only one API, you should use Restorm::API.setup to configure the default API
+    #
+    # @example Setting up a new API
+    #   api = Restorm::API.new :url => "https://api.example" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Restorm::Middleware::DefaultParseJSON
+    #   end
+    #
+    #   class User
+    #     uses_api api
+    #   end
+    def initialize(*args, &blk)
+      setup(*args, &blk)
+    end
+
+    # Setup the API connection.
+    #
+    # @param [Hash] opts the Faraday options
+    # @option opts [String] :url The main HTTP API root (eg. `https://api.example.com`)
+    # @option opts [String] :ssl A hash containing [SSL options](https://github.com/lostisland/faraday/wiki/Setting-up-SSL-certificates)
+    #
+    # @return Faraday::Connection
+    #
+    # @example Setting up the default API connection
+    #   Restorm::API.setup :url => "https://api.example"
+    #
+    # @example A custom middleware added to the default list
+    #   class MyAuthentication < Faraday::Middleware
+    #     def call(env)
+    #       env[:request_headers]["X-API-Token"] = "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
+    #       @app.call(env)
+    #     end
+    #   end
+    #   Restorm::API.setup :url => "https://api.example.com" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Restorm::Middleware::DefaultParseJSON
+    #     connection.use MyAuthentication
+    #     connection.use Faraday::Adapter::NetHttp
+    #   end
+    #
+    # @example A custom parse middleware
+    #   class MyCustomParser < Faraday::Response::Middleware
+    #     def on_complete(env)
+    #       json = JSON.parse(env[:body], :symbolize_names => true)
+    #       errors = json.delete(:errors) || {}
+    #       metadata = json.delete(:metadata) || []
+    #       env[:body] = { :data => json, :errors => errors, :metadata => metadata }
+    #     end
+    #   end
+    #   Restorm::API.setup :url => "https://api.example.com" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use MyCustomParser
+    #     connection.use Faraday::Adapter::NetHttp
+    #   end
+    def setup(opts = {}, &blk)
+      opts[:url] = opts.delete(:base_uri) if opts.include?(:base_uri) # Support legacy :base_uri option
+      @options = opts
+
+      faraday_options = @options.select { |key, _| FARADAY_OPTIONS.include?(key.to_sym) }
+      @connection = Faraday.new(faraday_options) do |connection|
+        yield connection if block_given?
+      end
+      self
+    end
+
+    # Define a custom parsing procedure. The procedure is passed the response object and is
+    # expected to return a hash with three keys: a main data Hash, an errors Hash
+    # and a metadata Hash.
+    #
+    # @private
+    def request(opts = {})
+      method = opts.delete(:_method)
+      path = opts.delete(:_path)
+      headers = opts.delete(:_headers)
+      opts.delete_if { |key, _| key.to_s =~ /^_/ } # Remove all internal parameters
+      if method == :options
+        # Faraday doesn't support the OPTIONS verb because of a name collision with an internal options method
+        # so we need to call run_request directly.
+        request.headers.merge!(headers) if headers
+        response = @connection.run_request method, path, opts, headers
+      else
+        response = @connection.send method do |request|
+          request.headers.merge!(headers) if headers
+          if method == :get
+            # For GET requests, treat additional parameters as querystring data
+            request.url path, opts
+          else
+            # For POST, PUT and DELETE requests, treat additional parameters as request body
+            request.url path
+            request.body = opts
+          end
+        end
+      end
+      { :parsed_data => response.env[:body], :response => response }
+    end
+
+    private
+
+    # @private
+    def self.default_api(opts = {})
+      defined?(@default_api) ? @default_api : nil
+    end
+  end
+end

data/lib/restorm/collection.rb

@@ -0,0 +1,13 @@
+module Restorm
+  class Collection < ::Array
+
+    attr_reader :metadata, :errors
+
+    # @private
+    def initialize(items = [], metadata = {}, errors = {})
+      super(items)
+      @metadata = metadata
+      @errors = errors
+    end
+  end
+end

data/lib/restorm/errors.rb

@@ -0,0 +1,29 @@
+module Restorm
+  module Errors
+    class PathError < StandardError
+
+      attr_reader :missing_parameter
+
+      def initialize(message, missing_parameter = nil)
+        super(message)
+        @missing_parameter = missing_parameter
+      end
+    end
+
+    class AssociationUnknownError < StandardError
+    end
+
+    class ParseError < StandardError
+    end
+
+    class ResourceInvalid < StandardError
+
+      attr_reader :resource
+      def initialize(resource)
+        @resource = resource
+        errors = @resource.response_errors.join(", ")
+        super("Remote validation failed: #{errors}")
+      end
+    end
+  end
+end

data/lib/restorm/json_api/model.rb

@@ -0,0 +1,42 @@
+module Restorm
+  module JsonApi
+    module Model
+      def self.included(klass)
+        klass.class_eval do
+          include Restorm::Model
+
+          [:parse_root_in_json, :include_root_in_json, :root_element, :primary_key].each do |method|
+            define_method method do |*_|
+              raise NoMethodError, "Restorm::JsonApi::Model does not support the #{method} configuration option"
+            end
+          end
+
+          method_for :update, :patch
+
+          @type = name.demodulize.tableize
+
+          def self.parse(data)
+            data.fetch(:attributes).merge(data.slice(:id))
+          end
+
+          def self.to_params(attributes, changes = {})
+            request_data = { type: @type }.tap do |request_body|
+              attrs = attributes.dup.symbolize_keys.tap do |filtered_attributes|
+                if her_api.options[:send_only_modified_attributes]
+                  filtered_attributes.slice! *changes.keys.map(&:to_sym)
+                end
+              end
+              request_body[:id] = attrs.delete(:id) if attrs[:id]
+              request_body[:attributes] = attrs
+            end
+            { data: request_data }
+          end
+
+          def self.type(type_name)
+            @type = type_name.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/restorm/middleware/accept_json.rb

@@ -0,0 +1,18 @@
+module Restorm
+  module Middleware
+    # This middleware adds a "Accept: application/json" HTTP header
+    class AcceptJSON < Faraday::Middleware
+
+      # @private
+      def add_header(headers)
+        headers.merge! "Accept" => "application/json"
+      end
+
+      # @private
+      def call(env)
+        add_header(env[:request_headers])
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/restorm/middleware/first_level_parse_json.rb

@@ -0,0 +1,37 @@
+module Restorm
+  module Middleware
+    # This middleware treat the received first-level JSON structure as the resource data.
+    class FirstLevelParseJSON < ParseJSON
+
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      # @private
+      def parse(body)
+        json = parse_json(body)
+        errors = json.delete(:errors) || {}
+        metadata = json.delete(:metadata) || {}
+        {
+          :data => json,
+          :errors => errors,
+          :metadata => metadata
+        }
+      end
+
+      # This method is triggered when the response has been received. It modifies
+      # the value of `env[:body]`.
+      #
+      # @param [Hash] env The response environment
+      # @private
+      def on_complete(env)
+        env[:body] = case env[:status]
+                     when 204
+                       parse('{}')
+                     else
+                       parse(env[:body])
+                     end
+      end
+    end
+  end
+end

data/lib/restorm/middleware/json_api_parser.rb

@@ -0,0 +1,37 @@
+module Restorm
+  module Middleware
+    # This middleware expects the resource/collection data to be contained in the `data`
+    # key of the JSON object
+    class JsonApiParser < ParseJSON
+
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      # @private
+      def parse(body)
+        json = parse_json(body)
+
+        {
+          :data => json[:data] || {},
+          :errors => json[:errors] || [],
+          :metadata => json[:meta] || {},
+        }
+      end
+
+      # This method is triggered when the response has been received. It modifies
+      # the value of `env[:body]`.
+      #
+      # @param [Hash] env The response environment
+      # @private
+      def on_complete(env)
+        env[:body] = case env[:status]
+                     when 204, 304
+                       parse('{}')
+                     else
+                       parse(env[:body])
+                     end
+      end
+    end
+  end
+end

data/lib/restorm/middleware/parse_json.rb

@@ -0,0 +1,22 @@
+module Restorm
+  module Middleware
+    class ParseJSON < Faraday::Middleware
+
+      # @private
+      def parse_json(body = nil)
+        body = '{}' if body.blank?
+        message = "Response from the API must behave like a Hash or an Array (last JSON response was #{body.inspect})"
+
+        json = begin
+          MultiJson.load(body, :symbolize_keys => true)
+        rescue MultiJson::LoadError
+          raise Restorm::Errors::ParseError, message
+        end
+
+        raise Restorm::Errors::ParseError, message unless json.is_a?(Hash) || json.is_a?(Array)
+
+        json
+      end
+    end
+  end
+end

data/lib/restorm/middleware/second_level_parse_json.rb

@@ -0,0 +1,37 @@
+module Restorm
+  module Middleware
+    # This middleware expects the resource/collection data to be contained in the `data`
+    # key of the JSON object
+    class SecondLevelParseJSON < ParseJSON
+
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      # @private
+      def parse(body)
+        json = parse_json(body)
+
+        {
+          :data => json[:data],
+          :errors => json[:errors],
+          :metadata => json[:metadata]
+        }
+      end
+
+      # This method is triggered when the response has been received. It modifies
+      # the value of `env[:body]`.
+      #
+      # @param [Hash] env The response environment
+      # @private
+      def on_complete(env)
+        env[:body] = case env[:status]
+                     when 204
+                       parse('{}')
+                     else
+                       parse(env[:body])
+                     end
+      end
+    end
+  end
+end

data/lib/restorm/middleware.rb

@@ -0,0 +1,12 @@
+require "restorm/middleware/parse_json"
+require "restorm/middleware/first_level_parse_json"
+require "restorm/middleware/second_level_parse_json"
+require "restorm/middleware/accept_json"
+
+module Restorm
+  module Middleware
+    DefaultParseJSON = FirstLevelParseJSON
+
+    autoload :JsonApiParser, 'restorm/middleware/json_api_parser'
+  end
+end

data/lib/restorm/model/associations/association.rb

@@ -0,0 +1,128 @@
+module Restorm
+  module Model
+    module Associations
+      class Association
+
+        # @private
+        attr_accessor :params
+
+        # @private
+        def initialize(parent, opts = {})
+          @parent = parent
+          @opts = opts
+          @params = {}
+
+          @klass = @parent.class.restorm_nearby_class(@opts[:class_name])
+          @name = @opts[:name]
+        end
+
+        # @private
+        def self.proxy(parent, opts = {})
+          AssociationProxy.new new(parent, opts)
+        end
+
+        # @private
+        def self.parse_single(association, klass, data)
+          data_key = association[:data_key]
+          return {} unless data[data_key]
+
+          klass = klass.restorm_nearby_class(association[:class_name])
+          { association[:name] => klass.instantiate_record(klass, data: data[data_key]) }
+        end
+
+        # @private
+        def assign_single_nested_attributes(attributes)
+          if @parent.attributes[@name].blank?
+            @parent.attributes[@name] = @klass.new(@klass.parse(attributes))
+          else
+            @parent.attributes[@name].assign_attributes(attributes)
+          end
+        end
+
+        # @private
+        def fetch(opts = {})
+          attribute_value = @parent.attributes[@name]
+          return @opts[:default].try(:dup) if @parent.attributes.include?(@name) && (attribute_value.nil? || !attribute_value.nil? && attribute_value.empty?) && @params.empty?
+
+          return @cached_result unless @params.any? || @cached_result.nil?
+          return @parent.attributes[@name] unless @params.any? || @parent.attributes[@name].blank?
+          return @opts[:default].try(:dup) if @parent.new?
+
+          path = build_association_path -> { "#{@parent.request_path(@params)}#{@opts[:path]}" }
+          @klass.get(path, @params).tap do |result|
+            @cached_result = result unless @params.any?
+          end
+        end
+
+        # @private
+        def build_association_path(code)
+          instance_exec(&code)
+        rescue Restorm::Errors::PathError
+          nil
+        end
+
+        # @private
+        def reset
+          @params = {}
+          @cached_result = nil
+          @parent.attributes.delete(@name)
+        end
+
+        # Add query parameters to the HTTP request performed to fetch the data
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #     has_many :comments
+        #   end
+        #
+        #   user = User.find(1)
+        #   user.comments.where(:approved => 1) # Fetched via GET "/users/1/comments?approved=1
+        def where(params = {})
+          return self if params.blank? && @parent.attributes[@name].blank?
+          AssociationProxy.new clone.tap { |a| a.params = a.params.merge(params) }
+        end
+        alias all where
+
+        # Fetches the data specified by id
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #     has_many :comments
+        #   end
+        #
+        #   user = User.find(1)
+        #   user.comments.find(3) # Fetched via GET "/users/1/comments/3
+        def find(id)
+          return nil if id.blank?
+          path = build_association_path -> { "#{@parent.request_path(@params)}#{@opts[:path]}/#{id}" }
+          @klass.get_resource(path, @params)
+        end
+
+        # Refetches the association and puts the proxy back in its initial state,
+        # which is unloaded. Cached associations are cleared.
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #     has_many :comments
+        #   end
+        #
+        #   class Comment
+        #     include Restorm::Model
+        #   end
+        #
+        #   user = User.find(1)
+        #   user.comments = [#<Comment(comments/2) id=2 body="Hello!">]
+        #   user.comments.first.id = "Oops"
+        #   user.comments.reload # => [#<Comment(comments/2) id=2 body="Hello!">]
+        #   # Fetched again via GET "/users/1/comments"
+        def reload
+          reset
+          fetch
+        end
+      end
+    end
+  end
+end