jpie 0.4.0 → 0.4.2

data/examples/single_table_inheritance.md

@@ -0,0 +1,160 @@
+# Single Table Inheritance (STI) Example
+
+This example demonstrates the minimal setup required to implement Single Table Inheritance with JPie resources and controllers.
+
+## Setup
+
+### 1. Base Model (`app/models/vehicle.rb`)
+```ruby
+class Vehicle < ApplicationRecord
+  validates :name, presence: true
+  validates :brand, presence: true
+  validates :year, presence: true
+end
+```
+
+### 2. STI Models (`app/models/car.rb`, `app/models/truck.rb`)
+```ruby
+class Car < Vehicle
+  validates :engine_size, presence: true
+end
+
+class Truck < Vehicle
+  validates :cargo_capacity, presence: true
+end
+```
+
+### 3. Base Resource (`app/resources/vehicle_resource.rb`)
+```ruby
+class VehicleResource < JPie::Resource
+  attributes :name, :brand, :year
+end
+```
+
+### 4. STI Resources (`app/resources/car_resource.rb`, `app/resources/truck_resource.rb`)
+```ruby
+class CarResource < VehicleResource
+  attributes :engine_size
+end
+
+class TruckResource < VehicleResource
+  attributes :cargo_capacity
+end
+```
+
+### 5. Controller (`app/controllers/vehicles_controller.rb`)
+```ruby
+class VehiclesController < ApplicationController
+  include JPie::Controller
+end
+```
+
+### 6. Routes (`config/routes.rb`)
+```ruby
+Rails.application.routes.draw do
+  resources :vehicles
+end
+```
+
+## HTTP Examples
+
+### Create Car
+```http
+POST /vehicles
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "cars",
+    "attributes": {
+      "name": "Civic",
+      "brand": "Honda",
+      "year": 2024,
+      "engine_size": 1500
+    }
+  }
+}
+
+HTTP/1.1 201 Created
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "cars",
+    "attributes": {
+      "name": "Civic",
+      "brand": "Honda",
+      "year": 2024,
+      "engine_size": 1500
+    }
+  }
+}
+```
+
+### Update Car
+```http
+PATCH /vehicles/1
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "cars",
+    "attributes": {
+      "name": "Civic Hybrid",
+      "engine_size": 1800
+    }
+  }
+}
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "cars",
+    "attributes": {
+      "name": "Civic Hybrid",
+      "brand": "Honda",
+      "year": 2024,
+      "engine_size": 1800
+    }
+  }
+}
+```
+
+### Get Mixed Vehicles
+```http
+GET /vehicles
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "cars",
+      "attributes": {
+        "name": "Civic",
+        "brand": "Honda",
+        "year": 2024,
+        "engine_size": 1500
+      }
+    },
+    {
+      "id": "2",
+      "type": "trucks",
+      "attributes": {
+        "name": "F-150",
+        "brand": "Ford",
+        "year": 2024,
+        "cargo_capacity": 1000
+      }
+    }
+  ]
+}
+``` 

data/lib/jpie/controller/crud_actions.rb

@@ -34,15 +34,23 @@ module JPie
 
         def define_index_method(resource_class)
           define_method :index do
+            validate_include_params
+            validate_sort_params
             resources = resource_class.scope(context)
             sort_fields = parse_sort_params
             resources = resource_class.sort(resources, sort_fields) if sort_fields.any?
-            render_jsonapi(resources)
+
+            pagination_params = parse_pagination_params
+            original_resources = resources
+            resources = apply_pagination(resources, pagination_params)
+
+            render_jsonapi(resources, pagination: pagination_params, original_scope: original_resources)
           end
         end
 
         def define_show_method(resource_class)
           define_method :show do
+            validate_include_params
             resource = resource_class.scope(context).find(params[:id])
             render_jsonapi(resource)
           end
@@ -50,6 +58,7 @@ module JPie
 
         def define_create_method(resource_class)
           define_method :create do
+            validate_json_api_request
             attributes = deserialize_params
             resource = resource_class.model.create!(attributes)
             render_jsonapi(resource, status: :created)
@@ -58,6 +67,7 @@ module JPie
 
         def define_update_method(resource_class)
           define_method :update do
+            validate_json_api_request
             resource = resource_class.scope(context).find(params[:id])
             attributes = deserialize_params
             resource.update!(attributes)
@@ -76,24 +86,34 @@ module JPie
 
       # These methods can still be called manually or used to override defaults
       def index
+        validate_include_params
+        validate_sort_params
         resources = resource_class.scope(context)
         sort_fields = parse_sort_params
         resources = resource_class.sort(resources, sort_fields) if sort_fields.any?
-        render_jsonapi(resources)
+
+        pagination_params = parse_pagination_params
+        original_resources = resources
+        resources = apply_pagination(resources, pagination_params)
+
+        render_jsonapi(resources, pagination: pagination_params, original_scope: original_resources)
       end
 
       def show
+        validate_include_params
         resource = resource_class.scope(context).find(params[:id])
         render_jsonapi(resource)
       end
 
       def create
+        validate_json_api_request
         attributes = deserialize_params
         resource = model_class.create!(attributes)
         render_jsonapi(resource, status: :created)
       end
 
       def update
+        validate_json_api_request
         resource = resource_class.scope(context).find(params[:id])
         attributes = deserialize_params
         resource.update!(attributes)
@@ -105,6 +125,17 @@ module JPie
         resource.destroy!
         head :no_content
       end
+
+      private
+
+      def apply_pagination(resources, pagination_params)
+        return resources unless pagination_params[:per_page]
+
+        page = pagination_params[:page] || 1
+        per_page = pagination_params[:per_page]
+
+        resources.limit(per_page).offset((page - 1) * per_page)
+      end
     end
   end
 end

data/lib/jpie/controller/error_handling/handler_setup.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module ErrorHandling
+      module HandlerSetup
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Allow applications to easily disable all JPie error handlers
+          def disable_jpie_error_handlers
+            self.jpie_error_handlers_enabled = false
+            # Remove any already-added handlers
+            remove_jpie_handlers
+          end
+
+          # Allow applications to enable specific handlers
+          def enable_jpie_error_handler(error_class, method_name = nil)
+            method_name ||= :"handle_#{error_class.name.demodulize.underscore}"
+            rescue_from error_class, with: method_name
+          end
+
+          # Check for application-defined error handlers
+          def rescue_handler?(exception_class)
+            # Use Rails' rescue_handlers method to check for existing handlers
+            return false unless respond_to?(:rescue_handlers, true)
+
+            begin
+              rescue_handlers.any? { |handler| handler.first == exception_class.name }
+            rescue NoMethodError
+              false
+            end
+          end
+
+          private
+
+          def setup_jpie_error_handlers
+            setup_jpie_specific_handlers
+          end
+
+          def setup_jpie_specific_handlers
+            setup_core_error_handlers
+            setup_activerecord_handlers
+            setup_json_api_compliance_handlers
+          end
+
+          def setup_core_error_handlers
+            return if rescue_handler?(JPie::Errors::Error)
+
+            rescue_from JPie::Errors::Error, with: :handle_jpie_error
+          end
+
+          def setup_activerecord_handlers
+            setup_not_found_handler
+            setup_invalid_record_handler
+          end
+
+          def setup_not_found_handler
+            return if rescue_handler?(ActiveRecord::RecordNotFound)
+
+            rescue_from ActiveRecord::RecordNotFound, with: :handle_record_not_found
+          end
+
+          def setup_invalid_record_handler
+            return if rescue_handler?(ActiveRecord::RecordInvalid)
+
+            rescue_from ActiveRecord::RecordInvalid, with: :handle_record_invalid
+          end
+
+          def setup_json_api_compliance_handlers
+            setup_json_api_request_handler
+            setup_include_handlers
+            setup_sort_handlers
+          end
+
+          def setup_json_api_request_handler
+            return if rescue_handler?(JPie::Errors::InvalidJsonApiRequestError)
+
+            rescue_from JPie::Errors::InvalidJsonApiRequestError, with: :handle_invalid_json_api_request
+          end
+
+          def setup_include_handlers
+            setup_unsupported_include_handler
+            setup_invalid_include_handler
+          end
+
+          def setup_unsupported_include_handler
+            return if rescue_handler?(JPie::Errors::UnsupportedIncludeError)
+
+            rescue_from JPie::Errors::UnsupportedIncludeError, with: :handle_unsupported_include
+          end
+
+          def setup_invalid_include_handler
+            return if rescue_handler?(JPie::Errors::InvalidIncludeParameterError)
+
+            rescue_from JPie::Errors::InvalidIncludeParameterError, with: :handle_invalid_include_parameter
+          end
+
+          def setup_sort_handlers
+            setup_unsupported_sort_handler
+            setup_invalid_sort_handler
+          end
+
+          def setup_unsupported_sort_handler
+            return if rescue_handler?(JPie::Errors::UnsupportedSortFieldError)
+
+            rescue_from JPie::Errors::UnsupportedSortFieldError, with: :handle_unsupported_sort_field
+          end
+
+          def setup_invalid_sort_handler
+            return if rescue_handler?(JPie::Errors::InvalidSortParameterError)
+
+            rescue_from JPie::Errors::InvalidSortParameterError, with: :handle_invalid_sort_parameter
+          end
+
+          def remove_jpie_handlers
+            # This is a placeholder - Rails doesn't provide an easy way to remove specific handlers
+            # In practice, applications should use the disable_jpie_error_handlers before including
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jpie/controller/error_handling/handlers.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module ErrorHandling
+      module Handlers
+        extend ActiveSupport::Concern
+
+        private
+
+        # Handle JPie-specific errors
+        def handle_jpie_error(error)
+          render_json_api_error(
+            status: error.status,
+            title: error.title,
+            detail: error.detail
+          )
+        end
+
+        # Handle ActiveRecord::RecordNotFound
+        def handle_record_not_found(error)
+          render_json_api_error(
+            status: 404,
+            title: 'Not Found',
+            detail: error.message
+          )
+        end
+
+        # Handle ActiveRecord::RecordInvalid
+        def handle_record_invalid(error)
+          errors = error.record.errors.full_messages.map do |message|
+            {
+              status: '422',
+              title: 'Validation Error',
+              detail: message
+            }
+          end
+
+          render json: { errors: errors }, status: :unprocessable_content
+        end
+
+        # Render a single JSON:API error
+        def render_json_api_error(status:, title:, detail:)
+          render json: {
+            errors: [{
+              status: status.to_s,
+              title: title,
+              detail: detail
+            }]
+          }, status: status
+        end
+
+        # Handle JSON:API compliance errors
+        def handle_invalid_json_api_request(error)
+          render_json_api_error(
+            status: error.status,
+            title: error.title || 'Invalid JSON:API Request',
+            detail: error.detail
+          )
+        end
+
+        def handle_unsupported_include(error)
+          render_json_api_error(
+            status: error.status,
+            title: error.title || 'Unsupported Include',
+            detail: error.detail
+          )
+        end
+
+        def handle_unsupported_sort_field(error)
+          render_json_api_error(
+            status: error.status,
+            title: error.title || 'Unsupported Sort Field',
+            detail: error.detail
+          )
+        end
+
+        def handle_invalid_sort_parameter(error)
+          render_json_api_error(
+            status: error.status,
+            title: error.title || 'Invalid Sort Parameter',
+            detail: error.detail
+          )
+        end
+
+        def handle_invalid_include_parameter(error)
+          render_json_api_error(
+            status: error.status,
+            title: error.title || 'Invalid Include Parameter',
+            detail: error.detail
+          )
+        end
+
+        # Backward compatibility aliases
+        alias jpie_handle_error handle_jpie_error
+        alias jpie_handle_not_found handle_record_not_found
+        alias jpie_handle_invalid handle_record_invalid
+
+        # Legacy method name aliases
+        alias render_jpie_error handle_jpie_error
+        alias render_jpie_not_found_error handle_record_not_found
+        alias render_jpie_validation_error handle_record_invalid
+        alias render_jsonapi_error handle_jpie_error
+        alias render_not_found_error handle_record_not_found
+        alias render_validation_error handle_record_invalid
+      end
+    end
+  end
+end

data/lib/jpie/controller/error_handling.rb

@@ -1,40 +1,22 @@
 # frozen_string_literal: true
 
+require_relative 'error_handling/handler_setup'
+require_relative 'error_handling/handlers'
+
 module JPie
   module Controller
     module ErrorHandling
       extend ActiveSupport::Concern
 
-      included do
-        rescue_from JPie::Errors::Error, with: :render_jsonapi_error
-
-        if defined?(ActiveRecord)
-          rescue_from ActiveRecord::RecordNotFound, with: :render_not_found_error
-          rescue_from ActiveRecord::RecordInvalid, with: :render_validation_error
-        end
-      end
-
-      private
+      include HandlerSetup
+      include Handlers
 
-      def render_jsonapi_error(error)
-        render json: { errors: [error.to_hash] },
-               status: error.status,
-               content_type: 'application/vnd.api+json'
-      end
-
-      def render_not_found_error(error)
-        json_error = JPie::Errors::NotFoundError.new(detail: error.message)
-        render_jsonapi_error(json_error)
-      end
-
-      def render_validation_error(error)
-        errors = error.record.errors.full_messages.map do
-          JPie::Errors::ValidationError.new(detail: it).to_hash
-        end
+      included do
+        # Use class_attribute to allow easy overriding
+        class_attribute :jpie_error_handlers_enabled, default: true
 
-        render json: { errors: },
-               status: :unprocessable_entity,
-               content_type: 'application/vnd.api+json'
+        # Set up default handlers unless explicitly disabled
+        setup_jpie_error_handlers if jpie_error_handlers_enabled
       end
     end
   end