jpie 0.1.0

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "json_api"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/jpie.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'json_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'jpie'
+  spec.version       = JSONAPI::VERSION
+  spec.authors       = ['Emil Kampp']
+  spec.email         = ['emil@kampp.me']
+
+  spec.summary       = 'JSON:API compliant Rails gem for producing and consuming JSON:API resources'
+  spec.description   = 'A Rails 8+ gem that provides jsonapi_resources routing DSL and generic JSON:API controllers'
+  spec.homepage      = 'https://github.com/klaay/jpie'
+  spec.license       = 'MIT'
+
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.4.0'
+
+  spec.add_dependency 'actionpack', '~> 8.0', '>= 8.0.0'
+  spec.add_dependency 'rails', '~> 8.0', '>= 8.0.0'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/kiln/app/resources/user_message_resource.rb

@@ -0,0 +1,2 @@
+class UserMessageResource < MessageResource
+end

data/lib/jpie.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# jpie gem entry point
+# Requires the json_api code which provides the JSONAPI namespace
+require "json_api"
+

data/lib/json_api/active_storage/deserialization.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module ActiveStorage
+    module Deserialization
+      module_function
+
+      def extract_params_from_hash(params_hash, model_class)
+        return {} unless defined?(::ActiveStorage)
+
+        attachment_params = {}
+        model_class.attachment_reflections.each_key do |attachment_name|
+          attachment_name_str = attachment_name.to_s
+          attachment_params[attachment_name] = params_hash[attachment_name_str] if params_hash.key?(attachment_name_str)
+        end
+        attachment_params
+      end
+
+      def attach_files(record, attachment_params, definition: nil)
+        return if attachment_params.empty?
+
+        attachment_params.each do |attachment_name, blob_or_blobs|
+          attachment = record.public_send(attachment_name)
+          is_has_many = blob_or_blobs.is_a?(Array)
+          append_only = is_has_many && append_only_enabled?(attachment_name, definition)
+
+          if is_has_many
+            handle_has_many_attachment(attachment, blob_or_blobs, append_only:,
+                                                                  attachment_name:, definition:)
+          else
+            handle_has_one_attachment(attachment, blob_or_blobs, attachment_name:,
+                                                                 definition:)
+          end
+        end
+      end
+
+      def process_attachment(attrs, association_name, id_or_ids, singular:)
+        if singular
+          blob = find_blob_by_signed_id(id_or_ids)
+          attrs[association_name.to_s] = blob
+        else
+          blobs = Array(id_or_ids).map { |id| find_blob_by_signed_id(id) }
+          attrs[association_name.to_s] = blobs
+        end
+      end
+
+      def find_blob_by_signed_id(signed_id)
+        return nil if signed_id.blank?
+
+        ::ActiveStorage::Blob.find_signed!(signed_id)
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        raise
+      rescue ActiveRecord::RecordNotFound => e
+        raise ArgumentError, "Blob not found for signed ID: #{e.message}"
+      end
+
+      def purge_on_nil_enabled?(attachment_name, definition)
+        return true unless definition
+
+        relationship_def = find_relationship_definition(attachment_name, definition)
+        return true unless relationship_def
+
+        relationship_def[:options].fetch(:purge_on_nil, true)
+      end
+
+      def append_only_enabled?(attachment_name, definition)
+        return false unless definition
+
+        relationship_def = find_relationship_definition(attachment_name, definition)
+        return false unless relationship_def
+
+        relationship_def[:options].fetch(:append_only, false)
+      end
+
+      def find_relationship_definition(attachment_name, definition)
+        return nil unless definition.respond_to?(:relationship_definitions)
+
+        definition.relationship_definitions.find { |r| r[:name].to_s == attachment_name.to_s }
+      end
+
+      # Private helper methods
+      def handle_has_many_attachment(attachment, blob_or_blobs, append_only:, attachment_name:, definition:)
+        if blob_or_blobs.empty?
+          return if append_only
+
+          attachment.purge if purge_on_nil_enabled?(attachment_name, definition) && attachment.attached?
+        elsif append_only
+          existing_blobs = attachment.attached? ? attachment.blobs.to_a : []
+          attachment.attach(existing_blobs + blob_or_blobs)
+        else
+          attachment.purge if attachment.attached?
+          attachment.attach(blob_or_blobs)
+        end
+      end
+
+      def handle_has_one_attachment(attachment, blob_or_blobs, attachment_name:, definition:)
+        if blob_or_blobs.present?
+          attachment.purge if attachment.attached?
+          attachment.attach(blob_or_blobs)
+        elsif blob_or_blobs.nil?
+          attachment.purge if purge_on_nil_enabled?(attachment_name, definition) && attachment.attached?
+        end
+      end
+    end
+  end
+end

data/lib/json_api/active_storage/detection.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module ActiveStorage
+    module Detection
+      module_function
+
+      def attachment?(association_name, model_class)
+        return false unless defined?(::ActiveStorage)
+
+        model_class.respond_to?(:reflect_on_attachment) &&
+          model_class.reflect_on_attachment(association_name.to_sym).present?
+      end
+
+      def blob_type?(type)
+        return false unless defined?(::ActiveStorage)
+
+        type.to_s == "active_storage_blobs"
+      end
+
+      def filter_from_includes(includes_hash, current_model_class)
+        return {} unless defined?(::ActiveStorage)
+
+        filtered = {}
+        includes_hash.each do |key, value|
+          # Skip ActiveStorage attachments - they'll be loaded on-demand by the serializer
+          next if current_model_class.reflect_on_attachment(key).present?
+
+          # Check if this is a regular association
+          association = current_model_class.reflect_on_association(key)
+          next if association.nil?
+
+          if value.is_a?(Hash) && value.any?
+            # For polymorphic associations, we can't determine the class at compile time,
+            # so we skip filtering and include the nested hash as-is
+            if association.polymorphic?
+              filtered[key] = value
+            else
+              # Recursively filter nested includes, using the associated class
+              nested_class = association.klass
+              nested_filtered = filter_from_includes(value, nested_class)
+              filtered[key] = nested_filtered if nested_filtered.any?
+            end
+          else
+            filtered[key] = value
+          end
+        end
+        filtered
+      end
+
+      def filter_polymorphic_from_includes(includes_hash, current_model_class)
+        filtered = {}
+
+        includes_hash.each do |key, value|
+          association = current_model_class.reflect_on_association(key)
+          next unless association
+
+          # Skip polymorphic associations entirely for preloading
+          next if association.polymorphic?
+
+          if value.is_a?(Hash) && value.any?
+            nested_class = association.klass
+            nested_filtered = filter_polymorphic_from_includes(value, nested_class)
+            filtered[key] = nested_filtered if nested_filtered.any?
+          else
+            filtered[key] = value
+          end
+        end
+
+        filtered
+      end
+    end
+  end
+end

data/lib/json_api/active_storage/serialization.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module ActiveStorage
+    module Serialization
+      module_function
+
+      def serialize_relationship(attachment_name, record)
+        return nil unless defined?(::ActiveStorage)
+
+        attachment = record.public_send(attachment_name)
+
+        if attachment.respond_to?(:attached?) && attachment.attached?
+          # has_many_attached returns an array-like object
+          if attachment.is_a?(::ActiveStorage::Attached::Many)
+            attachment.blobs.map { |blob| serialize_blob_identifier(blob) }
+          else
+            # has_one_attached
+            serialize_blob_identifier(attachment.blob)
+          end
+        elsif attachment.respond_to?(:attached?) && !attachment.attached?
+          # Not attached - return nil for has_one, empty array for has_many
+          attachment.is_a?(::ActiveStorage::Attached::Many) ? [] : nil
+        end
+      end
+
+      def serialize_blob_identifier(blob)
+        { type: "active_storage_blobs", id: blob.id.to_s }
+      end
+    end
+  end
+end

data/lib/json_api/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  class Configuration
+    attr_accessor :default_page_size, :max_page_size, :jsonapi_version, :jsonapi_meta, :authorization_handler,
+                  :authorization_scope, :document_meta_resolver
+
+    def initialize
+      @default_page_size = 25
+      @max_page_size = 100
+      @jsonapi_version = "1.1"
+      @jsonapi_meta = nil
+      @authorization_handler = nil
+      @authorization_scope = nil
+      @document_meta_resolver = ->(controller:) { {} }
+      @base_controller_class = "ActionController::API"
+    end
+
+    def base_controller_class=(value)
+      if value.is_a?(Class)
+        @base_controller_class = value.name
+      elsif value.is_a?(String)
+        raise ArgumentError, "base_controller_class cannot be blank" if value.blank?
+
+        @base_controller_class = value
+      else
+        raise ArgumentError, "base_controller_class must be a string or class"
+      end
+
+      return unless Rails.application&.initialized?
+
+      JSONAPI.rebuild_base_controllers!
+    end
+
+    def base_controller_class
+      @base_controller_class.constantize
+    end
+
+    def resolved_base_controller_class
+      class_name = @base_controller_class
+      raise ArgumentError, "base_controller_class cannot be blank" if class_name.blank?
+
+      class_name.constantize
+    end
+
+    def base_controller_overridden?
+      @base_controller_class != "ActionController::API"
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield configuration if block_given?
+  end
+end

data/lib/json_api/controllers/base_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  class BaseController < JSONAPI.configuration.resolved_base_controller_class
+    include ControllerHelpers
+    include ResourceActions
+
+    rescue_from JSONAPI::AuthorizationError, with: :render_jsonapi_authorization_error
+    rescue_from Pundit::NotAuthorizedError, with: :render_jsonapi_authorization_error if defined?(Pundit)
+
+    private
+
+    def render_jsonapi_authorization_error(error)
+      detail = error&.message.presence || "You are not authorized to perform this action"
+      render json: {
+        errors: [
+          {
+            status: "403",
+            title: "Forbidden",
+            detail:
+          }
+        ]
+      }, status: :forbidden
+    end
+  end
+end

data/lib/json_api/controllers/concerns/controller_helpers.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+    include Responders
+
+    included do
+      attr_reader :resource_class, :model_class
+
+      before_action :parse_jsonapi_body, if: -> { request.post? || request.patch? || request.put? || request.delete? }
+    end
+
+    protected
+
+    def parse_jsonapi_body
+      return unless request.content_type&.include?("application/vnd.api+json")
+      return if params[:data].present?
+
+      body = request.body.read
+      request.body.rewind
+      return if body.blank?
+
+      parsed = JSON.parse(body)
+      parsed.deep_transform_keys!(&:to_sym)
+      request.env["action_dispatch.request.request_parameters"] = parsed
+    rescue JSON::ParserError
+      # Invalid JSON - will be handled by validation
+    end
+
+    def jsonapi_params
+      data = params.require(:data)
+
+      # Relationship requests may send an array of resource identifier objects.
+      return data if data.is_a?(Array)
+
+      permitted = data.permit(:type, :id, attributes: {})
+
+      # Manually permit relationships with nested data structures
+      if data[:relationships].present?
+        permitted[:relationships] = {}
+        data[:relationships].each do |key, value|
+          permitted[:relationships][key] = value.permit(data: %i[type id]) if value.is_a?(ActionController::Parameters)
+        end
+      end
+
+      permitted
+    end
+
+    def jsonapi_attributes
+      (jsonapi_params[:attributes] || {}).to_h
+    end
+
+    def jsonapi_relationships
+      jsonapi_params[:relationships] || {}
+    end
+
+    def jsonapi_type
+      data = jsonapi_params
+      return data.first[:type] if data.is_a?(Array)
+
+      data[:type]
+    end
+
+    def jsonapi_id
+      data = jsonapi_params
+      return data.first[:id].to_s.presence if data.is_a?(Array)
+
+      data[:id].to_s.presence
+    end
+
+    def parse_include_param
+      return [] unless params[:include]
+
+      params[:include].to_s.split(",").map(&:strip)
+    end
+
+    def parse_fields_param
+      return {} unless params[:fields]
+
+      params[:fields].permit!.to_h.each_with_object({}) do |(type, fields), hash|
+        hash[type.to_sym] = fields.to_s.split(",").map(&:strip)
+      end
+    end
+
+    def parse_filter_param
+      return {} unless params[:filter]
+
+      raw_filters = params[:filter].permit!.to_h
+      JSONAPI::ParamHelpers.flatten_filter_hash(raw_filters)
+    end
+
+    def parse_sort_param
+      return [] unless params[:sort]
+
+      params[:sort].to_s.split(",").map(&:strip)
+    end
+
+    def invalid_sort_fields_for_columns(sorts, available_columns)
+      sorts.filter_map do |sort_field|
+        field = JSONAPI::RelationshipHelpers.extract_sort_field_name(sort_field)
+        field unless available_columns.include?(field.to_s)
+      end
+    end
+
+    def valid_sort_fields_for_resource(resource_class, model_class)
+      # Include both database columns and resource-defined sortable fields
+      # (attributes + sort-only fields via permitted_sortable_fields)
+      model_columns = model_class.column_names.map(&:to_sym)
+      resource_sortable_fields = resource_class.permitted_sortable_fields.map(&:to_sym)
+      (model_columns + resource_sortable_fields).uniq.map(&:to_s)
+    end
+
+    def parse_page_param
+      return {} unless params[:page]
+
+      params[:page].permit(:number, :size).to_h
+    end
+
+    def set_resource_name
+      @resource_name = params[:resource_type].to_s.singularize
+    end
+
+    def set_resource_class
+      @resource_class = JSONAPI::ResourceLoader.find(params[:resource_type])
+      @model_class = @resource_class.model_class
+    rescue JSONAPI::ResourceLoader::MissingResourceClass => e
+      render_resource_not_found_error(e.message)
+    rescue NameError => e
+      render_model_not_found_error(e)
+    end
+
+    def set_resource
+      @resource = @preloaded_resource || model_class.find(params[:id])
+    rescue ActiveRecord::RecordNotFound
+      render_jsonapi_error(
+        status: 404,
+        title: "Record Not Found",
+        detail: "Could not find #{@resource_name} with id '#{params[:id]}'"
+      ) and return
+    end
+
+    def render_resource_not_found_error(message)
+      render_jsonapi_error(
+        status: 404,
+        title: "Resource Not Found",
+        detail: message
+      ) and return
+    end
+
+    def render_model_not_found_error(error)
+      render_jsonapi_error(
+        status: 404,
+        title: "Resource Not Found",
+        detail: "Model class for '#{@resource_name}' not found: #{error.message}"
+      ) and return
+    end
+
+    def render_invalid_relationship_error(error)
+      render_jsonapi_error(
+        status: 400,
+        title: "Invalid Relationship",
+        detail: error.message
+      ) and return
+    end
+
+    def render_validation_errors(resource)
+      errors = resource.errors.map do |error|
+        {
+          status: "422",
+          title: "Validation Error",
+          detail: error.full_message,
+          source: { pointer: "/data/attributes/#{error.attribute}" }
+        }
+      end
+
+      render json: { errors: }, status: :unprocessable_entity
+    end
+
+    def render_parameter_not_allowed_error(error)
+      params = error.respond_to?(:params) ? error.params : []
+
+      render json: {
+        errors: [
+          {
+            status: "400",
+            code: "parameter_not_allowed",
+            title: "Parameter Not Allowed",
+            detail: params.present? ? params.join(", ") : "Relationship or attribute is read-only"
+          }
+        ]
+      }, status: :bad_request
+    end
+
+    def apply_authorization_scope(scope, action:)
+      handler = JSONAPI.configuration.authorization_scope
+      return scope unless handler
+
+      handler.call(controller: self, scope:, action:, model_class:)
+    end
+
+    def authorize_resource_action!(record, action:, context: nil)
+      handler = JSONAPI.configuration.authorization_handler
+      return unless handler
+
+      handler.call(controller: self, record:, action:, context:)
+    end
+
+    def current_user
+      nil
+    end
+    public :current_user
+
+    def jsonapi_document_meta(extra_meta = {})
+      resolver = JSONAPI.configuration.document_meta_resolver
+      base_meta = resolver ? resolver.call(controller: self) : {}
+      meta = base_meta.merge(extra_meta || {})
+      return {} if meta.empty?
+
+      meta
+    end
+  end
+end