actioncable 6.0.0

data/lib/action_cable/channel/naming.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+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
+        # colon separators in the channel name.
+        #
+        #   ChatChannel.channel_name # => 'chat'
+        #   Chats::AppearancesChannel.channel_name # => 'chats:appearances'
+        #   FooChats::BarAppearancesChannel.channel_name # => 'foo_chats:bar_appearances'
+        def channel_name
+          @channel_name ||= name.sub(/Channel$/, "").gsub("::", ":").underscore
+        end
+      end
+
+      # Delegates to the class' <tt>channel_name</tt>
+      delegate :channel_name, to: :class
+    end
+  end
+end

data/lib/action_cable/channel/periodic_timers.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ActionCable
+  module Channel
+    module PeriodicTimers
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :periodic_timers, instance_reader: false, default: []
+
+        after_subscribe   :start_periodic_timers
+        after_unsubscribe :stop_periodic_timers
+      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.
+        #
+        # 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.
+        #
+        #     periodically :transmit_progress, every: 5.seconds
+        #
+        #     periodically every: 3.minutes do
+        #       transmit action: :update_count, count: current_count
+        #     end
+        #
+        def periodically(callback_or_method_name = nil, every:, &block)
+          callback =
+            if block_given?
+              raise ArgumentError, "Pass a block or provide a callback arg, not both" if callback_or_method_name
+              block
+            else
+              case callback_or_method_name
+              when Proc
+                callback_or_method_name
+              when Symbol
+                -> { __send__ callback_or_method_name }
+              else
+                raise ArgumentError, "Expected a Symbol method name or a Proc, got #{callback_or_method_name.inspect}"
+              end
+            end
+
+          unless every.kind_of?(Numeric) && every > 0
+            raise ArgumentError, "Expected every: to be a positive number of seconds, got #{every.inspect}"
+          end
+
+          self.periodic_timers += [[ callback, every: every ]]
+        end
+      end
+
+      private
+        def active_periodic_timers
+          @active_periodic_timers ||= []
+        end
+
+        def start_periodic_timers
+          self.class.periodic_timers.each do |callback, options|
+            active_periodic_timers << start_periodic_timer(callback, every: options.fetch(:every))
+          end
+        end
+
+        def start_periodic_timer(callback, every:)
+          connection.server.event_loop.timer every do
+            connection.worker_pool.async_exec self, connection: connection, &callback
+          end
+        end
+
+        def stop_periodic_timers
+          active_periodic_timers.each { |timer| timer.shutdown }
+          active_periodic_timers.clear
+        end
+    end
+  end
+end

data/lib/action_cable/channel/streams.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+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
+    #
+    #     def unfollow
+    #       stop_all_streams
+    #     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.
+    #
+    # An example broadcasting for this channel looks like so:
+    #
+    #   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>.
+    #
+    #   class CommentsChannel < ApplicationCable::Channel
+    #     def subscribed
+    #       post = Post.find(params[:id])
+    #       stream_for post
+    #     end
+    #   end
+    #
+    # You can then broadcast to this channel using:
+    #
+    #   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:
+    #
+    #   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)
+    #
+    #           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
+    #       end
+    #     end
+    #   end
+    #
+    # You can stop streaming from all broadcasts by calling #stop_all_streams.
+    module Streams
+      extend ActiveSupport::Concern
+
+      included do
+        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.
+      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.
+        handler = worker_pool_stream_handler(broadcasting, callback || block, coder: coder)
+        streams << [ broadcasting, handler ]
+
+        connection.server.event_loop.post do
+          pubsub.subscribe(broadcasting, handler, lambda do
+            ensure_confirmation_sent
+            logger.info "#{self.class.name} is streaming from #{broadcasting}"
+          end)
+        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.
+      #
+      # 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.
+      def stream_for(model, callback = nil, coder: nil, &block)
+        stream_from(broadcasting_for(model), callback || block, coder: coder)
+      end
+
+      # Unsubscribes all streams associated with this channel from the pubsub queue.
+      def stop_all_streams
+        streams.each do |broadcasting, callback|
+          pubsub.unsubscribe broadcasting, callback
+          logger.info "#{self.class.name} stopped streaming from #{broadcasting}"
+        end.clear
+      end
+
+      private
+        delegate :pubsub, to: :connection
+
+        def streams
+          @_streams ||= []
+        end
+
+        # 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)
+
+          -> message do
+            connection.worker_pool.async_invoke handler, :call, message, connection: connection
+          end
+        end
+
+        # 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)
+          if user_handler
+            stream_decoder user_handler, coder: coder
+          else
+            default_stream_handler broadcasting, coder: coder
+          end
+        end
+
+        # 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.
+        def default_stream_handler(broadcasting, coder:)
+          coder ||= ActiveSupport::JSON
+          stream_transmitter stream_decoder(coder: coder), broadcasting: broadcasting
+        end
+
+        def stream_decoder(handler = identity_handler, coder:)
+          if coder
+            -> message { handler.(coder.decode(message)) }
+          else
+            handler
+          end
+        end
+
+        def stream_transmitter(handler = identity_handler, broadcasting:)
+          via = "streamed from #{broadcasting}"
+
+          -> (message) do
+            transmit handler.(message), via: via
+          end
+        end
+
+        def identity_handler
+          -> message { message }
+        end
+    end
+  end
+end

data/lib/action_cable/channel/test_case.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/test_case"
+require "active_support/core_ext/hash/indifferent_access"
+require "json"
+
+module ActionCable
+  module Channel
+    class NonInferrableChannelError < ::StandardError
+      def initialize(name)
+        super "Unable to determine the channel to test from #{name}. " +
+          "You'll need to specify it using `tests YourChannel` in your " +
+          "test case definition."
+      end
+    end
+
+    # 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?
+      end
+
+      def rejected?
+        subscription_rejected?
+      end
+
+      def stream_from(broadcasting, *)
+        streams << broadcasting
+      end
+
+      def stop_all_streams
+        @_streams = []
+      end
+
+      def streams
+        @_streams ||= []
+      end
+
+      # Make periodic timers no-op
+      def start_periodic_timers; end
+      alias stop_periodic_timers start_periodic_timers
+    end
+
+    class ConnectionStub
+      attr_reader :transmissions, :identifiers, :subscriptions, :logger
+
+      def initialize(identifiers = {})
+        @transmissions = []
+
+        identifiers.each do |identifier, val|
+          define_singleton_method(identifier) { val }
+        end
+
+        @subscriptions = ActionCable::Connection::Subscriptions.new(self)
+        @identifiers = identifiers.keys
+        @logger = ActiveSupport::TaggedLogging.new ActiveSupport::Logger.new(StringIO.new)
+      end
+
+      def transmit(cable_message)
+        transmissions << cable_message.with_indifferent_access
+      end
+    end
+
+    # Superclass for Action Cable channel functional tests.
+    #
+    # == 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.
+    #
+    # For example:
+    #
+    #   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 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
+    #
+    #     def test_does_not_stream_with_incorrect_room_number
+    #       subscribe room_number: -1
+    #
+    #       # Asserts that not streams was started
+    #       assert_no_streams
+    #     end
+    #
+    #     def test_does_not_subscribe_without_room_number
+    #       subscribe
+    #
+    #       # Asserts that the subscription was rejected
+    #       assert subscription.rejected?
+    #     end
+    #   end
+    #
+    # You can also perform actions:
+    #   def test_perform_speak
+    #     subscribe room_number: 1
+    #
+    #     perform :speak, message: "Hello, Rails!"
+    #
+    #     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:
+    #
+    # <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.
+    #
+    #
+    # == 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
+    #
+    # == Specifying connection identifiers
+    #
+    # You need to set up your connection manually to provide values for the identifiers.
+    # To do this just use:
+    #
+    #   stub_connection(user: users(:john))
+    #
+    # == 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
+    #
+    #  def test_speak
+    #    subscribe room_id: rooms(:chat).id
+    #
+    #    assert_broadcasts_on(rooms(:chat), text: "Hello, Rails!") do
+    #      perform :speak, message: "Hello, Rails!"
+    #    end
+    #  end
+    class TestCase < ActiveSupport::TestCase
+      module Behavior
+        extend ActiveSupport::Concern
+
+        include ActiveSupport::Testing::ConstantLookup
+        include ActionCable::TestHelper
+
+        CHANNEL_IDENTIFIER = "test_stub"
+
+        included do
+          class_attribute :_channel_class
+
+          attr_reader :connection, :subscription
+
+          ActiveSupport.run_load_hooks(:action_cable_channel_test_case, self)
+        end
+
+        module ClassMethods
+          def tests(channel)
+            case channel
+            when String, Symbol
+              self._channel_class = channel.to_s.camelize.constantize
+            when Module
+              self._channel_class = channel
+            else
+              raise NonInferrableChannelError.new(channel)
+            end
+          end
+
+          def channel_class
+            if channel = self._channel_class
+              channel
+            else
+              tests determine_default_channel(name)
+            end
+          end
+
+          def determine_default_channel(name)
+            channel = determine_constant_from_test_name(name) do |constant|
+              Class === constant && constant < ActionCable::Channel::Base
+            end
+            raise NonInferrableChannelError.new(name) if channel.nil?
+            channel
+          end
+        end
+
+        # Setup test connection with the specified identifiers:
+        #
+        #   class ApplicationCable < ActionCable::Connection::Base
+        #     identified_by :user, :token
+        #   end
+        #
+        #   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.
+        def subscribe(params = {})
+          @connection ||= stub_connection
+          @subscription = self.class.channel_class.new(connection, CHANNEL_IDENTIFIER, params.with_indifferent_access)
+          @subscription.singleton_class.include(ChannelStub)
+          @subscription.subscribe_to_channel
+          @subscription
+        end
+
+        # Unsubscribe the subscription under test.
+        def unsubscribe
+          check_subscribed!
+          subscription.unsubscribe_from_channel
+        end
+
+        # Perform action on a channel.
+        #
+        # NOTE: Must be subscribed.
+        def perform(action, data = {})
+          check_subscribed!
+          subscription.perform_action(data.stringify_keys.merge("action" => action.to_s))
+        end
+
+        # Returns messages transmitted into channel
+        def transmissions
+          # Return only directly sent message (via #transmit)
+          connection.transmissions.map { |data| data["message"] }.compact
+        end
+
+        # Enhance TestHelper assertions to handle non-String
+        # broadcastings
+        def assert_broadcasts(stream_or_object, *args)
+          super(broadcasting_for(stream_or_object), *args)
+        end
+
+        def assert_broadcast_on(stream_or_object, *args)
+          super(broadcasting_for(stream_or_object), *args)
+        end
+
+        # Asserts that no streams have been started.
+        #
+        #   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"
+        end
+
+        # Asserts that the specified stream has been started.
+        #
+        #   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"
+        end
+
+        # 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 assert_has_stream_for(object)
+          assert_has_stream(broadcasting_for(object))
+        end
+
+        private
+          def check_subscribed!
+            raise "Must be subscribed!" if subscription.nil? || subscription.rejected?
+          end
+
+          def broadcasting_for(stream_or_object)
+            return stream_or_object if stream_or_object.is_a?(String)
+
+            self.class.channel_class.broadcasting_for(stream_or_object)
+          end
+      end
+
+      include Behavior
+    end
+  end
+end