rage-rb 1.21.2 → 1.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bf38d642bfd73b2b1503d879649b40db0d22bd19114113a3706ee878969ff4f
-  data.tar.gz: 6e9c1028686606c4d62b6de407674ad4534ffe5052eb90200833a83cc3224e31
+  metadata.gz: b9116b996c0dd32f117d192f6fbb5df697a721a11a833a6f0e3aba30d683c691
+  data.tar.gz: a0ea041ff5ef2c7059e12fd32ab095f36d60bb6281c0679c66c33804e5401227
 SHA512:
-  metadata.gz: 8ca894824a43186b3ee65b1ea2984a937b6455ed43a44c258020656c27c23b24776cbd254bc33146c49d16f3a3320b6b1f0a481a8efafa56886a74500fbc304a
-  data.tar.gz: d9315ab5630d31b1075fe7c2430a9060c90d18b60234ee2e5c31ab4d99c64ae369dffc9b289b17c35baa959d02ce4eaee597889daebedf2cf3881e9deee56301
+  metadata.gz: 3962b6460dfc475f5d8709bd8847f994745b40b9cb486f720c967bc565e812d787613616eaa61fcb66c38153d49d5390983e5a2a10039b73abcfb414db60fadc
+  data.tar.gz: e844472bcfbcee55e78d4e2daf63f9e344ad977d7cad413b44c0adb3ffd0483e8e95bc3de24cce874d7d4f23c7dd8a820e7ac87cfcd8dda623264f4a4129304c

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [1.22.0] - 2026-03-12
+
+### Added
+
+- [Cable] Add support for `stop_stream_from` and `stop_stream_for`  by [@Digvijay](https://github.com/Digvijay-x1) (#217).
+- Add support for signed cookies by [@rfronczyk](https://github.com/rfronczyk) (#226).
+- [OpenAPI] Add support for shared components in `@auth` tags by [@Piyush-Goenka](https://github.com/Piyush-Goenka) (#221).
+- Add support for server-sent events (#220).
+
 ## [1.21.2] - 2026-03-11
 
 - Fix duplicate Rake tasks (#238).
@@ -418,4 +427,3 @@
     - support the `root`, `get`, `post`, `patch`, `put`, `delete` methods;
     - support the `scope` method with the `path` and `module` options;
     - support `host` constraint;
-

data/lib/rage/cable/cable.rb

@@ -44,7 +44,8 @@ module Rage::Cable
 
     application = ->(env) do
       Rage::Telemetry.tracer.span_cable_websocket_handshake(env:) do
-        if env["rack.upgrade?"] == :websocket
+        if env["HTTP_UPGRADE"] == "websocket" || env["HTTP_UPGRADE"]&.downcase == "websocket"
+          env["rack.upgrade?"] = :websocket
           env["rack.upgrade"] = handler
           accept_response
         else
@@ -162,6 +163,12 @@ module Rage::Cable
   #     def subscribe(name)
   #     end
   #
+  #     # Unsubscribe from a channel.
+  #     #
+  #     # @param name [String] the channel name
+  #     def unsubscribe(name)
+  #     end
+  #
   #     # Close the connection.
   #     def close
   #     end

data/lib/rage/cable/channel.rb

@@ -466,6 +466,40 @@ class Rage::Cable::Channel
     stream_from(self.class.__stream_name_for(streamable))
   end
 
+  # Unsubscribe from a global stream.
+  #
+  # @param stream [String] the name of the stream
+  # @raise [ArgumentError] if the stream name is not a String
+  # @example Unsubscribe from a stream and subscribe to a new one
+  #   class ChatChannel < Rage::Cable::Channel
+  #     def subscribed
+  #       stream_from "chat_#{params[:room]}"
+  #     end
+  #
+  #     def switch_room(data)
+  #       stop_stream_from "chat_#{params[:room]}"
+  #       stream_from "chat_#{data['new_room']}"
+  #     end
+  #   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)
+  end
+
+  # Unsubscribe from a local stream. The counterpart to {stream_for}.
+  #
+  # @param streamable [#id, String, Symbol, Numeric, Array] an object that will be used to generate the stream name
+  # @raise [ArgumentError] if the streamable object does not satisfy the type requirements
+  # @example Unsubscribe from a model stream
+  #   class NotificationsChannel < Rage::Cable::Channel
+  #     def unfollow(data)
+  #       stop_stream_for User.find(data['user_id'])
+  #     end
+  #   end
+  def stop_stream_for(streamable)
+    stop_stream_from(self.class.__stream_name_for(streamable))
+  end
+
   # Broadcast data to all the clients subscribed to a stream.
   #
   # @param stream [String] the name of the stream

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

@@ -62,6 +62,15 @@ class Rage::Cable::Protocols::Base
       end
     end
 
+    # Unsubscribe from 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 unsubscribe(connection, name, params)
+      connection.unsubscribe("cable:#{name}:#{stream_id(params)}")
+    end
+
     # Broadcast data to all clients connected to a stream.
     #
     # @param name [String] the stream name

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

@@ -141,4 +141,9 @@ class Rage::Cable::Protocols::RawWebSocketJson < Rage::Cable::Protocols::Base
   def self.subscribe(connection, name, _)
     super(connection, name, "")
   end
+
+  # @private
+  def self.unsubscribe(connection, name, _)
+    super(connection, name, "")
+  end
 end

data/lib/rage/configuration.rb

@@ -998,7 +998,7 @@ class Rage::Configuration
       middleware.insert_before(::Rack::Events, Rage::BodyFinalizer)
     end
 
-    Rage::Telemetry.__setup if @telemetry
+    Rage::Telemetry.__setup(@telemetry.handlers_map) if @telemetry
   end
 end
 

data/lib/rage/controller/api.rb

@@ -484,23 +484,31 @@ class RageController::API
   #
   # @param json [String, Object] send a json response to the client; objects like arrays will be serialized automatically
   # @param plain [String] send a text response to the client
+  # @param sse [#each, Proc, #to_json] send an SSE response to the client
   # @param status [Integer, Symbol] set a response status
-  # @example
+  # @example Render a JSON object
   #   render json: { hello: "world" }
-  # @example
+  # @example Set a response status
   #   render status: :ok
-  # @example
-  #   render plain: "hello world", status: 201
+  # @example Render an SSE stream
+  #   render sse: "hello world".each_char
+  # @example Render a one-off SSE update
+  #   render sse: { message: "hello world" }
+  # @example Write to an SSE connection manually
+  #   render sse: ->(connection) do
+  #     connection.write("data: Hello, World!\n\n")
+  #     connection.close
+  #   end
   # @note `render` doesn't terminate execution of the action, so if you want to exit an action after rendering, you need to do something like `render(...) and return`.
-  def render(json: nil, plain: nil, status: nil)
-    raise "Render was called multiple times in this action" if @__rendered
+  def render(json: nil, plain: nil, sse: nil, status: nil)
+    raise "Render was called multiple times in this action." if @__rendered
     @__rendered = true
 
     if json || plain
       @__body << if json
         json.is_a?(String) ? json : json.to_json
       else
-        headers["content-type"] = "text/plain; charset=utf-8"
+        @__headers["content-type"] = "text/plain; charset=utf-8"
         plain.to_s
       end
 
@@ -514,6 +522,20 @@ class RageController::API
         status
       end
     end
+
+    if sse
+      raise ArgumentError, "Cannot render both a standard body and an SSE stream." unless @__body.empty?
+
+      if status
+        return if @__status == 204
+        raise ArgumentError, "SSE responses only support 200 and 204 statuses." if @__status != 200
+      end
+
+      @__env["rack.upgrade?"] = :sse
+      @__env["rack.upgrade"] = Rage::SSE::Application.new(sse)
+      @__status = 200
+      @__headers["content-type"] = "text/event-stream; charset=utf-8"
+    end
   end
 
   # Send a response with no body.

data/lib/rage/cookies.rb

@@ -16,7 +16,7 @@ end
 # Cookies provide a convenient way to store small amounts of data on the client side that persists across requests.
 # They are commonly used for session management, personalization, and tracking user preferences.
 #
-# Rage cookies support both simple string-based cookies and encrypted cookies for sensitive data.
+# Rage cookies support simple, signed, and encrypted cookies.
 #
 # To use cookies, add the `domain_name` gem to your `Gemfile`:
 #
@@ -24,7 +24,7 @@ end
 # bundle add domain_name
 # ```
 #
-# Additionally, if you need to use encrypted cookies, see {Session} for setup steps.
+# Additionally, if you need to use signed or encrypted cookies, see {Session} for setup steps.
 #
 # ## Usage
 #
@@ -70,6 +70,18 @@ end
 #
 # ```
 #
+# ### Signed Cookies
+#
+# Store readable values with tamper protection:
+#
+# ```ruby
+# # Set a signed cookie
+# cookies.signed[:user_id] = 123
+#
+# # Read a signed cookie
+# cookies.signed[:user_id] # => "123"
+# ```
+#
 # ### Permanent Cookies
 #
 # Create cookies that expire 20 years from now:
@@ -146,6 +158,17 @@ class Rage::Cookies
     dup.tap { |c| c.jar = EncryptedJar }
   end
 
+  # Returns a jar that'll automatically sign cookie values before sending them to the client and verify them
+  # for read. If the cookie was tampered with by the user (or a 3rd party), `nil` will be returned.
+  #
+  # This jar requires that you set a suitable secret for the verification on your app's `secret_key_base`.
+  #
+  # @example
+  #   cookies.signed[:user_id] = current_user.id
+  def signed
+    dup.tap { |c| c.jar = SignedJar }
+  end
+
   # Returns a jar that'll automatically set the assigned cookies to have an expiration date 20 years from now.
   #
   # @example
@@ -249,11 +272,43 @@ class Rage::Cookies
     end
   end
 
+  module RbNaClKeyBuilder
+    RBNACL_MIN_VERSION = Gem::Version.create("3.3.0")
+    RBNACL_MAX_VERSION = Gem::Version.create("8.0.0")
+
+    private
+
+    def ensure_rbnacl!(purpose:)
+      return if defined?(RbNaCl) &&
+                Gem::Version.create(RbNaCl::VERSION) >= RBNACL_MIN_VERSION &&
+                Gem::Version.create(RbNaCl::VERSION) < RBNACL_MAX_VERSION
+
+      fail <<~ERR
+
+        Rage depends on `rbnacl` [>= #{RBNACL_MIN_VERSION}, < #{RBNACL_MAX_VERSION}] to support #{purpose}. Ensure the following line is added to your Gemfile:
+        gem "rbnacl"
+
+      ERR
+    end
+
+    def build_key(secret, purpose:)
+      ensure_rbnacl!(purpose: purpose)
+
+      if !secret
+        raise "Rage.config.secret_key_base should be set to use #{purpose}"
+      end
+
+      RbNaCl::Hash.blake2b("", key: [secret].pack("H*"), digest_size: 32, personal: purpose)
+    end
+  end
+
   class EncryptedJar
-    INFO = "encrypted cookie"
+    PURPOSE = "encrypted cookie"
     PADDING = "00"
 
     class << self
+      include RbNaClKeyBuilder
+
       def load(value)
         box = primary_box
 
@@ -282,38 +337,108 @@ class Rage::Cookies
       private
 
       def primary_box
-        @primary_box ||= begin
-          if !defined?(RbNaCl) || !(Gem::Version.create(RbNaCl::VERSION) >= Gem::Version.create("3.3.0") && Gem::Version.create(RbNaCl::VERSION) < Gem::Version.create("8.0.0"))
-            fail <<~ERR
-
-              Rage depends on `rbnacl` [>= 3.3, < 8.0] to encrypt cookies. Ensure the following line is added to your Gemfile:
-              gem "rbnacl"
-
-            ERR
-          end
-
-          unless Rage.config.secret_key_base
-            raise "Rage.config.secret_key_base should be set to use encrypted cookies"
-          end
-
-          RbNaCl::SimpleBox.from_secret_key(build_key(Rage.config.secret_key_base))
-        end
+        @primary_box ||= RbNaCl::SimpleBox.from_secret_key(build_key(Rage.config.secret_key_base, purpose: PURPOSE))
       end
 
       def fallback_boxes
         @fallback_boxes ||= begin
           fallbacks = Rage.config.fallback_secret_key_base.map do |key|
-            RbNaCl::SimpleBox.from_secret_key(build_key(key))
+            RbNaCl::SimpleBox.from_secret_key(build_key(key, purpose: PURPOSE))
           end
 
           fallbacks << RbNaCl::SimpleBox.from_secret_key(
-            RbNaCl::Hash.blake2b(Rage.config.secret_key_base, digest_size: 32, salt: INFO)
+            RbNaCl::Hash.blake2b(Rage.config.secret_key_base, digest_size: 32, salt: PURPOSE)
           )
         end
       end
+    end # class << self
+  end
+
+  class SignedJar
+    PURPOSE = "signed cookie"
+    SEPARATOR = "."
+    VERSION = "00"
+
+    class << self
+      include RbNaClKeyBuilder
+
+      def load(value)
+        version, encoded_value, digest = parse_signed_cookie(value)
+        return nil if digest.nil?
+
+        return nil unless version == VERSION
+
+        signed_payload = signed_payload_for(version, encoded_value)
+        return Base64.urlsafe_decode64(encoded_value) if verify_digest?(signed_payload, digest)
+
+        Rage.logger.debug("Failed to verify signed cookie")
+        nil
+      rescue ArgumentError
+        Rage.logger.debug("Failed to decode signed cookie")
+        nil
+      end
+
+      def dump(value)
+        encoded_value = Base64.urlsafe_encode64(value.to_s)
+        signed_payload = signed_payload_for(VERSION, encoded_value)
+        "#{signed_payload}#{SEPARATOR}#{digest_for(signed_payload, primary_signer)}"
+      end
+
+      private
+
+      def parse_signed_cookie(value)
+        parts = value.to_s.split(SEPARATOR, 3)
+        return [nil, nil, nil] unless parts.length == 3
+
+        version, encoded_value, digest = parts
+        return [nil, nil, nil] if version.empty? || digest.empty?
+
+        [version, encoded_value, digest]
+      end
+
+      def signed_payload_for(version, encoded_value)
+        "#{version}#{SEPARATOR}#{encoded_value}"
+      end
+
+      def primary_signer
+        @primary_signer ||= RbNaCl::HMAC::SHA512256.new(
+          build_key(Rage.config.secret_key_base, purpose: PURPOSE)
+        )
+      end
+
+      def fallback_signers
+        @fallback_signers ||= Rage.config.fallback_secret_key_base.map do |key|
+          RbNaCl::HMAC::SHA512256.new(build_key(key, purpose: PURPOSE))
+        end
+      end
+
+      def digest_for(value, signer)
+        Base64.urlsafe_encode64(signer.auth(value))
+      end
+
+      def verify_digest?(signed_payload, digest)
+        decoded_digest = Base64.urlsafe_decode64(digest)
+        signer = primary_signer
+        i = 0
+        while true
+          begin
+            if signer.verify(decoded_digest, signed_payload)
+              return true
+            end
+          rescue RbNaCl::BadAuthenticatorError, RbNaCl::CryptoError
+            # digest does not match this signer; continue to fallback keys
+          end
+
+          signer = fallback_signers[i]
+          break if signer.nil?
+
+          Rage.logger.debug { "Trying to verify signed cookie with fallback key ##{i + 1}" }
+          i += 1
+        end
 
-      def build_key(secret)
-        RbNaCl::Hash.blake2b("", key: [secret].pack("H*"), digest_size: 32, personal: INFO)
+        false
+      rescue ArgumentError
+        false
       end
     end # class << self
   end

data/lib/rage/fiber_scheduler.rb

@@ -97,7 +97,7 @@ class Rage::FiberScheduler
       unless fulfilled
         fulfilled = true
         ::Iodine.defer { ::Iodine.unsubscribe(channel) }
-        f.resume
+        f.resume if f.alive?
       end
     end
 

data/lib/rage/openapi/converter.rb

@@ -129,8 +129,12 @@ class Rage::OpenAPI::Converter
 
     node.auth.filter_map do |auth_entry|
       if available_before_actions.any? { |action_entry| action_entry[:name] == auth_entry[:method].to_sym }
-        auth_name = auth_entry[:name].gsub(/[^A-Za-z0-9\-._]/, "")
-        @used_security_schemes << auth_entry.merge(name: auth_name)
+        if auth_entry[:ref]
+          auth_name = auth_entry[:name]
+        else
+          auth_name = auth_entry[:name].gsub(/[^A-Za-z0-9\-._]/, "")
+          @used_security_schemes << auth_entry.merge(name: auth_name)
+        end
 
         { auth_name => [] }
       end

data/lib/rage/openapi/parser.rb

@@ -44,25 +44,28 @@ class Rage::OpenAPI::Parser
         parse_response_tag(expression, node, comments[i])
 
       elsif expression =~ /@auth\s/
-        method, name, tail_name = expression[6..].split(" ", 3)
+        method, name_or_ref, tail_name = expression[6..].split(" ", 3)
         children = find_children(comments[i + 1..], node)
 
         if tail_name
           Rage::OpenAPI.__log_warn "incorrect `@auth` name detected at #{location_msg(comments[i])}; security scheme name cannot contain spaces"
         end
 
-        auth_entry = {
+        auth_entry = parse_auth_tag(
           method:,
-          name: name || method,
-          definition: children.any? ? YAML.safe_load(children.join("\n")) : { "type" => "http", "scheme" => "bearer" }
-        }
-
-        if !node.controller.__before_action_exists?(method.to_sym)
-          Rage::OpenAPI.__log_warn "referenced before action `#{method}` is not defined in #{node.controller} at #{location_msg(comments[i])}; ensure a corresponding `before_action` call exists"
-        elsif node.auth.include?(auth_entry) || node.root.parent_nodes.any? { |parent_node| parent_node.auth.include?(auth_entry) }
-          Rage::OpenAPI.__log_warn "duplicate @auth tag detected at #{location_msg(comments[i])}"
-        else
-          node.auth << auth_entry
+          name_or_ref:,
+          children:,
+          comment: comments[i]
+        )
+
+        if auth_entry
+          if !node.controller.__before_action_exists?(method.to_sym)
+            Rage::OpenAPI.__log_warn "referenced before action `#{method}` is not defined in #{node.controller} at #{location_msg(comments[i])}; ensure a corresponding `before_action` call exists"
+          elsif node.auth.include?(auth_entry) || node.root.parent_nodes.any? { |parent_node| parent_node.auth.include?(auth_entry) }
+            Rage::OpenAPI.__log_warn "duplicate @auth tag detected at #{location_msg(comments[i])}"
+          else
+            node.auth << auth_entry
+          end
         end
       end
 
@@ -211,6 +214,48 @@ class Rage::OpenAPI::Parser
     end
   end
 
+  def parse_auth_tag(method:, name_or_ref:, children:, comment:)
+    if method&.start_with?("#/components/securitySchemes/")
+      Rage::OpenAPI.__log_warn "invalid `@auth` shared reference syntax detected at #{location_msg(comment)}; use `@auth <before_action> #{method}` and remove child definitions"
+      return
+    end
+
+    if name_or_ref&.start_with?("#/components")
+      ref = parse_auth_shared_reference(name_or_ref, comment)
+      return if ref.nil?
+
+      if children.any?
+        Rage::OpenAPI.__log_warn "ignored child `@auth` definition detected at #{location_msg(comment)}; shared security scheme references do not support child definitions"
+      end
+
+      return {
+        method:,
+        name: ref.delete_prefix("#/components/securitySchemes/"),
+        ref: { "$ref" => ref }
+      }
+    end
+
+    {
+      method:,
+      name: name_or_ref || method,
+      definition: children.any? ? YAML.safe_load(children.join("\n")) : { "type" => "http", "scheme" => "bearer" }
+    }
+  end
+
+  def parse_auth_shared_reference(name_or_ref, comment)
+    shared_reference_parser = Rage::OpenAPI::Parsers::SharedReference.new
+    is_valid_ref = shared_reference_parser.parse(name_or_ref)
+    has_valid_prefix = name_or_ref.start_with?("#/components/securitySchemes/")
+    scheme_name = name_or_ref.delete_prefix("#/components/securitySchemes/")
+
+    if is_valid_ref && has_valid_prefix && !scheme_name.empty? && !scheme_name.include?("/")
+      name_or_ref
+    else
+      Rage::OpenAPI.__log_warn "invalid shared reference detected at #{location_msg(comment)}"
+      nil
+    end
+  end
+
   def parse_param_tag(expression, node, comment)
     param = expression[7..].strip
 

data/lib/rage/sse/application.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# @private
+# This class is responsible for handling the lifecycle of an SSE connection.
+# It determines the type of SSE stream and manages the data flow.
+#
+class Rage::SSE::Application
+  def initialize(stream)
+    @stream = stream
+
+    @type = if @stream.is_a?(Enumerator)
+      :stream
+    elsif @stream.is_a?(Proc)
+      :manual
+    else
+      :single
+    end
+
+    @log_tags, @log_context = Fiber[:__rage_logger_tags], Fiber[:__rage_logger_context]
+  end
+
+  def on_open(connection)
+    @type == :single ? send_data(connection) : start_stream(connection)
+  end
+
+  private
+
+  def send_data(connection)
+    Rage::Telemetry.tracer.span_sse_stream_process(connection:, type: @type) do
+      connection.write(Rage::SSE.__serialize(@stream))
+      connection.close
+    end
+  end
+
+  def start_stream(connection)
+    Fiber.schedule do
+      Fiber[:__rage_logger_tags], Fiber[:__rage_logger_context] = @log_tags, @log_context
+      Rage::Telemetry.tracer.span_sse_stream_process(connection:, type: @type) do
+        @type == :stream ? start_formatted_stream(connection) : start_raw_stream(connection)
+      end
+    rescue => e
+      Rage.logger.error("SSE stream failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+    end
+  end
+
+  def start_formatted_stream(connection)
+    @stream.each do |event|
+      break if !connection.open?
+      connection.write(Rage::SSE.__serialize(event)) if event
+    end
+  ensure
+    connection.close
+  end
+
+  def start_raw_stream(connection)
+    @stream.call(Rage::SSE::ConnectionProxy.new(connection))
+  end
+end

data/lib/rage/sse/connection_proxy.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+##
+# This class acts as a proxy for the underlying SSE connection, providing a simplified and safe interface for interacting with the stream.
+# It ensures that operations are only performed on an open connection and abstracts away the direct connection handling.
+#
+# Example:
+#
+# ```ruby
+# render sse: ->(connection) do
+#   # `connection` is an instance of Rage::SSE::ConnectionProxy
+# end
+# ```
+#
+class Rage::SSE::ConnectionProxy
+  # @private
+  def initialize(connection)
+    @connection = connection
+  end
+
+  # Writes data to the SSE stream.
+  # @param data [#to_s]
+  # @raise [IOError] if the stream is already closed.
+  def write(data)
+    raise IOError, "closed stream" unless @connection.open?
+    @connection.write(data.to_s)
+  end
+
+  alias_method :<<, :write
+
+  # Closes the SSE stream.
+  def close
+    @connection.close
+  end
+
+  alias_method :close_write, :close
+
+  # Checks if the SSE stream is closed.
+  # @return [Boolean]
+  def closed?
+    !@connection.open?
+  end
+
+  # A no-op method to maintain interface compatibility.
+  # Flushing is handled by the underlying connection.
+  # @raise [IOError] if the stream is already closed.
+  def flush
+    raise IOError, "closed stream" unless @connection.open?
+  end
+
+  # A no-op method to maintain interface compatibility.
+  # Reading from an SSE stream is not supported on the server side.
+  def read(...)
+  end
+
+  # A no-op method to maintain interface compatibility.
+  # Reading from an SSE stream is not supported on the server side.
+  def close_read
+  end
+end

data/lib/rage/sse/message.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Represents a single Server-Sent Event. This class allows you to define the `id`, `event`, and `retry` fields for an SSE message.
+#
+# @!attribute id
+#   @return [String] The `id` field for the SSE event. This can be used to track messages.
+# @!attribute event
+#   @return [String] The `event` field for the SSE event. This can be used to define custom event types.
+# @!attribute retry
+#   @return [Integer] The `retry` field for the SSE event, in milliseconds. This value is a suggestion for the client about how long to wait before reconnecting.
+# @!attribute data
+#   @return [String, #to_json] The `data` field for the SSE event. If the object provided is not a string, it will be serialized to JSON.
+Rage::SSE::Message = Struct.new(:id, :event, :retry, :data, keyword_init: true) do
+  def to_s
+    data_entry = if !data.is_a?(String)
+      "data: #{data.to_json}\n"
+    elsif data.include?("\n")
+      data.split("\n").map { |d| "data: #{d}\n" }.join
+    else
+      "data: #{data}\n"
+    end
+
+    "#{data_entry}#{"id: #{id}\n" if id}#{"event: #{event}\n" if event}#{"retry: #{self.retry.to_i}\n" if self.retry && self.retry.to_i > 0}\n"
+  end
+end

data/lib/rage/sse/sse.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Rage::SSE
+  # A factory method for creating Server-Sent Events.
+  #
+  # @param data [String, #to_json] The `data` field for the SSE event. If the object provided is not a string, it will be serialized to JSON.
+  # @param id [String, nil] The `id` field for the SSE event. This can be used to track messages.
+  # @param event [String, nil] The `event` field for the SSE event. This can be used to define custom event types.
+  # @param retry [Integer, nil] The `retry` field for the SSE event, in milliseconds. This value is used to instruct the client how long to wait before attempting to reconnect.
+  # @return [Message] The formatted SSE event.
+  # @example
+  #   render sse: Rage::SSE.message(current_user.profile, id: current_user.id)
+  def self.message(data, id: nil, event: nil, retry: nil)
+    Message.new(data:, id:, event:, retry:)
+  end
+
+  # @private
+  def self.__serialize(data)
+    if data.is_a?(String)
+      data.include?("\n") ? Message.new(data:).to_s : "data: #{data}\n\n"
+    elsif data.is_a?(Message)
+      data.to_s
+    else
+      "data: #{data.to_json}\n\n"
+    end
+  end
+end
+
+require_relative "application"
+require_relative "connection_proxy"
+require_relative "message"

data/lib/rage/telemetry/spans/dispatch_fiber.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 ##
-# The **core.fiber.dispatch** span tracks the scheduling and processing of system-level fibers created by the framework to process requests and deferred tasks.
+# The **core.fiber.dispatch** span tracks the scheduling and processing of system-level fibers created by the framework to process requests, deferred tasks, or SSE streams.
 #
 # This span is started when a system fiber begins processing and ends when the fiber has completed processing.
 # See {handle handle} for the list of arguments passed to handler methods.

data/lib/rage/telemetry/spans/process_sse_stream.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+##
+# The **sse.stream.process** span wraps the processing of an SSE stream.
+#
+# This span starts when a connection is opened and ends when the stream is finished.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::ProcessSSEStream
+  class << self
+    # @private
+    def id
+      "sse.stream.process"
+    end
+
+    # @private
+    def span_parameters
+      %w[connection: type:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"SSE.process"',
+        env: "connection.env",
+        type: "type"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["sse.stream.process"] ID of the span
+    #   # @param name ["SSE.process"] human-readable name of the operation
+    #   # @param env [Hash] the Rack environment associated with the connection
+    #   # @param type [:stream, :single, :manual] the type of the SSE stream
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "sse.stream.process", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, env:, type:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, env:, type:)
+    #   end
+  end
+end

data/lib/rage/telemetry/telemetry.rb

@@ -46,12 +46,13 @@ module Rage::Telemetry
 
   # @private
   def self.tracer
-    @tracer ||= Tracer.new(__registry, Rage.config.telemetry.handlers_map)
+    @tracer ||= Tracer.new(__registry)
   end
 
   # @private
-  def self.__setup
-    tracer.setup
+  # @param handlers_map [Hash{String => Array<Rage::Telemetry::HandlerRef>}]
+  def self.__setup(handlers_map)
+    tracer.setup(handlers_map)
   end
 
   ##
@@ -81,6 +82,7 @@ module Rage::Telemetry
   # | `deferred.task.process` | {ProcessDeferredTask} | Wraps the processing of deferred tasks |
   # | `events.event.publish` | {PublishEvent} | Wraps the publishing of events via {Rage::Events Rage::Events} |
   # | `events.subscriber.process` | {ProcessEventSubscriber} | Wraps the processing of events by subscribers |
+  # | `sse.stream.process` | {ProcessSSEStream} | Wraps the processing of an SSE stream |
   #
   module Spans
   end

data/lib/rage/telemetry/tracer.rb

@@ -6,20 +6,18 @@ class Rage::Telemetry::Tracer
   private_constant :DEFAULT_SPAN_RESULT
 
   # @param spans_registry [Hash{String => Rage::Telemetry::Spans}]
-  # @param handlers_map [Hash{String => Array<Rage::Telemetry::HandlerRef>}]
-  def initialize(spans_registry, handlers_map)
+  def initialize(spans_registry)
     @spans_registry = spans_registry
-    @handlers_map = handlers_map
-
-    @all_handler_refs = handlers_map.values.flatten
 
     @spans_registry.each do |_, span|
       setup_noop(span)
     end
   end
 
-  def setup
-    @handlers_map.each do |span_id, handler_refs|
+  def setup(handlers_map)
+    @all_handler_refs = handlers_map.values.flatten
+
+    handlers_map.each do |span_id, handler_refs|
       setup_tracer(@spans_registry[span_id], handler_refs)
     end
   end

data/lib/rage/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rage
-  VERSION = "1.21.2"
+  VERSION = "1.22.0"
 end

data/lib/rage-rb.rb

@@ -40,6 +40,12 @@ module Rage
     Rage::Events
   end
 
+  # Shorthand to access {Rage::SSE Rage::SSE}.
+  # @return [Rage::SSE]
+  def self.sse
+    Rage::SSE
+  end
+
   # Configure routes for the Rage application.
   # @return [Rage::Router::DSL::Handler]
   # @example
@@ -185,6 +191,7 @@ module Rage
   autoload :OpenAPI, "rage/openapi/openapi"
   autoload :Deferred, "rage/deferred/deferred"
   autoload :Events, "rage/events/events"
+  autoload :SSE, "rage/sse/sse"
 end
 
 module RageController

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 1.21.2
+  version: 1.22.0
 platform: ruby
 authors:
 - Roman Samoilov
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.3'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.3'
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -221,6 +221,10 @@ files:
 - lib/rage/rspec.rb
 - lib/rage/session.rb
 - lib/rage/setup.rb
+- lib/rage/sse/application.rb
+- lib/rage/sse/connection_proxy.rb
+- lib/rage/sse/message.rb
+- lib/rage/sse/sse.rb
 - lib/rage/tasks.rb
 - lib/rage/telemetry/handler.rb
 - lib/rage/telemetry/spans/await_fiber.rb
@@ -233,6 +237,7 @@ files:
 - lib/rage/telemetry/spans/process_controller_action.rb
 - lib/rage/telemetry/spans/process_deferred_task.rb
 - lib/rage/telemetry/spans/process_event_subscriber.rb
+- lib/rage/telemetry/spans/process_sse_stream.rb
 - lib/rage/telemetry/spans/publish_event.rb
 - lib/rage/telemetry/spans/spawn_fiber.rb
 - lib/rage/telemetry/telemetry.rb