actioncable 7.1.3.4 → 7.2.0.beta1

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,11 +17,10 @@ module ActionCable
       end
     end
 
-    # = Action Cable \Channel Stub
+    # # Action Cable Channel Stub
     #
-    # Stub +stream_from+ to track streams for the channel.
-    # Add public aliases for +subscription_confirmation_sent?+ and
-    # +subscription_rejected?+.
+    # 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?
@@ -86,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
+    #       assert_equal "Hello, Rails!", transmissions.last["text"]
+    #     end
+    #
+    # ## Special methods
+    #
+    # 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 name, you can explicitly set it with `tests`.
     #
-    #   class SpecialEdgeCaseChannelTest < ActionCable::Channel::TestCase
-    #     tests SpecialChannel
-    #   end
-    #
-    # == 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
@@ -231,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)
@@ -269,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
@@ -281,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"
@@ -292,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"
@@ -303,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 an "unauthorized" reason.
+      # 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

data/lib/action_cable/connection/base.rb

@@ -1,48 +1,57 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "action_dispatch"
 require "active_support/rescuable"
 
 module ActionCable
   module Connection
-    # = Action Cable \Connection \Base
+    # # Action Cable Connection Base
     #
-    # For every WebSocket connection the Action Cable server accepts, a Connection object will be instantiated. This instance becomes the parent
-    # of all of the channel subscriptions that are created from there on. Incoming messages are then routed to these channel subscriptions
-    # based on an identifier sent by the Action Cable consumer. The Connection itself does not deal with any specific application logic beyond
-    # authentication and authorization.
+    # For every WebSocket connection the Action Cable server accepts, a Connection
+    # object will be instantiated. This instance becomes the parent of all of the
+    # channel subscriptions that are created from there on. Incoming messages are
+    # then routed to these channel subscriptions based on an identifier sent by the
+    # Action Cable consumer. The Connection itself does not deal with any specific
+    # application logic beyond authentication and authorization.
     #
     # Here's a basic example:
     #
-    #   module ApplicationCable
-    #     class Connection < ActionCable::Connection::Base
-    #       identified_by :current_user
-    #
-    #       def connect
-    #         self.current_user = find_verified_user
-    #         logger.add_tags current_user.name
-    #       end
+    #     module ApplicationCable
+    #       class Connection < ActionCable::Connection::Base
+    #         identified_by :current_user
     #
-    #       def disconnect
-    #         # Any cleanup work needed when the cable connection is cut.
-    #       end
+    #         def connect
+    #           self.current_user = find_verified_user
+    #           logger.add_tags current_user.name
+    #         end
     #
-    #       private
-    #         def find_verified_user
-    #           User.find_by_identity(cookies.encrypted[:identity_id]) ||
-    #             reject_unauthorized_connection
+    #         def disconnect
+    #           # Any cleanup work needed when the cable connection is cut.
     #         end
+    #
+    #         private
+    #           def find_verified_user
+    #             User.find_by_identity(cookies.encrypted[:identity_id]) ||
+    #               reject_unauthorized_connection
+    #           end
+    #       end
     #     end
-    #   end
     #
-    # First, we declare that this connection can be identified by its current_user. This allows us to later be able to find all connections
-    # established for that current_user (and potentially disconnect them). You can declare as many
-    # identification indexes as you like. Declaring an identification means that an attr_accessor is automatically set for that key.
+    # First, we declare that this connection can be identified by its current_user.
+    # This allows us to later be able to find all connections established for that
+    # current_user (and potentially disconnect them). You can declare as many
+    # identification indexes as you like. Declaring an identification means that an
+    # attr_accessor is automatically set for that key.
     #
-    # Second, we rely on the fact that the WebSocket connection is established with the cookies from the domain being sent along. This makes
-    # it easy to use signed cookies that were set when logging in via a web interface to authorize the WebSocket connection.
+    # Second, we rely on the fact that the WebSocket connection is established with
+    # the cookies from the domain being sent along. This makes it easy to use signed
+    # cookies that were set when logging in via a web interface to authorize the
+    # WebSocket connection.
     #
-    # Finally, we add a tag to the connection-specific logger with the name of the current user to easily distinguish their messages in the log.
+    # Finally, we add a tag to the connection-specific logger with the name of the
+    # current user to easily distinguish their messages in the log.
     #
     # Pretty simple, eh?
     class Base
@@ -69,8 +78,10 @@ module ActionCable
         @started_at = Time.now
       end
 
-      # Called by the server when a new WebSocket connection is established. This configures the callbacks intended for overwriting by the user.
-      # This method should not be called directly -- instead rely upon on the #connect (and #disconnect) callbacks.
+      # Called by the server when a new WebSocket connection is established. This
+      # configures the callbacks intended for overwriting by the user. This method
+      # should not be called directly -- instead rely upon on the #connect (and
+      # #disconnect) callbacks.
       def process # :nodoc:
         logger.info started_request_message
 
@@ -115,13 +126,15 @@ module ActionCable
         websocket.close
       end
 
-      # Invoke a method on the connection asynchronously through the pool of thread workers.
+      # Invoke a method on the connection asynchronously through the pool of thread
+      # workers.
       def send_async(method, *arguments)
         worker_pool.async_invoke(self, method, *arguments)
       end
 
-      # Return a basic hash of statistics for the connection keyed with <tt>identifier</tt>, <tt>started_at</tt>, <tt>subscriptions</tt>, and <tt>request_id</tt>.
-      # This can be returned by a health check against the connection.
+      # Return a basic hash of statistics for the connection keyed with `identifier`,
+      # `started_at`, `subscriptions`, and `request_id`. This can be returned by a
+      # health check against the connection.
       def statistics
         {
           identifier: connection_identifier,
@@ -160,7 +173,8 @@ module ActionCable
         attr_reader :websocket
         attr_reader :message_buffer
 
-        # The request that initiated the WebSocket connection is available here. This gives access to the environment, cookies, etc.
+        # The request that initiated the WebSocket connection is available here. This
+        # gives access to the environment, cookies, etc.
         def request # :doc:
           @request ||= begin
             environment = Rails.application.env_config.merge(env) if defined?(Rails.application) && Rails.application
@@ -168,7 +182,8 @@ module ActionCable
           end
         end
 
-        # The cookies of the request that initiated the WebSocket connection. Useful for performing authorization checks.
+        # The cookies of the request that initiated the WebSocket connection. Useful for
+        # performing authorization checks.
         def cookies # :doc:
           request.cookie_jar
         end
@@ -205,9 +220,8 @@ module ActionCable
         end
 
         def send_welcome_message
-          # Send welcome message to the internal connection monitor channel.
-          # This ensures the connection monitor state is reset after a successful
-          # websocket connection.
+          # Send welcome message to the internal connection monitor channel. This ensures
+          # the connection monitor state is reset after a successful websocket connection.
           transmit type: ActionCable::INTERNAL[:message_types][:welcome]
         end
 
@@ -238,7 +252,8 @@ module ActionCable
           [ 404, { Rack::CONTENT_TYPE => "text/plain; charset=utf-8" }, [ "Page not found" ] ]
         end
 
-        # Tags are declared in the server but computed in the connection. This allows us per-connection tailored tags.
+        # Tags are declared in the server but computed in the connection. This allows us
+        # per-connection tailored tags.
         def new_tagged_logger
           TaggedLoggerProxy.new server.logger,
             tags: server.config.log_tags.map { |tag| tag.respond_to?(:call) ? tag.call(request) : tag.to_s.camelize }

data/lib/action_cable/connection/callbacks.rb

@@ -1,33 +1,35 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/callbacks"
 
 module ActionCable
   module Connection
-    # = Action Cable \Connection \Callbacks
+    # # Action Cable Connection Callbacks
     #
-    # The {before_command}[rdoc-ref:ClassMethods#before_command],
-    # {after_command}[rdoc-ref:ClassMethods#after_command], and
-    # {around_command}[rdoc-ref:ClassMethods#around_command] callbacks are
-    # invoked when sending commands to the client, such as when subscribing,
-    # unsubscribing, or performing an action.
+    # The [before_command](rdoc-ref:ClassMethods#before_command),
+    # [after_command](rdoc-ref:ClassMethods#after_command), and
+    # [around_command](rdoc-ref:ClassMethods#around_command) callbacks are invoked
+    # when sending commands to the client, such as when subscribing, unsubscribing,
+    # or performing an action.
     #
-    # ==== Example
+    # #### Example
     #
-    #    module ApplicationCable
-    #      class Connection < ActionCable::Connection::Base
-    #        identified_by :user
+    #     module ApplicationCable
+    #       class Connection < ActionCable::Connection::Base
+    #         identified_by :user
     #
-    #        around_command :set_current_account
+    #         around_command :set_current_account
     #
-    #        private
+    #         private
     #
-    #        def set_current_account
-    #          # Now all channels could use Current.account
-    #          Current.set(account: user.account) { yield }
-    #        end
-    #      end
-    #    end
+    #         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

data/lib/action_cable/connection/client_socket.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "websocket/driver"
 
 module ActionCable
@@ -43,7 +45,7 @@ module ActionCable
 
         @ready_state = CONNECTING
 
-        # The driver calls +env+, +url+, and +write+
+        # The driver calls `env`, `url`, and `write`
         @driver = ::WebSocket::Driver.rack(self, protocols: protocols)
 
         @driver.on(:open)    { |e| open }

data/lib/action_cable/connection/identification.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "set"
 
 module ActionCable
@@ -12,18 +14,20 @@ module ActionCable
       end
 
       module ClassMethods
-        # Mark a key as being a connection identifier index that can then be used to find the specific connection again later.
-        # Common identifiers are current_user and current_account, but could be anything, really.
+        # Mark a key as being a connection identifier index that can then be used to
+        # find the specific connection again later. Common identifiers are current_user
+        # and current_account, but could be anything, really.
         #
-        # Note that anything marked as an identifier will automatically create a delegate by the same name on any
-        # channel instances created off the connection.
+        # Note that anything marked as an identifier will automatically create a
+        # delegate by the same name on any channel instances created off the connection.
         def identified_by(*identifiers)
           Array(identifiers).each { |identifier| attr_accessor identifier }
           self.identifiers += identifiers
         end
       end
 
-      # Return a single connection identifier that combines the value of all the registered identifiers into a single gid.
+      # Return a single connection identifier that combines the value of all the
+      # registered identifiers into a single gid.
       def connection_identifier
         unless defined? @connection_identifier
           @connection_identifier = connection_gid identifiers.filter_map { |id| instance_variable_get("@#{id}") }

data/lib/action_cable/connection/internal_channel.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Connection
-    # = Action Cable \InternalChannel
+    # # Action Cable InternalChannel
     #
-    # Makes it possible for the RemoteConnection to disconnect a specific connection.
+    # Makes it possible for the RemoteConnection to disconnect a specific
+    # connection.
     module InternalChannel
       extend ActiveSupport::Concern
 

data/lib/action_cable/connection/message_buffer.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Connection
-    # Allows us to buffer messages received from the WebSocket before the Connection has been fully initialized, and is ready to receive them.
+    # Allows us to buffer messages received from the WebSocket before the Connection
+    # has been fully initialized, and is ready to receive them.
     class MessageBuffer # :nodoc:
       def initialize(connection)
         @connection = connection

data/lib/action_cable/connection/stream.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Connection
     #--

data/lib/action_cable/connection/stream_event_loop.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "nio"
 
 module ActionCable
@@ -116,9 +118,8 @@ module ActionCable
                   stream.receive incoming
                 end
               rescue
-                # We expect one of EOFError or Errno::ECONNRESET in
-                # normal operation (when the client goes away). But if
-                # anything else goes wrong, this is still the best way
+                # We expect one of EOFError or Errno::ECONNRESET in normal operation (when the
+                # client goes away). But if anything else goes wrong, this is still the best way
                 # to handle it.
                 begin
                   stream.close

data/lib/action_cable/connection/subscriptions.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/hash/indifferent_access"
 
 module ActionCable
   module Connection
-    # = Action Cable \Connection \Subscriptions
+    # # Action Cable Connection Subscriptions
     #
-    # Collection class for all the channel subscriptions established on a given connection. Responsible for routing incoming commands that arrive on
-    # the connection to the proper channel.
+    # Collection class for all the channel subscriptions established on a given
+    # connection. Responsible for routing incoming commands that arrive on the
+    # connection to the proper channel.
     class Subscriptions # :nodoc:
       def initialize(connection)
         @connection = connection