jpie 0.4.0 → 0.4.2

data/lib/jpie/controller/json_api_validation.rb

@@ -0,0 +1,193 @@
+# 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 = read_request_body
+        return if request_body.blank?
+
+        parsed_body = parse_json_body(request_body)
+        validate_top_level_structure(parsed_body)
+        validate_data_structure(parsed_body['data'])
+      end
+
+      def read_request_body
+        request_body = request.body.read
+        request.body.rewind # Reset for later reading
+        request_body
+      end
+
+      def parse_json_body(request_body)
+        JSON.parse(request_body)
+      rescue JSON::ParserError => e
+        raise JPie::Errors::InvalidJsonApiRequestError.new(
+          detail: "Invalid JSON: #{e.message}"
+        )
+      end
+
+      def validate_top_level_structure(parsed_body)
+        return if 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 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)
+        path_parts = include_path.split('.')
+        current_level = supported_includes
+
+        path_parts.each_with_index do |part, index|
+          validate_include_part(part, current_level, path_parts, index)
+          current_level = move_to_next_include_level(part, current_level)
+        end
+      end
+
+      def validate_include_part(part, current_level, path_parts, index)
+        return if include_part_supported?(part, current_level)
+
+        current_path = path_parts[0..index].join('.')
+        available_at_level = extract_available_includes(current_level)
+
+        raise JPie::Errors::UnsupportedIncludeError.new(
+          include_path: current_path,
+          supported_includes: available_at_level.map(&:to_s)
+        )
+      end
+
+      def include_part_supported?(part, current_level)
+        current_level.include?(part.to_sym) || current_level.include?(part)
+      end
+
+      def extract_available_includes(current_level)
+        current_level.is_a?(Hash) ? current_level.keys : current_level
+      end
+
+      def move_to_next_include_level(part, current_level)
+        return current_level unless current_level.is_a?(Hash)
+
+        current_level[part.to_sym] if current_level[part.to_sym].is_a?(Hash)
+        current_level[part] if current_level[part].is_a?(Hash)
+        current_level
+      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/parameter_parsing.rb

@@ -11,6 +11,16 @@ module JPie
         params[:sort]&.split(',')&.map(&:strip) || []
       end
 
+      def parse_pagination_params
+        page_params = params[:page] || {}
+        per_page_param = params[:per_page]
+
+        {
+          page: extract_page_number(page_params, per_page_param),
+          per_page: extract_per_page_size(page_params, per_page_param)
+        }
+      end
+
       def deserialize_params
         deserializer.deserialize(request.body.read, context)
       rescue JSON::ParserError => e
@@ -30,6 +40,39 @@ module JPie
           action: action_name
         }
       end
+
+      def extract_page_number(page_params, per_page_param)
+        page_number = determine_page_number(page_params)
+        page_number = '1' if page_number.nil? && per_page_param.present?
+        return 1 if page_number.blank?
+
+        parsed_page = page_number.to_i
+        parsed_page.positive? ? parsed_page : 1
+      end
+
+      def extract_per_page_size(page_params, per_page_param)
+        per_page_size = determine_per_page_size(page_params, per_page_param)
+        return nil if per_page_size.blank?
+
+        parsed_size = per_page_size.to_i
+        parsed_size.positive? ? parsed_size : nil
+      end
+
+      def determine_page_number(page_params)
+        if page_params.is_a?(String) || page_params.is_a?(Integer)
+          page_params
+        else
+          page_params[:number] || page_params['number']
+        end
+      end
+
+      def determine_per_page_size(page_params, per_page_param)
+        if page_params.is_a?(String) || page_params.is_a?(Integer)
+          per_page_param
+        else
+          page_params[:size] || page_params['size'] || per_page_param
+        end
+      end
     end
   end
 end

data/lib/jpie/controller/rendering.rb

@@ -23,9 +23,15 @@ module JPie
       end
 
       # More concise method names following Rails conventions
-      def render_jsonapi(resource_or_resources, status: :ok, meta: nil)
+      def render_jsonapi(resource_or_resources, status: :ok, meta: nil, pagination: nil, original_scope: nil)
         includes = parse_include_params
         json_data = serializer.serialize(resource_or_resources, context, includes: includes)
+
+        # Add pagination metadata and links if pagination is provided and valid
+        if pagination && pagination[:per_page]
+          add_pagination_metadata(json_data, resource_or_resources, pagination, original_scope)
+        end
+
         json_data[:meta] = meta if meta
 
         render json: json_data, status:, content_type: 'application/vnd.api+json'
@@ -37,6 +43,94 @@ module JPie
 
       private
 
+      def add_pagination_metadata(json_data, resources, pagination, original_scope)
+        page = pagination[:page] || 1
+        per_page = pagination[:per_page]
+
+        # Get total count from the original scope before pagination
+        total_count = get_total_count(resources, original_scope)
+        total_pages = (total_count.to_f / per_page).ceil
+
+        # Add pagination metadata
+        json_data[:meta] ||= {}
+        json_data[:meta][:pagination] = {
+          page: page,
+          per_page: per_page,
+          total_pages: total_pages,
+          total_count: total_count
+        }
+
+        # Add pagination links
+        json_data[:links] = build_pagination_links(page, per_page, total_pages)
+      end
+
+      def get_total_count(resources, original_scope)
+        # Use original scope if provided, otherwise fall back to resources
+        scope_to_count = original_scope || resources
+
+        # If scope is an ActiveRecord relation, get the count
+        # Otherwise, if it's an array, get the length
+        if scope_to_count.respond_to?(:count) && !scope_to_count.loaded?
+          scope_to_count.count
+        elsif scope_to_count.respond_to?(:size)
+          scope_to_count.size
+        else
+          0
+        end
+      end
+
+      def build_pagination_links(page, per_page, total_pages)
+        url_components = extract_url_components
+        pagination_data = { page: page, per_page: per_page, total_pages: total_pages }
+
+        links = build_base_pagination_links(url_components, pagination_data)
+        add_conditional_pagination_links(links, url_components, pagination_data)
+
+        links
+      end
+
+      def extract_url_components
+        base_url = request.respond_to?(:base_url) ? request.base_url : 'http://example.com'
+        path = request.respond_to?(:path) ? request.path : '/resources'
+        query_params = request.respond_to?(:query_parameters) ? request.query_parameters.except('page') : {}
+
+        { base_url: base_url, path: path, query_params: query_params }
+      end
+
+      def build_base_pagination_links(url_components, pagination_data)
+        full_url = url_components[:base_url] + url_components[:path]
+        query_params = url_components[:query_params]
+        page = pagination_data[:page]
+        per_page = pagination_data[:per_page]
+        total_pages = pagination_data[:total_pages]
+
+        {
+          self: build_page_url(full_url, query_params, page, per_page),
+          first: build_page_url(full_url, query_params, 1, per_page),
+          last: build_page_url(full_url, query_params, total_pages, per_page)
+        }
+      end
+
+      def add_conditional_pagination_links(links, url_components, pagination_data)
+        full_url = url_components[:base_url] + url_components[:path]
+        query_params = url_components[:query_params]
+        page = pagination_data[:page]
+        per_page = pagination_data[:per_page]
+        total_pages = pagination_data[:total_pages]
+
+        links[:prev] = build_page_url(full_url, query_params, page - 1, per_page) if page > 1
+        links[:next] = build_page_url(full_url, query_params, page + 1, per_page) if page < total_pages
+      end
+
+      def build_page_url(base_url, query_params, page_num, per_page)
+        params = query_params.merge(
+          'page' => page_num.to_s,
+          'per_page' => per_page.to_s
+        )
+        query_string = params.respond_to?(:to_query) ? params.to_query : params.map { |k, v| "#{k}=#{v}" }.join('&')
+        "#{base_url}?#{query_string}"
+      end
+
       def infer_resource_class
         # Convert controller name to resource class name
         # e.g., "UsersController" -> "UserResource"

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/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,14 @@ module JPie
           "#{singularized_name.camelize}Resource"
         end
       end
+
+      private
+
+      # Handle through associations by calling the appropriate association method
+      def handle_through_association(name, options)
+        attr_name = options[:attr] || name
+        @object.public_send(attr_name)
+      end
     end
   end
 end

data/lib/jpie/resource.rb

@@ -37,6 +37,46 @@ 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
+        base_fields = extract_base_sort_fields
+        timestamp_fields = extract_timestamp_fields
+        (base_fields + timestamp_fields).uniq
+      end
+
+      private
+
+      def extract_base_sort_fields
+        (_attributes + _sortable_fields.keys).uniq.map(&:to_s)
+      end
+
+      def extract_timestamp_fields
+        return [] unless model.respond_to?(:column_names)
+
+        timestamp_fields = []
+        add_timestamp_field(timestamp_fields, 'created_at')
+        add_timestamp_field(timestamp_fields, 'updated_at')
+        timestamp_fields
+      end
+
+      def add_timestamp_field(fields, field_name)
+        return unless model.column_names.include?(field_name)
+        return if fields.include?(field_name)
+
+        fields << field_name
+      end
     end
 
     attr_reader :object, :context

data/lib/jpie/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Emil Kampp
 bindir: exe
 cert_chain: []
-date: 2025-05-24 00:00:00.000000000 Z
+date: 2025-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -169,18 +169,28 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".aiconfig"
+- ".cursorrules"
+- ".overcommit.yml"
 - ".rubocop.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/basic_example.md
+- examples/including_related_resources.md
+- examples/pagination.md
+- examples/resource_attribute_configuration.md
+- examples/resource_meta_configuration.md
+- examples/single_table_inheritance.md
 - jpie.gemspec
 - lib/jpie.rb
 - lib/jpie/configuration.rb
 - lib/jpie/controller.rb
 - lib/jpie/controller/crud_actions.rb
 - lib/jpie/controller/error_handling.rb
+- lib/jpie/controller/error_handling/handler_setup.rb
+- lib/jpie/controller/error_handling/handlers.rb
+- lib/jpie/controller/json_api_validation.rb
 - lib/jpie/controller/parameter_parsing.rb
 - lib/jpie/controller/rendering.rb
 - lib/jpie/deserializer.rb