rage-rb 1.17.1 → 1.19.0

data/lib/rage/controller/api.rb

@@ -9,7 +9,7 @@ class RageController::API
     # returns the name of the newly defined method;
     # rubocop:disable Layout/IndentationWidth, Layout/EndAlignment, Layout/HeredocIndentation
     def __register_action(action)
-      raise Rage::Errors::RouterError, "The action '#{action}' could not be found for #{self}" unless method_defined?(action)
+      raise Rage::Errors::RouterError, "The action `#{action}` could not be found in the `#{self}` controller. This is likely due to route helpers pointing to non-existent actions in the controller. Please check your routes and ensure that all referenced actions exist." unless method_defined?(action)
 
       around_actions_total = 0
 
@@ -153,7 +153,13 @@ class RageController::API
             <<~RUBY
               context = {}
               append_info_to_payload(context)
-              Thread.current[:rage_logger][:context] = context
+
+              log_context = Thread.current[:rage_logger][:context]
+              if log_context.empty?
+                Thread.current[:rage_logger][:context] = context
+              else
+                Thread.current[:rage_logger][:context] = log_context.merge(context)
+              end
             RUBY
           end}
         end
@@ -448,7 +454,7 @@ class RageController::API
   # Get the request object. See {Rage::Request}.
   # @return [Rage::Request]
   def request
-    @request ||= Rage::Request.new(@__env)
+    @request ||= Rage::Request.new(@__env, controller: self)
   end
 
   # Get the response object. See {Rage::Response}.
@@ -635,6 +641,12 @@ class RageController::API
     !still_fresh
   end
 
+  # Get the name of the currently executed action.
+  # @return [String] the name of the currently executed action
+  def action_name
+    @__params[:action]
+  end
+
   # @private
   # for comatibility with `Rails.application.routes.recognize_path`
   def self.binary_params_for?(_)

data/lib/rage/deferred/context.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+##
+# Context for deferred tasks.
+# The class encapsulates the context associated with a deferred task, and allows to store it without modifying the task instance.
+#
+class Rage::Deferred::Context
+  def self.build(task, args, kwargs, storage: nil)
+    logger = Thread.current[:rage_logger]
+
+    [
+      task,
+      args.empty? ? nil : args,
+      kwargs.empty? ? nil : kwargs,
+      nil,
+      logger&.dig(:tags),
+      logger&.dig(:context)
+    ]
+  end
+
+  def self.get_task(context)
+    context[0]
+  end
+
+  def self.get_args(context)
+    context[1]
+  end
+
+  def self.get_kwargs(context)
+    context[2]
+  end
+
+  def self.get_attempts(context)
+    context[3]
+  end
+
+  def self.inc_attempts(context)
+    context[3] = context[3].to_i + 1
+  end
+
+  def self.get_log_tags(context)
+    context[4]
+  end
+
+  def self.get_log_context(context)
+    context[5]
+  end
+end

data/lib/rage/deferred/deferred.rb

@@ -79,12 +79,16 @@ module Rage::Deferred
 
   class PushTimeout < StandardError
   end
+
+  # @private
+  class TaskFailed < StandardError
+  end
 end
 
 require_relative "task"
 require_relative "queue"
 require_relative "proxy"
-require_relative "metadata"
+require_relative "context"
 require_relative "backends/disk"
 require_relative "backends/nil"
 

data/lib/rage/deferred/queue.rb

@@ -10,7 +10,7 @@ class Rage::Deferred::Queue
   end
 
   # Write the task to the storage and schedule it for execution.
-  def enqueue(task_metadata, delay: nil, delay_until: nil, task_id: nil)
+  def enqueue(context, delay: nil, delay_until: nil, task_id: nil)
     apply_backpressure if @backpressure
 
     publish_in, publish_at = if delay
@@ -21,14 +21,14 @@ class Rage::Deferred::Queue
       [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:)
+    persisted_task_id = @backend.add(context, publish_at:, task_id:)
+    schedule(persisted_task_id, context, publish_in:)
   end
 
   # Schedule the task for execution.
-  def schedule(task_id, task_metadata, publish_in: nil)
+  def schedule(task_id, context, 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)
+    task = Rage::Deferred::Context.get_task(context)
     @backlog_size += 1 unless publish_in_ms
 
     Iodine.run_after(publish_in_ms) do
@@ -38,14 +38,14 @@ class Rage::Deferred::Queue
         Fiber.schedule do
           Iodine.task_inc!
 
-          is_completed = task.new.__perform(task_metadata)
+          is_completed = task.new.__perform(context)
 
           if is_completed
             @backend.remove(task_id)
           else
-            attempts = Rage::Deferred::Metadata.inc_attempts(task_metadata)
+            attempts = Rage::Deferred::Context.inc_attempts(context)
             if task.__should_retry?(attempts)
-              enqueue(task_metadata, delay: task.__next_retry_in(attempts), task_id:)
+              enqueue(context, delay: task.__next_retry_in(attempts), task_id:)
             else
               @backend.remove(task_id)
             end

data/lib/rage/deferred/task.rb

@@ -41,32 +41,36 @@ module Rage::Deferred::Task
   end
 
   # @private
-  def __with_optional_log_tag(tag)
-    if tag
-      Rage.logger.tagged(tag) { yield }
-    else
-      yield
+  def __perform(context)
+    args = Rage::Deferred::Context.get_args(context)
+    kwargs = Rage::Deferred::Context.get_kwargs(context)
+    attempts = Rage::Deferred::Context.get_attempts(context)
+
+    restore_log_info(context)
+
+    task_log_context = { task: self.class.name }
+    task_log_context[:attempt] = attempts + 1 if attempts
+
+    Rage.logger.with_context(task_log_context) do
+      perform(*args, **kwargs)
+      true
+    rescue Rage::Deferred::TaskFailed
+      false
+    rescue Exception => e
+      Rage.logger.error("Deferred task failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+      false
     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
+  private def restore_log_info(context)
+    log_tags = Rage::Deferred::Context.get_log_tags(context)
+    log_context = Rage::Deferred::Context.get_log_context(context)
 
-    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
+    if log_tags.is_a?(Array)
+      Thread.current[:rage_logger] = { tags: log_tags, context: log_context }
+    elsif log_tags
+      # support the previous format where only `request_id` was passed
+      Thread.current[:rage_logger] = { tags: [log_tags], context: {} }
     end
   end
 
@@ -77,10 +81,12 @@ module Rage::Deferred::Task
   module ClassMethods
     def enqueue(*args, delay: nil, delay_until: nil, **kwargs)
       Rage::Deferred.__queue.enqueue(
-        Rage::Deferred::Metadata.build(self, args, kwargs),
+        Rage::Deferred::Context.build(self, args, kwargs),
         delay:,
         delay_until:
       )
+
+      nil
     end
 
     # @private

data/lib/rage/env.rb

@@ -1,5 +1,16 @@
 # frozen_string_literal: true
 
+##
+# {Rage::Env Rage::Env} represents the current environment of the Rage application.
+#
+# The class automatically detects the application's current environment by checking the `RAGE_ENV`, `RAILS_ENV`, and `RACK_ENV` environment variables.
+# It provides predicate methods to check which environment is active.
+#
+# @example
+#   # Start the application with `rage s -e preprod`
+#   Rage.env.development? # => false
+#   Rage.env.preprod?     # => true
+#
 class Rage::Env
   STANDARD_ENVS = %w(development test staging production)
 
@@ -28,6 +39,10 @@ class Rage::Env
     @env.to_sym
   end
 
+  def to_str
+    @env
+  end
+
   def to_s
     @env
   end

data/lib/rage/events/events.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+##
+# `Rage::Events` provides a lightweight event-driven system for publishing and subscribing to events.
+# Define events as data structures, register subscriber classes, and publish events to notify all relevant subscribers.
+# Subscribers can process events and optionally receive additional context with each event.
+#
+# Define an event:
+# ```ruby
+# UserRegistered = Data.define(:user_id)
+# ```
+#
+# Define a subscriber:
+# ```ruby
+# class SendWelcomeEmail
+#   include Rage::Events::Subscriber
+#   subscribe_to UserRegistered
+#
+#   def call(event)
+#     puts "Sending welcome email to user #{event.user_id}"
+#   end
+# end
+# ```
+#
+# Publish an event:
+# ```ruby
+# Rage::Events.publish(UserRegistered.new(user_id: 1))
+# ```
+#
+module Rage::Events
+  # Publish an event to all subscribers registered for the event's class or its ancestors.
+  # Optionally, additional context data can be provided and passed to each subscriber.
+  #
+  # @param event [Object] the event to publish
+  # @param context [Object] additional data to publish along with the event
+  # @example Publish an event
+  #   Rage::Events.publish(MyEvent.new)
+  # @example Publish an event with context
+  #   Rage::Events.publish(MyEvent.new, context: { published_at: Time.now })
+  def self.publish(event, context: nil)
+    handler = __event_handlers[event.class] || __build_event_handler(event.class)
+    handler.call(event, context)
+
+    nil
+  end
+
+  # @private
+  def self.__registered_subscribers
+    @__registered_subscribers ||= Hash.new { |hash, key| hash[key] = [] }
+  end
+
+  # @private
+  def self.__register_subscriber(event_class, handler_class)
+    __registered_subscribers[event_class] << handler_class
+  end
+
+  # @private
+  def self.__get_subscribers(event_class)
+    event_class.ancestors.take_while { |klass|
+      klass != Object && klass != Data
+    }.each_with_object([]) { |klass, memo|
+      memo.concat(__registered_subscribers[klass]).uniq! if __registered_subscribers.has_key?(klass)
+    }
+  end
+
+  # @private
+  def self.__event_handlers
+    @__event_handlers ||= {}
+  end
+
+  # @private
+  def self.__build_event_handler(event_class)
+    subscriber_calls = __get_subscribers(event_class).map do |subscriber_class|
+      subscriber_class.__register_rescue_handlers
+
+      arguments = "event"
+
+      context_type, _ = subscriber_class.instance_method(:call).parameters.find do |param_type, param_name|
+        param_name == :context || param_type == :keyrest
+      end
+
+      if context_type
+        if context_type == :keyreq
+          arguments += ", context: context || {}"
+        else
+          arguments += ", context:"
+        end
+      end
+
+      if subscriber_class.__is_deferred
+        "#{subscriber_class}.enqueue(#{arguments})"
+      else
+        "#{subscriber_class}.new.__call(#{arguments})"
+      end
+    end
+
+    if subscriber_calls.empty?
+      ->(_, _) {}
+    else
+      __event_handlers[event_class] = eval <<-RUBY
+        ->(event, context) { #{subscriber_calls.join("; ")} }
+      RUBY
+    end
+  end
+
+  # @private
+  def self.__reset_subscribers
+    __registered_subscribers.clear
+    __event_handlers.clear
+
+    Rage::Events.__eager_load_subscribers
+  end
+
+  # @private
+  def self.__eager_load_subscribers
+    subscribers = Dir["#{Rage.root}/app/**/*.rb"].select do |path|
+      File.foreach(path).any? do |line|
+        line.include?("include Rage::Events::Subscriber") || line.include?("subscribe_to")
+      end
+    end
+
+    subscribers.each do |path|
+      Rage.code_loader.load_file(path)
+    end
+
+  rescue => e
+    puts "ERROR: Failed to load an event subscriber: #{e.class} (#{e.message})."
+    puts e.backtrace.join("\n")
+  end
+end
+
+require_relative "subscriber"
+
+if Rage.env.development?
+  if Rage.config.internal.initialized?
+    Rage::Events.__eager_load_subscribers
+  else
+    Rage.config.after_initialize { Rage::Events.__eager_load_subscribers }
+  end
+end

data/lib/rage/events/subscriber.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+##
+# Include this module in a class to make it an event subscriber.
+#
+# Example:
+#
+# ```ruby
+# # Define an event class
+# MyEvent = Data.define
+#
+# # Define the subscriber class
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to MyEvent
+#
+#   def call(event)
+#     puts "Received event: #{event.inspect}"
+#   end
+# end
+#
+# # Publish an event
+# Rage::Events.publish(MyEvent.new)
+# ```
+#
+# When an event matching the specified class is published, the `call` method will be invoked with the event instance.
+#
+# You can also subscribe to multiple event classes:
+#
+# ```ruby
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to EventA, EventB
+#
+#   def call(event)
+#     puts "Received event: #{event.inspect}"
+#   end
+# end
+# ```
+#
+# Subscribers are executed synchronously by default. You can make a subscriber asynchronous by passing the `deferred` option:
+#
+# ```ruby
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to MyEvent, deferred: true
+#
+#   def call(event)
+#     puts "Received event in background: #{event.inspect}"
+#   end
+# end
+# ```
+#
+# Such subscriber will be executed in the background using Rage's deferred task system.
+#
+# You can also define custom error handling for exceptions raised during event processing using `rescue_from`:
+#
+# ```ruby
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to MyEvent
+#
+#   rescue_from StandardError do |exception|
+#     puts "An error occurred: #{exception.message}"
+#   end
+# end
+# ```
+#
+# @see ClassMethods
+#
+module Rage::Events::Subscriber
+  def self.included(handler_class)
+    handler_class.extend ClassMethods
+  end
+
+  # @private
+  def call(_)
+  end
+
+  # @private
+  def __call(event, context: nil)
+    Rage.logger.with_context(self.class.__log_context) do
+      context.nil? ? call(event) : call(event, context: context.freeze)
+    rescue Exception => _e
+      e = self.class.__rescue_handlers ? __run_rescue_handlers(_e) : _e
+
+      if e
+        Rage.logger.error("Subscriber failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+        raise Rage::Deferred::TaskFailed if self.class.__is_deferred
+      end
+    end
+  end
+
+  module ClassMethods
+    # @private
+    attr_accessor :__event_classes, :__is_deferred, :__log_context, :__rescue_handlers
+
+    # Subscribe the class to one or more events.
+    #
+    # @param event_classes [Class, Array<Class>] one or more event classes to subscribe to
+    # @param deferred [Boolean] whether to process events asynchronously
+    def subscribe_to(*event_classes, deferred: false)
+      @__event_classes = (@__event_classes || []) | event_classes
+      @__is_deferred = !!deferred
+      @__log_context = { subscriber: name }.freeze
+
+      @__event_classes.each do |event_class|
+        Rage::Events.__register_subscriber(event_class, self)
+      end
+
+      if @__is_deferred
+        include Rage::Deferred::Task
+        alias_method :perform, :__call
+      end
+    end
+
+    # Define exception handlers for the subscriber.
+    #
+    # @param klasses [Class, Array<Class>] one or more exception classes to handle
+    # @param with [Symbol, String] the method name to call when an exception is raised
+    # @yield [exception] optional block to handle the exception
+    # @note If you do not re-raise exceptions in deferred subscribers, the subscriber will be marked as successful and Rage will not attempt to retry it.
+    def rescue_from(*klasses, with: nil, &block)
+      unless with
+        if block_given?
+          with = Rage::Internal.define_dynamic_method(self, block)
+        else
+          raise ArgumentError, "No handler provided. Pass the `with` keyword argument or provide a block."
+        end
+      end
+
+      if @__rescue_handlers.nil?
+        @__rescue_handlers = []
+      elsif @__rescue_handlers.frozen?
+        @__rescue_handlers = @__rescue_handlers.dup
+      end
+
+      @__rescue_handlers.unshift([klasses, with])
+    end
+
+    # @private
+    def inherited(klass)
+      klass.__rescue_handlers = @__rescue_handlers.freeze
+      klass.subscribe_to(*@__event_classes, deferred: @__is_deferred) if @__event_classes
+    end
+
+    # @private
+    def __register_rescue_handlers
+      return if method_defined?(:__run_rescue_handlers, false) || @__rescue_handlers.nil?
+
+      matcher_calls = @__rescue_handlers.map do |klasses, handler|
+        handler_call = instance_method(handler).arity == 0 ? handler : "#{handler}(exception)"
+
+        <<~RUBY
+          when #{klasses.join(", ")}
+            #{handler_call}
+            nil
+        RUBY
+      end
+
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def __run_rescue_handlers(exception)
+          case exception
+          #{matcher_calls.join("\n")}
+          else
+            exception
+          end
+        rescue Exception => e
+          e
+        end
+      RUBY
+    end
+  end
+end

data/lib/rage/fiber.rb

@@ -118,6 +118,14 @@ class Fiber
     "block:#{object_id}:#{@__block_channel_i}"
   end
 
+  # @private
+  def __await_channel(force = false)
+    @__fiber_channel_i ||= 0
+    @__fiber_channel_i += 1 if force
+
+    "await:#{object_id}:#{@__fiber_channel_i}"
+  end
+
   # @private
   attr_accessor :__awaited_fileno
 
@@ -148,6 +156,7 @@ class Fiber
   # @note This method should only be used when multiple fibers have to be processed in parallel. There's no need to use `Fiber.await` for single IO calls.
   def self.await(fibers)
     f, fibers = Fiber.current, Array(fibers)
+    await_channel = f.__await_channel(true)
 
     # check which fibers are alive (i.e. have yielded) and which have errored out
     i, err, num_wait_for = 0, nil, 0
@@ -169,7 +178,7 @@ class Fiber
     end
 
     # wait on async fibers; resume right away if one of the fibers errors out
-    Iodine.subscribe("await:#{f.object_id}") do |_, err|
+    Iodine.subscribe(await_channel) do |_, err|
       if err == AWAIT_ERROR_MESSAGE
         f.resume
       else
@@ -179,7 +188,7 @@ class Fiber
     end
 
     Fiber.defer(-1)
-    Iodine.defer { Iodine.unsubscribe("await:#{f.object_id}") }
+    Iodine.defer { Iodine.unsubscribe(await_channel) }
 
     # if num_wait_for is not 0 means we exited prematurely because of an error
     if num_wait_for > 0

data/lib/rage/fiber_scheduler.rb

@@ -130,10 +130,10 @@ class Rage::FiberScheduler
         Thread.current[:rage_logger] = logger
         Fiber.current.__set_result(block.call)
         # send a message for `Fiber.await` to work
-        Iodine.publish("await:#{parent.object_id}", "", Iodine::PubSub::PROCESS) if parent.alive?
+        Iodine.publish(parent.__await_channel, "", Iodine::PubSub::PROCESS) if parent.alive?
       rescue Exception => e
         Fiber.current.__set_err(e)
-        Iodine.publish("await:#{parent.object_id}", Fiber::AWAIT_ERROR_MESSAGE, Iodine::PubSub::PROCESS) if parent.alive?
+        Iodine.publish(parent.__await_channel, Fiber::AWAIT_ERROR_MESSAGE, Iodine::PubSub::PROCESS) if parent.alive?
       end
     end
 

data/lib/rage/hooks.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# @private
 module Hooks
   def hooks
     @hooks ||= Hash.new { |h, k| h[k] = [] }

data/lib/rage/internal.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# @private
+class Rage::Internal
+  class << self
+    # Define a method based on a block.
+    # @param klass [Class] the class to define the method in
+    # @param block [Proc] the implementation of the new method
+    # @return [Symbol] the name of the newly defined method
+    def define_dynamic_method(klass, block)
+      name = dynamic_name_seed.next.join
+      klass.define_method("__rage_dynamic_#{name}", block)
+    end
+
+    # Define a method that will call a specified method if a condition is `true` or yield if `false`.
+    # @param klass [Class] the class to define the method in
+    # @param method_name [Symbol] the method to call if the condition is `true`
+    # @return [Symbol] the name of the newly defined method
+    def define_maybe_yield(klass, method_name)
+      name = dynamic_name_seed.next.join
+
+      klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def __rage_dynamic_#{name}(condition)
+          if condition
+            #{method_name} { yield }
+          else
+            yield
+          end
+        end
+      RUBY
+    end
+
+    # Build a string representation of keyword arguments based on the parameters expected by the method.
+    # @param method [Method, Proc] the method to build arguments for
+    # @param arguments [Hash] the arguments to include in the string representation
+    # @return [String] the string representation of the method arguments
+    def build_arguments(method, arguments)
+      expected_parameters = method.parameters
+
+      arguments.filter_map { |arg_name, arg_value|
+        if expected_parameters.any? { |param_type, param_name| param_name == arg_name || param_type == :keyrest }
+          "#{arg_name}: #{arg_value}"
+        end
+      }.join(", ")
+    end
+
+    private
+
+    def dynamic_name_seed
+      @dynamic_name_seed ||= ("a".."j").to_a.permutation
+    end
+  end
+end