rage-rb 1.6.0 → 1.8.0

data/lib/rage/cable/channel.rb

@@ -0,0 +1,452 @@
+require "set"
+
+class Rage::Cable::Channel
+  # @private
+  INTERNAL_ACTIONS = [:subscribed, :unsubscribed]
+
+  class << self
+    # @private
+    attr_reader :__prepared_actions
+
+    # @private
+    attr_reader :__channels
+
+    # @private
+    # returns a list of actions that can be called remotely
+    def __register_actions
+      actions = (
+        public_instance_methods(true) - Rage::Cable::Channel.public_instance_methods(true)
+      ).reject { |m| m.start_with?("__rage_tmp") || m.start_with?("__run") }
+
+      @__prepared_actions = (INTERNAL_ACTIONS + actions).each_with_object({}) do |action_name, memo|
+        memo[action_name] = __register_action_proc(action_name)
+      end
+
+      actions - INTERNAL_ACTIONS
+    end
+
+    # @private
+    # rubocop:disable Layout/HeredocIndentation, Layout/IndentationWidth, Layout/EndAlignment, Layout/ElseAlignment
+    def __register_action_proc(action_name)
+      if action_name == :subscribed && @__hooks
+        before_subscribe_chunk = if @__hooks[:before_subscribe]
+          lines = @__hooks[:before_subscribe].map do |h|
+            condition = if h[:if] && h[:unless]
+              "if #{h[:if]} && !#{h[:unless]}"
+            elsif h[:if]
+              "if #{h[:if]}"
+            elsif h[:unless]
+              "unless #{h[:unless]}"
+            end
+
+            <<~RUBY
+              #{h[:name]} #{condition}
+              return if @__subscription_rejected
+            RUBY
+          end
+
+          lines.join("\n")
+        end
+
+        after_subscribe_chunk = if @__hooks[:after_subscribe]
+          lines = @__hooks[:after_subscribe].map do |h|
+            condition = if h[:if] && h[:unless]
+              "if #{h[:if]} && !#{h[:unless]}"
+            elsif h[:if]
+              "if #{h[:if]}"
+            elsif h[:unless]
+              "unless #{h[:unless]}"
+            end
+
+            <<~RUBY
+              #{h[:name]} #{condition}
+            RUBY
+          end
+
+          lines.join("\n")
+        end
+      end
+
+      if action_name == :unsubscribed && @__hooks
+        before_unsubscribe_chunk = if @__hooks[:before_unsubscribe]
+          lines = @__hooks[:before_unsubscribe].map do |h|
+            condition = if h[:if] && h[:unless]
+              "if #{h[:if]} && !#{h[:unless]}"
+            elsif h[:if]
+              "if #{h[:if]}"
+            elsif h[:unless]
+              "unless #{h[:unless]}"
+            end
+
+            <<~RUBY
+              #{h[:name]} #{condition}
+            RUBY
+          end
+
+          lines.join("\n")
+        end
+
+        after_unsubscribe_chunk = if @__hooks[:after_unsubscribe]
+          lines = @__hooks[:after_unsubscribe].map do |h|
+            condition = if h[:if] && h[:unless]
+              "if #{h[:if]} && !#{h[:unless]}"
+            elsif h[:if]
+              "if #{h[:if]}"
+            elsif h[:unless]
+              "unless #{h[:unless]}"
+            end
+
+            <<~RUBY
+              #{h[:name]} #{condition}
+            RUBY
+          end
+
+          lines.join("\n")
+        end
+      end
+
+      rescue_handlers_chunk = if @__rescue_handlers
+        lines = @__rescue_handlers.map do |klasses, handler|
+          <<~RUBY
+          rescue #{klasses.join(", ")} => __e
+            #{instance_method(handler).arity == 0 ? handler : "#{handler}(__e)"}
+          RUBY
+        end
+
+        lines.join("\n")
+      else
+        ""
+      end
+
+      periodic_timers_chunk = if @__periodic_timers
+        set_up_periodic_timers
+
+        if action_name == :subscribed
+          <<~RUBY
+            self.class.__channels << self unless subscription_rejected?
+          RUBY
+        elsif action_name == :unsubscribed
+          <<~RUBY
+            self.class.__channels.delete(self)
+          RUBY
+        end
+      else
+        ""
+      end
+
+      is_subscribing = action_name == :subscribed
+      activerecord_loaded = defined?(::ActiveRecord)
+
+      method_name = class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def __run_#{action_name}(data)
+          #{if is_subscribing
+            <<~RUBY
+              @__is_subscribing = true
+            RUBY
+          end}
+
+          #{before_subscribe_chunk}
+          #{before_unsubscribe_chunk}
+
+          #{if instance_method(action_name).arity == 0
+            <<~RUBY
+              #{action_name}
+            RUBY
+          else
+            <<~RUBY
+              #{action_name}(data)
+            RUBY
+          end}
+
+          #{after_subscribe_chunk}
+          #{after_unsubscribe_chunk}
+          #{periodic_timers_chunk}
+          #{rescue_handlers_chunk}
+
+          #{if activerecord_loaded
+            <<~RUBY
+            ensure
+              if ActiveRecord::Base.connection_pool.active_connection?
+                ActiveRecord::Base.connection_handler.clear_active_connections!
+              end
+            RUBY
+          end}
+        end
+      RUBY
+
+      eval("->(channel, data) { channel.#{method_name}(data) }")
+    end
+    # rubocop:enable all
+
+    # @private
+    def __prepare_id_method(method_name)
+      define_method(method_name) do
+        @__identified_by[method_name]
+      end
+    end
+
+    # Register a new `before_subscribe` hook that will be called before the {subscribed} method.
+    #
+    # @example
+    #   before_subscribe :my_method
+    # @example
+    #   before_subscribe do
+    #     ...
+    #   end
+    # @example
+    #   before_subscribe :my_method, if: -> { ... }
+    def before_subscribe(action_name = nil, **opts, &block)
+      add_action(:before_subscribe, action_name, **opts, &block)
+    end
+
+    # Register a new `after_subscribe` hook that will be called after the {subscribed} method.
+    #
+    # @example
+    #   after_subscribe do
+    #     ...
+    #   end
+    # @example
+    #   after_subscribe :my_method, unless: :subscription_rejected?
+    # @note This callback will be triggered even if the subscription was rejected with the {reject} method.
+    def after_subscribe(action_name = nil, **opts, &block)
+      add_action(:after_subscribe, action_name, **opts, &block)
+    end
+
+    # Register a new `before_unsubscribe` hook that will be called before the {unsubscribed} method.
+    def before_unsubscribe(action_name = nil, **opts, &block)
+      add_action(:before_unsubscribe, action_name, **opts, &block)
+    end
+
+    # Register a new `after_unsubscribe` hook that will be called after the {unsubscribed} method.
+    def after_unsubscribe(action_name = nil, **opts, &block)
+      add_action(:after_unsubscribe, action_name, **opts, &block)
+    end
+
+    # Register an exception handler.
+    #
+    # @param klasses [Class, Array<Class>] exception classes to watch on
+    # @param with [Symbol] the name of a handler method. The method can take one argument, which is the raised exception. Alternatively, you can pass a block, which can also take one argument.
+    # @example
+    #   rescue_from StandardError, with: :report_error
+    #
+    #   private
+    #
+    #   def report_error(e)
+    #     SomeExternalBugtrackingService.notify(e)
+    #   end
+    # @example
+    #   rescue_from StandardError do |e|
+    #     SomeExternalBugtrackingService.notify(e)
+    #   end
+    def rescue_from(*klasses, with: nil, &block)
+      unless with
+        if block_given?
+          with = define_tmp_method(block)
+        else
+          raise ArgumentError, "No handler provided. Pass the `with` keyword argument or provide a block."
+        end
+      end
+
+      if @__rescue_handlers.nil?
+        @__rescue_handlers = []
+      elsif @__rescue_handlers.frozen?
+        @__rescue_handlers = @__rescue_handlers.dup
+      end
+
+      @__rescue_handlers.unshift([klasses, with])
+    end
+
+    # Set up a timer to periodically perform a task on the channel. Accepts a method name or a block.
+    #
+    # @param method_name [Symbol, nil] the name of the method to call
+    # @param every [Integer] the calling period in seconds
+    # @example
+    #   periodically every: 3.minutes do
+    #     transmit({ action: :update_count, count: current_count })
+    #   end
+    # @example
+    #   periodically :update_count, every: 3.minutes
+    def periodically(method_name = nil, every:, &block)
+      callback_name = if block_given?
+        raise ArgumentError, "Pass the `method_name` argument or provide a block, not both" if method_name
+        define_tmp_method(block)
+      elsif method_name.is_a?(Symbol)
+        define_tmp_method(eval("-> { #{method_name} }"))
+      else
+        raise ArgumentError, "Expected a Symbol method name, got #{method_name.inspect}"
+      end
+
+      unless every.is_a?(Numeric) && every > 0
+        raise ArgumentError, "Expected every: to be a positive number of seconds, got #{every.inspect}"
+      end
+
+      callback = eval("->(channel) { channel.#{callback_name} }")
+
+      if @__periodic_timers.nil?
+        @__periodic_timers = []
+      elsif @__periodic_timers.frozen?
+        @__periodic_timers = @__periodic_timers.dup
+      end
+
+      @__periodic_timers << [callback, every]
+    end
+
+    protected
+
+    def set_up_periodic_timers
+      return if @__periodic_timers_set_up
+
+      @__channels = Set.new
+
+      @__periodic_timers.each do |callback, every|
+        ::Iodine.run_every((every * 1000).to_i) do
+          slice_length = (@__channels.length / 20.0).ceil
+
+          if slice_length != 0
+            @__channels.each_slice(slice_length) do |slice|
+              Fiber.schedule do
+                slice.each { |channel| callback.call(channel) }
+              rescue => e
+                Rage.logger.error("Unhandled exception has occured - #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+              end
+            end
+          end
+        end
+      end
+
+      @__periodic_timers_set_up = true
+    end
+
+    def add_action(action_type, action_name = nil, **opts, &block)
+      if block_given?
+        action_name = define_tmp_method(block)
+      elsif action_name.nil?
+        raise ArgumentError, "No handler provided. Pass the `action_name` parameter or provide a block."
+      end
+
+      _if, _unless = opts.values_at(:if, :unless)
+
+      action = {
+        name: action_name,
+        if: _if,
+        unless: _unless
+      }
+
+      action[:if] = define_tmp_method(action[:if]) if action[:if].is_a?(Proc)
+      action[:unless] = define_tmp_method(action[:unless]) if action[:unless].is_a?(Proc)
+
+      if @__hooks.nil?
+        @__hooks = {}
+      elsif @__hooks[action_type] && @__hooks.frozen?
+        @__hooks = @__hooks.dup
+        @__hooks[action_type] = @__hooks[action_type].dup
+      end
+
+      if @__hooks[action_type].nil?
+        @__hooks[action_type] = [action]
+      elsif (i = @__hooks[action_type].find_index { |a| a[:name] == action_name })
+        @__hooks[action_type][i] = action
+      else
+        @__hooks[action_type] << action
+      end
+    end
+
+    attr_writer :__hooks, :__rescue_handlers, :__periodic_timers
+
+    def inherited(klass)
+      klass.__hooks = @__hooks.freeze
+      klass.__rescue_handlers = @__rescue_handlers.freeze
+      klass.__periodic_timers = @__periodic_timers.freeze
+    end
+
+    @@__tmp_name_seed = ("a".."i").to_a.permutation
+
+    def define_tmp_method(block)
+      name = @@__tmp_name_seed.next.join
+      define_method("__rage_tmp_#{name}", block)
+    end
+  end # class << self
+
+  # @private
+  def __has_action?(action_name)
+    !INTERNAL_ACTIONS.include?(action_name) && self.class.__prepared_actions.has_key?(action_name)
+  end
+
+  # @private
+  def __run_action(action_name, data = nil)
+    self.class.__prepared_actions[action_name].call(self, data)
+  end
+
+  # @private
+  def initialize(connection, params, identified_by)
+    @__connection = connection
+    @__params = params
+    @__identified_by = identified_by
+  end
+
+  # Get the params hash passed in during the subscription process.
+  #
+  # @return [Hash{Symbol=>String,Array,Hash,Numeric,NilClass,TrueClass,FalseClass}]
+  def params
+    @__params
+  end
+
+  # Reject the subscription request. The method should only be called during the subscription
+  # process (i.e. inside the {subscribed} method or {before_subscribe}/{after_subscribe} hooks).
+  def reject
+    @__subscription_rejected = true
+  end
+
+  # Checks whether the {reject} method has been called.
+  #
+  # @return [Boolean]
+  def subscription_rejected?
+    !!@__subscription_rejected
+  end
+
+  # Subscribe to a stream.
+  #
+  # @param stream [String] the name of the stream
+  def stream_from(stream)
+    Rage.config.cable.protocol.subscribe(@__connection, stream, @__params)
+  end
+
+  # Broadcast data to all the clients subscribed to a stream.
+  #
+  # @param stream [String] the name of the stream
+  # @param data [Object] the data to send to the clients
+  # @example
+  #   def subscribed
+  #     broadcast("notifications", { message: "A new member has joined!" })
+  #   end
+  def broadcast(stream, data)
+    Rage.config.cable.protocol.broadcast(stream, data)
+  end
+
+  # Transmit data to the current client.
+  #
+  # @param data [Object] the data to send to the client
+  # @example
+  #   def subscribed
+  #     transmit({ message: "Hello!" })
+  #   end
+  def transmit(data)
+    message = Rage.config.cable.protocol.serialize(@__params, data)
+
+    if @__is_subscribing
+      # we expect a confirmation message to be sent as a result of a successful subscribe call;
+      # this will make sure `transmit` calls send data after the confirmation;
+      ::Iodine.defer { @__connection.write(message) }
+    else
+      @__connection.write(message)
+    end
+  end
+
+  # Called once a client has become a subscriber of the channel.
+  def subscribed
+  end
+
+  # Called once a client unsubscribes from the channel.
+  def unsubscribed
+  end
+end

data/lib/rage/cable/connection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class Rage::Cable::Connection
+  # @private
+  attr_reader :__identified_by_map
+
+  # 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.
+  #
+  # @param identifiers [Symbol,Array<Symbol>]
+  def self.identified_by(*identifiers)
+    identifiers.each do |method_name|
+      define_method(method_name) do
+        @__identified_by_map[method_name]
+      end
+
+      define_method("#{method_name}=") do |data|
+        @__identified_by_map[method_name] = data
+      end
+
+      Rage::Cable::Channel.__prepare_id_method(method_name)
+    end
+  end
+
+  # @private
+  def initialize(env, identified_by = {})
+    @__env = env
+    @__identified_by_map = identified_by
+  end
+
+  # @private
+  def connect
+  end
+
+  # Reject the WebSocket connection.
+  def reject_unauthorized_connection
+    @rejected = true
+  end
+
+  def rejected?
+    !!@rejected
+  end
+
+  # Get the request object. See {Rage::Request}.
+  #
+  # @return [Rage::Request]
+  def request
+    @__request ||= Rage::Request.new(@__env)
+  end
+
+  # Get the cookie object. See {Rage::Cookies}.
+  #
+  # @return [Rage::Cookies]
+  def cookies
+    @__cookies ||= Rage::Cookies.new(@__env, ReadOnlyHash.new)
+  end
+
+  # Get the session object. See {Rage::Session}.
+  #
+  # @return [Rage::Session]
+  def session
+    @__session ||= Rage::Session.new(cookies)
+  end
+
+  # Get URL query parameters.
+  #
+  # @return [Hash{Symbol=>String,Array,Hash}]
+  def params
+    @__params ||= Iodine::Rack::Utils.parse_nested_query(@__env["QUERY_STRING"])
+  end
+
+  # @private
+  class ReadOnlyHash < Hash
+    def []=(_, _)
+      raise "Cookies cannot be set for WebSocket clients"
+    end
+  end
+end

data/lib/rage/cable/protocol/actioncable_v1_json.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+##
+# A protocol defines the structure, rules and semantics for exchanging data between the client and the server.
+# The class that defines a protocol should respond to the following methods:
+#
+# * `protocol_definition`
+# * `init`
+# * `on_open`
+# * `on_message`
+# * `serialize`
+# * `subscribe`
+# * `broadcast`
+#
+# The two optional methods are:
+#
+# * `on_shutdown`
+# * `on_close`
+#
+class Rage::Cable::Protocol::ActioncableV1Json
+  module TYPE
+    WELCOME = "welcome"
+    DISCONNECT = "disconnect"
+    PING = "ping"
+    CONFIRM = "confirm_subscription"
+    REJECT = "reject_subscription"
+  end
+
+  module REASON
+    UNAUTHORIZED = "unauthorized"
+    INVALID = "invalid_request"
+  end
+
+  module COMMAND
+    SUBSCRIBE = "subscribe"
+    MESSAGE = "message"
+  end
+
+  module MESSAGES
+    WELCOME = { type: TYPE::WELCOME }.to_json
+    UNAUTHORIZED = { type: TYPE::DISCONNECT, reason: REASON::UNAUTHORIZED, reconnect: false }.to_json
+    INVALID = { type: TYPE::DISCONNECT, reason: REASON::INVALID, reconnect: true }.to_json
+  end
+
+  HANDSHAKE_HEADERS = { "Sec-WebSocket-Protocol" => "actioncable-v1-json" }
+
+  # The method defines the headers to send to the client after the handshake process.
+  def self.protocol_definition
+    HANDSHAKE_HEADERS
+  end
+
+  # This method serves as a constructor to prepare the object or set up recurring tasks (e.g. heartbeats).
+  #
+  # @param router [Rage::Cable::Router]
+  def self.init(router)
+    @router = router
+
+    ping_counter = Time.now.to_i
+    ::Iodine.run_every(3000) do
+      ping_counter += 1
+      ::Iodine.publish("cable:ping", { type: TYPE::PING, message: ping_counter }.to_json)
+    end
+
+    # Hash<String(stream name) => Array<Hash>(subscription params)>
+    @subscription_identifiers = Hash.new { |hash, key| hash[key] = [] }
+  end
+
+  # The method is called any time a new WebSocket connection is established.
+  # It is expected to call {Rage::Cable::Router#process_connection} and handle its return value.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @see Rage::Cable::Router
+  def self.on_open(connection)
+    accepted = @router.process_connection(connection)
+
+    if accepted
+      connection.subscribe("cable:ping")
+      connection.write(MESSAGES::WELCOME)
+    else
+      connection.write(MESSAGES::UNAUTHORIZED)
+      connection.close
+    end
+  end
+
+  # The method processes messages from existing connections. It should parse the message, call either
+  # {Rage::Cable::Router#process_subscription} or {Rage::Cable::Router#process_message}, and handle its return value.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @param raw_data [String] the message body
+  # @see Rage::Cable::Router
+  def self.on_message(connection, raw_data)
+    parsed_data = Rage::ParamsParser.json_parse(raw_data)
+
+    command, identifier = parsed_data[:command], parsed_data[:identifier]
+    params = Rage::ParamsParser.json_parse(identifier)
+
+    # process subscription messages
+    if command == COMMAND::SUBSCRIBE
+      status = @router.process_subscription(connection, identifier, params[:channel], params)
+      if status == :subscribed
+        connection.write({ identifier: identifier, type: TYPE::CONFIRM }.to_json)
+      elsif status == :rejected
+        connection.write({ identifier: identifier, type: TYPE::REJECT }.to_json)
+      elsif status == :invalid
+        connection.write(MESSAGES::INVALID)
+      end
+
+      return
+    end
+
+    # process data messages;
+    # plain `JSON` is used here to conform with the ActionCable API that passes `data` as a Hash with string keys;
+    data = JSON.parse(parsed_data[:data])
+
+    message_status = if command == COMMAND::MESSAGE && data.has_key?("action")
+      @router.process_message(connection, identifier, data["action"].to_sym, data)
+
+    elsif command == COMMAND::MESSAGE
+      @router.process_message(connection, identifier, :receive, data)
+    end
+
+    unless message_status == :processed
+      connection.write(MESSAGES::INVALID)
+    end
+  end
+
+  # The method should process client disconnections and call {Rage::Cable::Router#process_message}.
+  #
+  # @note This method is optional.
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @see Rage::Cable::Router
+  def self.on_close(connection)
+    @router.process_disconnection(connection)
+  end
+
+  # Serialize a Ruby object into the format the client would understand.
+  #
+  # @param params [Hash] parameters associated with the client
+  # @param data [Object] the object to serialize
+  def self.serialize(params, data)
+    { identifier: params.to_json, message: data }.to_json
+  end
+
+  # Subscribe to a stream.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @param name [String] the stream name
+  # @param params [Hash] parameters associated with the client
+  def self.subscribe(connection, name, params)
+    connection.subscribe("cable:#{name}:#{params.hash}")
+    @subscription_identifiers[name] << params unless @subscription_identifiers[name].include?(params)
+  end
+
+  # Broadcast data to all clients connected to a stream.
+  #
+  # @param name [String] the stream name
+  # @param data [Object] the data to send
+  def self.broadcast(name, data)
+    i, identifiers = 0, @subscription_identifiers[name]
+
+    while i < identifiers.length
+      params = identifiers[i]
+      ::Iodine.publish("cable:#{name}:#{params.hash}", serialize(params, data))
+      i += 1
+    end
+  end
+end