omg-actioncable 8.0.0.alpha2

data/lib/action_cable/channel/base.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+require "set"
+require "active_support/rescuable"
+require "active_support/parameter_filter"
+
+module ActionCable
+  module Channel
+    # # Action Cable Channel Base
+    #
+    # The channel provides the basic structure of grouping behavior into logical
+    # units when communicating over the WebSocket connection. You can think of a
+    # channel like a form of controller, but one that's capable of pushing content
+    # to the subscriber in addition to simply responding to the subscriber's direct
+    # requests.
+    #
+    # Channel instances are long-lived. A channel object will be instantiated when
+    # the cable consumer becomes a subscriber, and then lives until the consumer
+    # disconnects. This may be seconds, minutes, hours, or even days. That means you
+    # have to take special care not to do anything silly in a channel that would
+    # balloon its memory footprint or whatever. The references are forever, so they
+    # won't be released as is normally the case with a controller instance that gets
+    # thrown away after every request.
+    #
+    # Long-lived channels (and connections) also mean you're responsible for
+    # ensuring that the data is fresh. If you hold a reference to a user record, but
+    # the name is changed while that reference is held, you may be sending stale
+    # data if you don't take precautions to avoid it.
+    #
+    # The upside of long-lived channel instances is that you can use instance
+    # variables to keep reference to objects that future subscriber requests can
+    # interact with. Here's a quick example:
+    #
+    #     class ChatChannel < ApplicationCable::Channel
+    #       def subscribed
+    #         @room = Chat::Room[params[:room_number]]
+    #       end
+    #
+    #       def speak(data)
+    #         @room.speak data, user: current_user
+    #       end
+    #     end
+    #
+    # The #speak action simply uses the Chat::Room object that was created when the
+    # channel was first subscribed to by the consumer when that subscriber wants to
+    # say something in the room.
+    #
+    # ## Action processing
+    #
+    # Unlike subclasses of ActionController::Base, channels do not follow a RESTful
+    # constraint form for their actions. Instead, Action Cable operates through a
+    # remote-procedure call model. You can declare any public method on the channel
+    # (optionally taking a `data` argument), and this method is automatically
+    # exposed as callable to the client.
+    #
+    # Example:
+    #
+    #     class AppearanceChannel < ApplicationCable::Channel
+    #       def subscribed
+    #         @connection_token = generate_connection_token
+    #       end
+    #
+    #       def unsubscribed
+    #         current_user.disappear @connection_token
+    #       end
+    #
+    #       def appear(data)
+    #         current_user.appear @connection_token, on: data['appearing_on']
+    #       end
+    #
+    #       def away
+    #         current_user.away @connection_token
+    #       end
+    #
+    #       private
+    #         def generate_connection_token
+    #           SecureRandom.hex(36)
+    #         end
+    #     end
+    #
+    # In this example, the subscribed and unsubscribed methods are not callable
+    # methods, as they were already declared in ActionCable::Channel::Base, but
+    # `#appear` and `#away` are. `#generate_connection_token` is also not callable,
+    # since it's a private method. You'll see that appear accepts a data parameter,
+    # which it then uses as part of its model call. `#away` does not, since it's
+    # simply a trigger action.
+    #
+    # Also note that in this example, `current_user` is available because it was
+    # marked as an identifying attribute on the connection. All such identifiers
+    # will automatically create a delegation method of the same name on the channel
+    # instance.
+    #
+    # ## Rejecting subscription requests
+    #
+    # A channel can reject a subscription request in the #subscribed callback by
+    # invoking the #reject method:
+    #
+    #     class ChatChannel < ApplicationCable::Channel
+    #       def subscribed
+    #         @room = Chat::Room[params[:room_number]]
+    #         reject unless current_user.can_access?(@room)
+    #       end
+    #     end
+    #
+    # In this example, the subscription will be rejected if the `current_user` does
+    # not have access to the chat room. On the client-side, the `Channel#rejected`
+    # callback will get invoked when the server rejects the subscription request.
+    class Base
+      include Callbacks
+      include PeriodicTimers
+      include Streams
+      include Naming
+      include Broadcasting
+      include ActiveSupport::Rescuable
+
+      attr_reader :params, :connection, :identifier
+      delegate :logger, to: :connection
+
+      class << self
+        # A list of method names that should be considered actions. This includes all
+        # public instance methods on a channel, less any internal methods (defined on
+        # Base), adding back in any methods that are internal, but still exist on the
+        # class itself.
+        #
+        # #### Returns
+        # *   `Set` - A set of all methods that should be considered actions.
+        def action_methods
+          @action_methods ||= begin
+            # All public instance methods of this class, including ancestors
+            methods = (public_instance_methods(true) -
+              # Except for public instance methods of Base and its ancestors
+              ActionCable::Channel::Base.public_instance_methods(true) +
+              # Be sure to include shadowed public instance methods of this class
+              public_instance_methods(false)).uniq.map(&:to_s)
+            methods.to_set
+          end
+        end
+
+        private
+          # action_methods are cached and there is sometimes need to refresh them.
+          # ::clear_action_methods! allows you to do that, so next time you run
+          # action_methods, they will be recalculated.
+          def clear_action_methods! # :doc:
+            @action_methods = nil
+          end
+
+          # Refresh the cached action_methods when a new action_method is added.
+          def method_added(name) # :doc:
+            super
+            clear_action_methods!
+          end
+      end
+
+      def initialize(connection, identifier, params = {})
+        @connection = connection
+        @identifier = identifier
+        @params     = params
+
+        # When a channel is streaming via pubsub, we want to delay the confirmation
+        # transmission until pubsub subscription is confirmed.
+        #
+        # The counter starts at 1 because it's awaiting a call to #subscribe_to_channel
+        @defer_subscription_confirmation_counter = Concurrent::AtomicFixnum.new(1)
+
+        @reject_subscription = nil
+        @subscription_confirmation_sent = nil
+
+        delegate_connection_identifiers
+      end
+
+      # Extract the action name from the passed data and process it via the channel.
+      # The process will ensure that the action requested is a public method on the
+      # channel declared by the user (so not one of the callbacks like #subscribed).
+      def perform_action(data)
+        action = extract_action(data)
+
+        if processable_action?(action)
+          payload = { channel_class: self.class.name, action: action, data: data }
+          ActiveSupport::Notifications.instrument("perform_action.action_cable", payload) do
+            dispatch_action(action, data)
+          end
+        else
+          logger.error "Unable to process #{action_signature(action, data)}"
+        end
+      end
+
+      # This method is called after subscription has been added to the connection and
+      # confirms or rejects the subscription.
+      def subscribe_to_channel
+        run_callbacks :subscribe do
+          subscribed
+        end
+
+        reject_subscription if subscription_rejected?
+        ensure_confirmation_sent
+      end
+
+      # Called by the cable connection when it's cut, so the channel has a chance to
+      # cleanup with callbacks. This method is not intended to be called directly by
+      # the user. Instead, override the #unsubscribed callback.
+      def unsubscribe_from_channel # :nodoc:
+        run_callbacks :unsubscribe do
+          unsubscribed
+        end
+      end
+
+      private
+        # Called once a consumer has become a subscriber of the channel. Usually the
+        # place to set up any streams you want this channel to be sending to the
+        # subscriber.
+        def subscribed # :doc:
+          # Override in subclasses
+        end
+
+        # Called once a consumer has cut its cable connection. Can be used for cleaning
+        # up connections or marking users as offline or the like.
+        def unsubscribed # :doc:
+          # Override in subclasses
+        end
+
+        # Transmit a hash of data to the subscriber. The hash will automatically be
+        # wrapped in a JSON envelope with the proper channel identifier marked as the
+        # recipient.
+        def transmit(data, via: nil) # :doc:
+          logger.debug do
+            status = "#{self.class.name} transmitting #{data.inspect.truncate(300)}"
+            status += " (via #{via})" if via
+            status
+          end
+
+          payload = { channel_class: self.class.name, data: data, via: via }
+          ActiveSupport::Notifications.instrument("transmit.action_cable", payload) do
+            connection.transmit identifier: @identifier, message: data
+          end
+        end
+
+        def ensure_confirmation_sent # :doc:
+          return if subscription_rejected?
+          @defer_subscription_confirmation_counter.decrement
+          transmit_subscription_confirmation unless defer_subscription_confirmation?
+        end
+
+        def defer_subscription_confirmation! # :doc:
+          @defer_subscription_confirmation_counter.increment
+        end
+
+        def defer_subscription_confirmation? # :doc:
+          @defer_subscription_confirmation_counter.value > 0
+        end
+
+        def subscription_confirmation_sent? # :doc:
+          @subscription_confirmation_sent
+        end
+
+        def reject # :doc:
+          @reject_subscription = true
+        end
+
+        def subscription_rejected? # :doc:
+          @reject_subscription
+        end
+
+        def delegate_connection_identifiers
+          connection.identifiers.each do |identifier|
+            define_singleton_method(identifier) do
+              connection.send(identifier)
+            end
+          end
+        end
+
+        def extract_action(data)
+          (data["action"].presence || :receive).to_sym
+        end
+
+        def processable_action?(action)
+          self.class.action_methods.include?(action.to_s) unless subscription_rejected?
+        end
+
+        def dispatch_action(action, data)
+          logger.debug action_signature(action, data)
+
+          if method(action).arity == 1
+            public_send action, data
+          else
+            public_send action
+          end
+        rescue Exception => exception
+          rescue_with_handler(exception) || raise
+        end
+
+        def action_signature(action, data)
+          (+"#{self.class.name}##{action}").tap do |signature|
+            arguments = data.except("action")
+
+            if arguments.any?
+              arguments = parameter_filter.filter(arguments)
+              signature << "(#{arguments.inspect})"
+            end
+          end
+        end
+
+        def parameter_filter
+          @parameter_filter ||= ActiveSupport::ParameterFilter.new(connection.config.filter_parameters)
+        end
+
+        def transmit_subscription_confirmation
+          unless subscription_confirmation_sent?
+            logger.debug "#{self.class.name} is transmitting the subscription confirmation"
+
+            ActiveSupport::Notifications.instrument("transmit_subscription_confirmation.action_cable", channel_class: self.class.name, identifier: @identifier) do
+              connection.transmit identifier: @identifier, type: ActionCable::INTERNAL[:message_types][:confirmation]
+              @subscription_confirmation_sent = true
+            end
+          end
+        end
+
+        def reject_subscription
+          connection.subscriptions.remove_subscription self
+          transmit_subscription_rejection
+        end
+
+        def transmit_subscription_rejection
+          logger.debug "#{self.class.name} is transmitting the subscription rejection"
+
+          ActiveSupport::Notifications.instrument("transmit_subscription_rejection.action_cable", channel_class: self.class.name, identifier: @identifier) do
+            connection.transmit identifier: @identifier, type: ActionCable::INTERNAL[:message_types][:rejection]
+          end
+        end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks(:action_cable_channel, ActionCable::Channel::Base)

data/lib/action_cable/channel/broadcasting.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+require "active_support/core_ext/object/to_param"
+
+module ActionCable
+  module Channel
+    module Broadcasting
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Broadcast a hash to a unique broadcasting for this `model` in this channel.
+        def broadcast_to(model, message)
+          ActionCable.server.broadcast(broadcasting_for(model), message)
+        end
+
+        # Returns a unique broadcasting identifier for this `model` in this channel:
+        #
+        #     CommentsChannel.broadcasting_for("all") # => "comments:all"
+        #
+        # You can pass any object as a target (e.g. Active Record model), and it would
+        # be serialized into a string under the hood.
+        def broadcasting_for(model)
+          serialize_broadcasting([ channel_name, model ])
+        end
+
+        private
+          def serialize_broadcasting(object) # :nodoc:
+            case
+            when object.is_a?(Array)
+              object.map { |m| serialize_broadcasting(m) }.join(":")
+            when object.respond_to?(:to_gid_param)
+              object.to_gid_param
+            else
+              object.to_param
+            end
+          end
+      end
+
+      def broadcasting_for(model)
+        self.class.broadcasting_for(model)
+      end
+
+      def broadcast_to(model, message)
+        self.class.broadcast_to(model, message)
+      end
+    end
+  end
+end

data/lib/action_cable/channel/callbacks.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+require "active_support/callbacks"
+
+module ActionCable
+  module Channel
+    # # Action Cable Channel Callbacks
+    #
+    # Action Cable Channel provides callback hooks that are invoked during the life
+    # cycle of a channel:
+    #
+    # *   [before_subscribe](rdoc-ref:ClassMethods#before_subscribe)
+    # *   [after_subscribe](rdoc-ref:ClassMethods#after_subscribe) (aliased as
+    #     [on_subscribe](rdoc-ref:ClassMethods#on_subscribe))
+    # *   [before_unsubscribe](rdoc-ref:ClassMethods#before_unsubscribe)
+    # *   [after_unsubscribe](rdoc-ref:ClassMethods#after_unsubscribe) (aliased as
+    #     [on_unsubscribe](rdoc-ref:ClassMethods#on_unsubscribe))
+    #
+    #
+    # #### Example
+    #
+    #     class ChatChannel < ApplicationCable::Channel
+    #       after_subscribe :send_welcome_message, unless: :subscription_rejected?
+    #       after_subscribe :track_subscription
+    #
+    #       private
+    #         def send_welcome_message
+    #           broadcast_to(...)
+    #         end
+    #
+    #         def track_subscription
+    #           # ...
+    #         end
+    #     end
+    #
+    module Callbacks
+      extend  ActiveSupport::Concern
+      include ActiveSupport::Callbacks
+
+      included do
+        define_callbacks :subscribe
+        define_callbacks :unsubscribe
+      end
+
+      module ClassMethods
+        def before_subscribe(*methods, &block)
+          set_callback(:subscribe, :before, *methods, &block)
+        end
+
+        # This callback will be triggered after the Base#subscribed method is called,
+        # even if the subscription was rejected with the Base#reject method.
+        #
+        # To trigger the callback only on successful subscriptions, use the
+        # Base#subscription_rejected? method:
+        #
+        #     after_subscribe :my_method, unless: :subscription_rejected?
+        #
+        def after_subscribe(*methods, &block)
+          set_callback(:subscribe, :after, *methods, &block)
+        end
+        alias_method :on_subscribe, :after_subscribe
+
+        def before_unsubscribe(*methods, &block)
+          set_callback(:unsubscribe, :before, *methods, &block)
+        end
+
+        def after_unsubscribe(*methods, &block)
+          set_callback(:unsubscribe, :after, *methods, &block)
+        end
+        alias_method :on_unsubscribe, :after_unsubscribe
+      end
+    end
+  end
+end

data/lib/action_cable/channel/naming.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionCable
+  module Channel
+    module Naming
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Returns the name of the channel, underscored, without the `Channel` 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.delete_suffix("Channel").gsub("::", ":").underscore
+        end
+      end
+
+      def channel_name
+        self.class.channel_name
+      end
+    end
+  end
+end

data/lib/action_cable/channel/periodic_timers.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+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 `every:` 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