jpie 2.0.2 → 2.1.0

data/lib/json_api/controllers/concerns/resource_actions/sideposting.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json_api/sideposting/order"
+require_relative "sideposting_primary_first"
+
+module JSONAPI
+  module ResourceActions
+    module Sideposting
+      extend ActiveSupport::Concern
+      include SidepostingPrimaryFirst
+
+      class_methods do
+        def sidepost_order(value)
+          order = value.to_sym
+          unless JSONAPI::Sideposting::Order::VALID_ORDERS.include?(order)
+            raise ArgumentError, "sidepost_order must be one of #{JSONAPI::Sideposting::Order::VALID_ORDERS.join(", ")}"
+          end
+
+          @sidepost_order = order
+        end
+
+        def sidepost_order_value
+          @sidepost_order || JSONAPI::Sideposting::Order::PRIMARY_FIRST
+        end
+
+        def included_first?
+          sidepost_order_value == JSONAPI::Sideposting::Order::INCLUDED_FIRST
+        end
+      end
+
+      def sidepost_request?
+        params[:included].present?
+      end
+
+      def create_with_sidepost
+        if self.class.included_first?
+          create_with_sidepost_included_first
+        else
+          create_with_sidepost_primary_first
+        end
+      end
+
+      def create_with_sidepost_included_first
+        ActiveRecord::Base.transaction do
+          processor = JSONAPI::Sideposting::Processor.new(included: params[:included], controller: self)
+          processor.create_all!
+          resolved_data = processor.lid_resolver.resolve(raw_jsonapi_data)
+          resource = build_resource_from_resolved_data(resolved_data)
+          authorize_resource_action!(resource, action: :create)
+          attach_active_storage_files(resource, @create_attachments, resource_class: determine_sti_resource_class)
+          save_created_with_sidepost(resource, processor.created_records)
+        end
+      end
+
+      def extract_lid_relationships!(data)
+        extracted = {}
+        rels = data[:relationships] || {}
+        rels.each do |key, val|
+          next unless val.is_a?(Hash)
+
+          d = val[:data] || val["data"]
+          next unless contains_lid?(d)
+
+          extracted[key] = val
+        end
+        extracted.each_key { |k| rels.delete(k) }
+        extracted
+      end
+
+      def contains_lid?(rel_data)
+        return false if rel_data.blank?
+
+        if rel_data.is_a?(Array)
+          rel_data.any? { |item| contains_lid?(item) }
+        else
+          (rel_data[:lid] || rel_data["lid"]).to_s.present?
+        end
+      end
+
+      def apply_resolved_relationships!(resource, resolved_relationships)
+        payload = { relationships: resolved_relationships }
+        params_hash = JSONAPI::Deserializer.new(
+          payload,
+          model_class: resource.class,
+          action: :update,
+        ).to_model_attributes
+        resource.update!(params_hash)
+      end
+
+      def build_resource_from_resolved_data(resolved_data)
+        sti_class = determine_sti_class
+        params_hash, @create_attachments = prepare_create_params_from_data(sti_class, resolved_data)
+        sti_class.new(params_hash)
+      end
+    end
+  end
+end

data/lib/json_api/controllers/concerns/resource_actions/sideposting_primary_first.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module ResourceActions
+    module SidepostingPrimaryFirst
+      extend ActiveSupport::Concern
+
+      def create_with_sidepost_primary_first
+        ActiveRecord::Base.transaction do
+          data = raw_jsonapi_data.dup
+          lid_relationships = extract_lid_relationships!(data)
+          resource, lid_resolver = create_primary_and_lid_resolver(data)
+          processor = run_sidepost_processor(lid_resolver)
+          apply_lid_relationships_if_any(resource, lid_relationships, lid_resolver)
+          render_created_with_sidepost(resource, processor)
+        end
+      end
+
+      def create_primary_and_lid_resolver(data)
+        resource = build_resource_from_resolved_data(data)
+        authorize_resource_action!(resource, action: :create)
+        attach_active_storage_files(resource, @create_attachments, resource_class: determine_sti_resource_class)
+        raise JSONAPI::Sideposting::PrimaryValidationError, resource unless resource.save
+
+        [resource, build_lid_resolver_with_primary(data, resource)]
+      end
+
+      def build_lid_resolver_with_primary(data, resource)
+        lid_resolver = JSONAPI::Sideposting::LidResolver.new
+        primary_lid = (data[:lid] || data["lid"]).to_s.presence
+        if primary_lid
+          type_name = RelationshipHelpers.resource_type_name(determine_sti_resource_class)
+          lid_resolver.add(primary_lid, type: type_name, id: resource.id)
+        end
+        lid_resolver
+      end
+
+      def run_sidepost_processor(lid_resolver)
+        processor = JSONAPI::Sideposting::Processor.new(
+          included: params[:included],
+          controller: self,
+          lid_resolver: lid_resolver,
+        )
+        processor.create_all!
+        processor
+      end
+
+      def apply_lid_relationships_if_any(resource, lid_relationships, lid_resolver)
+        return if lid_relationships.blank?
+
+        resolved = lid_resolver.resolve(lid_relationships)
+        apply_resolved_relationships!(resource, resolved)
+      end
+
+      def render_created_with_sidepost(resource, processor)
+        emit_resource_event(:created, resource)
+        render json: serialize_resource_with_sidepost(resource, processor.created_records),
+               status: :created,
+               location: resource_url(resource)
+      end
+    end
+  end
+end

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

@@ -9,6 +9,7 @@ require_relative "resource_actions/pagination"
 require_relative "resource_actions/type_validation"
 require_relative "resource_actions/crud_helpers"
 require_relative "resource_actions/resource_loading"
+require_relative "resource_actions/sideposting"
 
 module JSONAPI
   module ResourceActions
@@ -22,6 +23,7 @@ module JSONAPI
     include TypeValidation
     include CrudHelpers
     include ResourceLoading
+    include Sideposting
 
     included do
       before_action :load_jsonapi_resource
@@ -47,16 +49,28 @@ module JSONAPI
     end
 
     def create
-      resource = build_resource_for_create
-      authorize_resource_action!(resource, action: :create)
-      attach_active_storage_files(resource, @create_attachments, resource_class: determine_sti_resource_class)
-      save_created(resource)
+      perform_create
     rescue ArgumentError => e
       render_create_error(e)
+    rescue JSONAPI::Sideposting::ValidationError => e
+      render_sidepost_validation_errors(e)
+    rescue JSONAPI::Sideposting::PrimaryValidationError => e
+      render_validation_errors(e.record)
     rescue JSONAPI::Errors::ParameterNotAllowed, ActiveSupport::MessageVerifier::InvalidSignature => e
       handle_create_exception(e)
     end
 
+    def perform_create
+      if sidepost_request?
+        create_with_sidepost
+      else
+        resource = build_resource_for_create
+        authorize_resource_action!(resource, action: :create)
+        attach_active_storage_files(resource, @create_attachments, resource_class: determine_sti_resource_class)
+        save_created(resource)
+      end
+    end
+
     def build_resource_for_create
       sti_class = determine_sti_class
       params_hash, @create_attachments = prepare_create_params(sti_class)

data/lib/json_api/railtie.rb

@@ -132,6 +132,8 @@ module JSONAPI
         load "json_api/controllers/base_controller.rb"
         JSONAPI.send(:remove_const, :RelationshipsController)
         load "json_api/controllers/relationships_controller.rb"
+        JSONAPI.send(:remove_const, :ResourcesController)
+        load "json_api/controllers/resources_controller.rb"
       end
 
       def include_jsonapi_concerns(base_controller_class)

data/lib/json_api/resources/resource.rb

@@ -23,6 +23,10 @@ module JSONAPI
         super
         subclass.type_format = type_format
       end
+
+      def sidepost_create(*)
+        nil
+      end
     end
 
     def initialize(record = nil, context = {})

data/lib/json_api/resources/resource_loader.rb

@@ -16,25 +16,7 @@ module JSONAPI
       end
     end
 
-    # Thread-safe caches for resource class lookups
-    # Using simple Hash with ||= is safe enough - worst case is duplicate computation
-    # which is acceptable since the result is always the same Class object
-    @find_cache = {}
-    @model_cache = {}
-
-    class << self
-      def clear_cache!
-        @find_cache = {}
-        @model_cache = {}
-      end
-    end
-
     def self.find(resource_type, namespace: nil)
-      cache_key = "#{namespace}::#{resource_type}"
-      @find_cache[cache_key] ||= find_uncached(resource_type, namespace:)
-    end
-
-    def self.find_uncached(resource_type, namespace: nil)
       return find_namespaced(resource_type, namespace) if namespace.present?
 
       find_flat(resource_type, namespace)
@@ -66,8 +48,7 @@ module JSONAPI
     def self.find_for_model(model_class, namespace: nil)
       return ActiveStorageBlobResource if active_storage_blob?(model_class)
 
-      cache_key = "#{namespace}::#{model_class.name}"
-      @model_cache[cache_key] ||= find_resource_for_model(model_class, namespace)
+      find_resource_for_model(model_class, namespace)
     end
 
     def self.find_resource_for_model(model_class, namespace)
@@ -76,7 +57,15 @@ module JSONAPI
 
       find(resource_type, namespace: effective_namespace)
     rescue MissingResourceClass
-      find_base_class_resource(model_class, effective_namespace)
+      try_flat_full_name_resource(model_class) || find_base_class_resource(model_class, effective_namespace)
+    end
+
+    def self.try_flat_full_name_resource(model_class)
+      return nil unless model_class.name.include?("::")
+
+      "#{model_class.name.gsub("::", "")}Resource".constantize
+    rescue NameError
+      nil
     end
 
     def self.find_base_class_resource(model_class, effective_namespace)

data/lib/json_api/routing.rb

@@ -85,9 +85,9 @@ module JSONAPI
         next if sub_resource_name == resource.to_sym
 
         jsonapi_resources(sub_resource_name, defaults:)
+      rescue NameError, JSONAPI::ResourceLoader::MissingResourceClass
+        next
       end
-    rescue NameError, JSONAPI::ResourceLoader::MissingResourceClass
-      nil
     end
   end
 end

data/lib/json_api/serialization/concerns/deserialization_helpers.rb

@@ -52,6 +52,11 @@ module JSONAPI
 
       def extract_id(resource_identifier)
         id = RelationshipHelpers.extract_id_from_identifier(resource_identifier)
+        if id.nil? && lid?(resource_identifier)
+          raise ArgumentError,
+                "lid references must be resolved before deserialization " \
+                "(include related resources in top-level included)"
+        end
         raise ArgumentError, "Missing id in relationship data" unless id
 
         id
@@ -75,11 +80,15 @@ module JSONAPI
       def valid_resource_identifier?(identifier)
         return false unless identifier.is_a?(Hash)
 
-        has_id?(identifier) && has_type?(identifier)
+        has_type?(identifier) && (has_id?(identifier) || lid?(identifier))
       end
 
       def has_id?(identifier)
-        identifier[:id]
+        identifier[:id].present?
+      end
+
+      def lid?(identifier)
+        identifier[:lid].to_s.present?
       end
 
       def has_type?(identifier)

data/lib/json_api/serialization/concerns/relationship_processing.rb

@@ -47,7 +47,7 @@ module JSONAPI
       def validate_relationship_data_format!(data, association_name)
         return if valid_relationship_data?(data)
 
-        raise ArgumentError, "Invalid relationship data for #{association_name}: missing type or id"
+        raise ArgumentError, "Invalid relationship data for #{association_name}: missing type or (id or lid)"
       end
 
       def process_relationship_data(attrs, association_name, param_name, data)

data/lib/json_api/serialization/concerns/relationships_deserialization.rb

@@ -35,10 +35,22 @@ module JSONAPI
         end
       end
 
+      def extract_identifiers_from_data(data)
+        if data.is_a?(Array)
+          data.map { |r| r.to_h.symbolize_keys }
+        else
+          [data.to_h.symbolize_keys]
+        end
+      end
+
       def extract_id_from_identifier(identifier)
         RelationshipHelpers.extract_id_from_identifier(identifier)
       end
 
+      def extract_lid_from_identifier(identifier)
+        RelationshipHelpers.extract_lid_from_identifier(identifier)
+      end
+
       def relationship_id(relationship_name)
         relationship_ids(relationship_name).first
       end

data/lib/json_api/sideposting/lid_resolver.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Sideposting
+    class LidResolver
+      def initialize
+        @map = {}
+      end
+
+      def add(lid, type:, id:)
+        raise ArgumentError, "lid is required" if lid.blank?
+        raise ArgumentError, "type is required" if type.blank?
+        raise ArgumentError, "id is required" if id.blank?
+
+        @map[lid.to_s] = { type: type.to_s, id: id.to_s }
+        self
+      end
+
+      def resolve(data)
+        return data if data.nil?
+
+        case data
+        when Hash
+          resolve_hash(data)
+        when Array
+          data.map { |item| resolve(item) }
+        else
+          data
+        end
+      end
+
+      def [](lid)
+        @map[lid.to_s]
+      end
+
+      private
+
+      def resolve_hash(hash)
+        result = {}
+        hash.each do |key, value|
+          result[key] = if resource_identifier_with_lid?(value)
+                          resolve_identifier(value)
+                        else
+                          resolve(value)
+                        end
+        end
+        result
+      end
+
+      def resource_identifier_with_lid?(value)
+        return false unless value.is_a?(Hash)
+
+        value = value.symbolize_keys if value.respond_to?(:symbolize_keys)
+        type = value[:type] || value["type"]
+        lid = value[:lid] || value["lid"]
+        type.present? && lid.to_s.present?
+      end
+
+      def resolve_identifier(identifier)
+        identifier = identifier.symbolize_keys if identifier.respond_to?(:symbolize_keys)
+        lid = (identifier[:lid] || identifier["lid"]).to_s
+        resolved = @map[lid]
+        unless resolved
+          raise ArgumentError,
+                "Unknown lid '#{lid}' (ensure the resource is in the top-level included array)"
+        end
+
+        { type: resolved[:type], id: resolved[:id] }
+      end
+    end
+  end
+end

data/lib/json_api/sideposting/order.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Sideposting
+    module Order
+      PRIMARY_FIRST = :primary_first
+      INCLUDED_FIRST = :included_first
+      VALID_ORDERS = [PRIMARY_FIRST, INCLUDED_FIRST].freeze
+    end
+  end
+end

data/lib/json_api/sideposting/processor.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json_api/sideposting/lid_resolver"
+
+module JSONAPI
+  module Sideposting
+    class ValidationError < JSONAPI::Error
+      attr_reader :record, :included_index
+
+      def initialize(record:, included_index:)
+        @record = record
+        @included_index = included_index
+        super("Validation failed for included resource at index #{included_index}")
+      end
+    end
+
+    class PrimaryValidationError < JSONAPI::Error
+      attr_reader :record
+
+      def initialize(record)
+        @record = record
+        super("Validation failed for primary resource")
+      end
+    end
+
+    class Processor
+      def initialize(included:, controller:, lid_resolver: nil)
+        raise ArgumentError, "included is required" if included.blank?
+        raise ArgumentError, "controller is required" if controller.nil?
+
+        @included = Array(included).map { |item| symbolize_item(item) }
+        @controller = controller
+        @lid_resolver = lid_resolver || LidResolver.new
+        @created_records = []
+      end
+
+      def create_all!
+        @included.each_with_index do |item, index|
+          record = create_one(item, index)
+          @created_records << record
+          lid = item[:lid].to_s.presence
+          next unless lid
+
+          resource_class = resource_class_for(item[:type])
+          type_name = RelationshipHelpers.resource_type_name(resource_class)
+          @lid_resolver.add(lid, type: type_name, id: record.id)
+        end
+        @created_records
+      end
+
+      attr_reader :lid_resolver, :created_records
+
+      private
+
+      def symbolize_item(item)
+        item = item.to_unsafe_h if item.respond_to?(:to_unsafe_h)
+        ParamHelpers.deep_symbolize_params(item.to_h)
+      end
+
+      def create_one(item, included_index)
+        type = item[:type].to_s.presence
+        raise ArgumentError, "Included resource is missing type" unless type
+
+        resource_class = resource_class_for(type)
+        model_class = resource_class.model_class
+        params_hash, attachments = prepare_create_params_for_item(item, model_class, resource_class)
+
+        custom = try_sidepost_create(resource_class, params_hash, included_index)
+        return custom if custom
+
+        create_record_default(model_class, params_hash, attachments, resource_class, included_index)
+      end
+
+      def try_sidepost_create(resource_class, params_hash, included_index)
+        custom = resource_class.sidepost_create(params: params_hash, controller: @controller)
+        return nil unless custom
+
+        raise ValidationError.new(record: custom, included_index: included_index) unless custom.persisted?
+
+        custom
+      end
+
+      def create_record_default(model_class, params_hash, attachments, resource_class, included_index)
+        record = model_class.new(params_hash)
+        @controller.send(:authorize_resource_action!, record, action: :create)
+        @controller.send(:attach_active_storage_files, record, attachments, resource_class: resource_class)
+        raise ValidationError.new(record: record, included_index: included_index) unless record.save
+
+        record
+      end
+
+      def resource_class_for(type)
+        namespace = @controller.instance_variable_get(:@jsonapi_namespace)
+        ResourceLoader.find(type, namespace: namespace)
+      end
+
+      def prepare_create_params_for_item(item, model_class, _resource_class)
+        hash = Deserializer.new(item, model_class: model_class, action: :create).to_model_attributes
+        attachments = @controller.send(:extract_active_storage_params_from_hash, hash, model_class)
+        attachments.each_key { |k| hash.delete(k.to_s) }
+        hash.delete("type")
+        hash.delete(:type)
+        apply_sti_type(model_class, hash) if sti_base_with_type_column?(model_class)
+        [hash, attachments]
+      end
+
+      def apply_sti_type(klass, params)
+        return unless sti_base_with_type_column?(klass)
+
+        params["type"] = klass.name
+      end
+
+      def sti_base_with_type_column?(klass)
+        klass.respond_to?(:base_class) && klass.base_class == klass && klass.column_names.include?("type")
+      end
+    end
+  end
+end

data/lib/json_api/support/relationship_helpers.rb

@@ -44,6 +44,10 @@ module JSONAPI
       ResourceIdentifier.extract_id(identifier)
     end
 
+    def extract_lid_from_identifier(identifier)
+      ResourceIdentifier.extract_lid(identifier)
+    end
+
     def extract_type_from_identifier(identifier)
       ResourceIdentifier.extract_type(identifier)
     end

data/lib/json_api/support/resource_identifier.rb

@@ -17,6 +17,10 @@ module JSONAPI
       identifier[:id].to_s.presence
     end
 
+    def extract_lid(identifier)
+      identifier[:lid].to_s.presence
+    end
+
     def extract_type(identifier)
       identifier[:type]
     end

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "2.0.2"
+  VERSION = "2.1.0"
 end

data/lib/json_api.rb

@@ -11,7 +11,7 @@ end
 require "json_api/errors/parameter_not_allowed"
 
 module JSONAPI
-  # Rebuild BaseController and RelationshipsController to reflect the current
+  # Rebuild BaseController, RelationshipsController, and ResourcesController to reflect the current
   # base_controller_class configuration. Safe to call repeatedly.
   def self.rebuild_base_controllers!
     remove_const(:BaseController) if const_defined?(:BaseController)
@@ -19,6 +19,9 @@ module JSONAPI
 
     remove_const(:RelationshipsController) if const_defined?(:RelationshipsController)
     load "json_api/controllers/relationships_controller.rb"
+
+    remove_const(:ResourcesController) if const_defined?(:ResourcesController)
+    load "json_api/controllers/resources_controller.rb"
   end
 end
 
@@ -48,6 +51,8 @@ require "json_api/support/responders"
 require "json_api/support/instrumentation"
 require "json_api/serialization/serializer"
 require "json_api/serialization/deserializer"
+require "json_api/sideposting/lid_resolver"
+require "json_api/sideposting/processor"
 require "json_api/controllers/concerns/controller_helpers"
 require "json_api/controllers/concerns/resource_actions"
 require "json_api/controllers/base_controller"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Emil Kampp
@@ -85,6 +85,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/skills/nasa-power-of-ten-ruby/SKILL.md"
+- ".claude/skills/root-cause-analysis/SKILL.md"
+- ".claude/skills/skills-and-subagents/SKILL.md"
+- ".cursor/agents/bias-reviewer.md"
+- ".cursor/agents/lint-format.md"
+- ".cursor/agents/nasa-power-of-ten-reviewer.md"
+- ".cursor/agents/systematic-debugging.md"
 - ".cursor/rules/release.mdc"
 - ".gitignore"
 - ".rspec"
@@ -127,6 +134,8 @@ files:
 - lib/json_api/controllers/concerns/resource_actions/pagination.rb
 - lib/json_api/controllers/concerns/resource_actions/resource_loading.rb
 - lib/json_api/controllers/concerns/resource_actions/serialization.rb
+- lib/json_api/controllers/concerns/resource_actions/sideposting.rb
+- lib/json_api/controllers/concerns/resource_actions/sideposting_primary_first.rb
 - lib/json_api/controllers/concerns/resource_actions/type_validation.rb
 - lib/json_api/controllers/relationships_controller.rb
 - lib/json_api/controllers/resources_controller.rb
@@ -158,6 +167,9 @@ files:
 - lib/json_api/serialization/deserializer.rb
 - lib/json_api/serialization/include_path_helpers.rb
 - lib/json_api/serialization/serializer.rb
+- lib/json_api/sideposting/lid_resolver.rb
+- lib/json_api/sideposting/order.rb
+- lib/json_api/sideposting/processor.rb
 - lib/json_api/support/active_storage_support.rb
 - lib/json_api/support/collection_query.rb
 - lib/json_api/support/concerns/condition_building.rb