caprese 0.2.0

data/lib/caprese/controller/concerns/relationships.rb

@@ -0,0 +1,250 @@
+require 'active_support/concern'
+require 'caprese/errors'
+
+module Caprese
+  module Relationships
+    extend ActiveSupport::Concern
+
+    # Applies further scopes to a collection association
+    # @note Can be overridden to customize scoping at a per-relationship level
+    #
+    # @example
+    #   def relationship_scope(name, scope)
+    #     case name
+    #     when :transactions
+    #       scope.by_merchant(...)
+    #     when :orders
+    #       scope.by_user(...)
+    #     end
+    #   end
+    #
+    # @param [String] name the name of the association
+    # @param [Relation] scope the scope corresponding to a collection association
+    def relationship_scope(name, scope)
+      scope
+    end
+
+    # Retrieves the data for a relationship, not just the definition/resource identifier
+    #   @note Resource Identifier = { id: '...', type: '....' }
+    #   @note Resource = Resource Identifier + { attributes: { ... } }
+    #
+    # @note Adds a links[:self] link to this endpoint itself, to be JSON API compliant
+    # @note When returning single resource, adds a related endpoint URL that points to
+    #   the root resource URL
+    #
+    # @example Order<token: 'asd27h'> with product
+    #   links[:self] = 'http://www.example.com/api/v1/orders/asd27h/product'
+    #   links[:related] = 'http://www.example.com/api/v1/products/h45sql'
+    #
+    # @example Order<token: 'asd27h'> with transactions
+    #   links[:self] = 'http://www.example.com/api/v1/orders/asd27h/transactions/7ytr4l'
+    #   links[:related] = 'http://www.example.com/api/v1/transactions/7ytr4l'
+    #
+    # GET /api/v1/:controller/:id/:relationship(/:relation_primary_key_value)
+    def get_relationship_data
+      target =
+        if queried_association.reflection.collection?
+          scope = relationship_scope(params[:relationship], queried_association.reader)
+
+          if params[:relation_primary_key_value].present?
+            get_record!(scope, self.class.config.resource_primary_key, params[:relation_primary_key_value])
+          else
+            apply_sorting_pagination_to_scope(scope)
+          end
+        else
+          queried_association.reader
+        end
+
+      links = { self: request.original_url }
+
+      if !target.respond_to?(:to_ary) &&
+        respond_to?(related_url = version_name("#{params[:relationship].singularize}_url"))
+
+        links[:related] =
+          send(
+            related_url,
+            target.read_attribute(self.config.resource_primary_key)
+          )
+      end
+
+      render json: target, links: links
+    end
+
+    # Returns relationship data for a resource
+    #
+    # 1. Find resource we are updating relationship for
+    # 2. Check relationship exists *or respond with error*
+    # 3. Add self/related links for relationship
+    # 4. Respond with relationship data
+    #
+    # @example to-one relationship
+    #   GET /orders/asd27h/relationships/product
+    #
+    #   {
+    #     "links": {
+    #       "self": "/orders/asd27h/relationships/product",
+    #       "related": "orders/asd27h/product"
+    #     },
+    #     "data": {
+    #       "type": "products",
+    #       "token": "hy7sql"
+    #     }
+    #   }
+    #
+    # @example to-many relationship
+    #   GET /orders/1/relationships/transactions
+    #
+    #   {
+    #     "links": {
+    #       "self": "/orders/asd27h/relationships/transactions",
+    #       "related": "orders/asd27h/transactions"
+    #     },
+    #     "data": [
+    #       { "type": "transactions", "token": "hy7sql" },
+    #       { "type": "transactions", "token": "lki26s" },
+    #     ]
+    #   }
+    #
+    # GET /api/v1/:controller/:id/relationships/:relationship
+    def get_relationship_definition
+      links = { self: request.original_url }
+
+      # Add related link for this relationship if it exists
+      if respond_to?(related_path = "relationship_data_#{version_name(unversion(params[:controller]).singularize)}_url")
+        links[:related] = send(related_path, params[:id], params[:relationship])
+      end
+
+      target = queried_association.reader
+
+      if queried_association.reflection.collection?
+        target = relationship_scope(params[:relationship], target)
+      end
+
+      render json: target, links: links, fields: {}
+    end
+
+    # Updates a relationship for a resource
+    #
+    # 1. Find resource we are updating relationship for
+    # 2. Check relationship exists *or respond with error*
+    # 3. Find each potential relationship resource corresponding to the resource identifiers passed in
+    # 4. Modify relationship based on relationship type (one-to-many, one-to-one) and HTTP verb (PATCH, POST, DELETE)
+    # 5. Check if update was successful
+    #   * If successful, return 204 No Content
+    #   * If unsuccessful, return 403 Forbidden
+    #
+    # @example modify to-one relationship
+    #   PATCH /orders/asd27h/relationships/product
+    #
+    #   {
+    #     "data": { "type": "products", "token": "hy7sql" }
+    #   }
+    #
+    # @example clear to-one relationship
+    #   PATCH /orders/asd27h/relationships/product
+    #
+    #   {
+    #     "data": null
+    #   }
+    #
+    # @example modify to-many relationship
+    #   PATCH /orders/asd27h/relationships/transactions
+    #
+    #   {
+    #     "data": [
+    #       { "type": "transactions", "token": "hy7sql" },
+    #       { "type": "transactions", "token": "lki26s" },
+    #     ]
+    #   }
+    #
+    # @example clear to to-many relationship
+    #   PATCH /orders/asd27h/relationships/transactions
+    #
+    #   {
+    #     "data": []
+    #   }
+    #
+    # @example append to to-many relationship
+    #   POST /orders/asd27h/relationships/transactions
+    #
+    #   {
+    #     "data": [
+    #       { "type": "transactions", "token": "hy7sql" },
+    #       { "type": "transactions", "token": "lki26s" },
+    #     ]
+    #   }
+    #
+    # @example remove from to-many relationship
+    #   DELETE /orders/asd27h/relationships/transactions
+    #
+    #   {
+    #     "data": [
+    #       { "type": "transactions", "token": "hy7sql" },
+    #       { "type": "transactions", "token": "lki26s" },
+    #     ]
+    #   }
+    #
+    # PATCH/POST/DELETE /api/v1/:controller/:id/relationships/:relationship
+    def update_relationship_definition
+      if queried_association &&
+        flattened_keys_for(permitted_params_for(:update)).include?(params[:relationship].to_sym)
+
+        relationship_resources =
+          Array.wrap(params[:data]).map do |resource_identifier|
+            get_record!(
+              resource_identifier[:type],
+              column = self.config.resource_primary_key,
+              resource_identifier[column]
+            )
+          end
+
+        successful =
+          case queried_association.reflection.macro
+          when :has_many
+            if request.patch?
+              queried_record.send("#{params[:relationship]}=", relationship_resources)
+            elsif request.post?
+              queried_record.send(params[:relationship]).push relationship_resources
+            elsif request.delete?
+              queried_record.send(params[:relationship]).delete relationship_resources
+            end
+          when :has_one
+            if request.patch?
+              queried_record.send("#{params[:relationship]}=", relationship_resources[0])
+              objects[0].save
+            end
+          when :belongs_to
+            if request.patch?
+              queried_record.send("#{params[:relationship]}=", relationship_resources[0])
+              queried_record.save
+            end
+          end
+      else
+        successful = false
+      end
+
+      if successful
+        head :no_content
+      else
+        fail ActionForbiddenError.new
+      end
+    end
+
+    private
+
+    # Gets the association queried by the relationship call
+    #
+    # @note Fails with 404 Not Found if association cannot be found
+    def queried_association
+      unless @queried_association
+        begin
+          @queried_association = queried_record.association(params[:relationship])
+        rescue ActiveRecord::AssociationNotFoundError => e
+          fail AssociationNotFoundError.new(params[:relationship])
+        end
+      end
+
+      @queried_association
+    end
+  end
+end

data/lib/caprese/controller/concerns/rendering.rb

@@ -0,0 +1,43 @@
+require 'active_support/concern'
+require 'caprese/adapter/json_api'
+
+module Caprese
+  module Rendering
+    extend ActiveSupport::Concern
+
+    # Override render so we can automatically use our adapter and find the appropriate serializer
+    # instead of requiring that they be explicity stated
+    def render(options = {})
+      options[:adapter] = Caprese::Adapter::JsonApi
+
+      if options[:json].respond_to?(:to_ary)
+        if options[:json].first.is_a?(Error)
+          options[:each_serializer] ||= Serializer::ErrorSerializer
+        elsif options[:json].any?
+          options[:each_serializer] ||= serializer_for(options[:json].first)
+        end
+      else
+        if options[:json].is_a?(Error)
+          options[:serializer] ||= Serializer::ErrorSerializer
+        elsif options[:json].present?
+          options[:serializer] ||= serializer_for(options[:json])
+        end
+      end
+
+      super
+    end
+
+    private
+
+    # Finds a versioned serializer for a given resource
+    #
+    # @example
+    #   serializer_for(post) => API::V1::PostSerializer
+    #
+    # @param [ActiveRecord::Base] record the record to find a serializer for
+    # @return [Serializer,Nil] the serializer for the given record
+    def serializer_for(record)
+      version_module("#{record.class.name}Serializer").constantize
+    end
+  end
+end

data/lib/caprese/controller/concerns/typing.rb

@@ -0,0 +1,39 @@
+require 'active_support/concern'
+require 'caprese/errors'
+
+# Manages type determination and checking for a given controller
+module Caprese
+  module Typing
+    extend ActiveSupport::Concern
+
+    # Gets the class for a record type
+    # @note "record type" can be plural, singular, or classified
+    #   i.e. 'orders', 'order', or 'Order'
+    #
+    # @example
+    #   record_class(:orders) # => Order
+    #
+    # @param [Symbol] type the record type to get the class for
+    # @return [Class] the class for a given record type
+    def record_class(type)
+      type.to_s.classify.constantize
+    end
+
+    # Gets the record class for the current controller
+    #
+    # @return [Class] the record class for the current controller
+    def controller_record_class
+      record_class(unversion(params[:controller]))
+    end
+
+    # Checks if a given type mismatches the controller type
+    # @note Throws :invalid_type error if true
+    #
+    # @param [String] type the pluralized type to check ('products','orders',etc.)
+    def fail_on_type_mismatch(type)
+      unless record_class(type) == controller_record_class
+        fail InvalidTypeError.new(type)
+      end
+    end
+  end
+end

data/lib/caprese/controller.rb

@@ -0,0 +1,26 @@
+require 'action_controller'
+require 'active_support/configurable'
+require 'caprese/concerns/versioning'
+require 'caprese/controller/concerns/callbacks'
+require 'caprese/controller/concerns/errors'
+require 'caprese/controller/concerns/persistence'
+require 'caprese/controller/concerns/query'
+require 'caprese/controller/concerns/relationships'
+require 'caprese/controller/concerns/rendering'
+require 'caprese/controller/concerns/typing'
+
+module Caprese
+  # TODO: Convert to ActionController::API with Rails 5
+  class Controller < ActionController::Base
+    include ActiveSupport::Configurable
+    include Callbacks
+    include Errors
+    include Persistence
+    include Query
+    include Relationships
+    include Rendering
+    include Typing
+    include Versioning
+    extend Versioning
+  end
+end

data/lib/caprese/error.rb

@@ -0,0 +1,121 @@
+# TODO: Remove in favor of Rails 5 error details and dynamically setting i18n_scope
+module Caprese
+  class Error < StandardError
+    attr_reader :field
+    attr_reader :code
+
+    attr_reader :header
+
+    # Initializes a new error
+    #
+    # @param [Symbol] model a symbol representing the model that the error occurred on
+    # @param [String] controller the name of the controller the error occurred in
+    # @param [String] action the name of the controller action the error occurred in
+    # @param [Symbol,String] field a symbol or string representing the field (model attribute or controller param) that the error occurred on
+    #   if Symbol, a shallow field name. EX: :password
+    #   if String, a nested field name.  EX: 'order_items.amount'
+    # @param [Symbol] code the error code
+    # @param [Hash] t the interpolation variables to supply to I18n.t when creating the full error message
+    def initialize(model: nil, controller: nil, action: nil, field: nil, code: :invalid, t: {})
+      @model = model
+
+      @controller = controller
+      @action = action
+
+      @field = field
+      @code = code
+
+      @t = t
+
+      @header = { status: :bad_request }
+    end
+
+    # @return [String] The scope to look for I18n translations in
+    def i18n_scope
+      Caprese.config.i18n_scope
+    end
+
+    # The full error message based on the different attributes we initialized the error with
+    #
+    # @return [String] the full error message
+    def full_message
+      if @model
+        if field
+          if i18n_set? "#{i18n_scope}.models.#{@model}.#{field}.#{code}", t
+            I18n.t("#{i18n_scope}.models.#{@model}.#{field}.#{code}", t)
+          elsif i18n_set?("#{i18n_scope}.field.#{code}", t)
+            I18n.t("#{i18n_scope}.field.#{code}", t)
+          else
+            I18n.t("#{i18n_scope}.#{code}", t)
+          end
+        else
+          if i18n_set? "#{i18n_scope}.models.#{@model}.#{code}", t
+            I18n.t("#{i18n_scope}.models.#{@model}.#{code}", t)
+          elsif i18n_set? "#{i18n_scope}.#{code}", t
+            I18n.t("#{i18n_scope}.#{code}", t)
+          else
+            code.to_s
+          end
+        end
+      elsif @controller && @action
+        if field && i18n_set?("#{i18n_scope}.controllers.#{@controller}.#{@action}.#{field}.#{code}", t)
+          I18n.t("#{i18n_scope}.controllers.#{@controller}.#{@action}.#{field}.#{code}", t)
+        elsif i18n_set?("#{i18n_scope}.controllers.#{@controller}.#{@action}.#{code}", t)
+          I18n.t("#{i18n_scope}.controllers.#{@controller}.#{@action}.#{code}", t)
+        else
+          I18n.t("#{i18n_scope}.#{code}", t)
+        end
+      elsif field && i18n_set?("#{i18n_scope}.field.#{code}", t)
+        I18n.t("#{i18n_scope}.field.#{code}", t)
+      elsif i18n_set? "#{i18n_scope}.#{code}", t
+        I18n.t("#{i18n_scope}.#{code}", t)
+      else
+        code.to_s
+      end
+    end
+    alias_method :message, :full_message
+
+    # Allows us to add to the response header when we are failing
+    #
+    # @note Should be used as such: fail Error.new(...).with_headers(...)
+    #
+    # @param [Hash] headers the headers to supply in the error response
+    # @option [Symbol] status the HTTP status code to return
+    # @option [String, Path] location the value for the Location header, useful for redirects
+    def with_header(header = {})
+      @header = header
+      @header[:status] ||= :bad_request
+      self
+    end
+
+    # Creates a serializable hash for the error so we can serialize and return it
+    #
+    # @return [Hash] the serializable hash of the error
+    def as_json
+      {
+        code: code,
+        field: field,
+        message: full_message
+      }
+    end
+
+    private
+
+    # Adds field and capitalized Field title to the translation params for every error
+    #
+    # @return [Hash] the full translation params of the error
+    def t
+      @t.merge(field: @field, field_title: @field.to_s.titleize)
+    end
+
+    # Checks whether or not a translation exists
+    #
+    # @param [String] key the I18n translation key
+    # @param [Hash]   params any params to pass into the translations so we only raise NotFound
+    #   exception we're looking for missing params would cause this to return false improperly
+    # @return [Boolean] whether or not the translation exists in I18n
+    def i18n_set?(key, params = {})
+      I18n.t key, params, :raise => true rescue false
+    end
+  end
+end

data/lib/caprese/errors.rb

@@ -0,0 +1,69 @@
+require 'caprese/error'
+
+module Caprese
+  # Thrown when a record was attempted to be persisted and was invalidated
+  #
+  # @param [ActiveRecord::Base] record the record that is invalid
+  class RecordInvalidError < Error
+    attr_reader :record
+
+    def initialize(record)
+      super()
+      @record = record
+      @header = { status: :unprocessable_entity }
+    end
+
+    def as_json
+      record.errors.as_json
+    end
+  end
+
+  # Thrown when a record could not be found
+  #
+  # @param [Symbol] field the field that we searched with
+  # @param [String] model the name of the model we searched for a record of
+  # @param [Value] value the value we searched for a match with
+  class RecordNotFoundError < Error
+    def initialize(field: :id, model: nil, value: nil)
+      super field: field, code: :not_found, t: { model: model, value: value }
+      @header = { status: :not_found }
+    end
+  end
+
+  # Thrown when an association was not found when calling `record.association()`
+  #
+  # @param [String] name the name of the association
+  class AssociationNotFoundError < Error
+    def initialize(name)
+      super field: name, code: :association_not_found
+      @header = { status: :not_found }
+    end
+  end
+
+  # Thrown when an action that is forbidden was attempted
+  class ActionForbiddenError < Error
+    def initialize
+      super code: :forbidden
+      @header = { status: :forbidden }
+    end
+  end
+
+  # Thrown when an attempt was made to delete a record, but the record could not be deleted
+  # because of restrictions
+  #
+  # @param [String] reason the reason for the restriction
+  class DeleteRestrictedError < Error
+    def initialize(reason)
+      super code: :delete_restricted, t: { reason: reason }
+      @header = { status: :forbidden }
+    end
+  end
+
+  # Thrown when an attempt was made to create a record of type that is different than the type
+  # of the controller that the data was sent to
+  class InvalidTypeError < Error
+    def initialize(type)
+      super code: :invalid_type, t: { type: type }
+    end
+  end
+end

data/lib/caprese/record/errors.rb

@@ -0,0 +1,82 @@
+require 'active_model'
+
+module Caprese
+  module Record
+    class Errors < ActiveModel::Errors
+      # Adds an error object for a field, with a code, to the messages hash
+      #
+      # @param [Symbol] attribute the attribute of the model that this error applies to
+      # @param [Symbol] code the error code for the attribute
+      # @option [Exception,Boolean] strict raise an exception when creating an error
+      #  if Exception, raises that exception
+      #  if Boolean `true`, raises ActiveModel::StrictValidationFailed
+      # @option [Hash] t interpolation variables to add into the translated full message
+      def add(attribute, code = :invalid, options = {})
+        options = options.dup
+        options[:t] ||= {}
+        options[:t][:count] = options[:count]
+        options[:t][:value] =
+          if attribute != :base && @base.respond_to?(attribute)
+            @base.send(:read_attribute_for_validation, attribute)
+          else
+            nil
+          end
+
+        e = Error.new(
+          model: @base.class.name.underscore.downcase,
+          field: attribute == :base ? nil : attribute,
+          code: code,
+          t: options[:t]
+        )
+
+        if (exception = options[:strict])
+          exception = ActiveModel::StrictValidationFailed if exception == true
+          raise exception, e.full_message
+        end
+
+        self[attribute] << e
+      end
+
+      # @return [Boolean] true if the model has no errors
+      def empty?
+        all? { |k,v| !v }
+      end
+
+      # Returns the full error messages for each error in the model
+      # @note Overriden because original renders full_messages using internal helpers of self instead of error
+      # @return [Hash] a hash mapped by attribute, with each value being an array of full messages for that attribute of the model
+      def full_messages
+        map { |_, e| e.full_message }
+      end
+
+      # @param attribute [Symbol] an attribute in the model
+      # @note Overriden because original renders full_messages using internal helpers of self instead of error
+      # @return [Array] an array of full error messages for a given attribute of the model
+      def full_messages_for(attribute)
+        (get(attribute) || []).map { |e| e.full_message }
+      end
+
+      # @note Overriden because traditionally to_a is an alias for `full_messages`, because in Rails standard there is
+      #   no difference between an error and a full message, an error is that full message. With our API, an error is a
+      #   model that can render full messages, but it is still a distinct model. `to_a` thus has a different meaning here
+      #   than in Rails standard.
+      # @return [Array] an array of all errors in the model
+      def to_a
+        values.flatten
+      end
+
+      # We have not and will not ever implement an XML rendering of these errors
+      def to_xml(options = {})
+        raise NotImplementedError
+      end
+
+      def as_json
+        Hash[
+          map do |field, errors|
+            [field, Array.wrap(errors).map { |e| e.as_json }]
+          end
+        ]
+      end
+    end
+  end
+end

data/lib/caprese/record.rb

@@ -0,0 +1,19 @@
+require 'active_model'
+require 'active_support/concern'
+require 'active_support/dependencies'
+require 'caprese/errors'
+require 'caprese/record/errors'
+
+module Caprese
+  module Record
+    extend ActiveSupport::Concern
+
+    mattr_accessor :caprese_style_errors
+    @@caprese_style_errors = true
+
+    # @return [Errors] a cached instance of the model errors class
+    def errors
+      @errors ||= (Caprese::Record.caprese_style_errors ? Caprese::Record : ActiveModel)::Errors.new(self)
+    end
+  end
+end

data/lib/caprese/routing/caprese_resources.rb

@@ -0,0 +1,27 @@
+require 'action_dispatch/routing/mapper'
+
+class ActionDispatch::Routing::Mapper
+  def caprese_resources(*resources, &block)
+    options = resources.extract_options!
+
+    resources.each do |r|
+      resources r, only: [:index, :show, :create, :update, :destroy] do
+        yield if block_given?
+
+        member do
+          get 'relationships/:relationship',
+            to: "#{parent_resource.name}#get_relationship_definition",
+            as: :relationship_definition
+
+          match 'relationships/:relationship',
+            to: "#{parent_resource.name}#update_relationship_definition",
+            via: [:patch, :post, :delete]
+
+          get ':relationship(/:relation_primary_key_value)',
+            to: "#{parent_resource.name}#get_relationship_data",
+            as: :relationship_data
+        end
+      end
+    end
+  end
+end