him 0.1.0

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-6.1

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "activemodel", "~> 6.1.0"
+gem "activesupport", "~> 6.1.0"

data/gemfiles/Gemfile.activemodel-7.0

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "activemodel", "~> 7.0.0"
+gem "activesupport", "~> 7.0.0"

data/gemfiles/Gemfile.activemodel-7.1

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "activemodel", "~> 7.1.0"
+gem "activesupport", "~> 7.1.0"

data/gemfiles/Gemfile.activemodel-7.2

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "activemodel", "~> 7.2.0"
+gem "activesupport", "~> 7.2.0"

data/gemfiles/Gemfile.activemodel-8.0

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "activemodel", "~> 8.0.0"
+gem "activesupport", "~> 8.0.0"

data/him.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+$:.push File.expand_path("../lib", __FILE__)
+require "him/version"
+
+Gem::Specification.new do |s|
+  s.name        = "him"
+  s.version     = Him::VERSION
+  s.authors     = ["Dale Stevens", "Rémi Prévost"]
+  s.email       = ["dale@twilightcoders.net"]
+  s.homepage    = "https://github.com/TwilightCoders/him"
+  s.license     = "MIT"
+  s.summary     = "An ORM that maps REST resources to Ruby objects. Forked from Her."
+  s.description = "Him is an ORM that maps REST resources and collections to Ruby objects, designed for RESTful API-powered applications."
+
+  s.required_ruby_version = ">= 3.1"
+
+  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", ">= 13.0"
+  s.add_development_dependency "rspec", "~> 3.5"
+
+  s.add_runtime_dependency "activemodel", ">= 6.1"
+  s.add_runtime_dependency "faraday", ">= 2.0"
+end

data/lib/him/api.rb

@@ -0,0 +1,121 @@
+module Him
+  # 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 :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 Him::API.setup to configure the default API
+    #
+    # @example Setting up a new API
+    #   api = Him::API.new :url => "https://api.example" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Him::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
+    #   Him::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
+    #   Him::API.setup :url => "https://api.example.com" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Him::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
+    #   Him::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/him/collection.rb

@@ -0,0 +1,21 @@
+module Him
+  class Collection < ::Array
+
+    attr_reader :metadata, :errors
+
+    # @private
+    def initialize(items = [], metadata = {}, errors = {})
+      super(items)
+      @metadata = metadata
+      @errors = errors
+    end
+
+    %i[select reject collect map compact flatten uniq reverse
+       sort sort_by sample shuffle slice drop take first last].each do |method|
+      define_method(method) do |*args, &block|
+        result = super(*args, &block)
+        result.is_a?(Array) ? self.class.new(result, @metadata, @errors) : result
+      end
+    end
+  end
+end

data/lib/him/errors.rb

@@ -0,0 +1,29 @@
+module Him
+  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/him/json_api/model.rb

@@ -0,0 +1,42 @@
+module Him
+  module JsonApi
+    module Model
+      def self.included(klass)
+        klass.class_eval do
+          include Him::Model
+
+          [:parse_root_in_json, :include_root_in_json, :root_element, :primary_key].each do |method|
+            define_method method do |*_|
+              raise NoMethodError, "Him::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/him/middleware/accept_json.rb

@@ -0,0 +1,18 @@
+module Him
+  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/him/middleware/first_level_parse_json.rb

@@ -0,0 +1,37 @@
+module Him
+  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/him/middleware/json_api_parser.rb

@@ -0,0 +1,65 @@
+module Him
+  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)
+
+        included = json.fetch(:included, [])
+        primary_data = json.fetch(:data, {})
+        Array(primary_data).each do |resource|
+          next unless resource.is_a?(Hash)
+          relationships = resource.delete(:relationships) { {} }
+          resource[:attributes].merge!(resolve_relationships(relationships, included))
+        end
+
+        {
+          data: primary_data || {},
+          errors: json[:errors] || [],
+          metadata: json[:meta] || {}
+        }
+      end
+
+      private
+
+      def resolve_relationships(relationships, included)
+        return {} if included.empty? || relationships.nil?
+        relationships.each_with_object({}) do |(rel_name, linkage), built|
+          linkage_data = linkage.fetch(:data, {})
+          built[rel_name] = if linkage_data.is_a?(Array)
+            linkage_data.map { |l| find_included(l, included) }.compact
+          else
+            find_included(linkage_data, included)
+          end
+        end
+      end
+
+      def find_included(linkage, included)
+        included.detect { |i| i.values_at(:id, :type) == linkage.values_at(:id, :type) }
+      end
+
+      public
+
+      # 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/him/middleware/parse_json.rb

@@ -0,0 +1,22 @@
+module Him
+  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
+          JSON.parse(body, symbolize_names: true)
+        rescue JSON::ParserError
+          raise Him::Errors::ParseError, message
+        end
+
+        raise Him::Errors::ParseError, message unless json.is_a?(Hash) || json.is_a?(Array)
+
+        json
+      end
+    end
+  end
+end

data/lib/him/middleware/second_level_parse_json.rb

@@ -0,0 +1,37 @@
+module Him
+  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/him/middleware.rb

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