actioncable 7.1.5 → 7.2.0.beta1

data/lib/action_cable/channel/callbacks.rb

@@ -1,36 +1,39 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/callbacks"
 
 module ActionCable
   module Channel
-    # = Action Cable \Channel \Callbacks
+    # # Action Cable Channel Callbacks
+    #
+    # Action Cable Channel provides callback hooks that are invoked during the life
+    # cycle of a channel:
     #
-    # Action Cable Channel provides callback hooks that are invoked during the
-    # life cycle of a channel:
+    # *   [before_subscribe](rdoc-ref:ClassMethods#before_subscribe)
+    # *   [after_subscribe](rdoc-ref:ClassMethods#after_subscribe) (aliased as
+    #     [on_subscribe](rdoc-ref:ClassMethods#on_subscribe))
+    # *   [before_unsubscribe](rdoc-ref:ClassMethods#before_unsubscribe)
+    # *   [after_unsubscribe](rdoc-ref:ClassMethods#after_unsubscribe) (aliased as
+    #     [on_unsubscribe](rdoc-ref:ClassMethods#on_unsubscribe))
     #
-    # * {before_subscribe}[rdoc-ref:ClassMethods#before_subscribe]
-    # * {after_subscribe}[rdoc-ref:ClassMethods#after_subscribe] (aliased as
-    #   {on_subscribe}[rdoc-ref:ClassMethods#on_subscribe])
-    # * {before_unsubscribe}[rdoc-ref:ClassMethods#before_unsubscribe]
-    # * {after_unsubscribe}[rdoc-ref:ClassMethods#after_unsubscribe] (aliased as
-    #   {on_unsubscribe}[rdoc-ref:ClassMethods#on_unsubscribe])
     #
-    # ==== Example
+    # #### Example
     #
-    #   class ChatChannel < ApplicationCable::Channel
-    #     after_subscribe :send_welcome_message, unless: :subscription_rejected?
-    #     after_subscribe :track_subscription
+    #     class ChatChannel < ApplicationCable::Channel
+    #       after_subscribe :send_welcome_message, unless: :subscription_rejected?
+    #       after_subscribe :track_subscription
     #
-    #     private
-    #       def send_welcome_message
-    #         broadcast_to(...)
-    #       end
+    #       private
+    #         def send_welcome_message
+    #           broadcast_to(...)
+    #         end
     #
-    #       def track_subscription
-    #         # ...
-    #       end
-    #   end
+    #         def track_subscription
+    #           # ...
+    #         end
+    #     end
     #
     module Callbacks
       extend  ActiveSupport::Concern
@@ -46,14 +49,13 @@ module ActionCable
           set_callback(:subscribe, :before, *methods, &block)
         end
 
-        # This callback will be triggered after the Base#subscribed method is
-        # called, even if the subscription was rejected with the Base#reject
-        # method.
+        # This callback will be triggered after the Base#subscribed method is called,
+        # even if the subscription was rejected with the Base#reject method.
         #
         # To trigger the callback only on successful subscriptions, use the
         # Base#subscription_rejected? method:
         #
-        #   after_subscribe :my_method, unless: :subscription_rejected?
+        #     after_subscribe :my_method, unless: :subscription_rejected?
         #
         def after_subscribe(*methods, &block)
           set_callback(:subscribe, :after, *methods, &block)

data/lib/action_cable/channel/naming.rb

@@ -1,26 +1,27 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Channel
     module Naming
       extend ActiveSupport::Concern
 
       module ClassMethods
-        # Returns the name of the channel, underscored, without the <tt>Channel</tt> ending.
-        # If the channel is in a namespace, then the namespaces are represented by single
+        # Returns the name of the channel, underscored, without the `Channel` ending. If
+        # the channel is in a namespace, then the namespaces are represented by single
         # colon separators in the channel name.
         #
-        #   ChatChannel.channel_name # => 'chat'
-        #   Chats::AppearancesChannel.channel_name # => 'chats:appearances'
-        #   FooChats::BarAppearancesChannel.channel_name # => 'foo_chats:bar_appearances'
+        #     ChatChannel.channel_name # => 'chat'
+        #     Chats::AppearancesChannel.channel_name # => 'chats:appearances'
+        #     FooChats::BarAppearancesChannel.channel_name # => 'foo_chats:bar_appearances'
         def channel_name
           @channel_name ||= name.delete_suffix("Channel").gsub("::", ":").underscore
         end
       end
 
-      included do
-        # Delegates to the class's ::channel_name.
-        delegate :channel_name, to: :class
+      def channel_name
+        self.class.channel_name
       end
     end
   end

data/lib/action_cable/channel/periodic_timers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Channel
     module PeriodicTimers
@@ -13,14 +15,12 @@ module ActionCable
       end
 
       module ClassMethods
-        # Periodically performs a task on the channel, like updating an online
-        # user counter, polling a backend for new status messages, sending
-        # regular "heartbeat" messages, or doing some internal work and giving
-        # progress updates.
+        # Periodically performs a task on the channel, like updating an online user
+        # counter, polling a backend for new status messages, sending regular
+        # "heartbeat" messages, or doing some internal work and giving progress updates.
         #
-        # Pass a method name or lambda argument or provide a block to call.
-        # Specify the calling period in seconds using the <tt>every:</tt>
-        # keyword argument.
+        # Pass a method name or lambda argument or provide a block to call. Specify the
+        # calling period in seconds using the `every:` keyword argument.
         #
         #     periodically :transmit_progress, every: 5.seconds
         #

data/lib/action_cable/channel/streams.rb

@@ -1,67 +1,77 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Channel
-    # = Action Cable \Channel \Streams
-    #
-    # Streams allow channels to route broadcastings to the subscriber. A broadcasting is, as discussed elsewhere, a pubsub queue where any data
-    # placed into it is automatically sent to the clients that are connected at that time. It's purely an online queue, though. If you're not
-    # streaming a broadcasting at the very moment it sends out an update, you will not get that update, even if you connect after it has been sent.
-    #
-    # Most commonly, the streamed broadcast is sent straight to the subscriber on the client-side. The channel just acts as a connector between
-    # the two parties (the broadcaster and the channel subscriber). Here's an example of a channel that allows subscribers to get all new
-    # comments on a given page:
-    #
-    #   class CommentsChannel < ApplicationCable::Channel
-    #     def follow(data)
-    #       stream_from "comments_for_#{data['recording_id']}"
-    #     end
+    # # Action Cable Channel Streams
+    #
+    # Streams allow channels to route broadcastings to the subscriber. A
+    # broadcasting is, as discussed elsewhere, a pubsub queue where any data placed
+    # into it is automatically sent to the clients that are connected at that time.
+    # It's purely an online queue, though. If you're not streaming a broadcasting at
+    # the very moment it sends out an update, you will not get that update, even if
+    # you connect after it has been sent.
+    #
+    # Most commonly, the streamed broadcast is sent straight to the subscriber on
+    # the client-side. The channel just acts as a connector between the two parties
+    # (the broadcaster and the channel subscriber). Here's an example of a channel
+    # that allows subscribers to get all new comments on a given page:
+    #
+    #     class CommentsChannel < ApplicationCable::Channel
+    #       def follow(data)
+    #         stream_from "comments_for_#{data['recording_id']}"
+    #       end
     #
-    #     def unfollow
-    #       stop_all_streams
+    #       def unfollow
+    #         stop_all_streams
+    #       end
     #     end
-    #   end
     #
-    # Based on the above example, the subscribers of this channel will get whatever data is put into the,
-    # let's say, <tt>comments_for_45</tt> broadcasting as soon as it's put there.
+    # Based on the above example, the subscribers of this channel will get whatever
+    # data is put into the, let's say, `comments_for_45` broadcasting as soon as
+    # it's put there.
     #
     # An example broadcasting for this channel looks like so:
     #
-    #   ActionCable.server.broadcast "comments_for_45", { author: 'DHH', content: 'Rails is just swell' }
+    #     ActionCable.server.broadcast "comments_for_45", { author: 'DHH', content: 'Rails is just swell' }
     #
-    # If you have a stream that is related to a model, then the broadcasting used can be generated from the model and channel.
-    # The following example would subscribe to a broadcasting like <tt>comments:Z2lkOi8vVGVzdEFwcC9Qb3N0LzE</tt>.
+    # If you have a stream that is related to a model, then the broadcasting used
+    # can be generated from the model and channel. The following example would
+    # subscribe to a broadcasting like `comments:Z2lkOi8vVGVzdEFwcC9Qb3N0LzE`.
     #
-    #   class CommentsChannel < ApplicationCable::Channel
-    #     def subscribed
-    #       post = Post.find(params[:id])
-    #       stream_for post
+    #     class CommentsChannel < ApplicationCable::Channel
+    #       def subscribed
+    #         post = Post.find(params[:id])
+    #         stream_for post
+    #       end
     #     end
-    #   end
     #
     # You can then broadcast to this channel using:
     #
-    #   CommentsChannel.broadcast_to(@post, @comment)
+    #     CommentsChannel.broadcast_to(@post, @comment)
     #
-    # If you don't just want to parlay the broadcast unfiltered to the subscriber, you can also supply a callback that lets you alter what is sent out.
-    # The below example shows how you can use this to provide performance introspection in the process:
+    # If you don't just want to parlay the broadcast unfiltered to the subscriber,
+    # you can also supply a callback that lets you alter what is sent out. The below
+    # example shows how you can use this to provide performance introspection in the
+    # process:
     #
-    #   class ChatChannel < ApplicationCable::Channel
-    #     def subscribed
-    #       @room = Chat::Room[params[:room_number]]
+    #     class ChatChannel < ApplicationCable::Channel
+    #       def subscribed
+    #         @room = Chat::Room[params[:room_number]]
     #
-    #       stream_for @room, coder: ActiveSupport::JSON do |message|
-    #         if message['originated_at'].present?
-    #           elapsed_time = (Time.now.to_f - message['originated_at']).round(2)
+    #         stream_for @room, coder: ActiveSupport::JSON do |message|
+    #           if message['originated_at'].present?
+    #             elapsed_time = (Time.now.to_f - message['originated_at']).round(2)
     #
-    #           ActiveSupport::Notifications.instrument :performance, measurement: 'Chat.message_delay', value: elapsed_time, action: :timing
-    #           logger.info "Message took #{elapsed_time}s to arrive"
-    #         end
+    #             ActiveSupport::Notifications.instrument :performance, measurement: 'Chat.message_delay', value: elapsed_time, action: :timing
+    #             logger.info "Message took #{elapsed_time}s to arrive"
+    #           end
     #
-    #         transmit message
+    #           transmit message
+    #         end
     #       end
     #     end
-    #   end
     #
     # You can stop streaming from all broadcasts by calling #stop_all_streams.
     module Streams
@@ -71,18 +81,20 @@ module ActionCable
         on_unsubscribe :stop_all_streams
       end
 
-      # Start streaming from the named <tt>broadcasting</tt> pubsub queue. Optionally, you can pass a <tt>callback</tt> that'll be used
-      # instead of the default of just transmitting the updates straight to the subscriber.
-      # Pass <tt>coder: ActiveSupport::JSON</tt> to decode messages as JSON before passing to the callback.
-      # Defaults to <tt>coder: nil</tt> which does no decoding, passes raw messages.
+      # Start streaming from the named `broadcasting` pubsub queue. Optionally, you
+      # can pass a `callback` that'll be used instead of the default of just
+      # transmitting the updates straight to the subscriber. Pass `coder:
+      # ActiveSupport::JSON` to decode messages as JSON before passing to the
+      # callback. Defaults to `coder: nil` which does no decoding, passes raw
+      # messages.
       def stream_from(broadcasting, callback = nil, coder: nil, &block)
         broadcasting = String(broadcasting)
 
         # Don't send the confirmation until pubsub#subscribe is successful
         defer_subscription_confirmation!
 
-        # Build a stream handler by wrapping the user-provided callback with
-        # a decoder or defaulting to a JSON-decoding retransmitter.
+        # Build a stream handler by wrapping the user-provided callback with a decoder
+        # or defaulting to a JSON-decoding retransmitter.
         handler = worker_pool_stream_handler(broadcasting, callback || block, coder: coder)
         streams[broadcasting] = handler
 
@@ -94,17 +106,18 @@ module ActionCable
         end
       end
 
-      # Start streaming the pubsub queue for the <tt>model</tt> in this channel. Optionally, you can pass a
-      # <tt>callback</tt> that'll be used instead of the default of just transmitting the updates straight
-      # to the subscriber.
+      # Start streaming the pubsub queue for the `model` in this channel. Optionally,
+      # you can pass a `callback` that'll be used instead of the default of just
+      # transmitting the updates straight to the subscriber.
       #
-      # Pass <tt>coder: ActiveSupport::JSON</tt> to decode messages as JSON before passing to the callback.
-      # Defaults to <tt>coder: nil</tt> which does no decoding, passes raw messages.
+      # Pass `coder: ActiveSupport::JSON` to decode messages as JSON before passing to
+      # the callback. Defaults to `coder: nil` which does no decoding, passes raw
+      # messages.
       def stream_for(model, callback = nil, coder: nil, &block)
         stream_from(broadcasting_for(model), callback || block, coder: coder)
       end
 
-      # Unsubscribes streams from the named <tt>broadcasting</tt>.
+      # Unsubscribes streams from the named `broadcasting`.
       def stop_stream_from(broadcasting)
         callback = streams.delete(broadcasting)
         if callback
@@ -113,7 +126,7 @@ module ActionCable
         end
       end
 
-      # Unsubscribes streams for the <tt>model</tt>.
+      # Unsubscribes streams for the `model`.
       def stop_stream_for(model)
         stop_stream_from(broadcasting_for(model))
       end
@@ -126,7 +139,7 @@ module ActionCable
         end.clear
       end
 
-      # Calls stream_for with the given <tt>model</tt> if it's present to start streaming,
+      # Calls stream_for with the given `model` if it's present to start streaming,
       # otherwise rejects the subscription.
       def stream_or_reject_for(model)
         if model
@@ -143,8 +156,8 @@ module ActionCable
           @_streams ||= {}
         end
 
-        # Always wrap the outermost handler to invoke the user handler on the
-        # worker pool rather than blocking the event loop.
+        # Always wrap the outermost handler to invoke the user handler on the worker
+        # pool rather than blocking the event loop.
         def worker_pool_stream_handler(broadcasting, user_handler, coder: nil)
           handler = stream_handler(broadcasting, user_handler, coder: coder)
 
@@ -153,8 +166,8 @@ module ActionCable
           end
         end
 
-        # May be overridden to add instrumentation, logging, specialized error
-        # handling, or other forms of handler decoration.
+        # May be overridden to add instrumentation, logging, specialized error handling,
+        # or other forms of handler decoration.
         #
         # TODO: Tests demonstrating this.
         def stream_handler(broadcasting, user_handler, coder: nil)
@@ -165,14 +178,14 @@ module ActionCable
           end
         end
 
-        # May be overridden to change the default stream handling behavior
-        # which decodes JSON and transmits to the client.
+        # May be overridden to change the default stream handling behavior which decodes
+        # JSON and transmits to the client.
         #
         # TODO: Tests demonstrating this.
         #
-        # TODO: Room for optimization. Update transmit API to be coder-aware
-        # so we can no-op when pubsub and connection are both JSON-encoded.
-        # Then we can skip decode+encode if we're just proxying messages.
+        # TODO: Room for optimization. Update transmit API to be coder-aware so we can
+        # no-op when pubsub and connection are both JSON-encoded. Then we can skip
+        # decode+encode if we're just proxying messages.
         def default_stream_handler(broadcasting, coder:)
           coder ||= ActiveSupport::JSON
           stream_transmitter stream_decoder(coder: coder), broadcasting: broadcasting