actioncable 7.0.8.1 → 7.2.2.1

data/lib/action_cable/channel/streams.rb

@@ -1,65 +1,77 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Channel
-    # 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
@@ -69,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
 
@@ -92,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
@@ -111,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
@@ -124,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
@@ -141,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)
 
@@ -151,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)
@@ -163,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

data/lib/action_cable/channel/test_case.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support"
 require "active_support/test_case"
 require "active_support/core_ext/hash/indifferent_access"
@@ -15,9 +17,10 @@ module ActionCable
       end
     end
 
-    # Stub +stream_from+ to track streams for the channel.
-    # Add public aliases for +subscription_confirmation_sent?+ and
-    # +subscription_rejected?+.
+    # # Action Cable Channel Stub
+    #
+    # Stub `stream_from` to track streams for the channel. Add public aliases for
+    # `subscription_confirmation_sent?` and `subscription_rejected?`.
     module ChannelStub
       def confirmed?
         subscription_confirmation_sent?
@@ -45,9 +48,12 @@ module ActionCable
     end
 
     class ConnectionStub
-      attr_reader :transmissions, :identifiers, :subscriptions, :logger
+      attr_reader :server, :transmissions, :identifiers, :subscriptions, :logger
+
+      delegate :pubsub, :config, to: :server
 
       def initialize(identifiers = {})
+        @server = ActionCable.server
         @transmissions = []
 
         identifiers.each do |identifier, val|
@@ -81,103 +87,106 @@ module ActionCable
 
     # Superclass for Action Cable channel functional tests.
     #
-    # == Basic example
+    # ## Basic example
     #
     # Functional tests are written as follows:
-    # 1. First, one uses the +subscribe+ method to simulate subscription creation.
-    # 2. Then, one asserts whether the current state is as expected. "State" can be anything:
-    #    transmitted messages, subscribed streams, etc.
+    # 1.  First, one uses the `subscribe` method to simulate subscription creation.
+    # 2.  Then, one asserts whether the current state is as expected. "State" can be
+    #     anything: transmitted messages, subscribed streams, etc.
+    #
     #
     # For example:
     #
-    #   class ChatChannelTest < ActionCable::Channel::TestCase
-    #     def test_subscribed_with_room_number
-    #       # Simulate a subscription creation
-    #       subscribe room_number: 1
+    #     class ChatChannelTest < ActionCable::Channel::TestCase
+    #       def test_subscribed_with_room_number
+    #         # Simulate a subscription creation
+    #         subscribe room_number: 1
     #
-    #       # Asserts that the subscription was successfully created
-    #       assert subscription.confirmed?
+    #         # Asserts that the subscription was successfully created
+    #         assert subscription.confirmed?
     #
-    #       # Asserts that the channel subscribes connection to a stream
-    #       assert_has_stream "chat_1"
+    #         # Asserts that the channel subscribes connection to a stream
+    #         assert_has_stream "chat_1"
     #
-    #       # Asserts that the channel subscribes connection to a specific
-    #       # stream created for a model
-    #       assert_has_stream_for Room.find(1)
-    #     end
+    #         # Asserts that the channel subscribes connection to a specific
+    #         # stream created for a model
+    #         assert_has_stream_for Room.find(1)
+    #       end
     #
-    #     def test_does_not_stream_with_incorrect_room_number
-    #       subscribe room_number: -1
+    #       def test_does_not_stream_with_incorrect_room_number
+    #         subscribe room_number: -1
     #
-    #       # Asserts that not streams was started
-    #       assert_no_streams
-    #     end
+    #         # Asserts that not streams was started
+    #         assert_no_streams
+    #       end
     #
-    #     def test_does_not_subscribe_without_room_number
-    #       subscribe
+    #       def test_does_not_subscribe_without_room_number
+    #         subscribe
     #
-    #       # Asserts that the subscription was rejected
-    #       assert subscription.rejected?
+    #         # Asserts that the subscription was rejected
+    #         assert subscription.rejected?
+    #       end
     #     end
-    #   end
     #
     # You can also perform actions:
-    #   def test_perform_speak
-    #     subscribe room_number: 1
+    #     def test_perform_speak
+    #       subscribe room_number: 1
+    #
+    #       perform :speak, message: "Hello, Rails!"
     #
-    #     perform :speak, message: "Hello, Rails!"
+    #       assert_equal "Hello, Rails!", transmissions.last["text"]
+    #     end
+    #
+    # ## Special methods
     #
-    #     assert_equal "Hello, Rails!", transmissions.last["text"]
-    #   end
+    # ActionCable::Channel::TestCase will also automatically provide the following
+    # instance methods for use in the tests:
     #
-    # == Special methods
+    # connection
+    # :   An ActionCable::Channel::ConnectionStub, representing the current HTTP
+    #     connection.
     #
-    # ActionCable::Channel::TestCase will also automatically provide the following instance
-    # methods for use in the tests:
+    # subscription
+    # :   An instance of the current channel, created when you call `subscribe`.
     #
-    # <b>connection</b>::
-    #      An ActionCable::Channel::ConnectionStub, representing the current HTTP connection.
-    # <b>subscription</b>::
-    #      An instance of the current channel, created when you call +subscribe+.
-    # <b>transmissions</b>::
-    #      A list of all messages that have been transmitted into the channel.
+    # transmissions
+    # :   A list of all messages that have been transmitted into the channel.
     #
     #
-    # == Channel is automatically inferred
+    # ## Channel is automatically inferred
     #
     # ActionCable::Channel::TestCase will automatically infer the channel under test
     # from the test class name. If the channel cannot be inferred from the test
-    # class name, you can explicitly set it with +tests+.
-    #
-    #   class SpecialEdgeCaseChannelTest < ActionCable::Channel::TestCase
-    #     tests SpecialChannel
-    #   end
+    # class name, you can explicitly set it with `tests`.
     #
-    # == Specifying connection identifiers
+    #     class SpecialEdgeCaseChannelTest < ActionCable::Channel::TestCase
+    #       tests SpecialChannel
+    #     end
     #
-    # You need to set up your connection manually to provide values for the identifiers.
-    # To do this just use:
+    # ## Specifying connection identifiers
     #
-    #   stub_connection(user: users(:john))
+    # You need to set up your connection manually to provide values for the
+    # identifiers. To do this just use:
     #
-    # == Testing broadcasting
+    #     stub_connection(user: users(:john))
     #
-    # ActionCable::Channel::TestCase enhances ActionCable::TestHelper assertions (e.g.
-    # +assert_broadcasts+) to handle broadcasting to models:
+    # ## Testing broadcasting
     #
+    # ActionCable::Channel::TestCase enhances ActionCable::TestHelper assertions
+    # (e.g. `assert_broadcasts`) to handle broadcasting to models:
     #
-    #  # in your channel
-    #  def speak(data)
-    #    broadcast_to room, text: data["message"]
-    #  end
+    #     # in your channel
+    #     def speak(data)
+    #       broadcast_to room, text: data["message"]
+    #     end
     #
-    #  def test_speak
-    #    subscribe room_id: rooms(:chat).id
+    #     def test_speak
+    #       subscribe room_id: rooms(:chat).id
     #
-    #    assert_broadcast_on(rooms(:chat), text: "Hello, Rails!") do
-    #      perform :speak, message: "Hello, Rails!"
-    #    end
-    #  end
+    #       assert_broadcast_on(rooms(:chat), text: "Hello, Rails!") do
+    #         perform :speak, message: "Hello, Rails!"
+    #       end
+    #     end
     class TestCase < ActiveSupport::TestCase
       module Behavior
         extend ActiveSupport::Concern
@@ -226,16 +235,17 @@ module ActionCable
 
         # Set up test connection with the specified identifiers:
         #
-        #   class ApplicationCable < ActionCable::Connection::Base
-        #     identified_by :user, :token
-        #   end
+        #     class ApplicationCable < ActionCable::Connection::Base
+        #       identified_by :user, :token
+        #     end
         #
-        #   stub_connection(user: users[:john], token: 'my-secret-token')
+        #     stub_connection(user: users[:john], token: 'my-secret-token')
         def stub_connection(identifiers = {})
           @connection = ConnectionStub.new(identifiers)
         end
 
-        # Subscribe to the channel under test. Optionally pass subscription parameters as a Hash.
+        # Subscribe to the channel under test. Optionally pass subscription parameters
+        # as a Hash.
         def subscribe(params = {})
           @connection ||= stub_connection
           @subscription = self.class.channel_class.new(connection, CHANNEL_IDENTIFIER, params.with_indifferent_access)
@@ -264,8 +274,7 @@ module ActionCable
           connection.transmissions.filter_map { |data| data["message"] }
         end
 
-        # Enhance TestHelper assertions to handle non-String
-        # broadcastings
+        # Enhance TestHelper assertions to handle non-String broadcastings
         def assert_broadcasts(stream_or_object, *args)
           super(broadcasting_for(stream_or_object), *args)
         end
@@ -276,10 +285,10 @@ module ActionCable
 
         # Asserts that no streams have been started.
         #
-        #   def test_assert_no_started_stream
-        #     subscribe
-        #     assert_no_streams
-        #   end
+        #     def test_assert_no_started_stream
+        #       subscribe
+        #       assert_no_streams
+        #     end
         #
         def assert_no_streams
           assert subscription.streams.empty?, "No streams started was expected, but #{subscription.streams.count} found"
@@ -287,10 +296,10 @@ module ActionCable
 
         # Asserts that the specified stream has been started.
         #
-        #   def test_assert_started_stream
-        #     subscribe
-        #     assert_has_stream 'messages'
-        #   end
+        #     def test_assert_started_stream
+        #       subscribe
+        #       assert_has_stream 'messages'
+        #     end
         #
         def assert_has_stream(stream)
           assert subscription.streams.include?(stream), "Stream #{stream} has not been started"
@@ -298,15 +307,37 @@ module ActionCable
 
         # Asserts that the specified stream for a model has started.
         #
-        #   def test_assert_started_stream_for
-        #     subscribe id: 42
-        #     assert_has_stream_for User.find(42)
-        #   end
+        #     def test_assert_started_stream_for
+        #       subscribe id: 42
+        #       assert_has_stream_for User.find(42)
+        #     end
         #
         def assert_has_stream_for(object)
           assert_has_stream(broadcasting_for(object))
         end
 
+        # Asserts that the specified stream has not been started.
+        #
+        #     def test_assert_no_started_stream
+        #       subscribe
+        #       assert_has_no_stream 'messages'
+        #     end
+        #
+        def assert_has_no_stream(stream)
+          assert subscription.streams.exclude?(stream), "Stream #{stream} has been started"
+        end
+
+        # Asserts that the specified stream for a model has not started.
+        #
+        #     def test_assert_no_started_stream_for
+        #       subscribe id: 41
+        #       assert_has_no_stream_for User.find(42)
+        #     end
+        #
+        def assert_has_no_stream_for(object)
+          assert_has_no_stream(broadcasting_for(object))
+        end
+
         private
           def check_subscribed!
             raise "Must be subscribed!" if subscription.nil? || subscription.rejected?

data/lib/action_cable/connection/authorization.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Connection
     module Authorization
       class UnauthorizedError < StandardError; end
 
-      # Closes the WebSocket connection if it is open and returns a 404 "File not Found" response.
+      # Closes the WebSocket connection if it is open and returns an "unauthorized"
+      # reason.
       def reject_unauthorized_connection
         logger.error "An unauthorized connection attempt was rejected"
         raise UnauthorizedError