omg-actioncable 8.0.0.alpha2

data/lib/action_cable/channel/streams.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionCable
+  module Channel
+    # # Action Cable Channel Streams
+    #
+    # Streams allow channels to route broadcastings to the subscriber. A
+    # broadcasting is, as discussed elsewhere, a pubsub queue where any data placed
+    # into it is automatically sent to the clients that are connected at that time.
+    # It's purely an online queue, though. If you're not streaming a broadcasting at
+    # the very moment it sends out an update, you will not get that update, even if
+    # you connect after it has been sent.
+    #
+    # Most commonly, the streamed broadcast is sent straight to the subscriber on
+    # the client-side. The channel just acts as a connector between the two parties
+    # (the broadcaster and the channel subscriber). Here's an example of a channel
+    # that allows subscribers to get all new comments on a given page:
+    #
+    #     class CommentsChannel < ApplicationCable::Channel
+    #       def follow(data)
+    #         stream_from "comments_for_#{data['recording_id']}"
+    #       end
+    #
+    #       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, `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' }
+    #
+    # 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
+    #       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 `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.
+        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 `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 `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 `broadcasting`.
+      def stop_stream_from(broadcasting)
+        callback = streams.delete(broadcasting)
+        if callback
+          pubsub.unsubscribe(broadcasting, callback)
+          logger.info "#{self.class.name} stopped streaming from #{broadcasting}"
+        end
+      end
+
+      # Unsubscribes streams for the `model`.
+      def stop_stream_for(model)
+        stop_stream_from(broadcasting_for(model))
+      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
+
+      # 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
+          stream_for model
+        else
+          reject
+        end
+      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,356 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+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
+
+    # # 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?
+      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 :server, :transmissions, :identifiers, :subscriptions, :logger
+
+      delegate :pubsub, :config, to: :server
+
+      def initialize(identifiers = {})
+        @server = ActionCable.server
+        @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
+
+      def connection_identifier
+        @connection_identifier ||= connection_gid(identifiers.filter_map { |id| send(id.to_sym) if id })
+      end
+
+      private
+        def connection_gid(ids)
+          ids.map do |o|
+            if o.respond_to?(:to_gid_param)
+              o.to_gid_param
+            else
+              o.to_s
+            end
+          end.sort.join(":")
+        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:
+    #
+    # connection
+    # :   An ActionCable::Channel::ConnectionStub, representing the current HTTP
+    #     connection.
+    #
+    # subscription
+    # :   An instance of the current channel, created when you call `subscribe`.
+    #
+    # transmissions
+    # :   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_broadcast_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
+
+        # Set up 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.filter_map { |data| data["message"] }
+        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
+
+        # 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?
+          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

data/lib/action_cable/connection/authorization.rb

@@ -0,0 +1,18 @@
+# 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.
+      def reject_unauthorized_connection
+        logger.error "An unauthorized connection attempt was rejected"
+        raise UnauthorizedError
+      end
+    end
+  end
+end