extended_her 0.5

data/lib/her/middleware.rb

@@ -0,0 +1,9 @@
+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,15 @@
+module Her
+  module Middleware
+    # This middleware adds a "Accept: application/json" HTTP header
+    class AcceptJSON < Faraday::Middleware
+      def add_header(headers)
+        headers.merge! "Accept" => "application/json"
+      end
+
+      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,34 @@
+module Her
+  module Middleware
+    # This middleware treat the received first-level JSON structure as the resource data.
+    class FirstLevelParseJSON < Faraday::Response::Middleware
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      def parse(body)
+        json = MultiJson.load(body, :symbolize_keys => true)
+        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
+      def on_complete(env)
+        case env[:status]
+        when 204
+          env[:body] = parse('{}')
+        else
+          env[:body] = parse(env[:body])
+        end
+      end
+    end
+  end
+end

data/lib/her/middleware/second_level_parse_json.rb

@@ -0,0 +1,28 @@
+module Her
+  module Middleware
+    # This middleware expects the resource/collection data to be contained in the `data`
+    # key of the JSON object
+    class SecondLevelParseJSON < Faraday::Response::Middleware
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      def parse(body)
+        json = MultiJson.load(body, :symbolize_keys => true)
+        {
+          :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
+      def on_complete(env)
+        env[:body] = parse(env[:body])
+      end
+    end
+  end
+end

data/lib/her/model.rb

@@ -0,0 +1,69 @@
+require 'her/model/base'
+require 'her/model/http'
+require 'her/model/orm/comparison_methods'
+require 'her/model/orm/create_methods'
+require 'her/model/orm/destroy_methods'
+require 'her/model/orm/error_methods'
+require 'her/model/orm/fields_definition'
+require 'her/model/orm/find_methods'
+require 'her/model/orm/persistance_methods'
+require 'her/model/orm/relation_mapper'
+require 'her/model/orm/save_methods'
+require 'her/model/orm/serialization_methods'
+require 'her/model/orm/update_methods'
+require 'her/model/orm'
+require 'her/model/relationships'
+require 'her/model/hooks'
+require 'her/model/introspection'
+require 'her/model/paths'
+
+module Her
+  # This module is the main element of Her. After creating a Her::API object,
+  # include this module in your models to get a few magic methods defined in them.
+  #
+  # @example
+  #   class User
+  #     include Her::Model
+  #   end
+  #
+  #   @user = User.new(:name => "Rémi")
+  #   @user.save
+  module Model
+    extend ActiveSupport::Concern
+
+    # Instance methods
+    include Her::Model::ORM
+    include Her::Model::Introspection
+    include Her::Model::Paths
+    include Her::Model::Relationships
+
+    # Class methods
+    included do
+      extend Her::Model::Base
+      extend Her::Model::HTTP
+      extend Her::Model::Hooks
+
+      # Define default settings
+      root_element name.demodulize.underscore
+      collection_path root_element.pluralize
+      resource_path [collection_path, '/:id'].join
+      uses_api Her::API.default_api
+    end
+
+    # Returns true if attribute_name is
+    # * in orm data
+    # * a relationship
+    def has_key?(attribute_name)
+      has_data?(attribute_name) ||
+      has_relationship?(attribute_name)
+    end
+
+    # Returns
+    # * the value of the attribute_nane attribute if it's in orm data
+    # * the resource/collection corrsponding to attribute_name if it's a relationship
+    def [](attribute_name)
+      get_data(attribute_name) ||
+      get_relationship(attribute_name)
+    end
+  end
+end

data/lib/her/model/base.rb

@@ -0,0 +1,7 @@
+module Her
+  module Model
+    # This module includes basic functionnality to Her::Model
+    module Base
+    end
+  end
+end

data/lib/her/model/hooks.rb

@@ -0,0 +1,114 @@
+module Her
+  module Model
+    # Her supports hooks/callbacks that are triggered whenever resources are created, updated or destroyed.
+    #
+    # @example Defining a hook with a block
+    #   class User
+    #     include Her::Model
+    #     before_save { |resource| resource.internal_id = 42 }
+    #   end
+    #
+    # @example Defining a hook with a method name
+    #   class User
+    #     include Her::Model
+    #     before_save :set_internal_id
+    #
+    #     private
+    #     def set_internal_id
+    #       self.internal_id = 42
+    #     end
+    #   end
+    module Hooks
+      # Add a *before save* callback. Triggered before a resource is created or updated.
+      # @param [Symbol, &block] method A method or a block to be called
+      def before_save(method=nil, &block); set_hook(:before, :save, method || block); end
+
+      # Add a *before create* callback. Triggered before a resource is created.
+      # @param [Symbol, &block] method A method or a block to be called
+      def before_create(method=nil, &block); set_hook(:before, :create, method || block); end
+
+      # Add a *before update* callback. Triggered before a resource is updated.
+      # @param [Symbol, &block] method A method or a block to be called
+      def before_update(method=nil, &block); set_hook(:before, :update, method || block); end
+
+      # Add a *before destroy* callback. Triggered before a resource is destroyed.
+      # @param [Symbol, &block] method A method or a block to be called
+      def before_destroy(method=nil, &block); set_hook(:before, :destroy, method || block); end
+
+      # Do not add a *before find* callback. Only *after find* is supported.
+      def before_find(method=nil, &block); raise NoMethodError, "undefined method `before_find' for #{self}"; end
+
+      # Add a *after save* callback. Triggered after a resource is created or updated.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_save(method=nil, &block); set_hook(:after, :save, method || block); end
+
+      # Add a *after create* callback. Triggered after a resource is created.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_create(method=nil, &block); set_hook(:after, :create, method || block); end
+
+      # Add a *after update* callback. Triggered after a resource is updated.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_update(method=nil, &block); set_hook(:after, :update, method || block); end
+
+      # Add a *after destroy* callback. Triggered after a resource is destroyed.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_destroy(method=nil, &block); set_hook(:after, :destroy, method || block); end
+
+      # Add a *after find* callback. Triggered after a resource is found.
+      # @param [Symbol, &block] method A method or a block to be called
+      def after_find(method=nil, &block); set_hook(:after, :find, method || block); end
+
+      # Wrap a block between “before” and “after” hooks
+      # @private
+      def wrap_in_hooks(resource, *hooks)
+        perform_before_hooks(resource, *hooks)
+        yield(resource, resource.class) if block_given?
+        perform_after_hooks(resource, *hooks.reverse)
+      end
+
+      # @private
+      def hooks
+        @her_hooks ||= begin
+          if superclass.respond_to?(:hooks)
+            superclass.hooks.dup
+          else
+            {}
+          end
+        end
+      end
+
+      private
+      # @private
+      def set_hook(time, name, action)
+        (self.hooks["#{time}_#{name}".to_sym] ||= []) << action
+      end
+
+      # @private
+      def perform_hook(record, time, name)
+        Array(self.hooks["#{time}_#{name}".to_sym]).each do |hook|
+          if hook.is_a? Symbol
+            record.send(hook)
+          else
+            hook.call(record)
+          end
+        end
+      end
+
+      # Perform “after” hooks on a resource
+      # @private
+      def perform_after_hooks(resource, *hooks)
+        hooks.each do |hook|
+          perform_hook(resource, :after, hook)
+        end
+      end
+
+      # Perform “before” hooks on a resource
+      # @private
+      def perform_before_hooks(resource, *hooks)
+        hooks.each do |hook|
+          perform_hook(resource, :before, hook)
+        end
+      end
+    end
+  end
+end

data/lib/her/model/http.rb

@@ -0,0 +1,284 @@
+module Her
+  module Model
+    # This module interacts with Her::API to fetch HTTP data
+    module HTTP
+      # Automatically inherit a superclass' api
+      def her_api
+        @her_api ||= begin
+          if superclass.respond_to?(:her_api)
+            superclass.her_api
+          else
+            Her::API.default_api
+          end
+        end
+      end
+
+      # Link a model with a Her::API object
+      def uses_api(api)
+        @her_api = api
+      end
+
+      # Main request wrapper around Her::API. Used to make custom request to the API.
+      # @private
+      def request(attrs={})
+        initial_attrs = attrs.dup
+        started = Time.now.to_f
+        parsed_data = her_api.request(attrs)
+        request_time = Time.now.to_f - started
+        log(initial_attrs, request_time)
+
+        if block_given?
+          yield parsed_data
+        else
+          parsed_data
+        end
+      end
+
+      def log(attrs, time)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger.respond_to?(:debug)
+
+        method = attrs.delete(:_method).to_s.upcase
+        path = attrs.delete(:_path)
+
+        Rails.logger.debug("* HER request: #{method} #{path} [#{time}s] #{attrs}")
+      end
+
+      # Make a GET request and return either a collection or a resource
+      #
+      # @example
+      #   class User
+      #     include Her::Model
+      #   end
+      #
+      #   @popular_users = User.get(:popular)
+      #   # Fetched via GET "/users/popular"
+      def get(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        get_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          end
+        end
+      end
+
+      # Make a GET request and return the parsed JSON response (not mapped to objects)
+      def get_raw(path, attrs={}, &block)
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        request(attrs.merge(:_method => :get, :_path => path), &block)
+      end
+
+      # Make a GET request and return a collection of resources
+      def get_collection(path=nil, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        get_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end
+
+      # Make a GET request and return a collection of resources
+      def get_resource(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        get_raw(path, attrs) do |parsed_data|
+          new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+        end
+      end
+
+      # Make a POST request and return either a collection or a resource
+      def post(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        post_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          end
+        end
+      end
+
+      # Make a POST request and return the parsed JSON response (not mapped to objects)
+      def post_raw(path, attrs={}, &block)
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        request(attrs.merge(:_method => :post, :_path => path), &block)
+      end
+
+      # Make a POST request and return a collection of resources
+      def post_collection(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        post_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end
+
+      # Make a POST request and return a collection of resources
+      def post_resource(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        post_raw(path, attrs) do |parsed_data|
+          new(parse(parsed_data[:data]))
+        end
+      end
+
+      # Make a PUT request and return either a collection or a resource
+      def put(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        put_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          end
+        end
+      end
+
+      # Make a PUT request and return the parsed JSON response (not mapped to objects)
+      def put_raw(path, attrs={}, &block)
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        request(attrs.merge(:_method => :put, :_path => path), &block)
+      end
+
+      # Make a PUT request and return a collection of resources
+      def put_collection(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        put_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end
+
+      # Make a PUT request and return a collection of resources
+      def put_resource(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        put_raw(path, attrs) do |parsed_data|
+          new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+        end
+      end
+
+      # Make a PATCH request and return either a collection or a resource
+      def patch(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        patch_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          end
+        end
+      end
+
+      # Make a PATCH request and return the parsed JSON response (not mapped to objects)
+      def patch_raw(path, attrs={}, &block)
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        request(attrs.merge(:_method => :patch, :_path => path), &block)
+      end
+
+      # Make a PATCH request and return a collection of resources
+      def patch_collection(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        patch_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end
+
+      # Make a PATCH request and return a collection of resources
+      def patch_resource(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        patch_raw(path, attrs) do |parsed_data|
+          new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+        end
+      end
+
+      # Make a DELETE request and return either a collection or a resource
+      def delete(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        delete_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          end
+        end
+      end
+
+      # Make a DELETE request and return the parsed JSON response (not mapped to objects)
+      def delete_raw(path, attrs={}, &block)
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        request(attrs.merge(:_method => :delete, :_path => path), &block)
+      end
+
+      # Make a DELETE request and return a collection of resources
+      def delete_collection(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        delete_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end
+
+      # Make a DELETE request and return a collection of resources
+      def delete_resource(path, attrs={})
+        path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
+        delete_raw(path, attrs) do |parsed_data|
+          new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+        end
+      end
+
+      # Define custom GET requests
+      #
+      # @example
+      #   class User
+      #     include Her::Model
+      #     custom_get :popular
+      #   end
+      #
+      #   User.popular
+      #   # Fetched from GET "/users/popular"
+      def custom_get(*paths)
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            get(path, attrs.first || Hash.new)
+          end
+        end
+      end
+
+      # Define custom POST requests
+      def custom_post(*paths)
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            post(path, attrs.first || Hash.new)
+          end
+        end
+      end
+
+      # Define custom PUT requests
+      def custom_put(*paths)
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            put(path, attrs.first || Hash.new)
+          end
+        end
+      end
+
+      # Define custom PATCH requests
+      def custom_patch(*paths)
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            patch(path, attrs.first || Hash.new)
+          end
+        end
+      end
+
+      # Define custom DELETE requests
+      def custom_delete(*paths)
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            delete(path, attrs.first || Hash.new)
+          end
+        end
+      end
+    end
+  end
+end