Merge pull request rails#45469 from skryukov/docs-for-action-cable-channel-callbacks [ci-skip]

Document Action Cable Callbacks

Author: p8

actioncable/lib/action_cable/channel/callbacks.rb

@@ -4,6 +4,22 @@
 
 module ActionCable
   module Channel
+    # = Action Cable Channel Callbacks
+    #
+    # Action Cable Channel provides hooks during the life cycle of a channel subscription.
+    # Callbacks allow triggering logic during this cycle. Available callbacks are:
+    #
+    # * <tt>before_subscribe</tt>
+    # * <tt>after_subscribe</tt> (also aliased as: <tt>on_subscribe</tt>)
+    # * <tt>before_unsubscribe</tt>
+    # * <tt>after_unsubscribe</tt> (also aliased as: <tt>on_unsubscribe</tt>)
+    #
+    # NOTE: the <tt>after_subscribe</tt> callback is triggered whenever
+    # the <tt>subscribed</tt> method is called, even if subscription was rejected
+    # with the <tt>reject</tt> method.
+    # To trigger <tt>after_subscribe</tt> only on successful subscriptions,
+    # use <tt>after_subscribe :my_method_name, unless: :subscription_rejected?</tt>
+    #
     module Callbacks
       extend  ActiveSupport::Concern
       include ActiveSupport::Callbacks

actioncable/lib/action_cable/connection/callbacks.rb

@@ -4,6 +4,27 @@
 
 module ActionCable
   module Connection
+    # = Action Cable Connection Callbacks
+    #
+    # There are <tt>before_command</tt>, <tt>after_command</tt>, and <tt>around_command</tt> callbacks
+    # available to be invoked before, after or around every command received by a client respectively.
+    # The term "command" here refers to any interaction received by a client (subscribing, unsubscribing or performing actions):
+    #
+    #    module ApplicationCable
+    #      class Connection < ActionCable::Connection::Base
+    #        identified_by :user
+    #
+    #        around_command :set_current_account
+    #
+    #        private
+    #
+    #        def set_current_account
+    #          # Now all channels could use Current.account
+    #          Current.set(account: user.account) { yield }
+    #        end
+    #      end
+    #    end
+    #
     module Callbacks
       extend  ActiveSupport::Concern
       include ActiveSupport::Callbacks

guides/source/action_cable_overview.md

@@ -165,6 +165,29 @@ end
 
 [`rescue_from`]: https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html#method-i-rescue_from
 
+#### Connection Callbacks
+
+There are `before_command`, `after_command`, and `around_command` callbacks available to be invoked before, after or around every command received by a client respectively.
+The term "command" here refers to any interaction received by a client (subscribing, unsubscribing or performing actions):
+
+```ruby
+# app/channels/application_cable/connection.rb
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :user
+
+    around_command :set_current_account
+
+    private
+
+    def set_current_account
+      # Now all channels could use Current.account
+      Current.set(account: user.account) { yield }
+    end
+  end
+end
+```
+
 ### Channels
 
 A *channel* encapsulates a logical unit of work, similar to what a controller does in a
@@ -234,6 +257,38 @@ class ChatChannel < ApplicationCable::Channel
 end
 ```
 
+#### Channel Callbacks
+
+`ApplicationCable::Channel` provides a number of callbacks that can be used to trigger logic
+during the life cycle of a channel. Available callbacks are:
+
+- `before_subscribe`
+- `after_subscribe` (also aliased as: `on_subscribe`)
+- `before_unsubscribe`
+- `after_unsubscribe` (also aliased as: `on_unsubscribe`)
+
+NOTE: The `after_subscribe` callback is triggered whenever the `subscribed` method is called,
+even if subscription was rejected with the `reject` method. To trigger `after_subscribe`
+only on successful subscriptions, use `after_subscribe :send_welcome_message, unless: :subscription_rejected?`
+
+```ruby
+# app/channels/chat_channel.rb
+class ChatChannel < ApplicationCable::Channel
+  after_subscribe :send_welcome_message, unless: :subscription_rejected?
+  after_subscribe :track_subscription
+
+  private
+
+  def send_welcome_message
+    broadcast_to(...)
+  end
+  
+  def track_subscription
+    # ...
+  end
+end
+```
+
 ## Client-Side Components
 
 ### Connections