wor-simple_crud 0.2.1

data/README.md

@@ -0,0 +1,286 @@
+SimpleCrud
+=============
+
+[![CI](https://github.com/icoluccio/simple-crud/actions/workflows/ci.yml/badge.svg)](https://github.com/icoluccio/simple-crud/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/wor-simple_crud.svg)](https://badge.fury.io/rb/wor-simple_crud)
+
+# Table of contents
+  - [Description](#description)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Setup](#setup)
+      - [Application controller](#application-controller)
+      - [Each controller](#each-controller)
+      - [Options](#options)
+        - [Paginate](#paginate)
+        - [Authorize](#authorize)
+        - [Serializer](#serializer)
+      - [Shared examples](#shared-examples)
+  - [Contributing](#contributing)
+  - [Releases](#releases)
+  - [About](#about)
+  - [License](#license)
+
+-----------------------
+
+## Description
+
+Simple Crud is a gem for Rails that simplifies writing standard CRUD actions, while also adding tools so it's not needed to write tests for them. Its main objective is replacing generally copy-pasted code like generic paginated, authenticated index methods for simple lines such as
+```ruby
+simple_crud_for :index
+```
+It includes support for index, create, destroy, update and show, and options to specify whether it should apply pagination, authorization and if a particular serializer should be used. Keep in mind, though, that the idea is not to replace writing methods in controllers altogether, but only to replace most standard cases.
+
+## Installation
+Add the following line to your application's Gemfile. The gem is named `wor-simple_crud`, but the require path is `simple_crud`, so tell Bundler where to find it:
+
+```ruby
+gem 'wor-simple_crud', require: 'simple_crud'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install wor-simple_crud
+```
+
+simple_crud only depends on Rails itself. Authorization (Pundit by default) and pagination (wor-paginate by default) are opt-in: add whichever libraries you actually use to your own Gemfile too.
+
+```ruby
+gem 'pundit'
+gem 'wor-paginate'
+```
+
+See [Paginate](#paginate) and [Authorize](#authorize) below for the other supported libraries, or to skip either feature (`authorize: false` / `paginate: false`) and depend on neither.
+
+## Usage
+### Setup
+#### Application controller
+Before SimpleCrud can be used, some boilerplate is needed. Add the following to your ApplicationController (or every controller in case you don't want it included in all controllers)
+```ruby
+include Pundit::Authorization
+include Wor::Paginate
+extend SimpleCrud
+
+before_action :set_params
+
+def set_params
+  SimpleCrudController.params = params
+end
+```
+
+(Skip `include Pundit::Authorization` / `include Wor::Paginate` if you're using a different adapter, or `authorize: false` / `paginate: false` everywhere.)
+
+
+### Each controller
+In case you need either update or create, create a method with the valid input params using standard rails:
+```ruby
+def author_params
+  params.permit(:first_name, :email, :last_name, :institution, :role)
+end
+```
+
+For the actual crud methods, just use the lines you need
+```ruby
+simple_crud_for :update
+simple_crud_for :show
+simple_crud_for :index
+simple_crud_for :create
+simple_crud_for :destroy
+```
+
+Each method supports different options, as in:
+```
+simple_crud_for :index, paginate: false, authorize: false, serializer: CustomSerializer
+```
+
+- Paginate: whether it should paginate or not. `true` paginates via the configured pagination adapter (wor-paginate by default), `false` doesn't paginate
+- Authorize: whether it should check authorization via the configured authorization adapter (Pundit by default)
+- Authenticate: whether it should use Devise to check for a current_user
+- Serializer: specify a particular serializer you should use
+
+You'll need a few things so they work correctly:
+
+### Options
+#### Paginate
+Pagination defaults to [wor-paginate](https://github.com/icoluccio/wor-paginate) and needs no extra options. Check its docs if you want to customize the output.
+
+Three other pagination libraries have adapters built in too:
+
+```ruby
+# Kaminari (https://github.com/kaminari/kaminari)
+require 'simple_crud/pagination/kaminari_adapter'
+SimpleCrud.configure { |config| config.pagination_adapter = SimpleCrud::Pagination::KaminariAdapter.new }
+
+# will_paginate (https://github.com/mislav/will_paginate)
+require 'simple_crud/pagination/will_paginate_adapter'
+SimpleCrud.configure { |config| config.pagination_adapter = SimpleCrud::Pagination::WillPaginateAdapter.new }
+
+# Pagy (https://github.com/ddnexus/pagy) -- requires `include Pagy::Method` in your ApplicationController
+require 'simple_crud/pagination/pagy_adapter'
+SimpleCrud.configure { |config| config.pagination_adapter = SimpleCrud::Pagination::PagyAdapter.new }
+```
+
+They render a plain JSON array rather than wor-paginate's `{page:, count:, total_pages:, ...}` envelope. None of the four pagination gems is installed automatically, so add whichever one you pick to your own Gemfile.
+
+Want something else, or nothing at all? Write your own `SimpleCrud::Pagination::Adapter`:
+
+```ruby
+class MyPaginationAdapter
+  include SimpleCrud::Pagination::Adapter
+
+  # Called from inside the generated index action when paginate: true.
+  # Must render the response itself.
+  def paginate(controller, klass, options)
+    records = klass.some_pagination_method(controller.params[:page])
+    controller.render({ json: records }.merge(options))
+  end
+end
+
+SimpleCrud.configure { |config| config.pagination_adapter = MyPaginationAdapter.new }
+```
+
+#### Authorize
+Authorization checks go through [Pundit](https://github.com/varvet/pundit) by default. Name the policy after the model plus `Policy`, e.g. `AuthorPolicy`, written as a regular Pundit policy:
+
+```ruby
+class AuthorPolicy
+  attr_reader :user, :author
+
+  def initialize(user, author)
+    @user = user
+    @author = author
+  end
+
+  def show?
+    user.present?
+  end
+end
+
+```
+
+Prefer CanCanCan or Action Policy instead? Both have adapters ready to go:
+
+```ruby
+# CanCanCan (https://github.com/CanCanCommunity/cancancan)
+require 'simple_crud/authorization/can_can_can_adapter'
+SimpleCrud.configure do |config|
+  config.authorization_adapter = SimpleCrud::Authorization::CanCanCanAdapter.new
+end
+```
+
+```ruby
+# Action Policy (https://github.com/palkan/action_policy)
+require 'simple_crud/authorization/action_policy_adapter'
+SimpleCrud.configure do |config|
+  config.authorization_adapter = SimpleCrud::Authorization::ActionPolicyAdapter.new
+end
+```
+
+As with pagination, simple_crud ships the adapter code but not the library itself. Add `cancancan` or `action_policy` to your own Gemfile, whichever you pick.
+
+Using something else, or skipping authorization entirely? Write your own `SimpleCrud::Authorization::Adapter`:
+
+```ruby
+class MyAuthorizationAdapter
+  include SimpleCrud::Authorization::Adapter
+
+  # Called from inside a generated CRUD action. Raise (or otherwise halt
+  # the request) when the current user may not act on +record+.
+  def authorize(controller, record)
+    controller.authorize!(record)
+  end
+
+  # Called once, when simple_crud_for is invoked, to fail fast if the
+  # given model has no authorization rules defined at all.
+  def policy_defined?(model_class)
+    Kernel.const_defined?("#{model_class}Policy")
+  end
+end
+
+SimpleCrud.configure do |config|
+  config.authorization_adapter = MyAuthorizationAdapter.new
+end
+```
+
+#### Authenticate
+SimpleCrud will assume a current_user method. Future versions will support a custom model. Defining a current_user method in ApplicationController should work if you're using a different model, as of now.
+
+#### Serializer
+The name of the serializer, by default, is the name of the model followed by Serializer, as is the standard for [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers). It's possible to just pass a custom serializer class though. As for the serializer itself, it's a standard serializer, with the gotcha that you need to include `:id` for the SimpleCrud examples to work.
+
+```ruby
+class AuthorSerializer < ActiveModel::Serializer
+  attributes :email, :first_name, :last_name, :institution, :role, :id
+end
+```
+
+### Shared examples
+While optional, using the included shared examples saves you from writing the standard test cases for the methods. You can even use them if you didn't use `simple_crud_for`, as a set of basic tests. To include them, just add `require 'simple_crud/rspec'` to your `rails_helper.rb` file and add the lines you need to your `*_spec.rb` files:
+```ruby
+require 'rails_helper'
+
+describe V1::Backoffice::AuthorsController do
+  include_examples 'simple crud for update'
+  include_examples 'simple crud for show'
+  include_examples 'simple crud for create'
+  include_examples 'simple crud for index'
+  include_examples 'simple crud for destroy'
+end
+```
+
+It's not needed to specify paginate: true and such, since the shared examples will use the configuration that was originally passed to simple_crud_for
+
+## Contributing
+
+1. Fork it
+2. Run `bundle install && bundle exec appraisal generate` once, to install dependencies and generate the per-Rails-version gemfiles (`gemfiles/rails_*.gemfile`) used for testing
+3. Run `bundle exec overcommit --install` once, to enable the pre-push hook (runs RuboCop and the full spec suite automatically on every `git push`)
+4. Create your feature branch (`git checkout -b my-new-feature`)
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Run RuboCop lint (`bundle exec rubocop lib spec --format simple`)
+7. Run rspec tests (`BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle exec rspec`)
+8. Push your branch (`git push origin my-new-feature`). The pre-push hook re-verifies both automatically
+9. Create a new Pull Request to `main` branch
+
+## Releases
+📢 [See what's changed in a recent version](https://github.com/icoluccio/simple-crud/releases)
+
+## About ##
+
+The current maintainer of this gem is:
+* [Ignacio Coluccio](https://github.com/icoluccio)
+
+This project was developed by:
+* [Ignacio Coluccio](https://github.com/icoluccio)
+
+Originally at Wolox
+
+## License
+
+**simple-crud** is available under the MIT [license](https://raw.githubusercontent.com/icoluccio/simple-crud/main/LICENSE.md).
+
+    Copyright (c) 2017 Wolox
+    Copyright (c) 2026 Ignacio Coluccio
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/simple_crud/authorization/action_policy_adapter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'action_policy'
+require_relative 'adapter'
+
+module SimpleCrud
+  module Authorization
+    # Assumes ActionPolicy::Controller (not the bare Behaviour) is included,
+    # which defaults the rule to the current action name.
+    class ActionPolicyAdapter
+      include Adapter
+
+      def authorize(controller, record)
+        controller.send(:authorize!, record)
+      end
+
+      def policy_defined?(model_class)
+        Kernel.const_defined?("#{model_class}Policy")
+      end
+    end
+  end
+end

data/lib/simple_crud/authorization/adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  module Authorization
+    # Implement to plug in an authorization library other than Pundit
+    # (the default, see PunditAdapter).
+    module Adapter
+      # Raise when +controller+'s current user may not act on +record+.
+      def authorize(controller, record)
+        raise NotImplementedError
+      end
+
+      # Called once, when simple_crud_for is invoked, to fail fast if
+      # +model_class+ has no authorization configured.
+      def policy_defined?(model_class)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/simple_crud/authorization/can_can_can_adapter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'cancancan'
+require_relative 'adapter'
+
+module SimpleCrud
+  module Authorization
+    # A single Ability class governs everything, so #policy_defined? can
+    # only confirm one is configured, not that it covers this model.
+    class CanCanCanAdapter
+      include Adapter
+
+      def authorize(controller, record)
+        controller.send(:authorize!, controller.action_name.to_sym, record)
+      end
+
+      def policy_defined?(_model_class)
+        Kernel.const_defined?('Ability')
+      end
+    end
+  end
+end

data/lib/simple_crud/authorization/pundit_adapter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'adapter'
+
+module SimpleCrud
+  module Authorization
+    # Default authorization adapter: standard Pundit `#{Model}Policy` classes.
+    class PunditAdapter
+      include Adapter
+
+      def authorize(controller, record)
+        # Pundit::Authorization#authorize is protected, hence send.
+        controller.send(:authorize, record)
+      end
+
+      def policy_defined?(model_class)
+        Kernel.const_defined?("#{model_class}Policy")
+      end
+    end
+  end
+end

data/lib/simple_crud/config.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  # Holds simple_crud's configurable pieces, set via SimpleCrud.configure.
+  class Config
+    class << self
+      attr_writer :authorization_adapter, :pagination_adapter
+
+      def authorization_adapter
+        @authorization_adapter ||= begin
+          require_relative 'authorization/pundit_adapter'
+          Authorization::PunditAdapter.new
+        end
+      end
+
+      def pagination_adapter
+        @pagination_adapter ||= begin
+          require_relative 'pagination/wor_paginate_adapter'
+          Pagination::WorPaginateAdapter.new
+        end
+      end
+    end
+  end
+end

data/lib/simple_crud/pagination/adapter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  module Pagination
+    # Implement to plug in a pagination library other than wor-paginate
+    # (the default, see WorPaginateAdapter).
+    module Adapter
+      # Called when paginate: true. Must render the response itself.
+      def paginate(controller, klass, options)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/simple_crud/pagination/kaminari_adapter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'kaminari'
+require 'kaminari/activerecord'
+require_relative 'adapter'
+
+module SimpleCrud
+  module Pagination
+    # https://github.com/kaminari/kaminari
+    class KaminariAdapter
+      include Adapter
+
+      def paginate(controller, klass, options)
+        records = klass.page(controller.params[:page]).per(controller.params[:per_page])
+        controller.render({ json: records }.merge(options))
+      end
+    end
+  end
+end

data/lib/simple_crud/pagination/pagy_adapter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'pagy'
+require_relative 'adapter'
+
+module SimpleCrud
+  module Pagination
+    # Assumes the controller includes Pagy::Method.
+    class PagyAdapter
+      include Adapter
+
+      # 43.5.0 renamed client_max_limit -> max_limit. Ruby < 3.3 resolves to
+      # the pre-rename 43.4.x, so pick whichever key the loaded Pagy expects.
+      MAX_LIMIT_KEY = Gem::Version.new(Pagy::VERSION) >= Gem::Version.new('43.5.0') ? :max_limit : :client_max_limit
+
+      def paginate(controller, klass, options)
+        _pagy, records = controller.send(:pagy, klass.all, MAX_LIMIT_KEY => 100)
+        controller.render({ json: records }.merge(options))
+      end
+    end
+  end
+end

data/lib/simple_crud/pagination/will_paginate_adapter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'will_paginate'
+require 'will_paginate/active_record'
+require_relative 'adapter'
+
+module SimpleCrud
+  module Pagination
+    # Adapter for will_paginate (https://github.com/mislav/will_paginate).
+    # Uses #paginate, not #page (also defined by Kaminari).
+    class WillPaginateAdapter
+      include Adapter
+
+      def paginate(controller, klass, options)
+        page = controller.params[:page] || 1
+        per_page = controller.params[:per_page] || WillPaginate.per_page
+        records = klass.paginate(page: page, per_page: per_page)
+        controller.render({ json: records }.merge(options))
+      end
+    end
+  end
+end

data/lib/simple_crud/pagination/wor_paginate_adapter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'wor/paginate'
+require_relative 'adapter'
+
+module SimpleCrud
+  module Pagination
+    # Assumes the controller includes Wor::Paginate.
+    class WorPaginateAdapter
+      include Adapter
+
+      def paginate(controller, klass, options)
+        controller.send(:render_paginated, klass, options)
+      end
+    end
+  end
+end

data/lib/simple_crud/rspec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative '../spec/response_helper'
+require_relative '../spec/shared_contexts/authenticate_user'
+require_relative '../spec/shared_examples/simple_crud_for_update'
+require_relative '../spec/shared_examples/simple_crud_for_show'
+require_relative '../spec/shared_examples/simple_crud_for_index'
+require_relative '../spec/shared_examples/simple_crud_for_destroy'
+require_relative '../spec/shared_examples/simple_crud_for_create'
+require_relative '../spec/shared_examples/unauthorized_when_not_logged_in'
+require_relative '../spec/matchers/have_been_serialized_with'

data/lib/simple_crud/simple_crud_controller.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+require_relative 'config'
+
+# Extended onto a controller for CRUD actions.
+module SimpleCrudController
+  cattr_accessor :params, :permitted
+
+  # Possible options:
+  ### authorize: check authorization via Config.authorization_adapter (Pundit by default)
+  ### paginate: paginate the list via Config.pagination_adapter (wor-paginate by default)
+  ### authenticate: use devise to authenticate
+  ### serializer: use a particular serializer (both each_serializer and serializer)
+  def simple_crud_for(method, parameters = {})
+    parameters = parameters_with_defaults(parameters)
+    klass = simple_crud_controller_model
+    check_valid_method(method)
+    check_policies(parameters)
+    check_serializer(parameters)
+    define_method(method, send("crud_lambda_for_#{method}", klass, parameters))
+    write_metadata(method, parameters)
+  end
+
+  def parameters_with_defaults(parameters)
+    defaults = { authorize: true, paginate: true, authenticate: true, serializer: nil }
+    defaults.each do |key, value|
+      parameters[key] = value unless parameters.key?(key)
+    end
+    parameters
+  end
+
+  def write_metadata(method, parameters)
+    @simple_crud_metadata ||= {}
+    @simple_crud_metadata[method] = parameters
+  end
+
+  def self.maybe_authorize(controller, record, parameters)
+    return unless parameters[:authorize] && parameters[:authenticate]
+
+    SimpleCrud::Config.authorization_adapter.authorize(controller, record)
+  end
+
+  def crud_lambda_for_show(klass, parameters = {})
+    lambda do
+      authenticate_user! if parameters[:authenticate]
+      requested = klass.find(params[:id])
+
+      options = {}.merge(serializer: parameters[:serializer]).compact
+      SimpleCrudController.maybe_authorize(self, requested, parameters)
+      render({ json: requested }.merge(options))
+    end
+  end
+
+  def crud_lambda_for_index(klass, parameters = {})
+    lambda do
+      authenticate_user! if parameters[:authenticate]
+      SimpleCrudController.maybe_authorize(self, klass.new, parameters)
+      options = {}.merge(each_serializer: parameters[:serializer]).compact
+      SimpleCrudController.render_index(self, klass, options, parameters)
+    end
+  end
+
+  def self.render_index(controller, klass, options, parameters)
+    if parameters[:paginate]
+      SimpleCrud::Config.pagination_adapter.paginate(controller, klass, options)
+    else
+      controller.render({ json: klass.all }.merge(options))
+    end
+  end
+
+  def crud_lambda_for_create(klass, parameters = {})
+    lambda do
+      authenticate_user! if parameters[:authenticate]
+      permitted_params = send("#{self.class.simple_crud_controller_model.to_s.underscore}_params")
+      SimpleCrudController.maybe_authorize(self, klass.new(permitted_params), parameters)
+      render json: klass.create!(permitted_params), status: :created
+    end
+  end
+
+  def crud_lambda_for_update(klass, parameters = {})
+    lambda do
+      authenticate_user! if parameters[:authenticate]
+      requested = klass.find(params[:id])
+      SimpleCrudController.maybe_authorize(self, requested, parameters)
+      permitted_params = send("#{self.class.simple_crud_controller_model.to_s.underscore}_params")
+      render json: requested.update!(permitted_params)
+    end
+  end
+
+  def crud_lambda_for_destroy(klass, parameters = {})
+    lambda do
+      authenticate_user! if parameters[:authenticate]
+      requested = klass.find(params[:id])
+      SimpleCrudController.maybe_authorize(self, requested, parameters)
+      render json: klass.find(params[:id]).destroy
+    end
+  end
+
+  def simple_crud_controller_model
+    to_s.split('::').last.sub('Controller', '').singularize.classify.constantize
+  end
+
+  def check_valid_method(method)
+    throw 'invalid method' unless %i[show index create update destroy].include? method
+  end
+
+  def check_policies(parameters)
+    return if !parameters.key?(:authorize) || !parameters[:authorize]
+
+    model = simple_crud_controller_model
+    return if SimpleCrud::Config.authorization_adapter.policy_defined?(model)
+
+    throw "no authorization policy configured for #{model}"
+  end
+
+  def check_serializer(parameters)
+    return if parameters[:serializer].blank?
+
+    serializer_name = parameters[:serializer].to_s
+    return if Kernel.const_defined?(serializer_name)
+
+    throw "create a valid serializer with name #{serializer_name}"
+  end
+end

data/lib/simple_crud/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  VERSION = '0.2.1'
+end

data/lib/simple_crud.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'simple_crud/version'
+require_relative 'simple_crud/config'
+require_relative 'simple_crud/simple_crud_controller'
+
+# Simplified CRUD endpoints for Rails API controllers.
+module SimpleCrud
+  def self.configure
+    yield Config
+  end
+end