herr 0.7.3

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,81 @@
+# Upgrade Her
+
+Here is a list of backward-incompatible changes that were introduced while Her is pre-1.0. After reaching 1.0, it will follow the [Semantic Versioning](http://semver.org/) system.
+
+## 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-3.2.x

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

data/gemfiles/Gemfile.activemodel-4.0

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

data/gemfiles/Gemfile.activemodel-4.1

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

data/gemfiles/Gemfile.activemodel-4.2

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

data/her.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "her/version"
+
+Gem::Specification.new do |s|
+  s.name        = "herr"
+  s.version     = Her::VERSION
+  s.authors     = ["Rémi Prévost", "Dermot Haughey"]
+  s.email       = ["hderms@gmail.com"]
+  s.homepage    = "http://her-rb.org"
+  s.license     = "MIT"
+  s.summary     = "A simple Representational State Transfer-based Hypertext Transfer Protocol-powered Object Relational Mapper. Forked from 'her'"
+  s.description = "Herr is an ORM that maps REST resources and collections to Ruby objects"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rake", "~> 10.0"
+  s.add_development_dependency "rspec", "~> 2.13"
+  s.add_development_dependency "rspec-its", "~> 1.0"
+  s.add_development_dependency "fivemat", "~> 1.2"
+  s.add_development_dependency "json", "~> 1.8"
+
+  s.add_runtime_dependency "activemodel", ">= 3.0.0", "<= 4.2"
+  s.add_runtime_dependency "activesupport", ">= 3.0.0", "<= 4.2"
+  s.add_runtime_dependency "faraday", ">= 0.8", "< 1.0"
+  s.add_runtime_dependency "multi_json", "~> 1.7"
+end

data/lib/her.rb

@@ -0,0 +1,16 @@
+require "her/version"
+
+require "multi_json"
+require "faraday"
+require "active_support"
+require "active_support/inflector"
+require "active_support/core_ext/hash"
+
+require "her/model"
+require "her/api"
+require "her/middleware"
+require "her/errors"
+require "her/collection"
+
+module Her
+end

data/lib/her/api.rb

@@ -0,0 +1,115 @@
+module Her
+  # This class is where all HTTP requests are made. Before using Her, you must configure it
+  # so it knows where to make those requests. In Rails, this is usually done in `config/initializers/her.rb`:
+  class API
+    # @private
+    attr_reader :base_uri, :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
+      @default_api.setup(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 Her::API.setup to configure the default API
+    #
+    # @example Setting up a new API
+    #   api = Her::API.new :url => "https://api.example" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Her::Middleware::DefaultParseJSON
+    #   end
+    #
+    #   class User
+    #     uses_api api
+    #   end
+    def initialize(*args, &blk)
+      self.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/technoweenie/faraday/wiki/Setting-up-SSL-certificates)
+    #
+    # @return Faraday::Connection
+    #
+    # @example Setting up the default API connection
+    #   Her::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
+    #   Her::API.setup :url => "https://api.example.com" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Her::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
+    #   Her::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
+      @base_uri = opts[:url]
+      @options = opts
+
+      faraday_options = @options.reject { |key, value| !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, value| key.to_s =~ /^_/ } # Remove all internal parameters
+      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
+
+      { :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/her/collection.rb

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

data/lib/her/errors.rb

@@ -0,0 +1,27 @@
+module Her
+  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/her/middleware.rb

@@ -0,0 +1,10 @@
+require "her/middleware/parse_json"
+require "her/middleware/first_level_parse_json"
+require "her/middleware/second_level_parse_json"
+require "her/middleware/accept_json"
+
+module Her
+  module Middleware
+    DefaultParseJSON = FirstLevelParseJSON
+  end
+end

data/lib/her/middleware/accept_json.rb

@@ -0,0 +1,17 @@
+module Her
+  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/her/middleware/first_level_parse_json.rb

@@ -0,0 +1,36 @@
+module Her
+  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/her/middleware/parse_json.rb

@@ -0,0 +1,21 @@
+module Her
+  module Middleware
+    class ParseJSON < Faraday::Response::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 Her::Errors::ParseError, message
+        end
+
+        raise Her::Errors::ParseError, message unless json.is_a?(Hash) or json.is_a?(Array)
+
+        json
+      end
+    end
+  end
+end

data/lib/her/middleware/second_level_parse_json.rb

@@ -0,0 +1,36 @@
+module Her
+  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