jpie 0.3.0

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+desc 'Run Brakeman security scanner'
+task brakeman: :environment do
+  require 'brakeman'
+  Brakeman.run app_path: '.', print_report: true, exit_on_warn: true
+end
+
+desc 'Run all checks (RSpec, RuboCop, Brakeman)'
+task check: %i[spec rubocop brakeman]
+
+task default: :check

data/jpie.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'lib/jpie/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'jpie'
+  spec.version = JPie::VERSION
+  spec.authors = ['Emil Kampp']
+  spec.email = ['emil@example.com']
+
+  spec.summary = 'A resource-focused Rails library for developing JSON:API compliant servers'
+  spec.description = 'JPie provides a framework for developing JSON:API compliant servers with Rails 8+. ' \
+                     'It focuses on clean architecture with strong separation of concerns.'
+  spec.homepage = 'https://github.com/emilkampp/jpie'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.4.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = "#{spec.homepage}.git"
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'activesupport', '~> 8.0', '>= 8.0.0'
+  spec.add_dependency 'rails', '~> 8.0', '>= 8.0.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'brakeman', '~> 6.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rspec-rails', '~> 7.0'
+  spec.add_development_dependency 'rubocop', '~> 1.50'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.16'
+  spec.add_development_dependency 'rubocop-rails', '~> 2.18'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.20'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/jpie/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JPie
+  class Configuration
+    attr_accessor :default_page_size, :maximum_page_size
+
+    def initialize
+      @default_page_size = 20
+      @maximum_page_size = 100
+    end
+  end
+end

data/lib/jpie/controller/crud_actions.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module CrudActions
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def jsonapi_resource(resource_class)
+          setup_jsonapi_resource(resource_class)
+        end
+
+        # More concise alias for modern Rails style
+        alias_method :resource, :jsonapi_resource
+
+        private
+
+        def setup_jsonapi_resource(resource_class)
+          define_method :resource_class do
+            resource_class
+          end
+
+          # Define automatic CRUD methods
+          define_automatic_crud_methods(resource_class)
+        end
+
+        def define_automatic_crud_methods(resource_class)
+          define_index_method(resource_class)
+          define_show_method(resource_class)
+          define_create_method(resource_class)
+          define_update_method(resource_class)
+          define_destroy_method(resource_class)
+        end
+
+        def define_index_method(resource_class)
+          define_method :index do
+            resources = resource_class.scope(context)
+            sort_fields = parse_sort_params
+            resources = resource_class.sort(resources, sort_fields) if sort_fields.any?
+            render_jsonapi(resources)
+          end
+        end
+
+        def define_show_method(resource_class)
+          define_method :show do
+            resource = resource_class.scope(context).find(params[:id])
+            render_jsonapi(resource)
+          end
+        end
+
+        def define_create_method(resource_class)
+          define_method :create do
+            attributes = deserialize_params
+            resource = resource_class.model.create!(attributes)
+            render_jsonapi(resource, status: :created)
+          end
+        end
+
+        def define_update_method(resource_class)
+          define_method :update do
+            resource = resource_class.scope(context).find(params[:id])
+            attributes = deserialize_params
+            resource.update!(attributes)
+            render_jsonapi(resource)
+          end
+        end
+
+        def define_destroy_method(resource_class)
+          define_method :destroy do
+            resource = resource_class.scope(context).find(params[:id])
+            resource.destroy!
+            head :no_content
+          end
+        end
+      end
+
+      # These methods can still be called manually or used to override defaults
+      def index
+        resources = resource_class.scope(context)
+        sort_fields = parse_sort_params
+        resources = resource_class.sort(resources, sort_fields) if sort_fields.any?
+        render_jsonapi(resources)
+      end
+
+      def show
+        resource = resource_class.scope(context).find(params[:id])
+        render_jsonapi(resource)
+      end
+
+      def create
+        attributes = deserialize_params
+        resource = model_class.create!(attributes)
+        render_jsonapi(resource, status: :created)
+      end
+
+      def update
+        resource = resource_class.scope(context).find(params[:id])
+        attributes = deserialize_params
+        resource.update!(attributes)
+        render_jsonapi(resource)
+      end
+
+      def destroy
+        resource = resource_class.scope(context).find(params[:id])
+        resource.destroy!
+        head :no_content
+      end
+    end
+  end
+end

data/lib/jpie/controller/error_handling.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module ErrorHandling
+      extend ActiveSupport::Concern
+
+      included do
+        rescue_from JPie::Errors::Error, with: :render_jsonapi_error
+
+        if defined?(ActiveRecord)
+          rescue_from ActiveRecord::RecordNotFound, with: :render_not_found_error
+          rescue_from ActiveRecord::RecordInvalid, with: :render_validation_error
+        end
+      end
+
+      private
+
+      def render_jsonapi_error(error)
+        render json: { errors: [error.to_hash] },
+               status: error.status,
+               content_type: 'application/vnd.api+json'
+      end
+
+      def render_not_found_error(error)
+        json_error = JPie::Errors::NotFoundError.new(detail: error.message)
+        render_jsonapi_error(json_error)
+      end
+
+      def render_validation_error(error)
+        errors = error.record.errors.full_messages.map do
+          JPie::Errors::ValidationError.new(detail: it).to_hash
+        end
+
+        render json: { errors: },
+               status: :unprocessable_entity,
+               content_type: 'application/vnd.api+json'
+      end
+    end
+  end
+end

data/lib/jpie/controller/parameter_parsing.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module ParameterParsing
+      def parse_include_params
+        params[:include]&.split(',')&.map(&:strip) || []
+      end
+
+      def parse_sort_params
+        params[:sort]&.split(',')&.map(&:strip) || []
+      end
+
+      def deserialize_params
+        deserializer.deserialize(request.body.read, context)
+      rescue JSON::ParserError => e
+        raise JPie::Errors::BadRequestError.new(detail: "Invalid JSON: #{e.message}")
+      end
+
+      def context
+        @context ||= build_context
+      end
+
+      private
+
+      def build_context
+        {
+          current_user: try(:current_user),
+          controller: self,
+          action: action_name
+        }
+      end
+    end
+  end
+end

data/lib/jpie/controller/rendering.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module Rendering
+      def resource_class
+        # Default implementation that infers from controller name
+        @resource_class ||= infer_resource_class
+      end
+
+      def serializer
+        @serializer ||= JPie::Serializer.new(resource_class)
+      end
+
+      def deserializer
+        @deserializer ||= JPie::Deserializer.new(resource_class)
+      end
+
+      protected
+
+      def model_class
+        resource_class.model
+      end
+
+      # More concise method names following Rails conventions
+      def render_jsonapi(resource_or_resources, status: :ok, meta: nil)
+        includes = parse_include_params
+        json_data = serializer.serialize(resource_or_resources, context, includes: includes)
+        json_data[:meta] = meta if meta
+
+        render json: json_data, status:, content_type: 'application/vnd.api+json'
+      end
+
+      # Keep original methods for backward compatibility
+      alias render_jsonapi_resource render_jsonapi
+      alias render_jsonapi_resources render_jsonapi
+
+      private
+
+      def infer_resource_class
+        # Convert controller name to resource class name
+        # e.g., "UsersController" -> "UserResource"
+        # e.g., "Api::V1::UsersController" -> "UserResource"
+        controller_name = self.class.name
+        return nil unless controller_name&.end_with?('Controller')
+
+        # Remove "Controller" suffix and any namespace
+        base_name = controller_name.split('::').last.chomp('Controller')
+
+        # Convert plural controller name to singular resource name
+        # e.g., "Users" -> "User"
+        singular_name = base_name.singularize
+        resource_class_name = "#{singular_name}Resource"
+
+        # Try to constantize the resource class
+        resource_class_name.constantize
+      end
+    end
+  end
+end

data/lib/jpie/controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require_relative 'controller/error_handling'
+require_relative 'controller/parameter_parsing'
+require_relative 'controller/rendering'
+require_relative 'controller/crud_actions'
+
+module JPie
+  module Controller
+    extend ActiveSupport::Concern
+
+    include ErrorHandling
+    include ParameterParsing
+    include Rendering
+    include CrudActions
+  end
+end

data/lib/jpie/deserializer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module JPie
+  class Deserializer
+    attr_reader :resource_class, :options
+
+    def initialize(resource_class, options = {})
+      @resource_class = resource_class
+      @options = options
+    end
+
+    def deserialize(json_data, context = {})
+      data = json_data.is_a?(String) ? JSON.parse(json_data) : json_data
+
+      validate_json_api_structure!(data)
+
+      if data['data'].is_a?(Array)
+        deserialize_collection(data['data'], context)
+      else
+        deserialize_single(data['data'], context)
+      end
+    rescue JSON::ParserError => e
+      raise Errors::BadRequestError.new(detail: "Invalid JSON: #{e.message}")
+    end
+
+    private
+
+    def deserialize_single(resource_data, context)
+      validate_resource_data!(resource_data)
+      extract_attributes(resource_data, context)
+    end
+
+    def deserialize_collection(resources_data, context)
+      resources_data.map { deserialize_single(it, context) }
+    end
+
+    def extract_attributes(resource_data, _context)
+      attributes = resource_data['attributes'] || {}
+      type = resource_data['type']
+      id = resource_data['id']
+
+      validate_type!(type) if type
+
+      model_attributes = transform_attribute_keys(attributes)
+      filtered_attributes = filter_allowed_attributes(model_attributes)
+      result = deserialize_attribute_values(filtered_attributes)
+
+      add_id_if_present(result, id)
+    end
+
+    def transform_attribute_keys(attributes)
+      attributes.transform_keys { it.to_s.underscore }
+    end
+
+    def filter_allowed_attributes(model_attributes)
+      allowed_attributes = resource_class._attributes.map(&:to_s)
+      model_attributes.slice(*allowed_attributes)
+    end
+
+    def deserialize_attribute_values(attributes)
+      attributes.transform_values { deserialize_value(it) }
+    end
+
+    def add_id_if_present(result, id)
+      result['id'] = id if id
+      result.with_indifferent_access
+    end
+
+    def deserialize_value(value)
+      case value
+      when String
+        # Only try to parse as datetime if it looks like an ISO8601 string
+        if value.match?(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)
+          begin
+            Time.parse(value)
+          rescue ArgumentError, TypeError
+            value
+          end
+        else
+          value
+        end
+      else
+        value
+      end
+    end
+
+    def validate_json_api_structure!(data)
+      return if data.is_a?(Hash) && data.key?('data')
+
+      raise Errors::BadRequestError.new(detail: 'Invalid JSON:API structure. Missing "data" key.')
+    end
+
+    def validate_resource_data!(resource_data)
+      raise Errors::BadRequestError.new(detail: 'Invalid resource data structure.') unless resource_data.is_a?(Hash)
+
+      return if resource_data.key?('type')
+
+      raise Errors::BadRequestError.new(detail: 'Resource data must include "type".')
+    end
+
+    def validate_type!(type)
+      expected_type = resource_class.type
+      return if type == expected_type
+
+      raise Errors::BadRequestError.new(
+        detail: "Expected type '#{expected_type}', got '#{type}'"
+      )
+    end
+  end
+end

data/lib/jpie/errors.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module JPie
+  module Errors
+    class Error < StandardError
+      attr_reader :status, :code, :title, :detail, :source
+
+      def initialize(status:, code: nil, title: nil, detail: nil, source: nil)
+        @status = status
+        @code = code
+        @title = title
+        @detail = detail
+        @source = source
+        super(detail || title || 'An error occurred')
+      end
+
+      def to_hash
+        {
+          status: status.to_s,
+          code:,
+          title:,
+          detail:,
+          source:
+        }.compact
+      end
+    end
+
+    class ValidationError < Error
+      def initialize(detail:, source: nil)
+        super(status: 422, title: 'Validation Error', detail:, source:)
+      end
+    end
+
+    class NotFoundError < Error
+      def initialize(detail: 'Resource not found')
+        super(status: 404, title: 'Not Found', detail:)
+      end
+    end
+
+    class BadRequestError < Error
+      def initialize(detail: 'Bad Request')
+        super(status: 400, title: 'Bad Request', detail:)
+      end
+    end
+
+    class UnauthorizedError < Error
+      def initialize(detail: 'Unauthorized')
+        super(status: 401, title: 'Unauthorized', detail:)
+      end
+    end
+
+    class ForbiddenError < Error
+      def initialize(detail: 'Forbidden')
+        super(status: 403, title: 'Forbidden', detail:)
+      end
+    end
+
+    class InternalServerError < Error
+      def initialize(detail: 'Internal Server Error')
+        super(status: 500, title: 'Internal Server Error', detail:)
+      end
+    end
+
+    class ResourceError < Error
+      def initialize(detail:)
+        super(status: 500, title: 'Resource Error', detail:)
+      end
+    end
+  end
+end

data/lib/jpie/generators/resource_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module JPie
+  module Generators
+    class ResourceGenerator < Rails::Generators::NamedBase
+      desc 'Generate a JPie resource class'
+
+      argument :attributes, type: :array, default: [], banner: 'field:type field:type'
+
+      class_option :model, type: :string, desc: 'Model class to associate with this resource'
+
+      def create_resource_file
+        template 'resource.rb.erb', File.join('app/resources', "#{file_name}_resource.rb")
+      end
+
+      private
+
+      def model_class_name
+        options[:model] || class_name
+      end
+
+      def resource_attributes
+        return [] if attributes.empty?
+
+        attributes.map(&:name)
+      end
+
+      def template_path
+        File.expand_path('templates', __dir__)
+      end
+
+      def source_root
+        template_path
+      end
+    end
+  end
+end

data/lib/jpie/generators/templates/resource.rb.erb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Resource < JPie::Resource
+  model <%= model_class_name %>
+
+<% if resource_attributes.any? -%>
+  attributes <%= resource_attributes.map { |attr| ":#{attr}" }.join(', ') %>
+<% else -%>
+  # Define your attributes here:
+  # attributes :name, :email, :created_at
+<% end -%>
+end 

data/lib/jpie/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module JPie
+  class Railtie < Rails::Railtie
+    railtie_name :jpie
+
+    config.jpie = ActiveSupport::OrderedOptions.new
+
+    # Configure Rails inflections to preserve JPie casing
+    initializer 'jpie.inflections' do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym 'JPie'
+      end
+    end
+
+    initializer 'jpie.configure' do |app|
+      JPie.configure do |config|
+        app.config.jpie.each do |key, value|
+          config.public_send("#{key}=", value) if config.respond_to?("#{key}=")
+        end
+      end
+    end
+
+    initializer 'jpie.action_controller' do
+      ActiveSupport.on_load(:action_controller) do
+        extend JPie::Controller::ClassMethods if defined?(JPie::Controller::ClassMethods)
+      end
+    end
+
+    generators do
+      require 'jpie/generators/resource_generator'
+    end
+  end
+end