permit_params 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e0261ffbdf435bd7abca5dd4f6fba035c695568e8eb731f5bd0422697114431
+  data.tar.gz: 011cbef5ce2019c59e48a33e3d8e4f6e0fd03e8ae8b713ad63e088cb69d29cc2
+SHA512:
+  metadata.gz: 8fceb998fc9889aff5fc65bc7245d043daac8d0d627b84c8e7a236e805f36bd0f766ab4aa7548dd96f015d368cd7da0c23a8c9c9b3a4e921b851da932f47461a
+  data.tar.gz: 6c2eacdaacb3746178ca59fea8b3121b47882fcced29e4218cea46f6e537ceac94a12887666f44dcda9188ce888189e6da32dd4a13a7dfc33d3b3e4a63a2e9eb

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+- Versão inicial.
+- Macro `permit_params` para declarar schemas de parâmetros por action.
+- Suporte a `permit`, `required` + `permit` e `expect` (Rails 8).
+- Atalho de array para `permit`.
+- Configuração global (`default_schema`, `raise_on_missing_schema`) via
+  `PermitParams.configure`.
+- Generator `permit_params:install`.
+- Inclusão automática em `ActionController::Base`/`ActionController::API`
+  através de um Railtie.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ronsal
+
+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/README.md

@@ -0,0 +1,183 @@
+# permit_params
+
+Schemas de parâmetros **declarativos e por action** para controllers Rails.
+
+Declare o que cada action espera e a gem cuida do `strong parameters` automaticamente.
+Suporta `permit`, `required` + `permit` e a API nova `expect` do Rails 8.
+
+```ruby
+class HeroesController < ApplicationController
+  permit_params :show,   { permit: [:id, { hero: {} }] }
+  permit_params :search, { permit: [:query, :page, :per_page, { filter: [] }, { sort: [] }] }
+  permit_params :create, { required: :hero, permit: [:name, :rank, :lat, :lng] }
+  permit_params :update, { expect: { hero: [:id, :name, :rank, :lat, :lng] } }
+
+  def show
+    status, content, serializer = Http::ShowHero::Service.(params)
+    render json: content, status: status, serializer: serializer
+  end
+end
+```
+
+## Como funciona
+
+- A gem é incluída automaticamente em `ActionController::Base` e
+  `ActionController::API` (via Railtie). **Instalar já basta.**
+- `permit_params :action, schema` guarda o schema por action.
+- No momento em que a action chama `params`, o schema da action é aplicado.
+- Actions sem schema continuam recebendo o `params` padrão do framework
+  (a menos que você configure `default_schema`/`raise_on_missing_schema`).
+
+## Instalação
+
+### Publicada no Rubygems
+
+```ruby
+# Gemfile
+gem "permit_params"
+```
+
+### Como gem local (path)
+
+```ruby
+# Gemfile
+gem "permit_params", path: "../permit_params"
+```
+
+Depois:
+
+```bash
+bundle install
+```
+
+Opcionalmente, gere o initializer de configuração:
+
+```bash
+rails generate permit_params:install
+```
+
+## Formatos de schema
+
+### `permit`
+
+Equivale a `params.permit(*...)`:
+
+```ruby
+permit_params :show, { permit: [:id, { hero: {} }] }
+# params.permit(:id, hero: {})
+```
+
+> `hero: {}` permite **todas** as chaves de dentro de `hero`.
+> Para filtrar o conteúdo, liste as chaves: `{ hero: [:name] }`.
+
+### `required` + `permit`
+
+Equivale a `params.required(:chave).permit(*...)`. Como o `require` do Rails
+**desembrulha** a chave, o resultado já são os atributos internos:
+
+```ruby
+permit_params :create, { required: :hero, permit: [:name, :rank, :lat, :lng] }
+# params.required(:hero).permit(:name, :rank, :lat, :lng)
+# => params com name/rank/lat/lng no topo
+```
+
+### `expect` (Rails 8+)
+
+Equivale a `params.expect(...)`. Quando o schema tem uma única chave raiz, o
+Rails também desembrulha o conteúdo:
+
+```ruby
+permit_params :update, { expect: { hero: [:id, :name, :rank, :lat, :lng] } }
+# params.expect(hero: [:id, :name, :rank, :lat, :lng])
+# => params com id/name/rank/lat/lng no topo
+```
+
+Para **arrays** de hashes use os colchetes duplos (regra do próprio Rails):
+
+```ruby
+permit_params :bulk, { expect: { heroes: [[:id, :name, :rank]] } }
+```
+
+### Atalho com array
+
+Um array puro vira um `permit`:
+
+```ruby
+permit_params :index, [:page, :per_page]
+# o mesmo que permit: [:page, :per_page]
+```
+
+## Configuração global
+
+```ruby
+# config/initializers/permit_params.rb
+PermitParams.configure do |config|
+  # Schema aplicado a actions que não declaram o próprio schema.
+  # nil (padrão) mantém o params padrão do framework.
+  config.default_schema = { permit: [:page, :per_page] }
+
+  # Levanta PermitParams::MissingSchemaError para actions sem schema.
+  config.raise_on_missing_schema = false
+end
+```
+
+## Erros
+
+| Erro                                   | Quando acontece                                                        |
+| -------------------------------------- | ---------------------------------------------------------------------- |
+| `PermitParams::InvalidSchemaError`     | Schema não é Array nem Hash com `:permit`, `:required` ou `:expect`.   |
+| `PermitParams::MissingSchemaError`     | Action sem schema com `raise_on_missing_schema` ligado.                |
+| `PermitParams::Error`                  | `expect:` usado em uma versão de Rails sem `Parameters#expect` (< 8.0).|
+| `ActionController::ParameterMissing`   | Chave obrigatória ausente (`required`/`expect`).                       |
+
+## Migrando do `BaseController`
+
+Antes (implementação manual):
+
+```ruby
+class BaseController < ApplicationController
+  class_attribute :param_schemas, default: {}
+
+  class << self
+    def permit_params(action, schema)
+      param_schemas[action.to_sym] = schema
+    end
+  end
+
+  private
+
+  def params
+    schema = self.class.param_schemas[action_name.to_sym]
+    return super unless schema
+    # ...
+  end
+end
+```
+
+Depois (com a gem instalada, o `BaseController` pode ficar vazio ou ser removido):
+
+```ruby
+class BaseController < ApplicationController
+end
+```
+
+> Bônus: a implementação manual mutava o mesmo Hash compartilhado entre todos
+> os controllers (schemas vazavam de um controller para o outro). A gem usa
+> `merge`, então cada controller tem seu próprio conjunto de schemas.
+
+## Requisitos
+
+- Ruby >= 3.1
+- `actionpack`/`activesupport` >= 7.0
+- `expect:` exige Rails >= 8.0
+
+## Desenvolvimento
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Licença
+
+MIT.

data/lib/generators/permit_params/install/install_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module PermitParams
+  module Generators
+    # Creates +config/initializers/permit_params.rb+.
+    #
+    #   rails generate permit_params:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a PermitParams initializer."
+
+      def copy_initializer
+        template "permit_params.rb", "config/initializers/permit_params.rb"
+      end
+    end
+  end
+end

data/lib/generators/permit_params/install/templates/permit_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+PermitParams.configure do |config|
+  # Schema applied to actions that do not declare their own through
+  # `permit_params`. Leave it as nil (the default) to keep the framework
+  # default for those actions.
+  #
+  # config.default_schema = { permit: [:page, :per_page] }
+
+  # Raise PermitParams::MissingSchemaError when an action has neither its own
+  # schema nor a default_schema. Handy to force every action to be explicit.
+  #
+  # config.raise_on_missing_schema = false
+end

data/lib/permit_params/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PermitParams
+  # Global configuration for the gem. Change it through +PermitParams.configure+,
+  # usually in +config/initializers/permit_params.rb+:
+  #
+  #   PermitParams.configure do |config|
+  #     config.default_schema = { permit: [:page, :per_page] }
+  #     config.raise_on_missing_schema = true
+  #   end
+  class Configuration
+    # Schema applied to actions that do not declare their own through
+    # +permit_params+. Accepts the same shapes as +permit_params+ (a Hash like
+    # <tt>{ permit: [...] }</tt>, <tt>{ required: :foo, permit: [...] }</tt> or
+    # <tt>{ expect: { ... } }</tt>, or a bare Array as shorthand for +permit+).
+    #
+    # When +nil+ (the default) actions without a schema are left untouched and
+    # receive the framework default +params+.
+    attr_accessor :default_schema
+
+    # When +true+, raises PermitParams::MissingSchemaError for any action that
+    # has neither its own schema nor a +default_schema+. Useful to enforce that
+    # every action is explicit. Defaults to +false+.
+    attr_accessor :raise_on_missing_schema
+
+    def initialize
+      @default_schema = nil
+      @raise_on_missing_schema = false
+    end
+  end
+end

data/lib/permit_params/controller.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module PermitParams
+  # Mixin that adds the +permit_params+ class macro and applies the schema
+  # declared for the current action to +params+.
+  #
+  # It is included automatically into +ActionController::Base+ and
+  # +ActionController::API+ by PermitParams::Railtie, so in a Rails app you
+  # usually do not need to include it yourself.
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :param_schemas, instance_accessor: false, default: {}
+    end
+
+    class_methods do
+      # Declares the parameter schema for +action+.
+      #
+      #   permit_params :show,   { permit: [:id, { hero: {} }] }
+      #   permit_params :create, required: :hero, permit: [:name, :rank]
+      #   permit_params :update, expect: { hero: [:id, :name, :rank] }
+      #   permit_params :index,  [:page, :per_page] # shorthand for permit
+      #
+      # The schema is validated eagerly, so a malformed one fails while the
+      # class is being (re)loaded instead of on the first request.
+      def permit_params(action, schema = nil, **options)
+        schema = options if schema.nil? && !options.empty?
+        raise ArgumentError, "missing schema for action #{action.inspect}" if schema.nil?
+
+        schema = PermitParams.normalize_schema(schema)
+        self.param_schemas = param_schemas.merge(action.to_sym => schema)
+      end
+
+      # Schema for +action+, falling back to the global default when the action
+      # does not declare one.
+      def param_schema_for(action)
+        param_schemas[action.to_sym] || PermitParams.configuration.default_schema
+      end
+    end
+
+    private
+
+    def params
+      schema = self.class.param_schema_for(action_name)
+
+      if schema.nil?
+        if PermitParams.configuration.raise_on_missing_schema
+          raise MissingSchemaError,
+                "no parameter schema declared for action #{action_name.inspect} on #{self.class}"
+        end
+
+        return super
+      end
+
+      PermitParams.apply(super, schema)
+    end
+  end
+end

data/lib/permit_params/railtie.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PermitParams
+  # Wires PermitParams::Controller into every controller as soon as
+  # ActionController is loaded, so installing the gem is enough to get the
+  # +permit_params+ DSL everywhere.
+  class Railtie < ::Rails::Railtie
+    initializer "permit_params.include_controller" do
+      # ActionController::Base and ActionController::API both run
+      # :action_controller in Rails 8. The other two hooks are kept so the gem
+      # also works on older versions; including the same module twice is a no-op.
+      ActiveSupport.on_load(:action_controller) do
+        include PermitParams::Controller
+      end
+
+      ActiveSupport.on_load(:action_controller_base) do
+        include PermitParams::Controller
+      end
+
+      ActiveSupport.on_load(:action_controller_api) do
+        include PermitParams::Controller
+      end
+    end
+  end
+end

data/lib/permit_params/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PermitParams
+  VERSION = "0.1.0"
+end

data/lib/permit_params.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/class/attribute"
+require "active_support/concern"
+
+require "permit_params/version"
+require "permit_params/configuration"
+require "permit_params/controller"
+require "permit_params/railtie" if defined?(::Rails::Railtie)
+
+# Declarative, per-action strong parameter schemas for Rails controllers.
+#
+#   class HeroesController < ApplicationController
+#     permit_params :show,   { permit: [:id, { hero: {} }] }
+#     permit_params :create, required: :hero, permit: [:name, :rank, :lat, :lng]
+#     permit_params :update, expect: { hero: [:id, :name, :rank, :lat, :lng] }
+#   end
+module PermitParams
+  class Error < StandardError; end
+
+  # Raised when a schema is neither an Array nor a Hash with one of
+  # +:permit+, +:required+ or +:expect+.
+  class InvalidSchemaError < Error; end
+
+  # Raised for actions without a schema when
+  # +PermitParams.configuration.raise_on_missing_schema+ is enabled.
+  class MissingSchemaError < Error; end
+
+  class << self
+    # Current global configuration.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration for modification and returns it.
+    #
+    #   PermitParams.configure do |config|
+    #     config.default_schema = { permit: [:page, :per_page] }
+    #   end
+    def configure
+      yield configuration if block_given?
+      configuration
+    end
+
+    # Restores the default configuration. Mainly useful in tests.
+    def reset_configuration!
+      @configuration = nil
+    end
+
+    # Applies +schema+ to an ActionController::Parameters instance and returns
+    # the filtered parameters.
+    def apply(params, schema)
+      schema = normalize_schema(schema)
+
+      if schema.key?(:expect)
+        expect_params(params, schema[:expect])
+      elsif schema.key?(:required)
+        params.required(schema[:required]).permit(*Array(schema[:permit]))
+      else
+        params.permit(*Array(schema[:permit]))
+      end
+    end
+
+    # Validates a schema and normalizes the Array shorthand into a Hash.
+    def normalize_schema(schema)
+      return { permit: schema } if schema.is_a?(Array)
+
+      unless schema.is_a?(Hash) && (schema.key?(:permit) || schema.key?(:required) || schema.key?(:expect))
+        raise InvalidSchemaError,
+              "schema must be an Array or a Hash with one of :permit, :required or :expect (got #{schema.inspect})"
+      end
+
+      schema
+    end
+
+    private
+
+    def expect_params(params, filters)
+      unless params.respond_to?(:expect)
+        raise Error, "`expect:` schemas require ActionController::Parameters#expect (Rails >= 8.0)"
+      end
+
+      params.expect(filters)
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: permit_params
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lasnor
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: |
+  permit_params adds a `permit_params` class macro that lets you declare the
+  expected parameters for each controller action and applies them automatically.
+  It supports `permit`, `required` + `permit`, and the Rails 8 `expect` API, and
+  is included into every ActionController::Base/ActionController::API by a Railtie.
+email:
+- leandrolsnr@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/permit_params/install/install_generator.rb
+- lib/generators/permit_params/install/templates/permit_params.rb
+- lib/permit_params.rb
+- lib/permit_params/configuration.rb
+- lib/permit_params/controller.rb
+- lib/permit_params/railtie.rb
+- lib/permit_params/version.rb
+homepage: https://github.com/leandrolasnor/permit_params
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/leandrolasnor/permit_params
+  source_code_uri: https://github.com/leandrolasnor/permit_params
+  changelog_uri: https://github.com/leandrolasnor/permit_params/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Declarative, per-action strong parameter schemas for Rails controllers.
+test_files: []