rage-rb 1.22.1 → 1.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c18be377e162e14f77e7709fc573ff35cb9965796f9451af4e05baac5da095ca
-  data.tar.gz: 9d6193d3a72322f0d9edb702f512975451cac38d32a7505b943065222aa45115
+  metadata.gz: bbc12eab5d13d5570107f5c7bf6d0b68f6f652eccc1eaafefdb47ef92ed3b264
+  data.tar.gz: 7adca2c0e96d38ca69c32f4fc12b03984b6aa46578d48d084645e11891915e99
 SHA512:
-  metadata.gz: 1ceffe055ffce47aca8970ee09de970665532ff4551afcbd0bf5efb9e55a380762e0b135f889b92be1acd6ba77c3d77d9025616e3d99ee75a6bfb4ccec5fbd4e
-  data.tar.gz: d9052e5e4c78aaca8425b2b7ae60622d275273ff85b18304db0657007103845c720465e744e73b077a180ae00813959c30288f174b798ec26e9518aec9062da0
+  metadata.gz: cb010618b1afebee5baa5fee44963d8cdf4f1543769b79ee81d26e9a0815c3ea59d6b0cf4dad2f53adabbe8d26ae0688876d2a0f690e1497173469446ba4a9e8
+  data.tar.gz: ee292c1c8b93fed32dbe015e6de898df1f0bb63ede69deb2b1eb41cddee1e339ade19ed8981682697721b02c3923bb8782358616c5d7c264cc0d465887b6e79b

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [1.23.0] - 2026-04-15
+
+### Fixed
+- [SSE] Ensure connection is closed for single-value SSE streams by [@jsxs0](https://github.com/jsxs0) (#264).
+- Ensure task ID seed is always greater than timestamps in existing WAL files by [@Abishekcs](https://github.com/Abishekcs) (#255)
+- Correctly load routes in Rails apps (#249).
+- [SSE] Ensure connection is closed when raw SSE stream raises by [@jsxs0](https://github.com/jsxs0) (#248).
+- [OpenAPI] Alba parser: silent fallback for unresolvable association resources by [@pratyush07-hub](https://github.com/pratyush07-hub) (#258).
+- Fix `Rage::UploadedFile#close` (#262).
+
+### Added
+- [SSE] Add tests for log context propagation across fiber boundaries by [@jsxs0](https://github.com/jsxs0) (#267).
+- Add singular `resource` routing with plural controller mapping and document the helper by [@anuj-pal27](https://github.com/anuj-pal27) (#247).
+- [SSE] Add support for unbounded streams (#266).
+- [OpenAPI] Support OpenAPI generation for file parameters by [@Digvijay-x1](https://github.com/Digvijay-x1) (#229).
+- [Deferred] Add configurable retry options by [@Digvijay-x1](https://github.com/Digvijay-x1) (#225).
+- [SSE] Add unit tests for `SSE::ConnectionProxy` by [@jsxs0](https://github.com/jsxs0) (#245).
+- Custom renderer support by [@anuj-pal27](https://github.com/anuj-pal27) (#244).
+- [SSE] Add graceful shutdown support for SSE streams by [@tmchow](https://github.com/tmchow) (#261).
+
 ## [1.22.1] - 2026-04-01
 
 ### Fixed

data/README.md

@@ -4,7 +4,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/rage-rb.svg)](https://badge.fury.io/rb/rage-rb)
 ![Tests](https://github.com/rage-rb/rage/actions/workflows/main.yml/badge.svg)
-![Ruby Requirement](https://img.shields.io/badge/Ruby-3.2%2B-%23f40000)
+![Ruby Requirement](https://img.shields.io/badge/Ruby-3.3%2B-%23f40000)
 
 **Rage** is an API-first Ruby framework with a modern, fiber-based runtime that enables transparent, non-blocking concurrency while preserving familiar developer ergonomics. It focuses on **capability and operational simplicity**, letting teams build production-grade systems in a single, coherent runtime.
 

data/lib/rage/all.rb

@@ -36,3 +36,4 @@ require_relative "middleware/request_id"
 require_relative "middleware/body_finalizer"
 
 require_relative "telemetry/telemetry"
+require_relative "sse/sse"

data/lib/rage/configuration.rb

@@ -139,6 +139,52 @@ class Rage::Configuration
   def after_initialize(&block)
     push_hook(block, :after_initialize)
   end
+
+  # Register a custom renderer that generates overloads `render` on all controllers.
+  # The block receives the object passed to `render` together with any additional keyword arguments.
+  # The code inside the block is executed in the context of the controller instance, so you can access all usual controller methods in it.
+  # The return value of the block is used as the response body.
+  #
+  # @param name [Symbol, String] the name of the renderer
+  # @param block [Proc] the rendering logic. The block is executed in the controller's context and its return value becomes the response body
+  # @raise [ArgumentError] if no block is given or if a renderer with the same name is already registered
+  #
+  # @example Register an ERB renderer
+  #   Rage.configure do
+  #     config.renderer(:erb) do |path, trim_mode: nil|
+  #       headers["content-type"] = "text/html"
+  #       template = File.read("app/views/#{path}.html.erb")
+  #
+  #       ERB.new(template, trim_mode:).result(binding)
+  #     end
+  #   end
+  # @example Use in a controller
+  #   class ReportsController < RageController::API
+  #     def index
+  #       render erb: "reports/index"
+  #     end
+  #   end
+  # @example Pass arguments
+  #   class ReportsController < RageController::API
+  #     def index
+  #       render erb: "reports/index", trim_mode: "%<>"
+  #     end
+  #   end
+  # @example Set response status
+  #   class ReportsController < RageController::API
+  #     def index
+  #       render erb: "reports/index", status: 202
+  #     end
+  #   end
+  def renderer(name, &block)
+    @renderers ||= {}
+    raise ArgumentError, "renderer requires a block" unless block_given?
+    name = name.to_sym
+    if @renderers.key?(name)
+      raise ArgumentError, "a renderer named :#{name} is already registered"
+    end
+    @renderers[name] = RendererEntry.new(block)
+  end
   # @!endgroup
 
   # @!group Middleware Configuration
@@ -219,6 +265,11 @@ class Rage::Configuration
   end
   # @!endgroup
 
+  # @private
+  def pubsub
+    @pubsub ||= PubSub.new
+  end
+
   # @private
   def internal
     @internal ||= Internal.new
@@ -937,6 +988,37 @@ class Rage::Configuration
     attr_accessor :key
   end
 
+  # @private
+  class PubSub
+    attr_reader :adapter
+
+    def initialize
+      @adapter = if config.any?
+        case config[:adapter]
+        when "redis"
+          Rage::PubSub::Adapters::Redis.new(adapter_config)
+        end
+      end
+    end
+
+    def config
+      @config ||= begin
+        config_file = Rage.root.join("config/pubsub.yml")
+
+        config = if config_file.exist?
+          yaml = ERB.new(config_file.read).result
+          YAML.safe_load(yaml, aliases: true, symbolize_names: true)&.dig(Rage.env.to_sym)
+        end
+
+        config || {}
+      end
+    end
+
+    def adapter_config
+      config.except(:adapter)
+    end
+  end
+
   # @private
   class Internal
     attr_accessor :rails_mode
@@ -999,7 +1081,32 @@ class Rage::Configuration
     end
 
     Rage::Telemetry.__setup(@telemetry.handlers_map) if @telemetry
+
+    __define_custom_renderers if @renderers
+  end
+
+  # @private
+  class RendererEntry
+    attr_reader :block
+
+    def initialize(block)
+      @block = block
+      @applied = false
+    end
+
+    def applied? = @applied
+    def applied! = (@applied = true)
+  end
+  private_constant :RendererEntry
+
+  def __define_custom_renderers
+    @renderers.each do |name, entry|
+      next if entry.applied?
+      RageController::API.__register_renderer(name, entry.block)
+      entry.applied!
+    end
   end
+  private :__define_custom_renderers
 end
 
 # @!parse [ruby]

data/lib/rage/controller/api.rb

@@ -211,6 +211,12 @@ class RageController::API
       RUBY
     end
 
+    # @private
+    def __register_renderer(name, block)
+      prepend(RageController::Renderers) unless ancestors.include?(RageController::Renderers)
+      RageController::Renderers.__register(name, block)
+    end
+
     ############
     #
     # PUBLIC API
@@ -445,11 +451,14 @@ class RageController::API
     end
   end # class << self
 
+  DEFAULT_CONTENT_TYPE = "application/json; charset=utf-8"
+  private_constant :DEFAULT_CONTENT_TYPE
+
   # @private
   def initialize(env, params)
     @__env = env
     @__params = params
-    @__status, @__headers, @__body = 204, { "content-type" => "application/json; charset=utf-8" }, []
+    @__status, @__headers, @__body = 204, { "content-type" => DEFAULT_CONTENT_TYPE }, []
     @__rendered = false
   end
 
@@ -480,10 +489,10 @@ class RageController::API
     @session ||= Rage::Session.new(cookies)
   end
 
-  # Send a response to the client.
+  # Send a response to the client. Keywords corresponding to custom renderers (see {Rage::Configuration#renderer}) will be delegated automatically.
   #
-  # @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 json [String, #to_json] send a json response to the client; objects will be serialized automatically
+  # @param plain [#to_s] 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 Render a JSON object
@@ -508,7 +517,8 @@ class RageController::API
       @__body << if json
         json.is_a?(String) ? json : json.to_json
       else
-        @__headers["content-type"] = "text/plain; charset=utf-8"
+        ct = @__headers["content-type"]
+        @__headers["content-type"] = "text/plain; charset=utf-8" if ct.nil? || ct == DEFAULT_CONTENT_TYPE
         plain.to_s
       end
 

data/lib/rage/controller/renderers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+##
+# This module overloads the `render` method on {RageController::API RageController::API} to enable the usage of custom renderers defined using {Rage::Configuration#renderer}.
+#
+module RageController::Renderers
+  # @private
+  def self.prepended(_)
+    @__renderers = {}
+  end
+
+  # @private
+  # rubocop:disable Layout/IndentationWidth, Layout/EndAlignment, Layout/HeredocIndentation
+  def self.__register(name, block)
+    @__renderers[name] = Rage::Internal.define_dynamic_method(self, block)
+
+    render_args = @__renderers.keys.map { |key| "#{key}: nil" }.join(", ")
+
+    class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def render(#{render_args}, status: nil, **)
+        raise "Render was called multiple times in this action." if @__rendered
+
+        active_renderers = []
+        #{@__renderers.keys.map { |key| "active_renderers << :#{key} if #{key}" }.join("\n")}
+
+        return super(status:, **) if active_renderers.empty?
+
+        if active_renderers.size > 1
+          raise Rage::Errors::AmbiguousRenderError, "Only one renderer can be used per 'render' call, but multiple were provided: \#{active_renderers.join(", ")}"
+        end
+
+        result = case active_renderers.first
+          #{@__renderers.map do |renderer_name, method_name|
+            <<~RUBY
+              when :#{renderer_name}
+                #{method_name}(#{renderer_name}, **)
+            RUBY
+          end.join("\n")}
+        end
+
+        return if @__rendered
+        render plain: result.to_s, status: (status || 200)
+      end
+    RUBY
+  end
+  # rubocop:enable all
+end

data/lib/rage/deferred/backends/disk.rb

@@ -44,8 +44,24 @@ class Rage::Deferred::Backends::Disk
       @recovered_storages = storage_files[1..] if storage_files.length > 1
     end
 
-    # create seed value for the task IDs
-    task_id_seed = Time.now.to_i # TODO: ensure timestamps in the file are not higher
+    # include recovered storages from crashed/previous workers
+    all_storages = [@storage, *@recovered_storages].compact
+
+    # find the highest task timestamp across all storage files
+    storage_file_max_timestamp = all_storages.map do |storage|
+      max_timestamp = 0
+      storage.tap(&:rewind).each_line(chomp: true) do |entry|
+        next unless entry[9...12] == "add"
+        timestamp = entry[13..].split("-").first.to_i
+        max_timestamp = timestamp if timestamp > max_timestamp
+      end
+      max_timestamp
+    end.max.to_i
+
+    # apply Lamport IR2(b) From time, clocks and the ordering of
+    # events in a distributed system to guard against clock skew
+    task_id_seed = [Time.now.to_i, storage_file_max_timestamp].max + 1
+
     @task_id_base, @task_id_i = "#{task_id_seed}-#{Process.pid}", 0
     Iodine.run_every(1_000) do
       task_id_seed += 1
@@ -117,7 +133,7 @@ class Rage::Deferred::Backends::Disk
       # `@recovered_storages` will only be present if the server has previously crashed and left
       # some storage files behind, or if the new cluster is started with fewer workers than before;
       # TLDR: this code is expected to execute very rarely
-      @recovered_storages.each { |storage| recover_tasks(storage) }
+      @recovered_storages.each { |storage| recover_tasks(storage.tap(&:rewind)) }
     end
 
     tasks = {}

data/lib/rage/deferred/metadata.rb

@@ -27,7 +27,7 @@ class Rage::Deferred::Metadata
     # @return [Boolean] `true` if a failure will schedule another attempt, `false` otherwise
     def will_retry?
       task = Rage::Deferred::Context.get_task(context)
-      task.__should_retry?(attempts)
+      !!task.__next_retry_in(attempts, nil)
     end
 
     private

data/lib/rage/deferred/queue.rb

@@ -38,14 +38,15 @@ class Rage::Deferred::Queue
         Fiber.schedule do
           Iodine.task_inc!
 
-          is_completed = task.new.__perform(context)
+          result = task.new.__perform(context)
 
-          if is_completed
+          if result == true
             @backend.remove(task_id)
           else
             attempts = Rage::Deferred::Context.inc_attempts(context)
-            if task.__should_retry?(attempts)
-              enqueue(context, delay: task.__next_retry_in(attempts), task_id:)
+            retry_in = task.__next_retry_in(attempts, result)
+            if retry_in
+              enqueue(context, delay: retry_in, task_id:)
             else
               @backend.remove(task_id)
             end

data/lib/rage/deferred/task.rb

@@ -85,7 +85,7 @@ module Rage::Deferred::Task
         Rage.logger.error("Deferred task failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
       end
     end
-    false
+    e
   end
 
   private def restore_log_info(context)
@@ -105,6 +105,62 @@ module Rage::Deferred::Task
   end
 
   module ClassMethods
+    # Set the maximum number of retry attempts for this task.
+    #
+    # @param count [Integer] the maximum number of retry attempts
+    # @example
+    #   class SendWelcomeEmail
+    #     include Rage::Deferred::Task
+    #     max_retries 10
+    #
+    #     def perform(email)
+    #       # ...
+    #     end
+    #   end
+    def max_retries(count)
+      value = Integer(count)
+
+      if value.negative?
+        raise ArgumentError, "max_retries should be a valid non-negative integer"
+      end
+
+      @__max_retries = value
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "max_retries should be a valid non-negative integer"
+    end
+
+    # Override this method to customize retry behavior per exception.
+    #
+    # Return an Integer to retry in that many seconds.
+    # Return `super` to use the default exponential backoff.
+    # Return `false` or `nil` to abort retries.
+    #
+    # @param exception [Exception] the exception that caused the failure
+    # @param attempt [Integer] the current attempt number (1-indexed)
+    # @return [Integer, false, nil] the retry interval in seconds, or false/nil to abort
+    # @example
+    #   class ProcessPayment
+    #     include Rage::Deferred::Task
+    #
+    #     def self.retry_interval(exception, attempt:)
+    #       case exception
+    #       when TemporaryNetworkError
+    #         10 # Retry in 10 seconds
+    #       when InvalidDataError
+    #         false # Do not retry
+    #       else
+    #         super # Default backoff strategy
+    #       end
+    #     end
+    #
+    #     def perform(payment_id)
+    #       # ...
+    #     end
+    #   end
+    def retry_interval(exception, attempt:)
+      __default_backoff(attempt)
+    end
+
     def enqueue(*args, delay: nil, delay_until: nil, **kwargs)
       context = Rage::Deferred::Context.build(self, args, kwargs)
 
@@ -118,13 +174,24 @@ module Rage::Deferred::Task
     end
 
     # @private
-    def __should_retry?(attempts)
-      attempts < MAX_ATTEMPTS
+    def __next_retry_in(attempts, exception)
+      max = @__max_retries || MAX_ATTEMPTS
+      return if attempts > max
+
+      interval = retry_interval(exception, attempt: attempts)
+      return if !interval
+
+      unless interval.is_a?(Numeric)
+        Rage.logger.warn("#{name}.retry_interval returned #{interval.class}, expected Numeric, false, or nil; falling back to default backoff")
+        return __default_backoff(attempts)
+      end
+
+      interval
     end
 
     # @private
-    def __next_retry_in(attempts)
-      rand(BACKOFF_INTERVAL * 2**attempts.to_i) + 1
+    def __default_backoff(attempt)
+      rand(BACKOFF_INTERVAL * 2**attempt) + 1
     end
   end
 end

data/lib/rage/errors.rb

@@ -10,4 +10,7 @@ module Rage::Errors
 
   class InvalidCustomProxy < StandardError
   end
+
+  class AmbiguousRenderError < StandardError
+  end
 end

data/lib/rage/internal.rb

@@ -44,6 +44,42 @@ class Rage::Internal
       }.join(", ")
     end
 
+    # Generate a stream name based on the provided object.
+    # @param streamables [#id, String, Symbol, Numeric, Array] an object that will be used to generate the stream name
+    # @return [String] the generated stream name
+    # @raise [ArgumentError] if the provided object cannot be used to generate a stream name
+    def stream_name_for(streamables)
+      return streamables if streamables.is_a?(String)
+
+      name_segments = Array(streamables).map do |streamable|
+        if streamable.respond_to?(:id)
+          "#{streamable.class.name}:#{streamable.id}"
+        elsif streamable.is_a?(String) || streamable.is_a?(Symbol) || streamable.is_a?(Numeric)
+          streamable
+        else
+          raise ArgumentError, "Unable to generate stream name. Expected an object that responds to `id`, got: #{streamable.class}"
+        end
+      end
+
+      name_segments.join(":")
+    end
+
+    # Pick a worker process to execute a block of code.
+    # This is useful for ensuring that certain code is only executed by a single worker in a multi-worker setup, e.g. for broadcasting messages to known streams or for running periodic tasks.
+    # @yield The block of code to be executed by the picked worker
+    def pick_a_worker(&block)
+      @lock_file, lock_path = Tempfile.new.yield_self { |file| [file, file.path] }
+
+      Iodine.on_state(:on_start) do
+        worker_lock = File.new(lock_path)
+
+        if worker_lock.flock(File::LOCK_EX | File::LOCK_NB)
+          @worker_lock = worker_lock
+          block.call
+        end
+      end
+    end
+
     private
 
     def dynamic_name_seed

data/lib/rage/logger/logger.rb

@@ -28,7 +28,7 @@ require "logger"
 # # => [fecbba0735355738] timestamp=2023-10-19T11:12:56+00:00 pid=1825 level=info cache_key=mykey message=cache miss
 # ```
 #
-# `Rage::Logger` also implements the interface of Ruby's native {https://ruby-doc.org/3.2.2/stdlibs/logger/Logger.html Logger}:
+# `Rage::Logger` also implements the interface of Ruby's native {https://ruby-doc.org/3.4.1/stdlibs/logger/Logger.html Logger}:
 # ```ruby
 # Rage.logger.info("Initializing")
 # Rage.logger.debug { "This is a " + potentially + " expensive operation" }

data/lib/rage/openapi/converter.rb

@@ -56,7 +56,47 @@ class Rage::OpenAPI::Converter
       }
 
       if node.parameters.any?
-        memo[path][method]["parameters"] = build_parameters(node)
+        has_file_param = node.parameters.values.any? { |p| !p.key?(:ref) && p[:type] && p[:type]["format"] == "binary" }
+
+        if has_file_param
+          schema_properties = {}
+          schema_required = []
+          query_ref_parameters = []
+
+          # When file params are present, non-ref params become part of the multipart/form-data
+          # request body schema. Shared refs (e.g., #/components/parameters/...) are kept as
+          # regular parameter references since we can't inline their definitions into the schema.
+          node.parameters.each do |param_name, param_info|
+            if param_info.key?(:ref)
+              # shared parameter refs stay as top-level parameters
+              query_ref_parameters << param_info[:ref]
+            else
+              # inline params become properties in the multipart schema
+              property_schema = get_param_type_spec(param_name, param_info[:type]).dup
+              if param_info[:description] && !param_info[:description].empty?
+                property_schema["description"] = param_info[:description]
+              end
+
+              schema_properties[param_name] = property_schema
+              schema_required << param_name if param_info[:required]
+            end
+          end
+
+          memo[path][method]["requestBody"] = {
+            "content" => {
+              "multipart/form-data" => {
+                "schema" => {
+                  "type" => "object",
+                  "properties" => schema_properties
+                }.tap { |s| s["required"] = schema_required if schema_required.any? }
+              }
+            }
+          }
+
+          memo[path][method]["parameters"] = query_ref_parameters if query_ref_parameters.any?
+        else
+          memo[path][method]["parameters"] = build_parameters(node)
+        end
       end
 
       responses = node.parents.reverse.map(&:responses).reduce(&:merge).merge(node.responses)
@@ -79,7 +119,8 @@ class Rage::OpenAPI::Converter
         if node.request.key?("$ref") && node.request["$ref"].start_with?("#/components/requestBodies")
           memo[path][method]["requestBody"] = node.request
         else
-          memo[path][method]["requestBody"] = { "content" => { "application/json" => { "schema" => node.request } } }
+          memo[path][method]["requestBody"] ||= {}
+          (memo[path][method]["requestBody"]["content"] ||= {})["application/json"] = { "schema" => node.request }
         end
       end
     end

data/lib/rage/openapi/openapi.rb

@@ -153,11 +153,22 @@ module Rage::OpenAPI
       { "type" => "string", "format" => "date-time" }
     when "String"
       { "type" => "string" }
+    when "File"
+      { "type" => "string", "format" => "binary" }
     else
       { "type" => "string" } if default
     end
   end
 
+  # @private
+  def self.__resolve_resource(klass_str, namespace)
+    return nil if klass_str.nil?
+    namespace.const_get(klass_str)
+  rescue NameError
+    __log_warn("could not resolve resource: #{klass_str}")
+    nil
+  end
+
   # @private
   def self.__log_warn(log)
     puts "[OpenAPI] WARNING: #{log}"

data/lib/rage/openapi/parsers/ext/alba.rb

@@ -151,12 +151,13 @@ class Rage::OpenAPI::Parsers::Ext::Alba
           with_inner_segment(key, is_array:) { visit(node.block) }
         else
           resource = context.keywords["resource"] || (::Alba.inflector && "#{::Alba.inflector.classify(association.to_s)}Resource")
-          is_valid_resource = @parser.namespace.const_get(resource) rescue false
+          resolved = Rage::OpenAPI.__resolve_resource(resource, @parser.namespace)
 
-          @segment[key] = if is_array
-            @parser.__parse_nested(is_valid_resource ? "[#{resource}]" : "[Rage]") # TODO
+          @segment[key] = if resolved
+            is_array ? @parser.__parse_nested("[#{resource}]") : @parser.__parse_nested(resource)
           else
-            @parser.__parse_nested(is_valid_resource ? resource : "Rage")
+            base = { "type" => "object" }
+            is_array ? { "type" => "array", "items" => base } : base
           end
         end