jpie 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e1d1634f188bca4057e3550479af557bd00ba0d262c919ba221aa99997490e
-  data.tar.gz: 89db580da555f310a1b840daad204e2315fcb8b7828278b328271412d3bc321d
+  metadata.gz: 17c72f6974e3f671d772c5acec6ccd40541e06c36797603b4e0625b2235834f2
+  data.tar.gz: 6e13c925f6c6605278a0f3544165c8c3f7c9c6feaf3f97c54265c033f0a498e5
 SHA512:
-  metadata.gz: d2ced2be2db661db82e08200be2e5df033c072dcbf249565719336d3b08532d2cb01c4bbcec78cfb5e14fbbbadddb0c127292b70a9b970da3ecc20891bc8c8ab
-  data.tar.gz: 5d1ac4453eb74ba6a8ea04036f00065e26a54c2ff85a603525dd90106bd4f82a839ed3985083c5ff60d087b6bb1239c7a618a7a024e7e3fa1955c82d863aefa8
+  metadata.gz: 8a9d2f4a6505c5bd7e94798fd63c382150b4170f8cd610548439161bec82dc9bfc07807468e32cc50d980018e7bc5625724db509742a97281e32dfb069acbe47
+  data.tar.gz: 8e1eb70f4967a8d83c25583b234172a6fd9e9767ef1ea816a2fe5b6dc447f7bd11a68e67cab7e27851eee342395e616249d32033680cdc83050d896bd5726ec9

data/.cursorrules

@@ -22,6 +22,7 @@
 - Test both success and error cases
 - Use modern RSpec features and syntax
 - Don't reduce test coverage (line, file, branch, or other)
+- Only care about coverge reduction when running all specs
 
 # Git commit guidelines
 - Write clear, descriptive commit messages

data/examples/relationships.md

@@ -0,0 +1,114 @@
+# JSON:API Relationship Management
+
+This example demonstrates how to manage relationships using JPie's JSON:API compliant relationship endpoints.
+
+## Setup
+
+Define your resources with relationships:
+
+```ruby
+# app/resources/user_resource.rb
+class UserResource < JPie::Resource
+  model User
+  attributes :name, :email
+  has_many :posts
+end
+
+# app/resources/post_resource.rb  
+class PostResource < JPie::Resource
+  model Post
+  attributes :title, :content
+  has_one :author, resource: 'UserResource'
+end
+
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include JPie::Controller
+end
+```
+
+Configure routes:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  jpie_resources :users
+  jpie_resources :posts
+end
+```
+
+## Relationship Operations
+
+### Get Relationship Linkage
+
+```http
+GET /users/1/relationships/posts
+
+Response:
+{
+  "data": [
+    { "type": "posts", "id": "1" },
+    { "type": "posts", "id": "3" }
+  ]
+}
+```
+
+### Replace Relationship
+
+```http
+PATCH /users/1/relationships/posts
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "2" },
+    { "type": "posts", "id": "4" }
+  ]
+}
+```
+
+### Add to Relationship
+
+```http
+POST /users/1/relationships/posts
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "5" }
+  ]
+}
+```
+
+### Remove from Relationship
+
+```http
+DELETE /users/1/relationships/posts
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "2" }
+  ]
+}
+```
+
+### Get Related Resources
+
+```http
+GET /users/1/posts
+
+Response:
+{
+  "data": [
+    {
+      "type": "posts",
+      "id": "1",
+      "attributes": {
+        "title": "First Post",
+        "content": "Hello world!"
+      }
+    }
+  ]
+}
+```

data/lib/jpie/controller/related_actions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module RelatedActions
+      extend ActiveSupport::Concern
+
+      # GET /resources/:id/:relationship_name
+      # Returns the related resources themselves (not just linkage)
+      def related_show
+        validate_relationship_exists
+        validate_include_params
+        resource = find_resource
+        related_resources = get_related_resources(resource)
+        render_jsonapi(related_resources)
+      end
+
+      private
+
+      def validate_relationship_exists
+        relationship_name = params[:relationship_name]
+        return unless relationship_name # Skip validation if no relationship_name param
+
+        return if resource_class._relationships.key?(relationship_name.to_sym)
+
+        raise JPie::Errors::NotFoundError.new(
+          detail: "Relationship '#{relationship_name}' does not exist for #{resource_class.name}"
+        )
+      end
+
+      def find_resource
+        resource_class.scope(context).find(params[:id])
+      end
+
+      def relationship_name
+        @relationship_name ||= params[:relationship_name].to_sym
+      end
+
+      def get_related_resources(resource)
+        relationship_method = relationship_name
+        resource.send(relationship_method)
+      end
+    end
+  end
+end

data/lib/jpie/controller/relationship_actions.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require_relative 'relationship_validation'
+
+module JPie
+  module Controller
+    module RelationshipActions
+      extend ActiveSupport::Concern
+      include RelationshipValidation
+
+      # GET /resources/:id/relationships/:relationship_name
+      # Returns relationship linkage data
+      def relationship_show
+        validate_relationship_exists
+        resource = find_resource
+        relationship_data = get_relationship_data(resource)
+        render_relationship_data(relationship_data)
+      end
+
+      # PATCH /resources/:id/relationships/:relationship_name
+      # Updates relationship linkage (replaces all relationships)
+      def relationship_update
+        validate_relationship_exists
+        validate_relationship_update_request
+        resource = find_resource
+        relationship_data = parse_relationship_data
+        update_relationship_data(resource, relationship_data)
+        render_relationship_data(get_relationship_data(resource))
+      end
+
+      # POST /resources/:id/relationships/:relationship_name
+      # Adds to relationship linkage (for to-many relationships)
+      def relationship_create
+        validate_relationship_exists
+        validate_relationship_update_request
+        resource = find_resource
+
+        unless relationship_is_to_many?
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'POST is only supported for to-many relationships'
+          )
+        end
+
+        relationship_data = parse_relationship_data
+
+        unless relationship_data.is_a?(Array)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Adding to relationships requires an array of resource identifier objects'
+          )
+        end
+
+        add_to_relationship(resource, relationship_data)
+        render_relationship_data(get_relationship_data(resource))
+      end
+
+      # DELETE /resources/:id/relationships/:relationship_name
+      # Removes from relationship linkage (for to-many relationships)
+      def relationship_destroy
+        validate_relationship_exists
+        validate_relationship_update_request
+        resource = find_resource
+
+        unless relationship_is_to_many?
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'DELETE is only supported for to-many relationships'
+          )
+        end
+
+        relationship_data = parse_relationship_data
+
+        unless relationship_data.is_a?(Array)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Removing from relationships requires an array of resource identifier objects'
+          )
+        end
+
+        remove_from_relationship(resource, relationship_data)
+        render_relationship_data(get_relationship_data(resource))
+      end
+
+      private
+
+      def find_resource
+        resource_class.scope(context).find(params[:id])
+      end
+
+      def relationship_name
+        @relationship_name ||= params[:relationship_name].to_sym
+      end
+
+      def relationship_config
+        @relationship_config ||= resource_class._relationships[relationship_name]
+      end
+
+      def get_relationship_data(resource)
+        relationship_method = relationship_name
+        related_objects = resource.send(relationship_method)
+
+        if related_objects.respond_to?(:each)
+          # to-many relationship
+          related_objects.map { |obj| { type: infer_type(obj), id: obj.id.to_s } }
+        elsif related_objects
+          # to-one relationship
+          { type: infer_type(related_objects), id: related_objects.id.to_s }
+        end
+      end
+
+      def parse_relationship_data
+        body = request.body.read
+        request.body.rewind
+        parsed_body = JSON.parse(body)
+
+        unless parsed_body.key?('data')
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Request must include a "data" member'
+          )
+        end
+
+        parsed_body['data']
+      end
+
+      def update_relationship_data(resource, relationship_data)
+        if relationship_data.nil?
+          # Set relationship to null (only valid for to-one relationships)
+          unless relationship_is_to_many?
+            clear_relationship(resource)
+          else
+            raise JPie::Errors::BadRequestError.new(
+              detail: 'Cannot set a to-many relationship to null'
+            )
+          end
+        elsif relationship_data.is_a?(Array)
+          # to-many relationship - replace all
+          if relationship_is_to_many?
+            replace_to_many_relationship(resource, relationship_data)
+          else
+            raise JPie::Errors::BadRequestError.new(
+              detail: 'Invalid data type for to-one relationship'
+            )
+          end
+        elsif relationship_data.is_a?(Hash)
+          # to-one relationship - replace
+          unless relationship_is_to_many?
+            replace_to_one_relationship(resource, relationship_data)
+          else
+            raise JPie::Errors::BadRequestError.new(
+              detail: 'Invalid data type for to-many relationship'
+            )
+          end
+        else
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Relationship data must be null, an object, or an array of objects'
+          )
+        end
+      end
+
+      def add_to_relationship(resource, relationship_data)
+        begin
+          related_objects = find_related_objects(relationship_data)
+          association = association_for_resource(resource)
+
+          related_objects.each do |related_object|
+            association << related_object unless association.include?(related_object)
+          end
+
+          resource.save!
+        rescue ActiveRecord::AssociationTypeMismatch => e
+          raise JPie::Errors::NotFoundError.new(
+            detail: "Related resource not found: Invalid resource type for relationship"
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          raise JPie::Errors::ValidationError.new(
+            detail: "Failed to add relationships: #{e.message}"
+          )
+        end
+      end
+
+      def remove_from_relationship(resource, relationship_data)
+        begin
+          related_objects = find_related_objects(relationship_data)
+          association = association_for_resource(resource)
+
+          related_objects.each do |related_object|
+            association.delete(related_object)
+          end
+
+          resource.save!
+        rescue ActiveRecord::AssociationTypeMismatch => e
+          raise JPie::Errors::NotFoundError.new(
+            detail: "Related resource not found: Invalid resource type for relationship"
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          raise JPie::Errors::ValidationError.new(
+            detail: "Failed to remove relationships: #{e.message}"
+          )
+        end
+      end
+
+      def clear_relationship(resource)
+        association_name = association_name_for_relationship
+        resource.send("#{association_name}=", nil)
+        resource.save!
+      rescue ActiveRecord::RecordInvalid => e
+        raise JPie::Errors::ValidationError.new(
+          detail: "Failed to clear relationship: #{e.message}"
+        )
+      end
+
+      def replace_to_many_relationship(resource, relationship_data)
+        begin
+          related_objects = find_related_objects(relationship_data)
+          association_name = association_name_for_relationship
+          resource.send("#{association_name}=", related_objects)
+          resource.save!
+        rescue ActiveRecord::AssociationTypeMismatch => e
+          raise JPie::Errors::NotFoundError.new(
+            detail: "Related resource not found: Invalid resource type for relationship"
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          raise JPie::Errors::ValidationError.new(
+            detail: "Failed to replace relationships: #{e.message}"
+          )
+        end
+      end
+
+      def replace_to_one_relationship(resource, relationship_data)
+        begin
+          related_object = find_related_object(relationship_data)
+          association_name = association_name_for_relationship
+          resource.send("#{association_name}=", related_object)
+          resource.save!
+        rescue ActiveRecord::AssociationTypeMismatch => e
+          raise JPie::Errors::NotFoundError.new(
+            detail: "Related resource not found: Invalid resource type for relationship"
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          raise JPie::Errors::ValidationError.new(
+            detail: "Failed to replace relationship: #{e.message}"
+          )
+        end
+      end
+
+      def find_related_objects(relationship_data)
+        relationship_data.map { |data| find_related_object(data) }
+      end
+
+      def find_related_object(resource_identifier)
+        validate_resource_identifier(resource_identifier)
+
+        type = resource_identifier['type']
+        id = resource_identifier['id']
+
+        related_model_class = infer_model_class_from_type(type)
+        related_model_class.find(id)
+      rescue ActiveRecord::RecordNotFound
+        raise JPie::Errors::NotFoundError.new(
+          detail: "Related resource not found: #{type}##{id}"
+        )
+      end
+
+      def association_for_resource(resource)
+        association_name = association_name_for_relationship
+        resource.send(association_name)
+      end
+
+      def association_name_for_relationship
+        # For now, assume the relationship name matches the association name
+        # This could be made more sophisticated to handle custom association names
+        relationship_name
+      end
+
+      def infer_type(object)
+        # Convert model class name to JSON:API type
+        # e.g., "User" -> "users", "BlogPost" -> "blog-posts"
+        object.class.name.underscore.dasherize.pluralize
+      end
+
+      def infer_model_class_from_type(type)
+        # Convert JSON:API type back to model class
+        # e.g., "users" -> User, "blog-posts" -> BlogPost
+        class_name = type.singularize.underscore.camelize
+        class_name.constantize
+      end
+
+      def render_relationship_data(relationship_data)
+        response_data = { data: relationship_data }
+        render json: response_data, content_type: 'application/vnd.api+json'
+      end
+    end
+  end
+end

data/lib/jpie/controller/relationship_validation.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module RelationshipValidation
+      private
+
+      def validate_relationship_exists
+        relationship_name = params[:relationship_name]
+        return unless relationship_name # Skip validation if no relationship_name param
+
+        return if resource_class._relationships.key?(relationship_name.to_sym)
+
+        raise JPie::Errors::NotFoundError.new(
+          detail: "Relationship '#{relationship_name}' does not exist for #{resource_class.name}"
+        )
+      end
+
+      def validate_relationship_update_request
+        validate_content_type
+        validate_request_body
+        validate_relationship_type
+      end
+
+      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
+
+      def validate_request_body
+        body = request.body.read
+        request.body.rewind
+
+        raise JPie::Errors::BadRequestError.new(detail: 'Request body cannot be empty') if body.blank?
+
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise JPie::Errors::BadRequestError.new(detail: "Invalid JSON: #{e.message}")
+      end
+
+      def validate_resource_identifier(resource_identifier)
+        unless resource_identifier.is_a?(Hash) &&
+               resource_identifier.key?('type') &&
+               resource_identifier.key?('id')
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Resource identifier objects must have "type" and "id" members'
+          )
+        end
+
+        type = resource_identifier['type']
+        id = resource_identifier['id']
+
+        unless type.is_a?(String) && id.is_a?(String)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Resource identifier object members must be strings'
+          )
+        end
+
+        if type.empty? || id.empty?
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Resource identifier object members cannot be empty strings'
+          )
+        end
+      end
+
+      def validate_relationship_type
+        validate_relationship_exists
+        data = parse_relationship_data
+
+        if relationship_is_to_many?
+          validate_to_many_relationship_data(data)
+        else
+          validate_to_one_relationship_data(data)
+        end
+      end
+
+      def validate_to_many_relationship_data(data)
+        if data.nil?
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Cannot set a to-many relationship to null'
+          )
+        end
+
+        unless data.is_a?(Array)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'The value of data must be an array for to-many relationships'
+          )
+        end
+
+        data.each { |identifier| validate_resource_identifier(identifier) }
+      end
+
+      def validate_to_one_relationship_data(data)
+        unless data.nil? || data.is_a?(Hash)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'The value of data must be a single resource identifier object or null for to-one relationships'
+          )
+        end
+
+        validate_resource_identifier(data) if data
+      end
+
+      def relationship_is_to_many?
+        return false unless relationship_config
+
+        relationship_config[:type] == :has_many
+      end
+    end
+  end
+end

data/lib/jpie/controller.rb

@@ -6,6 +6,8 @@ require_relative 'controller/parameter_parsing'
 require_relative 'controller/rendering'
 require_relative 'controller/crud_actions'
 require_relative 'controller/json_api_validation'
+require_relative 'controller/relationship_actions'
+require_relative 'controller/related_actions'
 
 module JPie
   module Controller
@@ -16,5 +18,28 @@ module JPie
     include Rendering
     include CrudActions
     include JsonApiValidation
+    include RelationshipActions
+    include RelatedActions
+
+    # Relationship route actions
+    def show_relationship
+      relationship_show
+    end
+
+    def update_relationship
+      relationship_update
+    end
+
+    def create_relationship
+      relationship_create
+    end
+
+    def destroy_relationship
+      relationship_destroy
+    end
+
+    def show_related
+      related_show
+    end
   end
 end

data/lib/jpie/errors.rb

@@ -55,6 +55,12 @@ module JPie
       end
     end
 
+    class UnsupportedMediaTypeError < Error
+      def initialize(detail: 'Unsupported Media Type')
+        super(status: 415, title: 'Unsupported Media Type', detail:)
+      end
+    end
+
     class InternalServerError < Error
       def initialize(detail: 'Internal Server Error')
         super(status: 500, title: 'Internal Server Error', detail:)

data/lib/jpie/railtie.rb

@@ -29,6 +29,12 @@ module JPie
       end
     end
 
+    initializer 'jpie.routing' do
+      ActiveSupport.on_load(:action_dispatch) do
+        ActionDispatch::Routing::Mapper.include JPie::Routing
+      end
+    end
+
     generators do
       require 'jpie/generators/resource_generator'
     end

data/lib/jpie/resource/attributable.rb

@@ -59,13 +59,13 @@ module JPie
         def has_many(name, options = {})
           name = name.to_sym
           resource_class_name = options[:resource] || infer_resource_class_name(name)
-          relationship(name, { resource: resource_class_name }.merge(options))
+          relationship(name, { type: :has_many, resource: resource_class_name }.merge(options))
         end
 
         def has_one(name, options = {})
           name = name.to_sym
           resource_class_name = options[:resource] || infer_resource_class_name(name)
-          relationship(name, { resource: resource_class_name }.merge(options))
+          relationship(name, { type: :has_one, resource: resource_class_name }.merge(options))
         end
 
         private

data/lib/jpie/routing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module JPie
+  module Routing
+    # Add jpie_resources method to Rails routing DSL that creates JSON:API compliant routes
+    def jpie_resources(*resources)
+      options = resources.extract_options!
+      merged_options = build_merged_options(options)
+
+      # Create standard RESTful routes for the resource
+      resources(*resources, merged_options) do
+        yield if block_given?
+        add_jsonapi_relationship_routes(merged_options) if relationship_routes_allowed?(merged_options)
+      end
+    end
+
+    private
+
+    def build_merged_options(options)
+      default_options = {
+        defaults: { format: :json },
+        constraints: { format: :json }
+      }
+      default_options.merge(options)
+    end
+
+    def relationship_routes_allowed?(merged_options)
+      only_actions = merged_options[:only]
+      except_actions = merged_options[:except]
+
+      if only_actions
+        # If only specific actions are allowed, don't add relationship routes
+        # unless multiple member actions (show, update, destroy) are included
+        (only_actions & %i[show update destroy]).size >= 2
+      elsif except_actions
+        # If actions are excluded, only add if member actions aren't excluded
+        !except_actions.intersect?(%i[show update destroy])
+      else
+        true
+      end
+    end
+
+    def add_jsonapi_relationship_routes(_merged_options)
+      # These routes handle relationship management as per JSON:API spec
+      member do
+        # Routes for fetching and updating relationships
+        # Pattern: /resources/:id/relationships/:relationship_name
+        get 'relationships/*relationship_name', action: :show_relationship, as: :relationship
+        patch 'relationships/*relationship_name', action: :update_relationship
+        post 'relationships/*relationship_name', action: :create_relationship
+        delete 'relationships/*relationship_name', action: :destroy_relationship
+
+        # Routes for fetching related resources
+        # Pattern: /resources/:id/:relationship_name
+        get '*relationship_name', action: :show_related, as: :related
+      end
+    end
+  end
+end

data/lib/jpie/version.rb

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

data/lib/jpie.rb

@@ -11,6 +11,7 @@ module JPie
   autoload :Controller, 'jpie/controller'
   autoload :Configuration, 'jpie/configuration'
   autoload :Errors, 'jpie/errors'
+  autoload :Routing, 'jpie/routing'
 
   class << self
     def configuration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors:
 - Emil Kampp
@@ -179,6 +179,7 @@ files:
 - examples/basic_example.md
 - examples/including_related_resources.md
 - examples/pagination.md
+- examples/relationships.md
 - examples/resource_attribute_configuration.md
 - examples/resource_meta_configuration.md
 - examples/single_table_inheritance.md
@@ -192,6 +193,9 @@ files:
 - lib/jpie/controller/error_handling/handlers.rb
 - lib/jpie/controller/json_api_validation.rb
 - lib/jpie/controller/parameter_parsing.rb
+- lib/jpie/controller/related_actions.rb
+- lib/jpie/controller/relationship_actions.rb
+- lib/jpie/controller/relationship_validation.rb
 - lib/jpie/controller/rendering.rb
 - lib/jpie/deserializer.rb
 - lib/jpie/errors.rb
@@ -202,6 +206,7 @@ files:
 - lib/jpie/resource/attributable.rb
 - lib/jpie/resource/inferrable.rb
 - lib/jpie/resource/sortable.rb
+- lib/jpie/routing.rb
 - lib/jpie/serializer.rb
 - lib/jpie/version.rb
 homepage: https://github.com/emk-klaay/jpie