jpie 0.3.1 → 0.4.1

data/lib/jpie/controller/error_handling.rb

@@ -6,36 +6,187 @@ module JPie
       extend ActiveSupport::Concern
 
       included do
-        rescue_from JPie::Errors::Error, with: :render_jsonapi_error
+        # Use class_attribute to allow easy overriding
+        class_attribute :jpie_error_handlers_enabled, default: true
 
-        if defined?(ActiveRecord)
-          rescue_from ActiveRecord::RecordNotFound, with: :render_not_found_error
-          rescue_from ActiveRecord::RecordInvalid, with: :render_validation_error
+        # Set up default handlers unless explicitly disabled
+        setup_jpie_error_handlers if jpie_error_handlers_enabled
+      end
+
+      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
+          # Only add handlers if they don't already exist
+          rescue_from JPie::Errors::Error, with: :handle_jpie_error unless rescue_handler?(JPie::Errors::Error)
+          unless rescue_handler?(ActiveRecord::RecordNotFound)
+            rescue_from ActiveRecord::RecordNotFound,
+                        with: :handle_record_not_found
+          end
+          return if rescue_handler?(ActiveRecord::RecordInvalid)
+
+          rescue_from ActiveRecord::RecordInvalid,
+                      with: :handle_record_invalid
+
+          # JSON:API compliance error handlers
+          unless rescue_handler?(JPie::Errors::InvalidJsonApiRequestError)
+            rescue_from JPie::Errors::InvalidJsonApiRequestError,
+                        with: :handle_invalid_json_api_request
+          end
+
+          unless rescue_handler?(JPie::Errors::UnsupportedIncludeError)
+            rescue_from JPie::Errors::UnsupportedIncludeError,
+                        with: :handle_unsupported_include
+          end
+
+          unless rescue_handler?(JPie::Errors::UnsupportedSortFieldError)
+            rescue_from JPie::Errors::UnsupportedSortFieldError,
+                        with: :handle_unsupported_sort_field
+          end
+
+          unless rescue_handler?(JPie::Errors::InvalidSortParameterError)
+            rescue_from JPie::Errors::InvalidSortParameterError,
+                        with: :handle_invalid_sort_parameter
+          end
+
+          return if rescue_handler?(JPie::Errors::InvalidIncludeParameterError)
+
+          rescue_from JPie::Errors::InvalidIncludeParameterError,
+                      with: :handle_invalid_include_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
 
       private
 
-      def render_jsonapi_error(error)
-        render json: { errors: [error.to_hash] },
-               status: error.status,
-               content_type: 'application/vnd.api+json'
+      # Handle JPie-specific errors
+      def handle_jpie_error(error)
+        render_json_api_error(
+          status: error.status,
+          title: error.title,
+          detail: error.detail
+        )
       end
 
-      def render_not_found_error(error)
-        json_error = JPie::Errors::NotFoundError.new(detail: error.message)
-        render_jsonapi_error(json_error)
+      # Handle ActiveRecord::RecordNotFound
+      def handle_record_not_found(error)
+        render_json_api_error(
+          status: 404,
+          title: 'Not Found',
+          detail: error.message
+        )
       end
 
-      def render_validation_error(error)
-        errors = error.record.errors.full_messages.map do
-          JPie::Errors::ValidationError.new(detail: it).to_hash
+      # 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: },
-               status: :unprocessable_entity,
-               content_type: 'application/vnd.api+json'
+        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

data/lib/jpie/controller/json_api_validation.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module JsonApiValidation
+      extend ActiveSupport::Concern
+
+      private
+
+      # Validate that the request is JSON:API compliant
+      def validate_json_api_request
+        validate_content_type if request.post? || request.patch? || request.put?
+        validate_json_api_structure if request.post? || request.patch? || request.put?
+      end
+
+      # Validate Content-Type header for write operations
+      def validate_content_type
+        # Only validate content type for write operations
+        return unless request.post? || request.patch? || request.put?
+
+        content_type = request.content_type
+        return if content_type&.include?('application/vnd.api+json')
+
+        raise JPie::Errors::InvalidJsonApiRequestError.new(
+          detail: 'Content-Type must be application/vnd.api+json for JSON:API requests'
+        )
+      end
+
+      # Validate basic JSON:API request structure
+      def validate_json_api_structure
+        request_body = request.body.read
+        request.body.rewind # Reset for later reading
+
+        return if request_body.blank?
+
+        begin
+          parsed_body = JSON.parse(request_body)
+        rescue JSON::ParserError => e
+          raise JPie::Errors::InvalidJsonApiRequestError.new(
+            detail: "Invalid JSON: #{e.message}"
+          )
+        end
+
+        unless parsed_body.is_a?(Hash) && parsed_body.key?('data')
+          raise JPie::Errors::InvalidJsonApiRequestError.new(
+            detail: 'JSON:API request must have a top-level "data" member'
+          )
+        end
+
+        validate_data_structure(parsed_body['data'])
+      end
+
+      # Validate the structure of the data member
+      def validate_data_structure(data)
+        if data.is_a?(Array)
+          data.each { |item| validate_resource_object(item) }
+        elsif data.is_a?(Hash)
+          validate_resource_object(data)
+        elsif !data.nil?
+          raise JPie::Errors::InvalidJsonApiRequestError.new(
+            detail: 'Data member must be an object, array, or null'
+          )
+        end
+      end
+
+      # Validate individual resource object structure
+      def validate_resource_object(resource)
+        unless resource.is_a?(Hash)
+          raise JPie::Errors::InvalidJsonApiRequestError.new(
+            detail: 'Resource objects must be JSON objects'
+          )
+        end
+
+        unless resource.key?('type')
+          raise JPie::Errors::InvalidJsonApiRequestError.new(
+            detail: 'Resource objects must have a "type" member'
+          )
+        end
+
+        # ID is required for updates but not for creates
+        return unless request.patch? || request.put?
+        return if resource.key?('id')
+
+        raise JPie::Errors::InvalidJsonApiRequestError.new(
+          detail: 'Resource objects must have an "id" member for updates'
+        )
+      end
+
+      # Validate include parameters against supported includes
+      def validate_include_params
+        return if params[:include].blank?
+
+        include_paths = params[:include].to_s.split(',').map(&:strip)
+        supported_includes = resource_class.supported_includes
+
+        include_paths.each do |include_path|
+          next if include_path.blank?
+
+          validate_include_path(include_path, supported_includes)
+        end
+      end
+
+      # Validate a single include path
+      def validate_include_path(include_path, supported_includes)
+        # Handle nested includes (e.g., "posts.comments")
+        path_parts = include_path.split('.')
+        current_level = supported_includes
+
+        path_parts.each_with_index do |part, index|
+          unless current_level.include?(part.to_sym) || current_level.include?(part)
+            current_path = path_parts[0..index].join('.')
+            available_at_level = current_level.is_a?(Hash) ? current_level.keys : current_level
+
+            raise JPie::Errors::UnsupportedIncludeError.new(
+              include_path: current_path,
+              supported_includes: available_at_level.map(&:to_s)
+            )
+          end
+
+          # Move to next level for nested validation
+          if current_level.is_a?(Hash) && current_level[part.to_sym].is_a?(Hash)
+            current_level = current_level[part.to_sym]
+          elsif current_level.is_a?(Hash) && current_level[part].is_a?(Hash)
+            current_level = current_level[part]
+          end
+        end
+      end
+
+      # Validate sort parameters against supported fields
+      def validate_sort_params
+        return if params[:sort].blank?
+
+        sort_fields = params[:sort].to_s.split(',').map(&:strip)
+        supported_fields = resource_class.supported_sort_fields
+
+        sort_fields.each do |sort_field|
+          next if sort_field.blank?
+
+          validate_sort_field(sort_field, supported_fields)
+        end
+      end
+
+      # Validate a single sort field
+      def validate_sort_field(sort_field, supported_fields)
+        # Remove leading minus for descending sort
+        field_name = sort_field.start_with?('-') ? sort_field[1..] : sort_field
+
+        # Validate field name format
+        unless field_name.match?(/\A[a-zA-Z][a-zA-Z0-9_]*\z/)
+          raise JPie::Errors::InvalidSortParameterError.new(
+            detail: "Invalid sort field format: '#{sort_field}'. Field names must start with a letter and contain only letters, numbers, and underscores"
+          )
+        end
+
+        return if supported_fields.include?(field_name.to_sym) || supported_fields.include?(field_name)
+
+        raise JPie::Errors::UnsupportedSortFieldError.new(
+          sort_field: field_name,
+          supported_fields: supported_fields.map(&:to_s)
+        )
+      end
+
+      # Validate all JSON:API request aspects
+      def validate_json_api_compliance
+        validate_json_api_request
+        validate_include_params
+        validate_sort_params
+      end
+    end
+  end
+end

data/lib/jpie/controller.rb

@@ -5,6 +5,7 @@ require_relative 'controller/error_handling'
 require_relative 'controller/parameter_parsing'
 require_relative 'controller/rendering'
 require_relative 'controller/crud_actions'
+require_relative 'controller/json_api_validation'
 
 module JPie
   module Controller
@@ -14,5 +15,6 @@ module JPie
     include ParameterParsing
     include Rendering
     include CrudActions
+    include JsonApiValidation
   end
 end

data/lib/jpie/errors.rb

@@ -66,5 +66,46 @@ module JPie
         super(status: 500, title: 'Resource Error', detail:)
       end
     end
+
+    # JSON:API Compliance Errors
+    class InvalidJsonApiRequestError < BadRequestError
+      def initialize(detail: 'Request is not JSON:API compliant')
+        super
+      end
+    end
+
+    class UnsupportedIncludeError < BadRequestError
+      def initialize(include_path:, supported_includes: [])
+        detail = if supported_includes.any?
+                   "Unsupported include '#{include_path}'. Supported includes: #{supported_includes.join(', ')}"
+                 else
+                   "Unsupported include '#{include_path}'. No includes are supported for this resource"
+                 end
+        super(detail: detail)
+      end
+    end
+
+    class UnsupportedSortFieldError < BadRequestError
+      def initialize(sort_field:, supported_fields: [])
+        detail = if supported_fields.any?
+                   "Unsupported sort field '#{sort_field}'. Supported fields: #{supported_fields.join(', ')}"
+                 else
+                   "Unsupported sort field '#{sort_field}'. No sorting is supported for this resource"
+                 end
+        super(detail: detail)
+      end
+    end
+
+    class InvalidSortParameterError < BadRequestError
+      def initialize(detail: 'Invalid sort parameter format')
+        super
+      end
+    end
+
+    class InvalidIncludeParameterError < BadRequestError
+      def initialize(detail: 'Invalid include parameter format')
+        super
+      end
+    end
   end
 end

data/lib/jpie/generators/resource_generator.rb

@@ -5,11 +5,17 @@ require 'rails/generators/base'
 module JPie
   module Generators
     class ResourceGenerator < Rails::Generators::NamedBase
-      desc 'Generate a JPie resource class'
+      source_root File.expand_path('templates', __dir__)
 
-      argument :attributes, type: :array, default: [], banner: 'field:type field:type'
+      desc 'Generate a JPie resource class with semantic field definitions'
 
-      class_option :model, type: :string, desc: 'Model class to associate with this resource'
+      argument :field_definitions, type: :array, default: [],
+                                   banner: 'attribute:field meta:field relationship:type:field'
+
+      class_option :model, type: :string,
+                           desc: 'Model class to associate with this resource (defaults to inferred model)'
+      class_option :skip_model, type: :boolean, default: false,
+                                desc: 'Skip explicit model declaration (use automatic inference)'
 
       def create_resource_file
         template 'resource.rb.erb', File.join('app/resources', "#{file_name}_resource.rb")
@@ -21,18 +27,89 @@ module JPie
         options[:model] || class_name
       end
 
+      def needs_explicit_model?
+        # Only need explicit model declaration if:
+        # 1. User explicitly provided a different model name, OR
+        # 2. User didn't use --skip-model flag AND the model name differs from the inferred name
+        return false if options[:skip_model]
+        return true if options[:model] && options[:model] != class_name
+
+        # For standard naming (UserResource -> User), we can skip the explicit declaration
+        false
+      end
+
       def resource_attributes
-        return [] if attributes.empty?
+        parse_field_definitions.fetch(:attributes, [])
+      end
+
+      def meta_attributes_list
+        parse_field_definitions.fetch(:meta_attributes, [])
+      end
+
+      def relationships_list
+        parse_field_definitions.fetch(:relationships, [])
+      end
+
+      def parse_relationships
+        relationships_list.map do |rel|
+          # rel is already a hash with :type and :name from parse_field_definitions
+          rel
+        end
+      end
+
+      def parse_field_definitions
+        return @parsed_definitions if @parsed_definitions
+
+        @parsed_definitions = { attributes: [], meta_attributes: [], relationships: [] }
+
+        field_definitions.each do |definition|
+          process_field_definition(definition)
+        end
+
+        @parsed_definitions
+      end
+
+      def process_field_definition(definition)
+        case definition
+        when /^attribute:(.+)$/
+          @parsed_definitions[:attributes] << ::Regexp.last_match(1)
+        when /^meta:(.+)$/
+          @parsed_definitions[:meta_attributes] << ::Regexp.last_match(1)
+        when /^relationship:(.+):(.+)$/, /^(has_many|has_one|belongs_to):(.+)$/
+          add_relationship(::Regexp.last_match(1), ::Regexp.last_match(2))
+        when /^(.+):(.+)$/
+          process_legacy_field(::Regexp.last_match(1))
+        else
+          process_plain_field(definition)
+        end
+      end
+
+      def add_relationship(type, name)
+        @parsed_definitions[:relationships] << { type: type, name: name }
+      end
 
-        attributes.map(&:name)
+      def process_legacy_field(field_name)
+        # Legacy support: field:type format - treat as attribute and ignore type
+        if meta_attribute_name?(field_name)
+          @parsed_definitions[:meta_attributes] << field_name
+        else
+          @parsed_definitions[:attributes] << field_name
+        end
       end
 
-      def template_path
-        File.expand_path('templates', __dir__)
+      def process_plain_field(field_name)
+        # Plain field name - treat as attribute
+        if meta_attribute_name?(field_name)
+          @parsed_definitions[:meta_attributes] << field_name
+        else
+          @parsed_definitions[:attributes] << field_name
+        end
       end
 
-      def source_root
-        template_path
+      def meta_attribute_name?(name)
+        # Check if field name suggests it's a meta attribute
+        meta_names = %w[created_at updated_at deleted_at published_at archived_at]
+        meta_names.include?(name)
       end
     end
   end

data/lib/jpie/generators/templates/resource.rb.erb

@@ -1,12 +1,31 @@
 # frozen_string_literal: true
 
 class <%= class_name %>Resource < JPie::Resource
+<% if needs_explicit_model? -%>
   model <%= model_class_name %>
+<% end -%>
 
 <% if resource_attributes.any? -%>
   attributes <%= resource_attributes.map { |attr| ":#{attr}" }.join(', ') %>
 <% else -%>
   # Define your attributes here:
-  # attributes :name, :email, :created_at
+  # attributes :name, :email, :title
+<% end -%>
+
+<% if meta_attributes_list.any? -%>
+  meta_attributes <%= meta_attributes_list.map { |attr| ":#{attr}" }.join(', ') %>
+<% else -%>
+  # Define your meta attributes here:
+  # meta_attributes :created_at, :updated_at
+<% end -%>
+
+<% if parse_relationships.any? -%>
+<% parse_relationships.each do |rel| -%>
+  <%= rel[:type] %> :<%= rel[:name] %>
+<% end -%>
+<% else -%>
+  # Define your relationships here:
+  # has_many :posts
+  # has_one :user
 <% end -%>
 end 

data/lib/jpie/resource/attributable.rb

@@ -45,8 +45,14 @@ module JPie
           return if method_defined?(name) || private_method_defined?(name)
 
           define_method(name) do
-            attr_name = options[:attr] || name
-            @object.public_send(attr_name)
+            # Handle through associations
+            if options[:through]
+              handle_through_association(name, options)
+            else
+              # Standard association handling
+              attr_name = options[:attr] || name
+              @object.public_send(attr_name)
+            end
           end
         end
 
@@ -93,6 +99,19 @@ module JPie
           "#{singularized_name.camelize}Resource"
         end
       end
+
+      private
+
+      # Handle through associations by calling the appropriate association method
+      def handle_through_association(name, options)
+        if options[:attr]
+          # Custom attribute name was provided - use it
+          @object.public_send(options[:attr])
+        else
+          # Use the relationship name directly - Rails will handle the through association
+          @object.public_send(name)
+        end
+      end
     end
   end
 end

data/lib/jpie/resource.rb

@@ -37,6 +37,32 @@ module JPie
       def scope(_context = {})
         model.all
       end
+
+      # Return supported include paths for validation
+      # Override this method to customize supported includes
+      def supported_includes
+        # Return relationship names as supported includes by default
+        _relationships.keys.map(&:to_s)
+
+        # Convert to nested hash format for complex includes
+        # For simple includes, return array format
+      end
+
+      # Return supported sort fields for validation
+      # Override this method to customize supported sort fields
+      def supported_sort_fields
+        # Return all attributes and sortable fields as supported sort fields by default
+        fields = (_attributes + _sortable_fields.keys).uniq.map(&:to_s)
+
+        # Add common model timestamp fields if the model supports them
+        if model.respond_to?(:column_names)
+          fields << 'created_at' if model.column_names.include?('created_at') && fields.exclude?('created_at')
+
+          fields << 'updated_at' if model.column_names.include?('updated_at') && fields.exclude?('updated_at')
+        end
+
+        fields
+      end
     end
 
     attr_reader :object, :context

data/lib/jpie/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JPie
-  VERSION = '0.3.1'
+  VERSION = '0.4.1'
 end