rage-rb 1.15.1 → 1.17.0

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,78 @@
+# 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 && !Fiber[:rage_backpressure_applied]
+      Fiber[:rage_backpressure_applied] = true
+
+      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/hooks.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hooks
+  def hooks
+    @hooks ||= Hash.new { |h, k| h[k] = [] }
+  end
+
+  def push_hook(callback, hook_family)
+    hooks[hook_family] << callback if callback.is_a?(Proc)
+  end
+
+  def run_hooks_for!(hook_family, context = nil)
+    hooks[hook_family].each do |callback|
+      if context
+        context.instance_exec(&callback)
+      else
+        callback.call
+      end
+    end
+
+    @hooks[hook_family] = []
+
+    true
+  end
+end

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

@@ -20,7 +20,7 @@ class Rage::OpenAPI::Parsers::Ext::Alba
 
   def __parse_nested(klass_str)
     __parse(klass_str).tap { |visitor|
-      visitor.root_key = visitor.root_key_for_collection = visitor.key_transformer = nil
+      visitor.root_key = visitor.root_key_for_collection = visitor.root_key_proc = visitor.key_transformer = nil
     }.build_schema
   end
 
@@ -50,7 +50,7 @@ class Rage::OpenAPI::Parsers::Ext::Alba
   end
 
   class Visitor < Prism::Visitor
-    attr_accessor :schema, :root_key, :root_key_for_collection, :key_transformer, :collection_key, :meta
+    attr_accessor :schema, :root_key, :root_key_for_collection, :root_key_proc, :key_transformer, :collection_key, :meta
 
     def initialize(parser, is_collection)
       @parser = parser
@@ -64,6 +64,7 @@ class Rage::OpenAPI::Parsers::Ext::Alba
       @self_name = nil
       @root_key = nil
       @root_key_for_collection = nil
+      @root_key_proc = nil
       @key_transformer = nil
       @collection_key = false
       @meta = {}
@@ -74,7 +75,7 @@ class Rage::OpenAPI::Parsers::Ext::Alba
 
       if node.name =~ /Resource$|Serializer$/ && node.superclass
         visitor = @parser.__parse(node.superclass.name)
-        @root_key, @root_key_for_collection = visitor.root_key, visitor.root_key_for_collection
+        @root_key, @root_key_for_collection, @root_key_proc = visitor.root_key, visitor.root_key_for_collection, visitor.root_key_proc
         @key_transformer, @collection_key, @meta = visitor.key_transformer, visitor.collection_key, visitor.meta
         @schema.merge!(visitor.schema)
       end
@@ -87,6 +88,13 @@ class Rage::OpenAPI::Parsers::Ext::Alba
 
       result["properties"] = @schema if @schema.any?
 
+      if @root_key_proc
+        dynamic_root_key, dynamic_root_key_for_collection = @root_key_proc.call(@self_name)
+
+        @root_key = dynamic_root_key
+        @root_key_for_collection = dynamic_root_key_for_collection
+      end
+
       if @is_collection
         result = if @collection_key && @root_key_for_collection
           { "type" => "object", "properties" => { @root_key_for_collection => { "type" => "object", "additionalProperties" => result }, **@meta } }
@@ -109,6 +117,7 @@ class Rage::OpenAPI::Parsers::Ext::Alba
     def visit_call_node(node)
       case node.name
       when :root_key
+        @root_key_proc = nil
         context = with_context { visit(node.arguments) }
         @root_key, @root_key_for_collection = context.symbols
 
@@ -135,12 +144,13 @@ class Rage::OpenAPI::Parsers::Ext::Alba
       when :many, :has_many, :one, :has_one, :association
         is_array = node.name == :many || node.name == :has_many
         context = with_context { visit(node.arguments) }
-        key = context.keywords["key"] || context.symbols[0]
+        association = context.symbols[0]
+        key = context.keywords["key"] || association
 
         if node.block
           with_inner_segment(key, is_array:) { visit(node.block) }
         else
-          resource = context.keywords["resource"] || (::Alba.inflector && "#{::Alba.inflector.classify(key.to_s)}Resource")
+          resource = context.keywords["resource"] || (::Alba.inflector && "#{::Alba.inflector.classify(association.to_s)}Resource")
           is_valid_resource = @parser.namespace.const_get(resource) rescue false
 
           @segment[key] = if is_array
@@ -159,10 +169,14 @@ class Rage::OpenAPI::Parsers::Ext::Alba
 
       when :root_key!
         if (inflector = ::Alba.inflector)
-          suffix = @self_name.end_with?("Resource") ? "Resource" : "Serializer"
-          name = inflector.demodulize(@self_name).delete_suffix(suffix)
-          @root_key = inflector.underscore(name)
-          @root_key_for_collection = inflector.pluralize(@root_key) if @is_collection
+          @root_key, @root_key_for_collection = nil
+
+          @root_key_proc = ->(resource_name) do
+            suffix = resource_name.end_with?("Resource") ? "Resource" : "Serializer"
+            name = inflector.demodulize(resource_name).delete_suffix(suffix)
+
+            inflector.underscore(name).yield_self { |key| [key, inflector.pluralize(key)] }
+          end
         end
       end
     end

data/lib/rage/request.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "time"
-require "set" # required for ruby 3.1
 
 class Rage::Request
   # @private

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/router/constrainer.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "set"
-
 class Rage::Router::Constrainer
   attr_reader :strategies
 

data/lib/rage/router/node.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "set"
-
 module Rage::Router
   class Node
     STATIC = 0

data/lib/rage/rspec.rb

@@ -101,7 +101,7 @@ end
 # patch MockResponse class
 class Rack::MockResponse
   def parsed_body
-    if headers["content-type"].start_with?("application/json")
+    if headers["content-type"]&.start_with?("application/json")
       JSON.parse(body)
     else
       body

data/lib/rage/setup.rb

@@ -14,4 +14,7 @@ require "rage/ext/setup"
 # Load application classes
 Rage.code_loader.setup
 
+# Run after_initialize hooks
+Rage.config.run_after_initialize!
+
 require_relative "#{Rage.root}/config/routes"

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.15.1"
+  VERSION = "1.17.0"
 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
@@ -107,6 +111,10 @@ module Rage
     end
   end
 
+  class << self
+    alias_method :configuration, :config
+  end
+
   module Router
     module Strategies
     end
@@ -126,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

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Fast web framework compatible with Rails."
   spec.homepage = "https://github.com/rage-rb/rage"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.1.0"
+  spec.required_ruby_version = ">= 3.2.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/rage-rb/rage"
@@ -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.15.1
+  version: 1.17.0
 platform: ruby
 authors:
 - Roman Samoilov
 bindir: exe
 cert_chain: []
-date: 2025-04-17 00:00:00.000000000 Z
+date: 2025-08-20 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
@@ -119,19 +119,29 @@ files:
 - lib/rage/cable/cable.rb
 - lib/rage/cable/channel.rb
 - lib/rage/cable/connection.rb
-- lib/rage/cable/protocol/actioncable_v1_json.rb
+- lib/rage/cable/protocols/actioncable_v1_json.rb
+- lib/rage/cable/protocols/base.rb
+- lib/rage/cable/protocols/raw_web_socket_json.rb
 - lib/rage/cable/router.rb
 - lib/rage/cli.rb
 - lib/rage/code_loader.rb
 - 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
 - lib/rage/ext/setup.rb
 - lib/rage/fiber.rb
 - lib/rage/fiber_scheduler.rb
+- lib/rage/hooks.rb
 - lib/rage/logger/json_formatter.rb
 - lib/rage/logger/logger.rb
 - lib/rage/logger/text_formatter.rb
@@ -186,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
@@ -213,7 +224,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="