rage-rb 1.28.2 → 1.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73e373fc25e95467aa4a38003efafda30488596a75fb1ad7cd617891a6918962
-  data.tar.gz: 4183890376650de1e9133bcbe08ed645e628610629745d20c729e7464cb9ecb3
+  metadata.gz: 3042d8b6494404e49b19c70a5ee464e0b8f35a932bd1d5eff76a8fae8bc0713f
+  data.tar.gz: 4d69ac24a0dbd116c3cea590ecaad949fed45abe379660ab820ed8b5cbd05eec
 SHA512:
-  metadata.gz: 4ac0ef8e80416b82f0249675ae98eb973df2e419b12f32521c30933105ad17cef790620a8965eec7c810dc67313d6be4d39e10d05bf937483eeea154c6136088
-  data.tar.gz: 10b35efd2ba54aabc8eddc446669e945b530f0f7078899b43d45f8450fd2cf9db6ba746c695b4d2386e300a1adc84d98a2b9a0bd2e86e30d8ecf2f1804dd223f
+  metadata.gz: bf528a5e500571e0ff1f8662b15edcce821561810efa0d6ff00c74b05909e5fceee7dad8d2c4e6ddf4d57d46ba7f9548ac5a26159b1c531344f2b9701baad6e9
+  data.tar.gz: 8b6675e67d81d59f2444d393659e35569f2ab73a24e399c8ad268c97477c4ee315cc7a6fd86185cb94fa88f74bc2906366fe9c69e10a742abb75c074a50cac8e

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [1.29.0] - 2026-10-23
+
+### Added
+
+- [Deferred] Add `Rage::Deferred.dead_tasks` for listing and inspecting tasks that exhausted their retries.
+- Add low-level `PubSub` API (#399).
+- [Cable] Serialize WS messages per connection (#400).
+- Update fiber scheduler to support Ruby 4.1 (#397).
+- Improve blocking mechanism for fibers (#401).
+- Support multiple isolated cable apps (#406).
+- [Daemon] Improve cleanup mechanism (#410).
+- [Cable] Support remote disconnect for `Rage::Cable` (#409).
+- [Cable] Support `allow_same_origin_as_host` (#412).
+- Skip FiberWrapper when building application from non-root fiber (#413).
+
 ## [1.28.2] - 2026-10-09
 
 - Support `unsubscribe` commands in Action Cable.

data/Gemfile

@@ -22,9 +22,9 @@ group :test do
   gem "connection_pool", "~> 2.0"
   gem "rbnacl"
   gem "domain_name"
-  gem "websocket-client-simple"
   gem "prism"
   gem "redis-client"
   gem "appraisal", "~> 2.5"
   gem "blueprinter"
+  gem "websocket", "~> 1.2"
 end

data/lib/rage/cable/cable.rb

@@ -38,9 +38,21 @@ module Rage::Cable
   #   map "/cable" do
   #     run Rage.cable.application
   #   end
-  def self.application
-    handler = __build_handler(__protocol)
-    accept_response = [0, __protocol.protocol_definition, []]
+  def self.application(namespace: Object, protocol: nil)
+    unless namespace.is_a?(Module)
+      raise ArgumentError, "The `namespace` option must be a Module, got #{namespace.class}."
+    end
+
+    protocol = __protocol_for(protocol || Rage.config.cable.protocol)
+
+    unless __protocols.include?(protocol)
+      __protocols << protocol.tap(&:init)
+      @__adapter&.add_broadcaster(PUBSUB_BROADCASTER_ID, Relay)
+    end
+
+    router = Router.new(protocol, namespace)
+    handler = __build_handler(protocol, router)
+    accept_response = [101, protocol.protocol_definition, []]
 
     application = ->(env) do
       Rage::Telemetry.tracer.span_cable_websocket_handshake(env:) do
@@ -55,8 +67,15 @@ module Rage::Cable
     end
 
     chain = Rage.with_middlewares(application, Rage.config.cable.middlewares)
-    application.define_singleton_method(:__rage_app_name) { "Rage::Cable" }
-    chain.define_singleton_method(:__rage_root_app) { application }
+
+    chain.define_singleton_method(:__rage_root_app) do
+      root_app = Rage.with_middlewares(application, Rage.config.cable.middlewares(include_http_middleware: false))
+      root_app.define_singleton_method(:__rage_app_name) do
+        namespace == Object ? "Rage::Cable" : "Rage::Cable(namespace: #{namespace})"
+      end
+
+      root_app
+    end
 
     chain
   end
@@ -64,25 +83,35 @@ module Rage::Cable
   # @private
   def self.__initialize
     if (adapter = Rage.config.pubsub.adapter)
-      adapter.add_broadcaster(PUBSUB_BROADCASTER_ID, __protocol)
+      adapter.add_broadcaster(PUBSUB_BROADCASTER_ID, Relay)
       @__adapter = adapter
     end
   end
 
   # @private
-  def self.__router
-    @__router ||= Router.new
+  def self.__protocols
+    @__protocols ||= []
   end
 
   # @private
-  def self.__protocol
-    @__protocol ||= Rage.config.cable.protocol.tap { |protocol| protocol.init(__router) }
+  # @param protocol [:actioncable_v1_json, :raw_websocket_json, Class]
+  def self.__protocol_for(protocol)
+    case protocol
+    when Class
+      protocol
+    when :actioncable_v1_json
+      Protocols::ActioncableV1Json
+    when :raw_websocket_json
+      Protocols::RawWebSocketJson
+    else
+      raise ArgumentError, "Unknown protocol. Supported values are `:actioncable_v1_json` and `:raw_websocket_json`."
+    end
   end
 
   # @private
-  def self.__build_handler(protocol)
+  def self.__build_handler(protocol, router)
     klass = Class.new do
-      def initialize(protocol)
+      def initialize(protocol, router)
         Iodine.on_state(:on_start) do
           unless Fiber.scheduler
             Fiber.set_scheduler(Rage::FiberScheduler.new)
@@ -90,27 +119,30 @@ module Rage::Cable
         end
 
         @protocol = protocol
+        @router = router
         @log_processor = Rage.__log_processor
       end
 
       def on_open(connection)
-        schedule_fiber(connection) { @protocol.on_open(connection) }
+        init_connection(connection)
+        schedule_processing(connection) { |env| @protocol.on_open(connection, env, @router) }
       end
 
       def on_message(connection, data)
-        schedule_fiber(connection) { @protocol.on_message(connection, data) }
+        schedule_processing(connection) { |env| @protocol.on_message(connection, env, data, @router) }
       end
 
       if protocol.respond_to?(:on_close)
         def on_close(connection)
           return unless ::Iodine.running?
-          schedule_fiber(connection) { @protocol.on_close(connection) }
+          schedule_processing(connection) { |env| @protocol.on_close(connection, env, @router) }
+          connection.env["rage.cable.queue"] << nil
         end
       end
 
       if protocol.respond_to?(:on_shutdown)
         def on_shutdown(connection)
-          @protocol.on_shutdown(connection)
+          @protocol.on_shutdown(connection, @router)
         rescue => e
           log_error(e)
         end
@@ -118,13 +150,31 @@ module Rage::Cable
 
       private
 
-      def schedule_fiber(connection)
-        Fiber.schedule do
-          @log_processor.init_request_logger(connection.env)
-          yield
-        rescue => e
-          log_error(e)
+      def init_connection(connection)
+        queue = Queue.new
+        fiber = Fiber.schedule do
+          # `connection.env` is reset once the connection is closed; since messages are processed asynchronously,
+          # a connection can already be closed by the time the message is processed, so we store `env` separately
+          env = connection.env
+
+          Rage.__log_processor.init_request_logger(env)
+
+          loop do
+            work = queue.shift
+            break unless work
+
+            work.call(env)
+          rescue => e
+            log_error(e)
+          end
         end
+
+        connection.env["rage.cable.fiber"] = fiber
+        connection.env["rage.cable.queue"] = queue
+      end
+
+      def schedule_processing(connection, &block)
+        connection.env["rage.cable.queue"] << block
       end
 
       def log_error(e)
@@ -133,7 +183,7 @@ module Rage::Cable
       end
     end
 
-    klass.new(protocol)
+    klass.new(protocol, router)
   end
 
   # Broadcast data directly to a named stream.
@@ -145,13 +195,22 @@ module Rage::Cable
   #   Rage.cable.broadcast("chat", { message: "A new member has joined!" })
   def self.broadcast(stream, data)
     Rage::Telemetry.tracer.span_cable_stream_broadcast(stream:) do
-      __protocol.broadcast(stream, data)
+      Relay.broadcast(stream, data)
       @__adapter&.publish(PUBSUB_BROADCASTER_ID, stream, data)
     end
 
     true
   end
 
+  # @private
+  module Relay
+    def self.broadcast(stream, data)
+      Rage::Cable.__protocols.each do |protocol|
+        protocol.broadcast(stream, data)
+      end
+    end
+  end
+
   # @!parse [ruby]
   #   # @abstract
   #   class WebSocketConnection
@@ -190,6 +249,7 @@ require_relative "protocols/raw_web_socket_json"
 require_relative "channel"
 require_relative "connection"
 require_relative "router"
+require_relative "remote_disconnect"
 
 if Rage.config.internal.initialized?
   Rage::Cable.__initialize

data/lib/rage/cable/channel.rb

@@ -4,19 +4,18 @@ class Rage::Cable::Channel
 
   class << self
     # @private
-    attr_reader :__prepared_actions
-
-    # @private
-    attr_reader :__channels
+    attr_reader :__prepared_actions, :__channels, :__protocol
 
     # @private
     # returns a list of actions that can be called remotely
-    def __register_actions
+    def __register_actions(protocol)
+      @__protocol = protocol
+
       actions = (
         public_instance_methods(true) - Rage::Cable::Channel.public_instance_methods(true)
       ).reject { |m| m.start_with?("__rage_tmp") || m.start_with?("__run") }
 
-      actions.reject! { |m| m != :receive } unless Rage.cable.__protocol.supports_rpc?
+      actions.reject! { |m| m != :receive } unless @__protocol.supports_rpc?
 
       @__prepared_actions = (INTERNAL_ACTIONS + actions).each_with_object({}) do |action_name, memo|
         memo[action_name] = __register_action_proc(action_name)
@@ -417,6 +416,13 @@ class Rage::Cable::Channel
     @__params
   end
 
+  # Get the Rack env hash that is attached to the underlying WebSocket connection.
+  #
+  # @return [Hash]
+  def env
+    @__connection.env
+  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
@@ -449,7 +455,7 @@ class Rage::Cable::Channel
   #   Rage::Cable.broadcast("notifications", { message: "A new member has joined!" })
   def stream_from(stream)
     raise ArgumentError, "Stream name must be a String" unless stream.is_a?(String)
-    Rage.cable.__protocol.subscribe(@__connection, stream, @__params)
+    self.class.__protocol.subscribe(@__connection, stream, @__params)
   end
 
   # Subscribe to a local stream. Local streams are associated with a specific channel instance and can be used to send data to the current channel only.
@@ -490,7 +496,7 @@ class Rage::Cable::Channel
   #   end
   def stop_stream_from(stream)
     raise ArgumentError, "Stream name must be a String" unless stream.is_a?(String)
-    Rage.cable.__protocol.unsubscribe(@__connection, stream, @__params)
+    self.class.__protocol.unsubscribe(@__connection, stream, @__params)
   end
 
   # Unsubscribe from a local stream. The counterpart to {stream_for}.
@@ -527,7 +533,7 @@ class Rage::Cable::Channel
   #     transmit({ message: "Hello!" })
   #   end
   def transmit(data)
-    message = Rage.cable.__protocol.serialize(@__params, data)
+    message = self.class.__protocol.serialize(@__params, data)
 
     if @__is_subscribing
       # we expect a confirmation message to be sent as a result of a successful subscribe call;

data/lib/rage/cable/connection.rb

@@ -4,18 +4,27 @@ class Rage::Cable::Connection
   # @private
   attr_reader :__identified_by_map
 
+  class << self
+    # @private
+    attr_reader :__identifiers
+  end
+
   # 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|
+      raise ArgumentError, "Identifier must be a Symbol" unless method_name.is_a?(Symbol)
+
+      (@__identifiers ||= []) << 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
+        @__identified_by_map[method_name] = data if data
       end
 
       Rage::Cable::Channel.__prepare_id_method(method_name)
@@ -79,4 +88,56 @@ class Rage::Cable::Connection
       raise "Cookies cannot be set for WebSocket clients"
     end
   end
+
+  # @private
+  def __connect(connection, protocol)
+    Rage::Telemetry.tracer.span_cable_connection_process(connection: self, action: :connect, env: @__env) do
+      connect
+    end
+
+    __remote_disconnect_setup(connection, protocol) if !rejected? && is_a?(Rage::Cable::RemoteDisconnect)
+  end
+
+  # @private
+  def __disconnect(connection)
+    Rage::Telemetry.tracer.span_cable_connection_process(connection: self, action: :disconnect, env: @__env) do
+      disconnect
+    end
+
+    __remote_disconnect_cleanup(connection) if is_a?(Rage::Cable::RemoteDisconnect)
+  end
+
+  # Disconnect all connections matching the specified identifier.
+  #
+  # Only one identifier can be provided per call. To disconnect connections matching multiple
+  # criteria, define a composite identifier.
+  #
+  # @note This method is only available when {Rage::Cable::RemoteDisconnect Rage::Cable::RemoteDisconnect} is
+  #   included in your connection class.
+  #
+  # @example Disconnect all connections for a user
+  #   RageCable::Connection.disconnect(current_user: User.find(1))
+  #
+  # @example Using a composite identifier
+  #   class RageCable::Connection < Rage::Cable::Connection
+  #     include Rage::Cable::RemoteDisconnect
+  #
+  #     identified_by :current_user, :current_user_device
+  #
+  #     def connect
+  #       self.current_user = find_user
+  #       self.current_user_device = [current_user, request.headers["Device-Id"]]
+  #     end
+  #   end
+  #
+  #   # Disconnect only the user's specific device
+  #   RageCable::Connection.disconnect(current_user_device: [user, "device-123"])
+  #
+  # @example Using protocol options
+  #   RageCable::Connection.disconnect(current_user: User.find(1), protocol_options: { reconnect: false })
+  #
+  # @param identified_by [Hash] a single key-value pair where the key is a declared identifier
+  # @param protocol_options [Hash] options passed to the connection's protocol when disconnecting
+  # @raise [ArgumentError] if no identifier, multiple identifiers, or an unknown identifier is provided
+  # @!method self.disconnect(protocol_options: nil, **identified_by)
 end

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

@@ -45,6 +45,7 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
   module REASON
     UNAUTHORIZED = "unauthorized"
     INVALID = "invalid_request"
+    REMOTE = "remote"
   end
 
   module COMMAND
@@ -57,6 +58,8 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
     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
+    DISCONNECT = { type: TYPE::DISCONNECT, reason: REASON::REMOTE, reconnect: true }.to_json
+    DISCONNECT_NO_RECONNECT = { type: TYPE::DISCONNECT, reason: REASON::REMOTE, reconnect: false }.to_json
   end
 
   HANDSHAKE_HEADERS = { "Sec-WebSocket-Protocol" => "actioncable-v1-json" }
@@ -67,9 +70,7 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
   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)
+  def self.init
     super
 
     Iodine.on_state(:on_start) do
@@ -86,9 +87,10 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
   # 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)
+  # @param env [Hash] the Rack environment
+  # @param router [Rage::Cable::Router] the Cable router
+  def self.on_open(connection, env, router)
+    accepted = router.process_connection(connection, env)
 
     if accepted
       connection.subscribe("cable:ping")
@@ -103,9 +105,10 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
   # {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 env [Hash] the Rack environment
   # @param raw_data [String] the message body
-  # @see Rage::Cable::Router
-  def self.on_message(connection, raw_data)
+  # @param router [Rage::Cable::Router] the Cable router
+  def self.on_message(connection, env, raw_data, router)
     parsed_data = Rage::ParamsParser.json_parse(raw_data)
 
     command, identifier = parsed_data[:command], parsed_data[:identifier]
@@ -113,7 +116,7 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
 
     # process subscription messages
     if command == COMMAND::SUBSCRIBE
-      status = @router.process_subscription(connection, identifier, params[:channel], params)
+      status = router.process_subscription(connection, env, identifier, params[:channel], params)
       if status == :subscribed
         connection.write({ identifier: identifier, type: TYPE::CONFIRM }.to_json)
       elsif status == :rejected
@@ -124,7 +127,7 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
 
       return
     elsif command == COMMAND::UNSUBSCRIBE
-      @router.process_disconnection(connection)
+      router.process_unsubscription(connection, env, identifier)
       return
     end
 
@@ -133,10 +136,10 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
     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)
+      router.process_message(connection, env, identifier, data["action"].to_sym, data)
 
     elsif command == COMMAND::MESSAGE
-      @router.process_message(connection, identifier, :receive, data)
+      router.process_message(connection, env, identifier, :receive, data)
     end
 
     unless message_status == :processed
@@ -148,9 +151,10 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
   #
   # @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)
+  # @param env [Hash] the Rack environment
+  # @param router [Rage::Cable::Router] the Cable router
+  def self.on_close(connection, env, router)
+    router.process_disconnection(connection, env)
   end
 
   # Serialize a Ruby object into the format the client would understand.
@@ -160,4 +164,21 @@ class Rage::Cable::Protocols::ActioncableV1Json < Rage::Cable::Protocols::Base
   def self.serialize(params, data)
     { identifier: params.to_json, message: data }.to_json
   end
+
+  # A unique identifier of the protocol used in multi-server setups by {Rage::PubSub}.
+  # @return [String]
+  def self.protocol_id
+    "acv1"
+  end
+
+  # Process the disconnect initiated by the server.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @param options [Hash, nil] options passed to the protocol when disconnecting
+  def self.on_remote_disconnect(connection, options)
+    reconnect = options.nil? || options.fetch(:reconnect, true)
+    message = reconnect ? MESSAGES::DISCONNECT : MESSAGES::DISCONNECT_NO_RECONNECT
+
+    connection.write(message)
+  end
 end

data/lib/rage/cable/protocols/base.rb

@@ -9,38 +9,39 @@ require "digest"
 # * `on_open`
 # * `on_message`
 # * `serialize`
+# * `protocol_id`
 #
 # The optional methods are:
 #
 # * `protocol_definition`
+# * `supports_rpc?`
 # * `on_shutdown`
 # * `on_close`
+# * `on_remote_disconnect`
 #
 class Rage::Cable::Protocols::Base
   # @private
   HANDSHAKE_HEADERS = {}
 
   class << self
-    # @param router [Rage::Cable::Router]
-    def init(router)
-      @router = router
-
+    def init
       # Hash<String(stream name) => Set<Hash>(subscription params)>
       @subscription_identifiers = Hash.new { |hash, key| hash[key] = Set.new }
+      @sync_channel = "cable:#{protocol_id}:synchronize"
 
       Iodine.on_state(:pre_start) do
         # this is a fallback to synchronize subscription identifiers across different worker processes;
         # we expect connections to be distributed among all workers, so this code will almost never be called;
         # we also synchronize subscriptions with the master process so that the forks that are spun up instead
         # of the crashed ones also had access to the identifiers;
-        Iodine.subscribe("cable:synchronize") do |_, subscription_msg|
+        Iodine.subscribe(@sync_channel) do |_, subscription_msg|
           stream_name, params = Rage::ParamsParser.json_parse(subscription_msg)
           @subscription_identifiers[stream_name] << params
         end
       end
 
       Iodine.on_state(:on_finish) do
-        Iodine.unsubscribe("cable:synchronize")
+        Iodine.unsubscribe(@sync_channel)
       end
     end
 
@@ -54,11 +55,11 @@ class Rage::Cable::Protocols::Base
     # @param name [String] the stream name
     # @param params [Hash] parameters associated with the client
     def subscribe(connection, name, params)
-      connection.subscribe("cable:#{name}:#{stream_id(params)}")
+      connection.subscribe("cable:#{protocol_id}:#{name}:#{stream_id(params)}")
 
       unless @subscription_identifiers[name].include?(params)
         @subscription_identifiers[name] << params
-        ::Iodine.publish("cable:synchronize", [name, params].to_json)
+        ::Iodine.publish(@sync_channel, [name, params].to_json)
       end
     end
 
@@ -68,7 +69,7 @@ class Rage::Cable::Protocols::Base
     # @param name [String] the stream name
     # @param params [Hash] parameters associated with the client
     def unsubscribe(connection, name, params)
-      connection.unsubscribe("cable:#{name}:#{stream_id(params)}")
+      connection.unsubscribe("cable:#{protocol_id}:#{name}:#{stream_id(params)}")
     end
 
     # Broadcast data to all clients connected to a stream.
@@ -77,7 +78,7 @@ class Rage::Cable::Protocols::Base
     # @param data [Object] the data to send
     def broadcast(name, data)
       @subscription_identifiers[name].each do |params|
-        ::Iodine.publish("cable:#{name}:#{stream_id(params)}", serialize(params, data))
+        ::Iodine.publish("cable:#{protocol_id}:#{name}:#{stream_id(params)}", serialize(params, data))
       end
     end
 
@@ -88,6 +89,13 @@ class Rage::Cable::Protocols::Base
       true
     end
 
+    # Process the disconnect initiated by the server.
+    #
+    # @param connection [Rage::Cable::WebSocketConnection] the connection object
+    # @param options [Hash, nil] options passed to the protocol when disconnecting
+    def on_remote_disconnect(connection, options)
+    end
+
     private
 
     def stream_id(params)