actioncable 7.0.8.1 → 7.2.2.1

data/lib/action_cable/connection/base.rb

@@ -1,56 +1,68 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "action_dispatch"
 require "active_support/rescuable"
 
 module ActionCable
   module Connection
-    # 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.
+    # # Action Cable Connection Base
     #
-    # Here's a basic example:
+    # 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.
     #
-    #   module ApplicationCable
-    #     class Connection < ActionCable::Connection::Base
-    #       identified_by :current_user
+    # Here's a basic example:
     #
-    #       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
       include Identification
       include InternalChannel
       include Authorization
+      include Callbacks
       include ActiveSupport::Rescuable
 
       attr_reader :server, :env, :subscriptions, :logger, :worker_pool, :protocol
-      delegate :event_loop, :pubsub, to: :server
+      delegate :event_loop, :pubsub, :config, to: :server
 
       def initialize(server, env, coder: ActiveSupport::JSON)
         @server, @env, @coder = server, env, coder
@@ -66,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
 
@@ -86,12 +100,18 @@ module ActionCable
 
       def dispatch_websocket_message(websocket_message) # :nodoc:
         if websocket.alive?
-          subscriptions.execute_command decode(websocket_message)
+          handle_channel_command decode(websocket_message)
         else
           logger.error "Ignoring message processed after the WebSocket was closed: #{websocket_message.inspect})"
         end
       end
 
+      def handle_channel_command(payload)
+        run_callbacks :command do
+          subscriptions.execute_command payload
+        end
+      end
+
       def transmit(cable_message) # :nodoc:
         websocket.transmit encode(cable_message)
       end
@@ -106,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,
@@ -143,11 +165,16 @@ module ActionCable
         send_async :handle_close
       end
 
+      def inspect # :nodoc:
+        "#<#{self.class.name}:#{'%#016x' % (object_id << 1)}>"
+      end
+
       private
         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
@@ -155,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
@@ -192,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
 
@@ -222,10 +249,11 @@ module ActionCable
 
           logger.error invalid_request_message
           logger.info finished_request_message
-          [ 404, { "Content-Type" => "text/plain" }, [ "Page not found" ] ]
+          [ 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 }
@@ -237,7 +265,7 @@ module ActionCable
             request.filtered_path,
             websocket.possible? ? " [WebSocket]" : "[non-WebSocket]",
             request.ip,
-            Time.now.to_default_s ]
+            Time.now.to_s ]
         end
 
         def finished_request_message
@@ -245,7 +273,7 @@ module ActionCable
             request.filtered_path,
             websocket.possible? ? " [WebSocket]" : "[non-WebSocket]",
             request.ip,
-            Time.now.to_default_s ]
+            Time.now.to_s ]
         end
 
         def invalid_request_message

data/lib/action_cable/connection/callbacks.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+require "active_support/callbacks"
+
+module ActionCable
+  module Connection
+    # # 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.
+    #
+    # #### Example
+    #
+    #     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
+
+      included do
+        define_callbacks :command
+      end
+
+      module ClassMethods
+        def before_command(*methods, &block)
+          set_callback(:command, :before, *methods, &block)
+        end
+
+        def after_command(*methods, &block)
+          set_callback(:command, :after, *methods, &block)
+        end
+
+        def around_command(*methods, &block)
+          set_callback(:command, :around, *methods, &block)
+        end
+      end
+    end
+  end
+end

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,8 +1,13 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Connection
-    # Makes it possible for the RemoteConnection to disconnect a specific connection.
+    # # Action Cable InternalChannel
+    #
+    # Makes it possible for the RemoteConnection to disconnect a specific
+    # connection.
     module InternalChannel
       extend ActiveSupport::Concern
 
@@ -32,7 +37,7 @@ module ActionCable
           case message["type"]
           when "disconnect"
             logger.info "Removing connection (#{connection_identifier})"
-            websocket.close
+            close(reason: ActionCable::INTERNAL[:disconnect_reasons][:remote], reconnect: message.fetch("reconnect", true))
           end
         rescue Exception => e
           logger.error "There was an exception - #{e.class}(#{e.message})"

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,6 +1,6 @@
 # frozen_string_literal: true
 
-require "thread"
+# :markup: markdown
 
 module ActionCable
   module Connection
@@ -100,7 +100,7 @@ module ActionCable
 
         # This should return the underlying io according to the SPEC:
         @rack_hijack_io = @socket_object.env["rack.hijack"].call
-        # Retain existing behaviour if required:
+        # Retain existing behavior if required:
         @rack_hijack_io ||= @socket_object.env["rack.hijack_io"]
 
         @event_loop.attach(@rack_hijack_io, self)

data/lib/action_cable/connection/stream_event_loop.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "nio"
-require "thread"
 
 module ActionCable
   module Connection
@@ -117,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,11 +1,16 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/hash/indifferent_access"
 
 module ActionCable
   module Connection
-    # 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.
+    # # 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.
     class Subscriptions # :nodoc:
       def initialize(connection)
         @connection = connection

data/lib/action_cable/connection/tagged_logger_proxy.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionCable
   module Connection
-    # Allows the use of per-connection tags against the server logger. This wouldn't work using the traditional
-    # ActiveSupport::TaggedLogging enhanced Rails.logger, as that logger will reset the tags between requests.
-    # The connection is long-lived, so it needs its own set of tags for its independent duration.
+    # # Action Cable Connection TaggedLoggerProxy
+    #
+    # Allows the use of per-connection tags against the server logger. This wouldn't
+    # work using the traditional ActiveSupport::TaggedLogging enhanced Rails.logger,
+    # as that logger will reset the tags between requests. The connection is
+    # long-lived, so it needs its own set of tags for its independent duration.
     class TaggedLoggerProxy
       attr_reader :tags
 
@@ -28,14 +33,14 @@ module ActionCable
       end
 
       %i( debug info warn error fatal unknown ).each do |severity|
-        define_method(severity) do |message|
-          log severity, message
+        define_method(severity) do |message = nil, &block|
+          log severity, message, &block
         end
       end
 
       private
-        def log(type, message) # :doc:
-          tag(@logger) { @logger.send type, message }
+        def log(type, message, &block) # :doc:
+          tag(@logger) { @logger.send type, message, &block }
         end
     end
   end

data/lib/action_cable/connection/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"
@@ -18,25 +20,33 @@ module ActionCable
     end
 
     module Assertions
-      # Asserts that the connection is rejected (via +reject_unauthorized_connection+).
+      # Asserts that the connection is rejected (via
+      # `reject_unauthorized_connection`).
       #
-      #   # Asserts that connection without user_id fails
-      #   assert_reject_connection { connect params: { user_id: '' } }
+      #     # Asserts that connection without user_id fails
+      #     assert_reject_connection { connect params: { user_id: '' } }
       def assert_reject_connection(&block)
         assert_raises(Authorization::UnauthorizedError, "Expected to reject connection but no rejection was made", &block)
       end
     end
 
-    # We don't want to use the whole "encryption stack" for connection
-    # unit-tests, but we want to make sure that users test against the correct types
-    # of cookies (i.e. signed or encrypted or plain)
-    class TestCookieJar < ActiveSupport::HashWithIndifferentAccess
+    class TestCookies < ActiveSupport::HashWithIndifferentAccess # :nodoc:
+      def []=(name, options)
+        value = options.is_a?(Hash) ? options.symbolize_keys[:value] : options
+        super(name, value)
+      end
+    end
+
+    # We don't want to use the whole "encryption stack" for connection unit-tests,
+    # but we want to make sure that users test against the correct types of cookies
+    # (i.e. signed or encrypted or plain)
+    class TestCookieJar < TestCookies
       def signed
-        self[:signed] ||= {}.with_indifferent_access
+        @signed ||= TestCookies.new
       end
 
       def encrypted
-        self[:encrypted] ||= {}.with_indifferent_access
+        @encrypted ||= TestCookies.new
       end
     end
 
@@ -56,75 +66,77 @@ module ActionCable
       end
     end
 
+    # # Action Cable Connection TestCase
+    #
     # Unit test Action Cable connections.
     #
-    # Useful to check whether a connection's +identified_by+ gets assigned properly
+    # Useful to check whether a connection's `identified_by` gets assigned properly
     # and that any improper connection requests are rejected.
     #
-    # == Basic example
+    # ## Basic example
     #
     # Unit tests are written as follows:
     #
-    # 1. Simulate a connection attempt by calling +connect+.
-    # 2. Assert state, e.g. identifiers, has been assigned.
+    # 1.  Simulate a connection attempt by calling `connect`.
+    # 2.  Assert state, e.g. identifiers, has been assigned.
     #
     #
-    #   class ApplicationCable::ConnectionTest < ActionCable::Connection::TestCase
-    #     def test_connects_with_proper_cookie
-    #       # Simulate the connection request with a cookie.
-    #       cookies["user_id"] = users(:john).id
+    #     class ApplicationCable::ConnectionTest < ActionCable::Connection::TestCase
+    #       def test_connects_with_proper_cookie
+    #         # Simulate the connection request with a cookie.
+    #         cookies["user_id"] = users(:john).id
     #
-    #       connect
+    #         connect
     #
-    #       # Assert the connection identifier matches the fixture.
-    #       assert_equal users(:john).id, connection.user.id
-    #     end
+    #         # Assert the connection identifier matches the fixture.
+    #         assert_equal users(:john).id, connection.user.id
+    #       end
     #
-    #     def test_rejects_connection_without_proper_cookie
-    #       assert_reject_connection { connect }
+    #       def test_rejects_connection_without_proper_cookie
+    #         assert_reject_connection { connect }
+    #       end
     #     end
-    #   end
     #
-    # +connect+ accepts additional information about the HTTP request with the
-    # +params+, +headers+, +session+, and Rack +env+ options.
+    # `connect` accepts additional information about the HTTP request with the
+    # `params`, `headers`, `session`, and Rack `env` options.
     #
-    #   def test_connect_with_headers_and_query_string
-    #     connect params: { user_id: 1 }, headers: { "X-API-TOKEN" => "secret-my" }
+    #     def test_connect_with_headers_and_query_string
+    #       connect params: { user_id: 1 }, headers: { "X-API-TOKEN" => "secret-my" }
     #
-    #     assert_equal "1", connection.user.id
-    #     assert_equal "secret-my", connection.token
-    #   end
+    #       assert_equal "1", connection.user.id
+    #       assert_equal "secret-my", connection.token
+    #     end
     #
-    #   def test_connect_with_params
-    #     connect params: { user_id: 1 }
+    #     def test_connect_with_params
+    #       connect params: { user_id: 1 }
     #
-    #     assert_equal "1", connection.user.id
-    #   end
+    #       assert_equal "1", connection.user.id
+    #     end
     #
     # You can also set up the correct cookies before the connection request:
     #
-    #   def test_connect_with_cookies
-    #     # Plain cookies:
-    #     cookies["user_id"] = 1
+    #     def test_connect_with_cookies
+    #       # Plain cookies:
+    #       cookies["user_id"] = 1
     #
-    #     # Or signed/encrypted:
-    #     # cookies.signed["user_id"] = 1
-    #     # cookies.encrypted["user_id"] = 1
+    #       # Or signed/encrypted:
+    #       # cookies.signed["user_id"] = 1
+    #       # cookies.encrypted["user_id"] = 1
     #
-    #     connect
+    #       connect
     #
-    #     assert_equal "1", connection.user_id
-    #   end
+    #       assert_equal "1", connection.user_id
+    #     end
     #
-    # == Connection is automatically inferred
+    # ## Connection is automatically inferred
     #
-    # ActionCable::Connection::TestCase will automatically infer the connection 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+.
+    # ActionCable::Connection::TestCase will automatically infer the connection
+    # 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 ConnectionTest < ActionCable::Connection::TestCase
-    #     tests ApplicationCable::Connection
-    #   end
+    #     class ConnectionTest < ActionCable::Connection::TestCase
+    #       tests ApplicationCable::Connection
+    #     end
     #
     class TestCase < ActiveSupport::TestCase
       module Behavior
@@ -176,10 +188,10 @@ module ActionCable
         #
         # Accepts request path as the first argument and the following request options:
         #
-        # - params – URL parameters (Hash)
-        # - headers – request headers (Hash)
-        # - session – session data (Hash)
-        # - env – additional Rack env configuration (Hash)
+        # *   params – URL parameters (Hash)
+        # *   headers – request headers (Hash)
+        # *   session – session data (Hash)
+        # *   env – additional Rack env configuration (Hash)
         def connect(path = ActionCable.server.config.mount_path, **request_params)
           path ||= DEFAULT_PATH