jpie 0.4.5 → 1.0.1

data/lib/json_api/controllers/relationships_controller.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json_api/support/relationship_guard"
+require_relative "concerns/relationships/serialization"
+require_relative "concerns/relationships/updating"
+require_relative "concerns/relationships/removal"
+require_relative "concerns/relationships/sorting"
+require_relative "concerns/relationships/events"
+require_relative "concerns/relationships/response_helpers"
+
+module JSONAPI
+  class RelationshipsController < BaseController
+    include Relationships::Serialization
+    include Relationships::Updating
+    include Relationships::Removal
+    include Relationships::Sorting
+    include Relationships::Events
+    include Relationships::ResponseHelpers
+
+    skip_before_action :validate_resource_type!, only: %i[update destroy]
+    skip_before_action :validate_resource_id!, only: %i[update destroy]
+
+    before_action :set_resource_name
+    before_action :set_resource_class
+    before_action :set_resource
+    before_action :set_relationship_name
+    before_action :validate_relationship_exists
+    before_action :validate_sort_param, only: [:show]
+    skip_before_action :validate_resource_type!, :validate_resource_id!
+
+    def show
+      authorize_resource_action!(@resource, action: :show, context: { relationship: @relationship_name })
+      render json: build_show_response, status: :ok
+    end
+
+    def update
+      authorize_resource_action!(@resource, action: :update, context: { relationship: @relationship_name })
+      relationship_data = parse_relationship_data
+      update_relationship(relationship_data)
+      save_and_render_relationship(relationship_data)
+    rescue ArgumentError => e
+      render_invalid_relationship_error(e)
+    rescue JSONAPI::Exceptions::ParameterNotAllowed => e
+      render_parameter_not_allowed_error(e)
+    end
+
+    def destroy
+      authorize_resource_action!(@resource, action: :update, context: { relationship: @relationship_name })
+      relationship_data = parse_relationship_data
+      return head :no_content if relationship_data.nil?
+
+      remove_relationship(relationship_data)
+      finalize_relationship_removal(relationship_data)
+    rescue ArgumentError => e
+      render_invalid_relationship_error(e)
+    rescue JSONAPI::Exceptions::ParameterNotAllowed => e
+      render_parameter_not_allowed_error(e)
+    end
+
+    private
+
+    def set_relationship_name
+      @relationship_name = params[:relationship_name].to_sym
+    end
+
+    def validate_relationship_exists
+      return if find_relationship_definition
+
+      render_jsonapi_error(
+        status: 404,
+        title: "Relationship Not Found",
+        detail: "Relationship '#{@relationship_name}' not found on #{@resource_name}",
+      )
+    end
+
+    def find_relationship_definition
+      RelationshipHelpers.find_relationship_definition(@resource_class, @relationship_name)
+    end
+
+    def parse_relationship_data
+      raw_data = params[:data]
+      return nil if raw_data.nil?
+      return [] if raw_data.is_a?(Array) && raw_data.empty?
+      return raw_data.map { |item| ParamHelpers.deep_symbolize_params(item) } if raw_data.is_a?(Array)
+
+      ParamHelpers.deep_symbolize_params(raw_data)
+    end
+
+    def polymorphic_association?
+      RelationshipHelpers.polymorphic_association?(@resource_class, @relationship_name)
+    end
+
+    def ensure_relationship_writable!(association)
+      return if active_storage_writable?(association)
+
+      relationship_def = find_relationship_definition
+      readonly = relationship_def && (relationship_def[:options] || {})[:readonly] == true
+
+      JSONAPI::RelationshipGuard.ensure_writable!(association, @relationship_name, readonly:)
+    end
+
+    def active_storage_writable?(association)
+      self.class.respond_to?(:active_storage_attachment?) &&
+        active_storage_attachment?(@relationship_name, @resource.class) &&
+        association.nil?
+    end
+  end
+end

data/lib/json_api/controllers/resources_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  class ResourcesController < BaseController
+  end
+end

data/lib/json_api/errors/parameter_not_allowed.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Errors
+    class ParameterNotAllowed < JSONAPI::Error
+      attr_reader :params
+
+      def initialize(params = [])
+        @params = params
+        super("Parameter not allowed: #{Array(params).join(", ")}")
+      end
+    end
+  end
+
+  # Backward compatibility alias
+  module Exceptions
+    ParameterNotAllowed = Errors::ParameterNotAllowed
+  end
+end

data/lib/json_api/railtie.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module JSONAPI
+  class Railtie < Rails::Railtie
+    config.before_initialize do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym "JSON"
+        inflect.acronym "API"
+        # Ensure json_api converts to JSONAPI
+      end
+    end
+
+    initializer "json_api.mime_type" do |_app|
+      Mime::Type.register "application/vnd.api+json", :jsonapi
+    end
+
+    initializer "json_api.routes" do |_app|
+      require "json_api/routing"
+      ActionDispatch::Routing::Mapper.include JSONAPI::Routing
+    end
+
+    # Removed eager_load_namespaces registration - JSONAPI module doesn't implement eager_load!
+    # Controllers and resources are autoloaded via Zeitwerk
+
+    initializer "json_api.parameter_parsing", after: "action_dispatch.configure" do |_app|
+      ActionDispatch::Request.parameter_parsers[:jsonapi] = lambda do |raw_post|
+        ActiveSupport::JSON.decode(raw_post)
+      rescue JSON::ParserError => e
+        raise ActionDispatch::Http::Parameters::ParseError, e.message
+      end
+    end
+
+    initializer "json_api.controllers.include_base", before: :add_routing_paths do |_app|
+      mixin = lambda do |base|
+        next unless JSONAPI.configuration.base_controller_overridden?
+
+        # Use class name comparison instead of object equality to avoid timing issues
+        # when ApplicationController loads before JSONAPIController
+        expected_class_name = JSONAPI.configuration.instance_variable_get(:@base_controller_class)
+        next unless base.name == expected_class_name
+
+        base.include(JSONAPI::ControllerHelpers)
+        base.include(JSONAPI::ResourceActions)
+      end
+
+      ActiveSupport.on_load(:action_controller_base, &mixin)
+      ActiveSupport.on_load(:action_controller_api, &mixin)
+    end
+
+    # Inject JSON:API concerns into the configured base controller class only when it's been overridden
+    # This allows empty controllers inheriting from ApplicationController to work automatically
+    # We don't mix into ActionController::API by default to avoid Rails filtering action methods
+    # (Rails treats public methods on abstract base classes as internal methods)
+    #
+    # We use after_initialize because:
+    # 1. App controllers (e.g., JSONAPIController) must be autoloaded first
+    # 2. Rails 8 freezes autoload paths during initialization, and config.to_prepare runs
+    #    before app controllers are available, causing FrozenError or NameError
+    # 3. We register with reloader.to_prepare for code reloading in development
+    config.after_initialize do |app|
+      # Register for code reloading in development
+      app.reloader.to_prepare do
+        Railtie.setup_base_controllers
+      end
+
+      # Run once immediately after initialization
+      # In eager_load environments (production, test with config.eager_load = true),
+      # controllers are already loaded. In development, this triggers autoloading
+      # which is now safe since initialization is complete.
+      Railtie.setup_base_controllers
+    end
+
+    class << self
+      def setup_base_controllers
+        return unless JSONAPI.configuration.base_controller_overridden?
+
+        base_controller_class = resolve_base_controller_class
+        return unless base_controller_class
+
+        rebuild_controllers_if_needed(base_controller_class)
+        include_jsonapi_concerns(base_controller_class)
+      end
+
+      private
+
+      def resolve_base_controller_class
+        class_name = JSONAPI.configuration.instance_variable_get(:@base_controller_class)
+        class_name.constantize
+      rescue NameError
+        # Controller not yet loaded - this can happen in test environments
+        # where eager_load is false and autoloading hasn't run yet.
+        nil
+      end
+
+      def rebuild_controllers_if_needed(base_controller_class)
+        return if JSONAPI::BaseController.superclass == base_controller_class
+
+        JSONAPI.send(:remove_const, :BaseController)
+        load "json_api/controllers/base_controller.rb"
+        JSONAPI.send(:remove_const, :RelationshipsController)
+        load "json_api/controllers/relationships_controller.rb"
+      end
+
+      def include_jsonapi_concerns(base_controller_class)
+        base_controller_class.include(JSONAPI::ControllerHelpers)
+        base_controller_class.include(JSONAPI::ResourceActions)
+      end
+    end
+  end
+end

data/lib/json_api/resources/active_storage_blob_resource.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  class ActiveStorageBlobResource < Resource
+    attributes :filename, :content_type, :byte_size, :checksum, :url
+
+    def self.model_class
+      ::ActiveStorage::Blob
+    end
+
+    def url
+      return nil unless resource.persisted?
+
+      Rails.application.routes.url_helpers.rails_blob_path(resource, only_path: true)
+    rescue StandardError
+      "/rails/active_storage/blobs/#{resource.signed_id}/#{resource.filename}"
+    end
+  end
+end

data/lib/json_api/resources/concerns/attributes_dsl.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Resources
+    module AttributesDsl
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def attributes(*attrs)
+          @attributes ||= []
+          @attributes.concat(attrs.map(&:to_sym))
+          @attributes.uniq!
+        end
+
+        def creatable_fields(*fields)
+          @creatable_fields ||= []
+          @creatable_fields.concat(fields.map(&:to_sym))
+          @creatable_fields.uniq!
+        end
+
+        def updatable_fields(*fields)
+          @updatable_fields ||= []
+          @updatable_fields.concat(fields.map(&:to_sym))
+          @updatable_fields.uniq!
+        end
+      end
+
+      module FieldResolution
+        def permitted_attributes
+          declared_attributes = instance_variable_defined?(:@attributes)
+          attrs = @attributes || []
+          attrs = superclass.permitted_attributes + attrs if should_inherit_attributes?(declared_attributes)
+          attrs.uniq
+        end
+
+        def permitted_creatable_fields
+          resolve_field_list(:@creatable_fields, :permitted_creatable_fields)
+        end
+
+        def permitted_updatable_fields
+          resolve_field_list(:@updatable_fields, :permitted_updatable_fields)
+        end
+
+        def resolve_field_list(ivar, method)
+          return (instance_variable_get(ivar) || []).uniq if instance_variable_defined?(ivar)
+          return superclass.public_send(method).uniq if inherits_field?(ivar, method)
+
+          permitted_attributes.uniq
+        end
+
+        def inherits_field?(ivar, method)
+          superclass != JSONAPI::Resource &&
+            superclass.respond_to?(method) &&
+            superclass.instance_variable_defined?(ivar)
+        end
+
+        def should_inherit_attributes?(declared_attributes)
+          !declared_attributes &&
+            superclass != JSONAPI::Resource &&
+            superclass.respond_to?(:permitted_attributes)
+        end
+      end
+
+      included do
+        extend FieldResolution
+      end
+    end
+  end
+end

data/lib/json_api/resources/concerns/filters_dsl.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Resources
+    module FiltersDsl
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def filters(*filter_names)
+          @filters ||= []
+          @filters.concat(filter_names.map(&:to_sym))
+          @filters.uniq!
+        end
+
+        def permitted_filters_through
+          relationship_names
+        end
+
+        def permitted_filters
+          declared_filters = instance_variable_defined?(:@filters)
+          filter_list = @filters || []
+          if !declared_filters &&
+             superclass != JSONAPI::Resource &&
+             superclass.respond_to?(:permitted_filters)
+            filter_list = superclass.permitted_filters + filter_list
+          end
+          filter_list.uniq
+        end
+      end
+    end
+  end
+end

data/lib/json_api/resources/concerns/meta_dsl.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Resources
+    module MetaDsl
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def meta(hash = nil, &block)
+          @meta = hash || block
+        end
+
+        def resource_meta
+          if instance_variable_defined?(:@meta)
+            @meta
+          elsif superclass != JSONAPI::Resource && superclass.respond_to?(:resource_meta)
+            superclass.resource_meta
+          end
+        end
+      end
+    end
+  end
+end

data/lib/json_api/resources/concerns/model_class_helpers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Resources
+    module ModelClassHelpers
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def resource_for_model(model_class)
+          resource_const = "#{model_class.name}Resource"
+          resource_const.safe_constantize if resource_const.respond_to?(:safe_constantize) || defined?(ActiveSupport)
+        rescue NameError
+          nil
+        end
+
+        def model_class
+          name.sub(/Resource$/, "").classify.constantize
+        end
+
+        def safe_model_class
+          return nil unless respond_to?(:name) && name
+          return nil unless defined?(ActiveSupport)
+
+          name.sub(/Resource$/, "").classify.safe_constantize
+        rescue NoMethodError
+          nil
+        end
+
+        def reflection_model_class
+          model_class
+        rescue StandardError
+          safe_model_class
+        end
+      end
+    end
+  end
+end

data/lib/json_api/resources/concerns/relationships_dsl.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Resources
+    module RelationshipsDsl
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def has_one(name, meta: nil, **options)
+          @relationships ||= []
+          detect_polymorphic(name, options)
+          @relationships << { name: name.to_sym, type: :has_one, meta:, options: }
+        end
+
+        def has_many(name, meta: nil, **options)
+          @relationships ||= []
+          validate_append_only_options!(options)
+          detect_polymorphic(name, options)
+          @relationships << { name: name.to_sym, type: :has_many, meta:, options: }
+        end
+
+        def belongs_to(name, meta: nil, **options)
+          @relationships ||= []
+          detect_polymorphic(name, options)
+          @relationships << { name: name.to_sym, type: :belongs_to, meta:, options: }
+        end
+
+        def relationship_definitions
+          declared_relationships = instance_variable_defined?(:@relationships)
+          rels = @relationships || []
+          rels = superclass.relationship_definitions + rels if should_inherit_relationships?(declared_relationships)
+          rels.uniq { |r| r[:name] }
+        end
+
+        def relationship_names
+          relationship_definitions.map { |r| r[:name] }
+        end
+      end
+
+      module RelationshipHelperMethods
+        def validate_append_only_options!(options)
+          if options[:append_only] && options[:purge_on_nil] == true
+            raise ArgumentError, "Cannot use append_only: true with purge_on_nil: true"
+          end
+
+          options[:purge_on_nil] = false if options[:append_only] && !options.key?(:purge_on_nil)
+        end
+
+        def detect_polymorphic(name, options)
+          return if options.key?(:polymorphic)
+
+          model_klass = reflection_model_class
+          return unless model_klass.respond_to?(:reflect_on_association)
+
+          reflection = model_klass.reflect_on_association(name)
+          options[:polymorphic] = reflection&.polymorphic?
+        end
+
+        def should_inherit_relationships?(declared_relationships)
+          !declared_relationships &&
+            superclass != JSONAPI::Resource &&
+            superclass.respond_to?(:relationship_definitions)
+        end
+      end
+
+      included do
+        extend RelationshipHelperMethods
+      end
+    end
+  end
+end

data/lib/json_api/resources/concerns/sortable_fields_dsl.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Resources
+    module SortableFieldsDsl
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def sortable_fields(*field_names)
+          @sortable_fields ||= []
+          @sortable_fields.concat(field_names.map(&:to_sym))
+          @sortable_fields.uniq!
+        end
+
+        def permitted_sortable_fields
+          sort_fields = @sortable_fields || []
+          sort_fields = inherited_sort_only_fields + sort_fields if should_inherit_sortable_fields?
+          (permitted_attributes + sort_fields).uniq
+        end
+
+        def should_inherit_sortable_fields?
+          !instance_variable_defined?(:@sortable_fields) &&
+            !instance_variable_defined?(:@attributes) &&
+            superclass != JSONAPI::Resource &&
+            superclass.respond_to?(:permitted_sortable_fields)
+        end
+
+        def inherited_sort_only_fields
+          parent_sort_fields = superclass.permitted_sortable_fields
+          parent_attributes = superclass.permitted_attributes
+          parent_sort_fields - parent_attributes
+        end
+      end
+    end
+  end
+end

data/lib/json_api/resources/resource.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "concerns/attributes_dsl"
+require_relative "concerns/filters_dsl"
+require_relative "concerns/sortable_fields_dsl"
+require_relative "concerns/relationships_dsl"
+require_relative "concerns/meta_dsl"
+require_relative "concerns/model_class_helpers"
+
+module JSONAPI
+  class Resource
+    include Resources::AttributesDsl
+    include Resources::FiltersDsl
+    include Resources::SortableFieldsDsl
+    include Resources::RelationshipsDsl
+    include Resources::MetaDsl
+    include Resources::ModelClassHelpers
+
+    def initialize(record = nil, context = {})
+      @record = record
+      @context = context
+      @transformed_params = {}
+    end
+
+    attr_reader :record
+    alias resource record
+
+    def transformed_params
+      @transformed_params || {}
+    end
+  end
+end

data/lib/json_api/resources/resource_loader.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  class ResourceLoader
+    class MissingResourceClass < JSONAPI::Error
+      def initialize(resource_type)
+        super("Resource class for '#{resource_type}' not found. Define #{resource_type.singularize.classify}Resource < JSONAPI::Resource")
+      end
+    end
+
+    def self.find(resource_type)
+      resource_class_name = "#{resource_type.singularize.classify}Resource"
+      resource_class_name.constantize
+    rescue NameError
+      raise MissingResourceClass, resource_type
+    end
+
+    def self.find_for_model(model_class)
+      # Handle ActiveStorage::Blob specially
+      return ActiveStorageBlobResource if defined?(::ActiveStorage) && model_class == ::ActiveStorage::Blob
+
+      # For STI subclasses, try the specific subclass resource first
+      resource_type = model_class.name.underscore.pluralize
+      begin
+        find(resource_type)
+      rescue MissingResourceClass
+        # For STI subclasses, fall back to base class resource
+        raise unless model_class.respond_to?(:base_class) && model_class.base_class != model_class
+
+        base_resource_type = model_class.base_class.name.underscore.pluralize
+        find(base_resource_type)
+      end
+    end
+  end
+end

data/lib/json_api/routing.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Routing
+    def jsonapi_resources(resource, controller: nil, defaults: {}, sti: false, **options, &)
+      resource_name = resource.to_s
+      controller = detect_controller(resource_name) if controller.nil?
+
+      JSONAPI::ResourceLoader.find(resource_name)
+      defaults = defaults.merge(format: :jsonapi, resource_type: resource_name)
+      options[:only] = :index if sti
+
+      define_resource_routes(resource, controller, defaults, options, &)
+      define_sti_routes(resource, resource_name, defaults, sti)
+    end
+
+    private
+
+    def detect_controller(resource_name)
+      potential_controller_name = build_controller_name(resource_name)
+      potential_controller_name.constantize
+      nil
+    rescue NameError
+      "json_api/resources"
+    end
+
+    def build_controller_name(resource_name)
+      scoped_module = @scope[:module]
+      base_name = "#{resource_name.pluralize.camelize}Controller"
+      return base_name unless scoped_module
+
+      "#{scoped_module.to_s.camelize}::#{base_name}"
+    end
+
+    def define_resource_routes(resource, controller, defaults, options, &block)
+      resources(resource, controller:, defaults:, **options) do
+        define_relationship_routes
+        instance_eval(&block) if block
+      end
+    end
+
+    def define_relationship_routes
+      member do
+        get "relationships/:relationship_name", to: "json_api/relationships#show", as: :relationship
+        patch "relationships/:relationship_name", to: "json_api/relationships#update"
+        delete "relationships/:relationship_name", to: "json_api/relationships#destroy"
+      end
+    end
+
+    def define_sti_routes(resource, resource_name, defaults, sti)
+      return unless sti
+
+      if sti.is_a?(Array)
+        define_explicit_sti_routes(sti,
+                                   defaults,)
+      else
+        define_auto_sti_routes(resource, resource_name,
+                               defaults,)
+      end
+    end
+
+    def define_explicit_sti_routes(sti_resources, defaults)
+      sti_resources.each { |sub_resource_name| jsonapi_resources(sub_resource_name, defaults:) }
+    end
+
+    def define_auto_sti_routes(resource, resource_name, defaults)
+      resource_class = JSONAPI::ResourceLoader.find(resource_name)
+      model_class = resource_class.model_class
+      return unless model_class.respond_to?(:descendants)
+
+      model_class.descendants.each do |subclass|
+        sub_resource_name = subclass.name.underscore.pluralize.to_sym
+        next if sub_resource_name == resource.to_sym
+
+        jsonapi_resources(sub_resource_name, defaults:)
+      end
+    rescue NameError, JSONAPI::ResourceLoader::MissingResourceClass
+      nil
+    end
+  end
+end