caprese 0.2.0

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

@@ -0,0 +1,42 @@
+require 'active_support/concern'
+require 'caprese/error'
+require 'caprese/serializer/error_serializer'
+
+module Caprese
+  module Errors
+    extend ActiveSupport::Concern
+
+    included do
+      around_action :enable_caprese_style_errors
+
+      rescue_from Error do |e|
+        output = { json: e }
+        render output.merge(e.header)
+      end
+    end
+
+    # Fail with a controller action error
+    #
+    # @param [Symbol] field the field (a controller param) that caused the error
+    # @param [Symbol] code the code for the error
+    # @param [Hash] t the interpolation params to be passed into I18n.t
+    def error(field: nil, code: :invalid, t: {})
+      fail Error.new(
+        controller: unversion(params[:controller]),
+        action: params[:action],
+        field: field,
+        code: code,
+        t: t
+      )
+    end
+
+    private
+
+    # Temporarily render model errors as Caprese::Record::Errors instead of ActiveModel::Errors
+    def enable_caprese_style_errors
+      Caprese::Record.caprese_style_errors = true
+      yield
+      Caprese::Record.caprese_style_errors = false
+    end
+  end
+end

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

@@ -0,0 +1,327 @@
+require 'active_record/associations'
+require 'active_record/validations'
+require 'active_support/concern'
+
+module Caprese
+  module Persistence
+    extend ActiveSupport::Concern
+
+    included do
+      # Rescue from instances where required parameters are missing
+      #
+      # @note The only instance this may be called, at least in JSON API settings, is a
+      #   missing params['data'] param
+      rescue_from ActionController::ParameterMissing do |e|
+        rescue_with_handler Error.new(
+          field: e.param,
+          code: :blank
+        )
+      end
+
+      rescue_from ActiveRecord::RecordInvalid do |e|
+        rescue_with_handler RecordInvalidError.new(e.record)
+      end
+
+      rescue_from ActiveRecord::RecordNotDestroyed do |e|
+        rescue_with_handler ActionForbiddenError.new
+      end
+
+      rescue_from ActiveRecord::DeleteRestrictionError do |e|
+        rescue_with_handler DeleteRestrictedError.new(e.message)
+      end
+    end
+
+    # Creates a new record of whatever type a given controller manages
+    #
+    # @note For this action to succeed, the given controller must define `create_params`
+    #   @see #create_params
+    #
+    # 1. Check that type of record to be created matches type that the given controller manages
+    # 2. Build the appropriate attributes/associations for the create action
+    # 3. Build a record with the attributes
+    # 4. Execute after_initialize callbacks
+    # 5. Execute before_create callbacks
+    # 6. Execute before_save callbacks
+    # 7. Create the record by saving it (or fail with RecordInvalid and render errors)
+    # 8. Execute after_create callbacks
+    # 9. Execute after_save callbacks
+    # 10. Return the created resource with 204 Created
+    #    @see #rescue_from ActiveRecord::RecordInvalid
+    def create
+      fail_on_type_mismatch(data_params[:type])
+
+      record = queried_record_scope.build
+      assign_record_attributes(record, permitted_params_for(:create), data_params)
+      execute_after_initialize_callbacks(record)
+
+      execute_before_create_callbacks(record)
+      execute_before_save_callbacks(record)
+
+      record.save!
+
+      execute_after_create_callbacks(record)
+      execute_after_save_callbacks(record)
+
+      render(
+        json: record,
+        status: :created,
+        fields: query_params[:fields],
+        include: query_params[:include]
+      )
+    end
+
+    # Updates a record of whatever type a given controller manages
+    #
+    # @note For this action to succeed, the given controller must define `update_params`
+    #   @see #update_params
+    #
+    # 1. Check that type of record to be updated matches type that the given controller manages
+    # 2. Execute before_update callbacks
+    # 3. Execute before_save callbacks
+    # 4. Update the record (or fail with RecordInvalid and render errors)
+    # 5. Execute after_update callbacks
+    # 6. Execute after_save callbacks
+    # 7. Return the updated resource
+    #    @see #rescue_from ActiveRecord::RecordInvalid
+    def update
+      fail_on_type_mismatch(data_params[:type])
+
+      execute_before_update_callbacks(queried_record)
+      execute_before_save_callbacks(queried_record)
+
+      assign_record_attributes(queried_record, permitted_params_for(:update), data_params)
+      queried_record.save!
+
+      execute_after_update_callbacks(queried_record)
+      execute_after_save_callbacks(queried_record)
+
+      render(
+        json: queried_record,
+        fields: query_params[:fields],
+        include: query_params[:include]
+      )
+    end
+
+    # Destroys a record of whatever type a given controller manages
+    #
+    # 1. Execute any before_destroy callbacks, with the record to be destroyed passed in
+    # 2. Destroy the record, ensuring that it checks the model for dependencies before doing so
+    # 3. Execute any after_destroy callbacks, with the destroyed resource passed in
+    # 4. Return 204 No Content if the record was successfully deleted
+    def destroy
+      execute_before_destroy_callbacks(queried_record)
+      queried_record.destroy!
+      execute_after_destroy_callbacks(queried_record)
+
+      head :no_content
+    end
+
+    private
+
+    # Requires the data param standard to JSON API
+    #
+    # @return [StrongParameters] the strong params in the `data` object param
+    def data_params
+      params.require('data')
+    end
+
+    # An array of symbols stating params that are permitted for a #create action
+    #   for a record
+    #
+    # @note Abstract function, must be overridden by every controller
+    #
+    # @return [Array] a list of params permitted to create a record of whatever type
+    #   a given controller manages
+    def permitted_create_params
+      fail NotImplementedError
+    end
+
+    # An array of symbols stating params that are permitted for a #update action
+    #   for a record
+    #
+    # @note Abstract function, must be overridden by every controller
+    #
+    # @return [Array] a list of params permitted to update a record of whatever type
+    #   a given controller manages
+    def permitted_update_params
+      fail NotImplementedError
+    end
+
+    # Gets the permitted params for a given action (create, update)
+    #
+    # @param [Symbol] action the action to get permitted params for
+    # @return [Array] the permitted params for a given action
+    def permitted_params_for(action)
+      send("permitted_#{action}_params")
+    end
+
+    # Gets a set of nested params in an action_params definition
+    #
+    # @example
+    #   create_params => [:body, user: [:name, :email]]
+    #   nested_params_for(user, create_params)
+    #     => [:name, :email]
+    #
+    # @param [Symbol] key the key of the nested params
+    # @param [Array] params the params to search for the key in
+    # @return [Array,Nil] the nested params for a given key
+    def nested_params_for(key, params)
+      params.detect { |p| p.is_a?(Hash) }.try(:[], key.to_sym)
+    end
+
+    # Flattens an array of the top level keys for a given set of params
+    #
+    # @example
+    #   create_params => [:body, user: [:name], post: [:title]]
+    #   flattened_keys_for(create_params) => [:body, :user, :post]
+    #
+    # @param [Array] params the params to flatten keys for
+    # @return [Array] the flattened array of keys for the action params
+    def flattened_keys_for(params)
+      params.map do |p|
+        if p.is_a?(Hash)
+          p.keys
+        else
+          p
+        end
+      end.flatten
+    end
+
+    # Builds permitted attributes and relationships into the queried record
+    #
+    # @example
+    #   params = {
+    #     type: 'orders',
+    #     attributes: { price: '...', other: '...' },
+    #     relationships: {
+    #       product: {
+    #         data: { token: 'asj38k', type: 'products' }
+    #       }
+    #     }
+    #   }
+    #   create_params => [:price]
+    #
+    #   assign_record_attributes(record, create_params, params)
+    #     => { price: '...', product: Product<@token='asj38k'> }
+    #
+    # @example
+    #   params = {
+    #     type: 'orders',
+    #     attributes: { price: '...', other: '...' },
+    #     relationships: {
+    #       order_items: {
+    #         data: [{
+    #           type: 'order_items',
+    #           attributes: {
+    #             title: 'An order item',
+    #             amount: 5.0,
+    #             tax: 0.0
+    #           }
+    #         }]
+    #       }
+    #     }
+    #   }
+    #
+    #   create_params => [:price, order_items: [:title, :amount, :tax]]
+    #
+    #   assign_record_attributes(record, create_params, params) # => {
+    #     price: '...',
+    #     order_items: [OrderItem<@token=nil,@title='An order item',@amount=5.0,@tax=0.0>]
+    #   }
+    #
+    # @param [ActiveRecord::Base] record the record to build attribute into
+    # @param [Array] permitted_params the permitted params for the action
+    # @param [Parameters] data the data sent to the server to construct and assign to the record
+    def assign_record_attributes(record, permitted_params, data)
+      attributes = data[:attributes].try(:permit, *permitted_params) || {}
+
+      data[:relationships]
+      .try(:slice, *flattened_keys_for(permitted_params))
+      .try(:each) do |relationship_name, relationship_data|
+        attributes[relationship_name] = records_for_relationship(
+          record,
+          nested_params_for(relationship_name, permitted_params),
+          relationship_name,
+          relationship_data
+        )
+      end
+
+      record.assign_attributes(attributes)
+    end
+
+    # Gets all the records for a relationship given a relationship data definition
+    #
+    # @param [ActiveRecord::Base] owner the owner of the relationship
+    # @param [Array] permitted_params the permitted params for the
+    # @param [String] relationship_name the name of the relationship to get records for
+    # @param [Hash,Array<Hash>] relationship_data the resource identifier data to use to find/build records
+    # @return [ActiveRecord::Base,Array<ActiveRecord::Base>] the record(s) for the relationship
+    def records_for_relationship(owner, permitted_params, relationship_name, relationship_data)
+      if relationship_data.is_a?(Array)
+        relationship_data.map do |relationship_data_item|
+          ref = record_for_relationship(owner, relationship_name, relationship_data_item[:data])
+
+          if ref && contains_constructable_data?(relationship_data_item[:data])
+            assign_record_attributes(ref, permitted_params, relationship_data_item[:data])
+          end
+
+          ref
+        end
+      else
+        ref = record_for_relationship(owner, relationship_name, relationship_data[:data])
+
+        if ref && contains_constructable_data?(relationship_data[:data])
+          assign_record_attributes(ref, permitted_params, relationship_data[:data])
+        end
+
+        ref
+      end
+    end
+
+    # Given a resource identifier, finds or builds a resource for a relationship
+    #
+    # @param [ActiveRecord::Base] owner the owner of the relationship record
+    # @param [String] relationship_name the name of the relationship
+    # @param [Hash] resource_identifier the resource identifier for the resource
+    # @return [ActiveRecord::Base] the found or built resource for the relationship
+    def record_for_relationship(owner, relationship_name, resource_identifier)
+      record =
+        if (id = resource_identifier[Caprese.config.resource_primary_key])
+          get_record!(
+            resource_identifier[:type],
+            Caprese.config.resource_primary_key,
+            id
+          )
+        elsif contains_constructable_data?(resource_identifier)
+          record_scope(resource_identifier[:type]).build
+        else
+          owner.errors.add(relationship_name)
+          nil
+        end
+
+      record
+    end
+
+    # Assigns permitted attributes for a record in a relationship, for a given action
+    # like create/update
+    #
+    # @param [ActiveRecord::Base] record the relationship record
+    # @param [String] relationship_name the name of the relationship
+    # @param [Symbol] action the action that is calling this method (create, update)
+    # @param [Hash] resource_identifier the resource identifier
+    def assign_relationship_record_attributes(record, relationship_name, action, attributes)
+      record.assign_attributes(
+        attributes.permit(nested_permitted_params_for(action, relationship_name))
+      )
+    end
+
+    # Indicates whether or not :attributes or :relationships keys are in a resource identifier,
+    # thus allowing us to construct this data into the final record
+    #
+    # @param [Hash] resource_identifier the resource identifier to check for constructable data in
+    # @return [Boolean] whether or not the resource identifier contains constructable data
+    def contains_constructable_data?(resource_identifier)
+      [:attributes, :relationships].any? { |k| resource_identifier.key?(k) }
+    end
+  end
+end

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

@@ -0,0 +1,209 @@
+require 'active_support/concern'
+require 'caprese/errors'
+require 'kaminari'
+
+module Caprese
+  module Query
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :execute_before_query_callbacks
+      after_action  :execute_after_query_callbacks
+    end
+
+    # Standardizes the index action since it always does the same thing
+    def index
+      render(
+        json: queried_collection,
+        fields: query_params[:fields],
+        include: query_params[:include]
+      )
+    end
+
+    # Standardizes the show action since it always does the same thing
+    def show
+      render(
+        json: queried_record,
+        fields: query_params[:fields],
+        include: query_params[:include]
+      )
+    end
+
+    # The params that affect the query and subsequent response
+    #
+    # @example INCLUDE ASSOCIATED RESOURCES
+    #   `GET /api/v1/products?include=merchant`
+    #
+    # @example INCLUDE NESTED ASSOCIATED RESOURCES
+    #   `GET /api/v1/products?include=merchant.currency`
+    #
+    # @example FIELDSETS
+    #   `GET /api/v1/products?include=merchant&fields[product]=title,description&fields[merchant]=id,name`
+    #
+    # @example SORT
+    #   `GET /api/v1/products?sort=updated_at`
+    #
+    # @example SORT DESCENDING
+    #   `GET /api/v1/products?sort=-updated_at`
+    #
+    # @example PAGINATION
+    #   `GET /api/v1/products?page[number]=1&page[size]=5`
+    #
+    # @example LIMIT AND OFFSET
+    #   `GET /api/v1/products?limit=1&offset=1`
+    #
+    # @example LIMIT AND OFFSET (GET LAST)
+    #   `GET /api/v1/products?limit=1&offset=-1`
+    #
+    # @example FILTERING
+    #   `GET /api/v1/products?filter[venue_id]=10`
+    #
+    # @return [Hash] the params that modify our query
+    def query_params
+      if @query_params.blank?
+        @query_params = params.except(:action, :controller)
+
+        # Sort query by column, ascending or descending
+        @query_params[:sort] = @query_params[:sort].split(',') if @query_params[:sort]
+
+        # Convert fields params into arrays for each resource
+        @query_params[:fields].each do |resource, fields|
+          @query_params[:fields][resource] = fields.split(',')
+        end if @query_params[:fields]
+      end
+
+      @query_params
+    end
+
+    # Gets a collection of type `type`, providing the collection as
+    # a `record scope` by which to query records
+    #
+    # @note We use the term scope, because the collection may be all records of that type,
+    #   or the records may be scoped further by overriding this method
+    #
+    # @note If no `type` is provided, the type is assumed to be the controller_record_class
+    #
+    # @param [Symbol] type the type to get a record scope for
+    # @return [Relation] the scope of records of type `type`
+    def record_scope(type = nil)
+      (type && record_class(type) || controller_record_class).all
+    end
+
+    # Gets a record in a scope using a column/value to search by
+    #
+    # @example
+    #   get_record(:orders, :id, '1e0da61f-0229-4035-99a5-3e5c37a221fb')
+    #     # => Order.find_by(id: '1e0da61f-0229-4035-99a5-3e5c37a221fb')
+    #
+    # @param [Symbol,Relation] scope the scope to find the record in
+    #   if Symbol, call record_scope for that type and use it
+    #   if Relation, use it as a scope
+    # @param [Symbol] column the name of the column to find the record by
+    # @param [Value] value the value to match to a column/row value
+    # @return [APIRecord] the record that was found
+    def get_record(scope, column, value)
+      scope = record_scope(scope) unless scope.respond_to?(:find_by)
+
+      scope.find_by(column => value)
+    end
+
+    # Gets a record in a scope using a column/value to search by
+    # @note Fails with error 404 Not Found if the record was not found
+    #
+    # @see get_record
+    def get_record!(scope, column, value)
+      scope = record_scope(scope) unless scope.respond_to?(:find_by!)
+
+      begin
+        scope.find_by!(column => value)
+      rescue ActiveRecord::RecordNotFound => e
+        fail RecordNotFoundError.new(
+          field: column,
+          model: scope.name.underscore,
+          value: value
+        )
+      end
+    end
+
+    # Applies query_params[:sort] and query_params[:page] to a given scope
+    #
+    # @param [Relation] scope the scope to apply sorting and pagination to
+    # @return [Relation] the sorted and paginated scope
+    def apply_sorting_pagination_to_scope(scope)
+      if query_params[:sort].try(:any?)
+        ordering = {}
+        query_params[:sort].each do |sort_field|
+          ordering = ordering.merge(
+            if sort_field[0] == '-' # EX: -created_at, sort by created_at descending
+              { sort_field[1..-1] => :desc }
+            else
+              { sort_field => :asc }
+            end
+          )
+        end
+        scope = scope.reorder(ordering)
+      end
+
+      if query_params[:offset] || query_params[:limit]
+        offset = query_params[:offset].to_i || 0
+
+        if offset < 0
+          offset = scope.count + offset
+        end
+
+        limit = query_params[:limit] && query_params[:limit].to_i || self.config.default_page_size
+        limit = [limit, self.config.max_page_size].min
+
+        scope.offset(offset).limit(limit)
+      else
+        page_number = query_params[:page].try(:[], :number)
+        page_size = query_params[:page].try(:[], :size).try(:to_i) || self.config.default_page_size
+        page_size = [page_size, self.config.max_page_size].min
+
+        scope.page(page_number).per(page_size)
+      end
+    end
+
+    # Gets the scope by which to query controller records, taking into account custom scoping and
+    # the filters provided in the query
+    #
+    # @return [Relation] the record scope of the queried controller
+    def queried_record_scope
+      unless @queried_record_scope
+        scope = record_scope
+
+        if scope.any? && query_params[:filter].try(:any?)
+          if (valid_filters = query_params[:filter].select { |k, _| scope.column_names.include? k }).present?
+            valid_filters.each do |k, v|
+              scope = scope.where(k => v)
+            end
+          end
+        end
+
+        @queried_record_scope = scope
+      end
+
+      @queried_record_scope
+    end
+
+    # Gets the record that was queried, i.e. the record corresponding to the primary key in the
+    # route param (/:id), in the queried_record_scope
+    #
+    # @return [ActiveRecord::Base] the queried record
+    def queried_record
+      @queried_record ||=
+        get_record!(
+          queried_record_scope,
+          column = self.config.resource_primary_key,
+          params[column]
+        )
+    end
+
+    # Gets the collection that was queried, i.e. the sorted & paginated queried_record_scope
+    #
+    # @return [Relation] the queried collection
+    def queried_collection
+      @queried_collection ||= apply_sorting_pagination_to_scope(queried_record_scope)
+    end
+  end
+end