rage-rb 1.16.0 → 1.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf740bcbb20d075fa39c87bf6b97b10daf6f2a92daf6bcf7a12a03f04dbf5621
-  data.tar.gz: 7fd73455dfd6cb646d52d2e6f798b558e62ffe343d3156901a867af53179e973
+  metadata.gz: aa6f9f4b7b4e1f422fd778585be775834fbe1e8e30c523e2cac096bab71d0046
+  data.tar.gz: 776090fd9779c994c95bf4ec368cb4562c544b8fc2d99043fa0c2cb5c91903af
 SHA512:
-  metadata.gz: 0d74c740eec61265329a2f7623e3fa053d1d3bb07c3da7162b7551beded19bb3f6dc855cf5f92ec8acc501446ab72ee8d147904794f8892d967ceba939b3a10e
-  data.tar.gz: 169cab9535c8dc1ec9d99614dc8201e3cc2215126669965809618ae2effdd9384a6a4ab121913ce149d299111fce7f39eef8a00a2ba362abee755514f5b5c099
+  metadata.gz: c5bbbfc62d7da523ae2f7e1d9b3be2acaa67072fd34fe464f23ab909324c46c707983e828c451969c46cb019f11c6ca0abc026d641b44c4df5340add13c830dd
+  data.tar.gz: 814cebf4625dc114d07de548981e0a593b78f2d55dd514ca9824d68296cfabd99f79e838b2580fdc07480ed906c8081585a38d6361f33bd64c3a06a070155bed

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [1.17.1] - 2025-08-21
+
+### Fixed
+
+- Apply backpressure to every `enqueue` call (#166).
+
+## [1.17.0] - 2025-08-20
+
+### Added
+
+- Add `Rage::Deferred` (#164).
+- Add a controller generator by [@alex-rogachev](https://github.com/alex-rogachev) (#160).
+- Update `stale?` to set cache headers by [@serhii-sadovskyi](https://github.com/serhii-sadovskyi) (#159).
+
+### Fixed
+
+- Sub-millisecond sleep results in hang (#161).
+
 ## [1.16.0] - 2025-05-20
 
 ### Added

data/Gemfile

@@ -12,6 +12,7 @@ gem "yard"
 gem "rubocop", "~> 1.65.0", require: false
 
 group :test do
+  gem "activesupport"
   gem "http"
   gem "pg"
   gem "mysql2"

data/README.md

@@ -62,11 +62,12 @@ Built-in middleware:
 - [CORS](https://rage-rb.pages.dev/Rage/Cors)
 - [RequestId](https://rage-rb.pages.dev/Rage/RequestId)
 
-Also, see the following integration guides:
+Also, see the following guides:
 
 - [Rails Integration](https://github.com/rage-rb/rage/wiki/Rails-integration)
 - [RSpec Integration](https://github.com/rage-rb/rage/wiki/RSpec-integration)
 - [WebSockets Guide](https://github.com/rage-rb/rage/wiki/WebSockets-guide)
+- [Background Tasks Guide](https://github.com/rage-rb/rage/wiki/Background-Tasks-Guide)
 
 If you are a first-time contributor, make sure to check the [overview doc](https://github.com/rage-rb/rage/blob/master/OVERVIEW.md) that shows how Rage's core components interact with each other.
 

data/lib/rage/cli.rb

@@ -30,6 +30,26 @@ module Rage
       template("model-template/model.rb", "app/models/#{name.singularize.underscore}.rb")
     end
 
+    desc "controller NAME", "Generate a new controller."
+    def controller(name = nil)
+      return help("controller") if name.nil?
+
+      setup
+      unless defined?(ActiveSupport::Inflector)
+        raise LoadError, <<~ERR
+          ActiveSupport::Inflector is required to run this command. Add the following line to your Gemfile:
+          gem "activesupport", require: "active_support/inflector"
+        ERR
+      end
+
+      # remove trailing Controller if already present
+      normalized_name = name.sub(/_?controller$/i, "")
+      @controller_name = "#{normalized_name.camelize}Controller"
+      file_name = "#{normalized_name.underscore}_controller.rb"
+
+      template("controller-template/controller.rb", "app/controllers/#{file_name}")
+    end
+
     private
 
     def setup

data/lib/rage/code_loader.rb

@@ -22,6 +22,8 @@ class Rage::CodeLoader
     @loader.enable_reloading if enable_reloading
     @loader.setup
     @loader.eager_load if enable_eager_loading
+
+    configure_components
   end
 
   # in standalone mode - reload the code and the routes
@@ -34,13 +36,7 @@ class Rage::CodeLoader
     Rage.__router.reset_routes
     load("#{Rage.root}/config/routes.rb")
 
-    unless Rage.autoload?(:Cable) # the `Cable` component is loaded
-      Rage::Cable.__router.reset
-    end
-
-    unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
-      Rage::OpenAPI.__reset_data_cache
-    end
+    reload_components
   end
 
   # in Rails mode - reset the routes; everything else will be done by Rails
@@ -50,13 +46,7 @@ class Rage::CodeLoader
     @reloading = true
     Rage.__router.reset_routes
 
-    unless Rage.autoload?(:Cable) # the `Cable` component is loaded
-      Rage::Cable.__router.reset
-    end
-
-    unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
-      Rage::OpenAPI.__reset_data_cache
-    end
+    reload_components
   end
 
   def reloading?
@@ -73,4 +63,25 @@ class Rage::CodeLoader
   ensure
     @last_watched, @last_update_at = current_watched, current_update_at
   end
+
+  private
+
+  def configure_components
+    if Rage.env.development? && (Rage.config.deferred.configured? || Rage.config.deferred.has_default_disk_storage?)
+      # if there's at least one task, `Rage::Deferred` will be automatically loaded in production;
+      # in development, however, eager loading is disabled, and we want to automatically load
+      # the module in case it was explicitly configured or if a disk storage exists
+      Rage::Deferred
+    end
+  end
+
+  def reload_components
+    unless Rage.autoload?(:Cable) # the `Cable` component is loaded
+      Rage::Cable.__router.reset
+    end
+
+    unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
+      Rage::OpenAPI.__reset_data_cache
+    end
+  end
 end

data/lib/rage/configuration.rb

@@ -145,6 +145,38 @@ require "erb"
 # end
 # > ```
 #
+# # Deferred Configuration
+# • _config.deferred.backend_
+#
+# > Specifies the backend for deferred tasks. Supported values are `:disk`, which uses disk storage, or `nil`, which disables persistence of deferred tasks.
+# > The `:disk` backend accepts the following options:
+# >
+# > - `:path` - the path to the directory where deferred tasks will be stored. Defaults to `storage`.
+# > - `:prefix` - the prefix for the deferred task files. Defaults to `deferred-`.
+# > - `:fsync_frequency` - the frequency of `fsync` calls in seconds. Defaults to `0.5`.
+#
+# > ```ruby
+# config.deferred.backend = :disk, { path: "storage" }
+# > ```
+#
+# • _config.deferred.backpressure_
+#
+# > Enables the backpressure for deferred tasks. The backpressure is used to limit the number of pending tasks in the queue. It accepts a hash with the following options:
+# >
+# > - `:high_water_mark` - the maximum number of pending tasks in the queue. Defaults to `1000`.
+# > - `:low_water_mark` - the minimum number of pending tasks in the queue before the backpressure is released. Defaults to `high_water_mark * 0.8`.
+# > - `:timeout` - the timeout for the backpressure in seconds. Defaults to `2`.
+#
+# > ```ruby
+# config.deferred.backpressure = { high_water_mark: 1000, low_water_mark: 800, timeout: 2 }
+# > ```
+#
+# > Additionally, you can set the backpressure value to `true` to use the default values:
+#
+# > ```ruby
+# config.deferred.backpressure = true
+# ```
+#
 # # Transient Settings
 #
 # The settings described in this section should be configured using **environment variables** and are either temporary or will become the default in the future.
@@ -208,6 +240,10 @@ class Rage::Configuration
     @openapi ||= OpenAPI.new
   end
 
+  def deferred
+    @deferred ||= Deferred.new
+  end
+
   def internal
     @internal ||= Internal.new
   end
@@ -347,6 +383,121 @@ class Rage::Configuration
     attr_accessor :tag_resolver
   end
 
+  class Deferred
+    attr_reader :backpressure
+
+    def initialize
+      @configured = false
+    end
+
+    def backend
+      unless @backend_class
+        @backend_class = Rage::Deferred::Backends::Disk
+        @backend_options = parse_disk_backend_options({})
+      end
+
+      @backend_class.new(**@backend_options)
+    end
+
+    def backend=(config)
+      @configured = true
+
+      backend_id, opts = if config.is_a?(Array)
+        [config[0], config[1]]
+      else
+        [config, {}]
+      end
+
+      @backend_class = case backend_id
+      when :disk
+        @backend_options = parse_disk_backend_options(opts)
+        Rage::Deferred::Backends::Disk
+      when nil
+        Rage::Deferred::Backends::Nil
+      else
+        raise ArgumentError, "unsupported backend value; supported keys are `:disk` and `nil`"
+      end
+    end
+
+    class Backpressure
+      attr_reader :high_water_mark, :low_water_mark, :timeout, :sleep_interval, :timeout_iterations
+
+      def initialize(high_water_mark = nil, low_water_mark = nil, timeout = nil)
+        @high_water_mark = high_water_mark || 1_000
+        @low_water_mark = low_water_mark || (@high_water_mark * 0.8).round
+
+        @timeout = timeout || 2
+        @sleep_interval = 0.05
+        @timeout_iterations = (@timeout / @sleep_interval).round
+      end
+    end
+
+    def backpressure=(config)
+      @configured = true
+
+      if config == true
+        @backpressure = Backpressure.new
+        return
+      elsif config == false
+        @backpressure = nil
+        return
+      end
+
+      if config.except(:high_water_mark, :low_water_mark, :timeout).any?
+        raise ArgumentError, "unsupported backpressure options; supported keys are `:high_water_mark`, `:low_water_mark`, `:timeout`"
+      end
+
+      high_water_mark, low_water_mark, timeout = config.values_at(:high_water_mark, :low_water_mark, :timeout)
+      @backpressure = Backpressure.new(high_water_mark, low_water_mark, timeout)
+    end
+
+    def default_disk_storage_path
+      Pathname.new("storage")
+    end
+
+    def default_disk_storage_prefix
+      "deferred-"
+    end
+
+    def has_default_disk_storage?
+      default_disk_storage_path.glob("#{default_disk_storage_prefix}*").any?
+    end
+
+    def configured?
+      @configured
+    end
+
+    private
+
+    def parse_disk_backend_options(opts)
+      if opts.except(:path, :prefix, :fsync_frequency).any?
+        raise ArgumentError, "unsupported backend options; supported values are `:path`, `:prefix`, `:fsync_frequency`"
+      end
+
+      parsed_options = {}
+
+      parsed_options[:path] = if opts[:path]
+        opts[:path].is_a?(Pathname) ? opts[:path] : Pathname.new(opts[:path])
+      else
+        default_disk_storage_path
+      end
+
+      parsed_options[:prefix] = if opts[:prefix]
+        opts[:prefix].end_with?("-") ? opts[:prefix] : "#{opts[:prefix]}-"
+      else
+        default_disk_storage_prefix
+      end
+
+      parsed_options[:fsync_frequency] = if opts[:fsync_frequency]
+        (opts[:fsync_frequency].to_i * 1_000).round
+      else
+        500
+      end
+
+      parsed_options
+    end
+  end
+
   # @private
   class Internal
     attr_accessor :rails_mode

data/lib/rage/controller/api.rb

@@ -618,6 +618,7 @@ class RageController::API
   #  stale?(etag: "123", last_modified: Time.utc(2023, 12, 15))
   #  stale?(last_modified: Time.utc(2023, 12, 15))
   #  stale?(etag: "123")
+  # @note `stale?` will set ETag and Last-Modified response headers made of passed arguments in the method. Value for ETag will be additionally hashified using SHA1 algorithm, whereas value for Last-Modified will be converted to the string which represents time as RFC 1123 date of HTTP-date defined by RFC 2616.
   # @note `stale?` will set the response status to 304 if the request is fresh. This side effect will cause a double render error, if `render` gets called after this method. Make sure to implement a proper conditional in your action to prevent this from happening:
   #  ```ruby
   #  if stale?(etag: "123")
@@ -625,7 +626,10 @@ class RageController::API
   #  end
   #  ```
   def stale?(etag: nil, last_modified: nil)
-    still_fresh = request.fresh?(etag:, last_modified:)
+    response.etag = etag
+    response.last_modified = last_modified
+
+    still_fresh = request.fresh?(etag: response.etag, last_modified: last_modified)
 
     head :not_modified if still_fresh
     !still_fresh

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

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+##
+# `Rage::Deferred::Backends` implements a storage layer to persist deferred tasks.
+# A storage should implement the following instance methods:
+#
+# * `add` - called when a task has to be added to the storage;
+# * `remove` - called when a task has to be removed from the storage;
+# * `pending_tasks` - the method should iterate over the underlying storage and return a list of tasks to replay;
+#
+class Rage::Deferred::Backends::Disk
+  STORAGE_VERSION = "0"
+  STORAGE_SIZE_INCREASE_RATIO = 1.5
+
+  DEFAULT_PUBLISH_AT = "0"
+  DEFAULT_STORAGE_SIZE_LIMIT = 2_000_000
+
+  def initialize(path:, prefix:, fsync_frequency:)
+    @storage_path = path
+    @storage_prefix = "#{prefix}#{STORAGE_VERSION}"
+    @fsync_frequency = fsync_frequency
+
+    @storage_path.mkpath
+
+    # try to open and take ownership of all storage files in the storage directory
+    storage_files = @storage_path.glob("#{@storage_prefix}-*").filter_map do |file_path|
+      file = file_path.open("a+b")
+      if file.flock(File::LOCK_EX | File::LOCK_NB)
+        sleep 0.01 # reduce contention between workers
+        file
+      else
+        file.close
+      end
+    end
+
+    # if there are no storage files - create one;
+    # otherwise the first one is used as the main storage; the rest will be merged into the main storage
+    if storage_files.empty?
+      @storage = create_storage
+    else
+      @storage = storage_files[0]
+      @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
+    @task_id_base, @task_id_i = "#{task_id_seed}-#{Process.pid}", 0
+    Iodine.run_every(1_000) do
+      task_id_seed += 1
+      @task_id_base, @task_id_i = "#{task_id_seed}-#{Process.pid}", 0
+    end
+
+    @storage_size_limit = DEFAULT_STORAGE_SIZE_LIMIT
+    @storage_size = @storage.size
+    @fsync_scheduled = false
+    @should_rotate = false
+
+    # we use different counters for different tasks:
+    # delayed tasks are stored in the hash; for regular tasks we only maintain a counter;
+    # this information is only used during storage rotation
+    @immediate_tasks_in_queue = 0
+    @delayed_tasks = {}
+
+    # ensure data is written to disk
+    @storage_has_changes = false
+    Iodine.run_every(@fsync_frequency) do
+      if @storage_has_changes
+        @storage_has_changes = false
+        @storage.fsync
+      end
+    end
+  end
+
+  # Add a record to the log representing a new task.
+  # @param task [Rage::Deferred::Task]
+  # @param publish_at [Integer, nil]
+  # @param task_id [String, nil]
+  # @return [String]
+  def add(task, publish_at: nil, task_id: nil)
+    serialized_task = Marshal.dump(task).dump
+
+    persisted_task_id = task_id || generate_task_id
+
+    entry = build_add_entry(persisted_task_id, serialized_task, publish_at)
+    write_to_storage(entry)
+
+    if publish_at
+      @delayed_tasks[persisted_task_id] = [serialized_task, publish_at]
+    else
+      @immediate_tasks_in_queue += 1
+    end
+
+    persisted_task_id
+  end
+
+  # Add a record to the log representing a task removal.
+  # @param task_id [String]
+  def remove(task_id)
+    write_to_storage(build_remove_entry(task_id))
+
+    if @delayed_tasks.has_key?(task_id)
+      @delayed_tasks.delete(task_id)
+    else
+      @immediate_tasks_in_queue -= 1
+    end
+
+    # rotate the storage once the size is over the limit and all non-delayed tasks are processed
+    rotate_storage if @should_rotate && @immediate_tasks_in_queue == 0
+  end
+
+  # Return a list of pending tasks in the storage.
+  # @return [Array<(String, Rage::Deferred::Task, Integer, Integer)>
+  def pending_tasks
+    if @recovered_storages
+      # `@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) }
+    end
+
+    tasks = {}
+    corrupted_tasks_count = 0
+
+    # find pending tasks in the storage
+    @storage.tap(&:rewind).each_line(chomp: true) do |entry|
+      signature, op, payload = entry[0...8], entry[9...12], entry[9..]
+      next if signature&.empty? || payload&.empty? || op&.empty?
+
+      unless signature == Zlib.crc32(payload).to_s(16).rjust(8, "0")
+        corrupted_tasks_count += 1
+        next
+      end
+
+      if op == "add"
+        task_id = entry[13...entry.index(":", 13).to_i]
+        tasks[task_id] = entry
+      elsif op == "rem"
+        task_id = entry[13..]
+        tasks.delete(task_id)
+      end
+    end
+
+    if corrupted_tasks_count != 0
+      puts "WARNING: Detected #{corrupted_tasks_count} corrupted deferred task(s)"
+    end
+
+    tasks.filter_map do |task_id, entry|
+      _, _, _, serialized_publish_at, serialized_task = entry.split(":", 5)
+
+      task = Marshal.load(serialized_task.undump)
+
+      publish_at = (serialized_publish_at == DEFAULT_PUBLISH_AT ? nil : serialized_publish_at.to_i)
+
+      if publish_at
+        @delayed_tasks[task_id] = [serialized_task, publish_at]
+      else
+        @immediate_tasks_in_queue += 1
+      end
+
+      [task_id, task, publish_at]
+
+    rescue ArgumentError, NameError => e
+      puts "ERROR: Can't deserialize the task with id #{task_id}: (#{e.class}) #{e.message}"
+      nil
+    end
+  end
+
+  private
+
+  def generate_task_id
+    @task_id_i += 1
+    "#{@task_id_base}-#{@task_id_i}"
+  end
+
+  def create_storage
+    file = @storage_path.join("#{@storage_prefix}-#{Time.now.strftime("%Y%m%d")}-#{Process.pid}-#{rand(0x100000000).to_s(36)}")
+
+    file.open("a+b").tap { |f| f.flock(File::LOCK_EX) }
+  end
+
+  def write_to_storage(content, adjust_size_limit: false)
+    @storage.write(content)
+    @storage_has_changes = true
+
+    @storage_size += content.bytesize
+    @should_rotate = true if @storage_size >= @storage_size_limit
+
+    if adjust_size_limit
+      # if the data copied from recovered storages or during the rotation takes up most of the storage, we might
+      # end up in an infinite rotation loop; instead, we dynamically increase the storage size limit
+      if @storage_size * STORAGE_SIZE_INCREASE_RATIO >= @storage_size_limit
+        @storage_size_limit *= STORAGE_SIZE_INCREASE_RATIO
+        @should_rotate = false
+      end
+    end
+  end
+
+  def rotate_storage
+    old_storage = @storage
+    @storage = nil # in case `create_storage` ends up blocking the fiber
+
+    # create a new storage and update internal state;
+    # after this point all new tasks will be written to the new storage
+    @should_rotate = false
+    @storage_size = 0
+    @storage_size_limit = DEFAULT_STORAGE_SIZE_LIMIT
+    @storage = create_storage
+
+    # copy delayed tasks to the new storage in batches
+    @delayed_tasks.keys.each_slice(100) do |task_ids|
+      entries = task_ids.filter_map do |task_id|
+        # don't copy the task if it has already been processed during the rotation
+        next unless @delayed_tasks.has_key?(task_id)
+
+        serialized_task, publish_at = @delayed_tasks[task_id]
+        build_add_entry(task_id, serialized_task, publish_at)
+      end
+
+      write_to_storage(entries.join, adjust_size_limit: true)
+
+      Fiber.pause
+    end
+
+    # delete the old storage ensuring the copied data has already been written to disk
+    Iodine.run_after(@fsync_frequency) do
+      old_storage.close
+      File.unlink(old_storage.path)
+    end
+  end
+
+  def build_add_entry(task_id, serialized_task, publish_at)
+    entry = "add:#{task_id}:#{publish_at || DEFAULT_PUBLISH_AT}:#{serialized_task}"
+    crc = Zlib.crc32(entry).to_s(16).rjust(8, "0")
+
+    "#{crc}:#{entry}\n"
+  end
+
+  def build_remove_entry(task_id)
+    entry = "rem:#{task_id}"
+    crc = Zlib.crc32(entry).to_s(16).rjust(8, "0")
+
+    "#{crc}:#{entry}\n"
+  end
+
+  def recover_tasks(storage)
+    # copy records to the main storage
+    while (content = storage.read(262_144))
+      write_to_storage(content, adjust_size_limit: true)
+    end
+
+    Iodine.run_after(@fsync_frequency) do
+      storage.close
+      File.unlink(storage.path)
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Rage::Deferred::Backends::Nil
+  def initialize(**)
+  end
+
+  def add(_, **)
+  end
+
+  def remove(_)
+  end
+
+  def pending_tasks
+    []
+  end
+end

data/lib/rage/deferred/deferred.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+##
+# `Rage::Deferred` is an in-process background task queue with at-least-once delivery guarantee that allows you to schedule tasks to be executed later.
+# It can be used to offload long-running operations, such as sending emails or communicating with external APIs.
+#
+# To schedule a task, first define a task class that includes `Rage::Deferred::Task` and implements the `#perform` method.
+#
+# ```ruby
+# class SendWelcomeEmail
+#   include Rage::Deferred::Task
+#
+#   def perform(email)
+#     # logic to send the welcome email
+#   end
+# end
+# ```
+#
+# Then, push the task to the deferred queue:
+#
+# ```ruby
+# SendWelcomeEmail.enqueue(email: user.email)
+# ```
+#
+# You can also specify a delay for the task execution using the `delay` option:
+#
+# ```ruby
+# SendWelcomeEmail.enqueue(email: user.email, delay: 10) # execute after 10 seconds
+# ```
+#
+# Or you can specify a specific time in the future when the task should be executed:
+#
+# ```ruby
+# SendWelcomeEmail.enqueue(email: user.email, delay_until: Time.now + 3600) # execute in 1 hour
+# ```
+#
+module Rage::Deferred
+  # Push an instance to the deferred queue without including the `Rage::Deferred::Task` module.
+  # @param instance [Object] the instance to wrap
+  # @param delay [Integer, nil] the delay in seconds before the task is executed
+  # @param delay_until [Time, nil] the specific time when the task should be executed
+  # @example Schedule an arbitrary method to be called in the background
+  #   class SendWelcomeEmail < Struct.new(:email)
+  #     def call
+  #     end
+  #   end
+  #
+  #   email_service = SendWelcomeEmail.new(email: user.email)
+  #   Rage::Deferred.wrap(email_service).call
+  def self.wrap(instance, delay: nil, delay_until: nil)
+    Rage::Deferred::Proxy.new(instance, delay:, delay_until:)
+  end
+
+  # @private
+  def self.__backend
+    @__backend ||= Rage.config.deferred.backend
+  end
+
+  # @private
+  def self.__queue
+    @__queue ||= Rage::Deferred::Queue.new(__backend)
+  end
+
+  # @private
+  def self.__load_tasks
+    current_time = Time.now.to_i
+
+    __backend.pending_tasks.each do |task_id, task_wrapper, publish_at|
+      publish_in = publish_at - current_time if publish_at
+      __queue.schedule(task_id, task_wrapper, publish_in:)
+    rescue => e
+      puts "ERROR: Failed to load deferred task #{task_id}: #{e.class} (#{e.message}). Removing task from the queue."
+      __backend.remove(task_id)
+    end
+  end
+
+  module Backends
+  end
+
+  class PushTimeout < StandardError
+  end
+end
+
+require_relative "task"
+require_relative "queue"
+require_relative "proxy"
+require_relative "metadata"
+require_relative "backends/disk"
+require_relative "backends/nil"
+
+if Iodine.running?
+  Rage::Deferred.__load_tasks
+else
+  Iodine.on_state(:on_start) { Rage::Deferred.__load_tasks }
+end

data/lib/rage/deferred/metadata.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+##
+# Metadata for deferred tasks.
+# The class encapsulates the metadata associated with a deferred task, and allows to store it without modifying the task instance.
+#
+class Rage::Deferred::Metadata
+  def self.build(task, args, kwargs)
+    request_id = Thread.current[:rage_logger][:tags][0] if Thread.current[:rage_logger]
+
+    [
+      task,
+      args.empty? ? nil : args,
+      kwargs.empty? ? nil : kwargs,
+      nil,
+      request_id
+    ]
+  end
+
+  def self.get_task(metadata)
+    metadata[0]
+  end
+
+  def self.get_args(metadata)
+    metadata[1]
+  end
+
+  def self.get_kwargs(metadata)
+    metadata[2]
+  end
+
+  def self.get_attempts(metadata)
+    metadata[3]
+  end
+
+  def self.get_request_id(metadata)
+    metadata[4]
+  end
+
+  def self.inc_attempts(metadata)
+    metadata[3] = metadata[3].to_i + 1
+  end
+end

data/lib/rage/deferred/proxy.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class Rage::Deferred::Proxy
+  class Wrapper
+    include Rage::Deferred::Task
+
+    def perform(instance, method_name, *, **)
+      instance.public_send(method_name, *, **)
+    end
+  end
+
+  def initialize(instance, delay: nil, delay_until: nil)
+    @instance = instance
+
+    @delay = delay
+    @delay_until = delay_until
+  end
+
+  def method_missing(method_name, *, **)
+    if @instance.respond_to?(method_name)
+      self.class.define_method(method_name) do |*args, **kwargs|
+        Wrapper.enqueue(@instance, method_name, *args, delay: @delay, delay_until: @delay_until, **kwargs)
+      end
+
+      send(method_name, *, **)
+    else
+      @instance.public_send(method_name, *, **)
+    end
+  end
+
+  def respond_to_missing?(method_name, _)
+    @instance.respond_to?(method_name)
+  end
+end

data/lib/rage/deferred/queue.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+class Rage::Deferred::Queue
+  attr_reader :backlog_size
+
+  def initialize(backend)
+    @backend = backend
+    @backlog_size = 0
+    @backpressure = Rage.config.deferred.backpressure
+  end
+
+  # Write the task to the storage and schedule it for execution.
+  def enqueue(task_metadata, delay: nil, delay_until: nil, task_id: nil)
+    apply_backpressure if @backpressure
+
+    publish_in, publish_at = if delay
+      delay_i = delay.to_i
+      [delay_i, Time.now.to_i + delay_i] if delay_i > 0
+    elsif delay_until
+      delay_until_i, current_time_i = delay_until.to_i, Time.now.to_i
+      [delay_until_i - current_time_i, delay_until_i] if delay_until_i > current_time_i
+    end
+
+    persisted_task_id = @backend.add(task_metadata, publish_at:, task_id:)
+    schedule(persisted_task_id, task_metadata, publish_in:)
+  end
+
+  # Schedule the task for execution.
+  def schedule(task_id, task_metadata, publish_in: nil)
+    publish_in_ms = publish_in.to_i * 1_000 if publish_in && publish_in > 0
+    task = Rage::Deferred::Metadata.get_task(task_metadata)
+    @backlog_size += 1 unless publish_in_ms
+
+    Iodine.run_after(publish_in_ms) do
+      @backlog_size -= 1 unless publish_in_ms
+
+      unless Iodine.stopping?
+        Fiber.schedule do
+          Iodine.task_inc!
+
+          is_completed = task.new.__perform(task_metadata)
+
+          if is_completed
+            @backend.remove(task_id)
+          else
+            attempts = Rage::Deferred::Metadata.inc_attempts(task_metadata)
+            if task.__should_retry?(attempts)
+              enqueue(task_metadata, delay: task.__next_retry_in(attempts), task_id:)
+            else
+              @backend.remove(task_id)
+            end
+          end
+
+        ensure
+          Iodine.task_dec!
+        end
+      end
+    end
+  end
+
+  private
+
+  def apply_backpressure
+    if @backlog_size > @backpressure.high_water_mark
+      i, target_backlog_size = 0, @backpressure.low_water_mark
+      while @backlog_size > target_backlog_size && i < @backpressure.timeout_iterations
+        sleep @backpressure.sleep_interval
+        i += 1
+      end
+
+      if i == @backpressure.timeout_iterations
+        raise Rage::Deferred::PushTimeout, "could not enqueue deferred task within #{@backpressure.timeout} seconds"
+      end
+    end
+  end
+end

data/lib/rage/deferred/task.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+##
+# `Rage::Deferred::Task` is a module that should be included in classes that represent tasks to be executed
+# in the background by the `Rage::Deferred` queue. It ensures the tasks can be retried in case of a failure,
+# with a maximum number of attempts and an exponential backoff strategy.
+#
+# To define a task, include the module and implement the `#perform` method:
+#
+# ```ruby
+# class ProcessImage
+#   include Rage::Deferred::Task
+#
+#   def perform(image_path:)
+#     # logic to process the image
+#   end
+# end
+# ```
+#
+# The task can be enqueued using the `enqueue` method:
+#
+# ```ruby
+# ProcessImage.enqueue(image_path: 'path/to/image.jpg')
+# ```
+#
+# The `delay` and `delay_until` options can be used to specify when the task should be executed.
+#
+# ```ruby
+# ProcessImage.enqueue(image_path: 'path/to/image.jpg', delay: 10) # delays execution by 10 seconds
+# ProcessImage.enqueue(image_path: 'path/to/image.jpg', delay_until: Time.now + 3600) # executes after 1 hour
+# ```
+#
+module Rage::Deferred::Task
+  MAX_ATTEMPTS = 5
+  private_constant :MAX_ATTEMPTS
+
+  BACKOFF_INTERVAL = 5
+  private_constant :BACKOFF_INTERVAL
+
+  def perform
+  end
+
+  # @private
+  def __with_optional_log_tag(tag)
+    if tag
+      Rage.logger.tagged(tag) { yield }
+    else
+      yield
+    end
+  end
+
+  # @private
+  def __perform(metadata)
+    args = Rage::Deferred::Metadata.get_args(metadata)
+    kwargs = Rage::Deferred::Metadata.get_kwargs(metadata)
+    attempts = Rage::Deferred::Metadata.get_attempts(metadata)
+    request_id = Rage::Deferred::Metadata.get_request_id(metadata)
+
+    context = { task: self.class.name }
+    context[:attempt] = attempts + 1 if attempts
+
+    Rage.logger.with_context(context) do
+      __with_optional_log_tag(request_id) do
+        perform(*args, **kwargs)
+        true
+      rescue Exception => e
+        Rage.logger.error("Deferred task failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+        false
+      end
+    end
+  end
+
+  def self.included(klass)
+    klass.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def enqueue(*args, delay: nil, delay_until: nil, **kwargs)
+      Rage::Deferred.__queue.enqueue(
+        Rage::Deferred::Metadata.build(self, args, kwargs),
+        delay:,
+        delay_until:
+      )
+    end
+
+    # @private
+    def __should_retry?(attempts)
+      attempts < MAX_ATTEMPTS
+    end
+
+    # @private
+    def __next_retry_in(attempts)
+      rand(BACKOFF_INTERVAL * 2**attempts.to_i) + 1
+    end
+  end
+end

data/lib/rage/fiber_scheduler.rb

@@ -63,6 +63,7 @@ class Rage::FiberScheduler
 
   def kernel_sleep(duration = nil)
     block(nil, duration || 0)
+    Fiber.pause if duration.nil? || duration < 1
   end
 
   # TODO: GC works a little strange with this closure;

data/lib/rage/response.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
+require "digest"
+require "time"
+
 class Rage::Response
+  ETAG_HEADER = "ETag"
+  LAST_MODIFIED_HEADER = "Last-Modified"
+
   # @private
   def initialize(headers, body)
     @headers = headers
@@ -18,4 +24,37 @@ class Rage::Response
   def headers
     @headers
   end
+
+  # Returns ETag response header or +nil+ if it's empty.
+  #
+  # @return [String, nil]
+  def etag
+    headers[Rage::Response::ETAG_HEADER]
+  end
+
+  # Sets ETag header to the response. Additionally, it will hashify the value using +Digest::SHA1.hexdigest+. Pass +nil+ for resetting it.
+  # @note ETag will be always Weak since no strong validation is implemented.
+  # @note ArgumentError is raised if ETag value is neither +String+, nor +nil+
+  # @param etag [String, nil] The etag of the resource in the response.
+  def etag=(etag)
+    raise ArgumentError, "Expected `String` but `#{etag.class}` is received" unless etag.is_a?(String) || etag.nil?
+
+    headers[Rage::Response::ETAG_HEADER] = etag.nil? ? nil : %(W/"#{Digest::SHA1.hexdigest(etag)}")
+  end
+
+  # Returns Last-Modified response header or +nil+ if it's empty.
+  #
+  # @return [String, nil]
+  def last_modified
+    headers[Rage::Response::LAST_MODIFIED_HEADER]
+  end
+
+  # Sets Last-Modified header to the response by calling httpdate on the argument.
+  # @note ArgumentError is raised if +last_modified+ is not a +Time+ object instance
+  # @param last_modified [Time, nil] The last modified time of the resource in the response.
+  def last_modified=(last_modified)
+    raise ArgumentError, "Expected `Time` but `#{last_modified.class}` is received" unless last_modified.is_a?(Time) || last_modified.nil?
+
+    headers[Rage::Response::LAST_MODIFIED_HEADER] = last_modified&.httpdate
+  end
 end

data/lib/rage/templates/controller-template/controller.rb

@@ -0,0 +1,2 @@
+class <%= @controller_name %> < ApplicationController
+end

data/lib/rage/version.rb

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

data/lib/rage-rb.rb

@@ -22,6 +22,10 @@ module Rage
     Rage::OpenAPI
   end
 
+  def self.deferred
+    Rage::Deferred
+  end
+
   def self.routes
     Rage::Router::DSL.new(__router)
   end
@@ -130,6 +134,7 @@ module Rage
   autoload :Session, "rage/session"
   autoload :Cable, "rage/cable/cable"
   autoload :OpenAPI, "rage/openapi/openapi"
+  autoload :Deferred, "rage/deferred/deferred"
 end
 
 module RageController

data/rage.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "thor", "~> 1.0"
   spec.add_dependency "rack", "~> 2.0"
-  spec.add_dependency "rage-iodine", "~> 4.1"
+  spec.add_dependency "rage-iodine", "~> 4.3"
   spec.add_dependency "zeitwerk", "~> 2.6"
   spec.add_dependency "rack-test", "~> 2.1"
   spec.add_dependency "rake", ">= 12.0"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 1.16.0
+  version: 1.17.1
 platform: ruby
 authors:
 - Roman Samoilov
 bindir: exe
 cert_chain: []
-date: 2025-05-20 00:00:00.000000000 Z
+date: 2025-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.3'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -128,6 +128,13 @@ files:
 - lib/rage/configuration.rb
 - lib/rage/controller/api.rb
 - lib/rage/cookies.rb
+- lib/rage/deferred/backends/disk.rb
+- lib/rage/deferred/backends/nil.rb
+- lib/rage/deferred/deferred.rb
+- lib/rage/deferred/metadata.rb
+- lib/rage/deferred/proxy.rb
+- lib/rage/deferred/queue.rb
+- lib/rage/deferred/task.rb
 - lib/rage/env.rb
 - lib/rage/errors.rb
 - lib/rage/ext/active_record/connection_pool.rb
@@ -189,6 +196,7 @@ files:
 - lib/rage/templates/config-initializers-.keep
 - lib/rage/templates/config-routes.rb
 - lib/rage/templates/config.ru
+- lib/rage/templates/controller-template/controller.rb
 - lib/rage/templates/db-templates/app-models-application_record.rb
 - lib/rage/templates/db-templates/db-seeds.rb
 - lib/rage/templates/db-templates/mysql/config-database.yml