responders 2.0.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1dc27831fc7b12f53a28dba5186e256cceab2d17
-  data.tar.gz: 277b5266e4495e11b903ca12b36aecd192d494b3
+SHA256:
+  metadata.gz: c070413f30e2321496c58e5c47349b4b62b4409ecb73552d0e58e71394d588fd
+  data.tar.gz: 3853489006f9236c38e2b3842a8c29e6cec2a47f3f919250f6d88e2b5029309d
 SHA512:
-  metadata.gz: 6cb93c417ef6b0dd0844684cecc12e29822e422f88bdaf3fee3188d83c581042e6fc302b25e2717168821fc248dd2530f104d2819501aeec4887cdfdaaf3b575
-  data.tar.gz: b289b2e512aa9fcbb8ffdeaaa04857bbcf0caeef8a0026a257891856e4e0f13f8d90858bb276d44d4a1fe38919fd832c831b09e26fa79da15ed1855d237465cf
+  metadata.gz: 6120b807812d05222247bd55464aaf762b00620cbd8b26877f2d9de38d096d9894f272c00a1f6c796247bbb6260ddeb45234b57947a4f596c9725f8bcf50a3b7
+  data.tar.gz: fd412c3c3c9dc33d66f2695c99180e98bbdc3dc6300481372068c5a3ae79e17a1c7f8d8f5e4eeddc9c7590de5e0996584e02e64728ccdb535ff8e19c529bf7b6

data/CHANGELOG.md

@@ -1,8 +1,73 @@
+## 3.1.1
+
+* Add support for Rails 7.1. (no changes required.)
+
+## 3.1.0
+
+* Add config `responders.redirect_status` to allow overriding the redirect code/status used in redirects. The default is `302 Found`, which matches Rails, but it allows to change responders to redirect with `303 See Other` for example, to make it more compatible with how Hotwire/Turbo expects redirects to work.
+* Add config `responders.error_status` to allow overriding the status code used to respond to `HTML` or `JS` requests that have errors on the resource. The default is `200 OK`, but it allows to change the response to be `422 Unprocessable Entity` in such cases for example, which makes it more consistent with other statuses more commonly used in APIs (like JSON/XML), and works by default with Turbo/Hotwire which expects a 422 on form error HTML responses. Note that changing this may break your application if you're relying on the previous 2xx status to handle error cases.
+* Add support for Ruby 3.0, 3.1, and 3.2, drop support for Ruby < 2.5.
+* Add support for Rails 6.1 and 7.0, drop support for Rails < 5.2.
+* Move CI to GitHub Actions.
+
+## 3.0.1
+
+* Add support to Ruby 2.7
+
+## 3.0.0
+
+* Remove support for Rails 4.2
+* Remove support for Ruby < 2.4
+
+## 2.4.1
+
+* Add support for Rails 6 beta
+
+## 2.4.0
+
+* `respond_with` now accepts a new kwarg called `:render` which goes straight to the `render`
+   call after an unsuccessful post request. Useful if for example you need to render a template
+   which is outside of controller's path eg:
+
+   `respond_with resource, render: { template: 'path/to/template' }`
+
+## 2.3.0
+
+* `verify_request_format!` is aliased to `verify_requested_format!` now.
+* Implementing the `interpolation_options` method on your controller is deprecated
+  in favor of naming it `flash_interpolation_options` instead.
+
+## 2.2.0
+
+* Added the `verify_request_format!` method, that can be used as a `before_action`
+  callback to prevent your actions from being invoked when the controller does
+  not respond to the request mime type, preventing the execution of complex
+  queries or creating/deleting records from your app.
+
+## 2.1.2
+
+* Fix rendering when using `ActionController::API`. (by @eLod)
+* Added API controller template for the controller generator. (by @vestimir)
+
+## 2.1.1
+
+* Added support for Rails 5.
+
+## 2.1.0
+
+* No longer automatically set the responders generator as many projects may use this gem as a dependency. When upgrading, users will need to add `config.app_generators.scaffold_controller :responders_controller` to their application. The `responders:install` generator has been updated to automatically insert it in new applications
+
+## 2.0.1
+
+* Require `rails/railtie` explicitly before using it
+* Require `action_controller` explicitly before using it
+* Remove unnecessary and limiting `resourceful?` check that required models to implement `to_#{format}` (such checks are responsibility of the rendering layer)
+
 ## 2.0.0
 
 * Import `respond_with` and class-level `respond_to` from Rails
 * Support only Rails ~> 4.2
-* `Responders::LocationResponder` is now included by in the default responder (and therefore deprecated)
+* `Responders::LocationResponder` is now included by the default responder (and therefore deprecated)
 
 ## 1.1.0
 

data/MIT-LICENSE

@@ -1,4 +1,5 @@
-Copyright 2009-2014 Plataforma Tecnologia. http://blog.plataformatec.com.br
+Copyright (c) 2020-2023 Rafael França, Carlos Antônio da Silva
+Copyright (c) 2009-2019 Plataformatec
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,10 +1,23 @@
 # Responders
 
-[![Gem Version](https://fury-badge.herokuapp.com/rb/responders.png)](http://badge.fury.io/rb/responders)
-[![Build Status](https://api.travis-ci.org/plataformatec/responders.png?branch=master)](http://travis-ci.org/plataformatec/responders)
-[![Code Climate](https://codeclimate.com/github/plataformatec/responders.png)](https://codeclimate.com/github/plataformatec/responders)
+[![Gem Version](https://fury-badge.herokuapp.com/rb/responders.svg)](http://badge.fury.io/rb/responders)
 
-A set of responders modules to dry up your Rails 3.2+ app.
+A set of responders modules to dry up your Rails app.
+
+## Installation
+
+Add the responders gem to your Gemfile:
+
+    gem "responders"
+
+Update your bundle and run the install generator:
+
+    $ bundle install
+    $ rails g responders:install
+
+If you are including this gem to support backwards compatibilty for responders in previous releases of Rails, you only need to include the gem and bundle.
+
+    $ bundle install
 
 ## Responders Types
 
@@ -60,77 +73,78 @@ You can also have embedded HTML. Just create a `_html` scope.
 
 See also the `namespace_lookup` option to search the full hierarchy of possible keys.
 
-### Location Responder
+### HttpCacheResponder
+
+Automatically adds Last-Modified headers to API requests. This
+allows clients to easily query the server if a resource changed and if the client tries
+to retrieve a resource that has not been modified, it returns not_modified status.
+
+### CollectionResponder
+
+Makes your create and update action redirect to the collection on success.
+
+### LocationResponder
 
 This responder allows you to use callable objects as the redirect location.
 Useful when you want to use the `respond_with` method with
 a custom route that requires persisted objects, but the validation may fail.
 
+Note: this responder is included by default, and doesn't need to be included
+on the top of your controller (including it will issue a deprecation warning).
+
 ```ruby
 class ThingsController < ApplicationController
-  responders :location, :flash
   respond_to :html
 
   def create
-    @thing = Things.create(params[:thing])
+    @thing = Thing.create(params[:thing])
     respond_with @thing, location: -> { thing_path(@thing) }
   end
 end
 ```
 
-### HttpCacheResponder
+**Dealing with namespaced routes**
 
-Automatically adds Last-Modified headers to API requests. This
-allows clients to easily query the server if a resource changed and if the client tries
-to retrieve a resource that has not been modified, it returns not_modified status.
-
-### CollectionResponder
-
-Makes your create and update action redirect to the collection on success.
+In order for the LocationResponder to find the correct route helper for namespaced routes you need to pass the namespaces to `respond_with`:
 
-## Configuring your own responder
-
-The first step is to install the responders gem and configure it in your application:
+```ruby
+class Api::V1::ThingsController < ApplicationController
+  respond_to :json
 
-```console
-gem install responders
+  # POST /api/v1/things
+  def create
+    @thing = Thing.create(thing_params)
+    respond_with :api, :v1, @thing
+  end
+end
 ```
 
-In your Gemfile, add this line:
-
-```ruby
-gem 'responders'
-```
+## Configuring your own responder
 
-Responders only provides a set of modules, to use them, you have to create your own
-responder. This can be done inside the lib folder for example:
+Responders only provides a set of modules and to use them you have to create your own
+responder. After you run the install command, the following responder will be
+generated in your application:
 
 ```ruby
-# lib/app_responder.rb
-class AppResponder < ActionController::Responder
+# lib/application_responder.rb
+class ApplicationResponder < ActionController::Responder
   include Responders::FlashResponder
   include Responders::HttpCacheResponder
 end
 ```
 
-And then you need to configure your application to use it:
+Your application also needs to be configured to use it:
 
 ```ruby
 # app/controllers/application_controller.rb
-require "app_responder"
+require "application_responder"
 
 class ApplicationController < ActionController::Base
-  self.responder = AppResponder
+  self.responder = ApplicationResponder
   respond_to :html
 end
 ```
 
-Or, for your convenience, just do:
-
-```console
-rails generate responders:install
-```
-
 ## Controller method
 
 This gem also includes the controller method `responders`, which allows you to cherry-pick which
@@ -144,7 +158,7 @@ end
 
 ## Interpolation Options
 
-You can pass in extra interpolation options for the translation by adding an `interpolation_options` method to your controller:
+You can pass in extra interpolation options for the translation by adding an `flash_interpolation_options` method to your controller:
 
 ```ruby
 class InvitationsController < ApplicationController
@@ -157,33 +171,120 @@ class InvitationsController < ApplicationController
 
   private
 
-  def interpolation_options
+  def flash_interpolation_options
     { resource_name: @invitation.email }
   end
 end
 ```
 
-Now you would see the message "bob@bob.com was successfully created" instead of the default "Invitation was successfully created."
+Now you would see the message `"name@example.com was successfully created"` instead of the default `"Invitation was successfully created."`
 
 ## Generator
 
 This gem also includes a responders controller generator, so your scaffold can be customized
-to use `respond_with` instead of default `respond_to` blocks. Installing this gem automatically
-sets the generator.
+to use `respond_with` instead of default `respond_to` blocks. From 2.1, you need to explicitly opt-in to use this generator by adding the following to your `config/application.rb`:
+
+```ruby
+config.app_generators.scaffold_controller :responders_controller
+```
+
+## Failure handling
+
+Responders don't use `valid?` to check for errors in models to figure out if
+the request was successful or not, and relies on your controllers to call
+`save` or `create` to trigger the validations.
+
+```ruby
+def create
+  @widget = Widget.new(widget_params)
+  # @widget will be a valid record for responders, as we haven't called `save`
+  # on it, and will always redirect to the `widgets_path`.
+  respond_with @widget, location: -> { widgets_path }
+end
+```
+
+Responders will check if the `errors` object in your model is empty or not. Take
+this in consideration when implementing different actions or writing test
+assertions on this behavior for your controllers.
+
+```ruby
+def create
+  @widget = Widget.new(widget_params)
+  @widget.errors.add(:base, :invalid)
+  # `respond_with` will render the `new` template again,
+  # and set the status based on the configured `error_status`.
+  respond_with @widget
+end
+```
+
+## Verifying request formats
+
+`respond_with` will raise an `ActionController::UnknownFormat` if the request
+MIME type was not configured through the class level `respond_to`, but the
+action will still be executed and any side effects (like creating a new record)
+will still occur. To raise the `UnknownFormat` exception before your action
+is invoked you can set the `verify_requested_format!` method as a `before_action`
+on your controller.
+
+```ruby
+class WidgetsController < ApplicationController
+  respond_to :json
+  before_action :verify_requested_format!
+
+  # POST /widgets.html won't reach the `create` action.
+  def create
+    widget = Widget.create(widget_params)
+    respond_with widget
+  end
+end
+```
+
+## Configuring error and redirect statuses
+
+By default, `respond_with` will respond to errors on `HTML` & `JS` requests using the HTTP status code `200 OK`,
+and perform redirects using the HTTP status code `302 Found`, both for backwards compatibility reasons.
+
+You can configure this behavior by setting `config.responders.error_status` and `config.responders.redirect_status` to the desired status codes.
+
+```ruby
+config.responders.error_status = :unprocessable_entity
+config.responders.redirect_status = :see_other
+```
+
+These can also be set in your custom `ApplicationResponder` if you have generated one: (see install instructions)
+
+```ruby
+class ApplicationResponder < ActionController::Responder
+  self.error_status = :unprocessable_entity
+  self.redirect_status = :see_other
+end
+```
+
+_Note_: the application responder generated for new apps already configures a different set of defaults: `422 Unprocessable Entity` for errors, and `303 See Other` for redirects. _Responders may change the defaults to match these in a future major release._
+
+### Hotwire/Turbo and fetch APIs
+
+Hotwire/Turbo expects successful redirects after form submissions to respond with HTTP status `303 See Other`, and error responses to be 4xx or 5xx statuses, for example `422 Unprocessable Entity` for displaying form validation errors and `500 Internal Server Error` for other server errors. [Turbo documentation: Redirecting After a Form Submission](https://turbo.hotwired.dev/handbook/drive#redirecting-after-a-form-submission).
+
+The example configuration showed above matches the statuses that better integrate with Hotwire/Turbo.
 
 ## Examples
 
-Want more examples ? Check out this blog posts:
+Want more examples ? Check out these blog posts:
 
-* [One in Three: Inherited Resources, Has Scope and Responders](http://blog.plataformatec.com.br/2009/12/one-in-three-inherited-resources-has-scope-and-responders/)
 * [Embracing REST with mind, body and soul](http://blog.plataformatec.com.br/2009/08/embracing-rest-with-mind-body-and-soul/)
 * [Three reasons to love ActionController::Responder](http://weblog.rubyonrails.org/2009/8/31/three-reasons-love-responder/)
-* [My five favorite things about Rails 3](http://www.engineyard.com/blog/2009/my-five-favorite-things-about-rails-3/)
+* [My five favorite things about Rails 3](http://www.engineyard.com/blog/2009/my-five-favorite-things-about-rails-3)
+
+## Supported Ruby / Rails versions
+
+We intend to maintain support for all Ruby / Rails versions that haven't reached end-of-life.
+
+For more information about specific versions please check [Ruby](https://www.ruby-lang.org/en/downloads/branches/)
+and [Rails](https://guides.rubyonrails.org/maintenance_policy.html) maintenance policies, and our test matrix.
 
 ## Bugs and Feedback
 
 If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.
 
-http://github.com/plataformatec/responders/issues
-
-MIT License. Copyright 2009-2014 Plataforma Tecnologia. http://blog.plataformatec.com.br
+MIT License. Copyright 2020-2023 Rafael França, Carlos Antônio da Silva. Copyright 2009-2019 Plataformatec.

data/lib/action_controller/respond_with.rb

@@ -1,7 +1,9 @@
-require 'active_support/core_ext/array/extract_options'
-require 'action_controller/metal/mime_responds'
+# frozen_string_literal: true
 
-module ActionController #:nodoc:
+require "active_support/core_ext/array/extract_options"
+require "action_controller/metal/mime_responds"
+
+module ActionController # :nodoc:
   module RespondWith
     extend ActiveSupport::Concern
 
@@ -37,17 +39,17 @@ module ActionController #:nodoc:
       def respond_to(*mimes)
         options = mimes.extract_options!
 
-        only_actions   = Array(options.delete(:only)).map(&:to_s)
-        except_actions = Array(options.delete(:except)).map(&:to_s)
+        only_actions   = Array(options.delete(:only)).map(&:to_sym)
+        except_actions = Array(options.delete(:except)).map(&:to_sym)
 
-        new = mimes_for_respond_to.dup
+        hash = mimes_for_respond_to.dup
         mimes.each do |mime|
           mime = mime.to_sym
-          new[mime]          = {}
-          new[mime][:only]   = only_actions   unless only_actions.empty?
-          new[mime][:except] = except_actions unless except_actions.empty?
+          hash[mime]          = {}
+          hash[mime][:only]   = only_actions   unless only_actions.empty?
+          hash[mime][:except] = except_actions unless except_actions.empty?
         end
-        self.mimes_for_respond_to = new.freeze
+        self.mimes_for_respond_to = hash.freeze
       end
 
       # Clear all mime types in <tt>respond_to</tt>.
@@ -93,7 +95,10 @@ module ActionController #:nodoc:
     #      i.e. its +show+ action.
     #   2. If there are validation errors, the response
     #      renders a default action, which is <tt>:new</tt> for a
-    #      +post+ request or <tt>:edit</tt> for +patch+ or +put+.
+    #      +post+ request or <tt>:edit</tt> for +patch+ or +put+,
+    #      and the status is set based on the configured `error_status`.
+    #      (defaults to `422 Unprocessable Entity` on new apps,
+    #       `200 OK` for compatibility reasons on old apps.)
     #   Thus an example like this -
     #
     #     respond_to :html, :xml
@@ -114,8 +119,8 @@ module ActionController #:nodoc:
     #           format.html { redirect_to(@user) }
     #           format.xml { render xml: @user }
     #         else
-    #           format.html { render action: "new" }
-    #           format.xml { render xml: @user }
+    #           format.html { render action: "new", status: :unprocessable_entity }
+    #           format.xml { render xml: @user, status: :unprocessable_entity }
     #         end
     #       end
     #     end
@@ -175,26 +180,34 @@ module ActionController #:nodoc:
     # Also, a hash passed to +respond_with+ immediately after the specified
     # resource(s) is interpreted as a set of options relevant to all
     # formats. Any option accepted by +render+ can be used, e.g.
+    #
     #   respond_with @people, status: 200
+    #
     # However, note that these options are ignored after an unsuccessful attempt
     # to save a resource, e.g. when automatically rendering <tt>:new</tt>
     # after a post request.
     #
-    # Two additional options are relevant specifically to +respond_with+ -
+    # Three additional options are relevant specifically to +respond_with+ -
     # 1. <tt>:location</tt> - overwrites the default redirect location used after
     #    a successful html +post+ request.
     # 2. <tt>:action</tt> - overwrites the default render action used after an
     #    unsuccessful html +post+ request.
+    # 3. <tt>:render</tt> - allows to pass any options directly to the <tt>:render<tt/>
+    #    call after unsuccessful html +post+ request. Useful if for example you
+    #    need to render a template which is outside of controller's path or you
+    #    want to override the default http <tt>:status</tt> code, e.g.
+    #
+    #    respond_with(resource, render: { template: 'path/to/template', status: 418 })
     def respond_with(*resources, &block)
       if self.class.mimes_for_respond_to.empty?
         raise "In order to use respond_with, first you need to declare the " \
           "formats your controller responds to in the class level."
       end
 
-      mimes = collect_mimes_from_class_level()
+      mimes = collect_mimes_from_class_level
       collector = ActionController::MimeResponds::Collector.new(mimes, request.variant)
       block.call(collector) if block_given?
-      
+
       if format = collector.negotiate_format(request)
         _process_format(format)
         options = resources.size == 1 ? {} : resources.extract_options!
@@ -206,12 +219,31 @@ module ActionController #:nodoc:
       end
     end
 
-  protected
+    protected
+
+    # Before action callback that can be used to prevent requests that do not
+    # match the mime types defined through <tt>respond_to</tt> from being executed.
+    #
+    #   class PeopleController < ApplicationController
+    #     respond_to :html, :xml, :json
+    #
+    #     before_action :verify_requested_format!
+    #   end
+    def verify_requested_format!
+      mimes = collect_mimes_from_class_level
+      collector = ActionController::MimeResponds::Collector.new(mimes, request.variant)
+
+      unless collector.negotiate_format(request)
+        raise ActionController::UnknownFormat
+      end
+    end
+
+    alias :verify_request_format! :verify_requested_format!
 
     # Collect mimes declared in the class method respond_to valid for the
     # current action.
-    def collect_mimes_from_class_level #:nodoc:
-      action = action_name.to_s
+    def collect_mimes_from_class_level # :nodoc:
+      action = action_name.to_sym
 
       self.class.mimes_for_respond_to.keys.select do |mime|
         config = self.class.mimes_for_respond_to[mime]
@@ -226,4 +258,4 @@ module ActionController #:nodoc:
       end
     end
   end
-end
+end