rage-rb 1.19.2 → 1.20.0

data/lib/rage/deferred/task.rb

@@ -37,29 +37,55 @@ module Rage::Deferred::Task
   BACKOFF_INTERVAL = 5
   private_constant :BACKOFF_INTERVAL
 
+  # @private
+  CONTEXT_KEY = :__rage_deferred_execution_context
+
   def perform
   end
 
+  # Access metadata for the current task execution.
+  # @return [Rage::Deferred::Metadata] the metadata object for the current task execution
+  # @example
+  #   class MyTask
+  #     include Rage::Deferred::Task
+  #
+  #     def perform
+  #       puts meta.retries
+  #     end
+  #   end
+  def meta
+    Rage::Deferred::Metadata
+  end
+
   # @private
   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)
 
+    attempts = Rage::Deferred::Context.get_attempts(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
+    Fiber[CONTEXT_KEY] = context
+
+    Rage::Telemetry.tracer.span_deferred_task_process(task: self, context:) do
+      Rage::Deferred.__middleware_chain.with_perform_middleware(context, task: self) do
+        Rage.logger.with_context(task_log_context) do
+          args = Rage::Deferred::Context.get_args(context)
+          kwargs = Rage::Deferred::Context.get_kwargs(context)
+
+          perform(*args, **kwargs)
+        end
+      end
     end
+
+    true
+  rescue Exception => e
+    unless respond_to?(:__deferred_suppress_exception_logging?, true) && __deferred_suppress_exception_logging?
+      Rage.logger.with_context(task_log_context) do
+        Rage.logger.error("Deferred task failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+      end
+    end
+    false
   end
 
   private def restore_log_info(context)
@@ -80,11 +106,13 @@ module Rage::Deferred::Task
 
   module ClassMethods
     def enqueue(*args, delay: nil, delay_until: nil, **kwargs)
-      Rage::Deferred.__queue.enqueue(
-        Rage::Deferred::Context.build(self, args, kwargs),
-        delay:,
-        delay_until:
-      )
+      context = Rage::Deferred::Context.build(self, args, kwargs)
+
+      Rage::Telemetry.tracer.span_deferred_task_enqueue(task_class: self, context:) do
+        Rage::Deferred.__middleware_chain.with_enqueue_middleware(context, delay:, delay_until:) do
+          Rage::Deferred.__queue.enqueue(context, delay:, delay_until:)
+        end
+      end
 
       nil
     end

data/lib/rage/events/events.rb

@@ -39,7 +39,9 @@ module Rage::Events
   #   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)
+    Rage::Telemetry.tracer.span_events_event_publish(event:, context:) do
+      handler.call(event, context)
+    end
 
     nil
   end
@@ -71,8 +73,6 @@ module Rage::Events
   # @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|

data/lib/rage/events/subscriber.rb

@@ -79,16 +79,28 @@ module Rage::Events::Subscriber
 
   # @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
+    Rage::Telemetry.tracer.span_events_subscriber_process(event:, context:, subscriber: self) do
+      Rage.logger.with_context(self.class.__log_context) do
+        with_exception_handler do
+          context.nil? ? call(event) : call(event, context: context.freeze)
+        end
       end
     end
+  rescue Exception => e
+    Rage.logger.with_context(self.class.__log_context) do
+      Rage.logger.error("Subscriber failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+    end
+    raise e if self.class.__is_deferred
+  end
+
+  private
+
+  def __deferred_suppress_exception_logging?
+    true
+  end
+
+  def with_exception_handler
+    yield
   end
 
   module ClassMethods
@@ -136,6 +148,14 @@ module Rage::Events::Subscriber
       end
 
       @__rescue_handlers.unshift([klasses, with])
+
+      rebuild_exception_handler!
+    end
+
+    # Check if the subscriber is executed in the background.
+    # @return [Boolean] `true` if the subscriber is deferred, `false` otherwise
+    def deferred?
+      @__is_deferred
     end
 
     # @private
@@ -144,29 +164,20 @@ module Rage::Events::Subscriber
       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)"
+    private
 
+    def rebuild_exception_handler!
+      rescue_calls = @__rescue_handlers.map do |klasses, handler|
         <<~RUBY
-          when #{klasses.join(", ")}
-            #{handler_call}
-            nil
+          rescue #{klasses.join(", ")} => e
+            method(:#{handler}).arity == 0 ? #{handler} : #{handler}(e)
         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
+        private def with_exception_handler
+          yield
+          #{rescue_calls.join("\n")}
         end
       RUBY
     end

data/lib/rage/fiber.rb

@@ -158,43 +158,45 @@ class Fiber
     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
-    while i < fibers.length
-      if fibers[i].alive?
-        num_wait_for += 1
-      else
-        err = fibers[i].__get_err
-        break if err
+    Rage::Telemetry.tracer.span_core_fiber_await(fibers:) do
+      # check which fibers are alive (i.e. have yielded) and which have errored out
+      i, err, num_wait_for = 0, nil, 0
+      while i < fibers.length
+        if fibers[i].alive?
+          num_wait_for += 1
+        else
+          err = fibers[i].__get_err
+          break if err
+        end
+        i += 1
       end
-      i += 1
-    end
 
-    # raise if one of the fibers has errored out or return the result if none have yielded
-    if err
-      raise err
-    elsif num_wait_for == 0
-      return fibers.map!(&:__get_result)
-    end
+      # raise if one of the fibers has errored out or return the result if none have yielded
+      if err
+        raise err
+      elsif num_wait_for == 0
+        return fibers.map!(&:__get_result)
+      end
 
-    # wait on async fibers; resume right away if one of the fibers errors out
-    Iodine.subscribe(await_channel) do |_, err|
-      if err == AWAIT_ERROR_MESSAGE
-        f.resume
-      else
-        num_wait_for -= 1
-        f.resume if num_wait_for == 0
+      # wait on async fibers; resume right away if one of the fibers errors out
+      Iodine.subscribe(await_channel) do |_, err|
+        if err == AWAIT_ERROR_MESSAGE
+          f.resume
+        else
+          num_wait_for -= 1
+          f.resume if num_wait_for == 0
+        end
       end
-    end
 
-    Fiber.defer(-1)
-    Iodine.defer { Iodine.unsubscribe(await_channel) }
+      Fiber.defer(-1)
+      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
-      raise fibers.find(&:__get_err).__get_err
-    else
-      fibers.map!(&:__get_result)
+      # if num_wait_for is not 0 means we exited prematurely because of an error
+      if num_wait_for > 0
+        raise fibers.find(&:__get_err).__get_err
+      else
+        fibers.map!(&:__get_result)
+      end
     end
   end
 

data/lib/rage/fiber_scheduler.rb

@@ -120,7 +120,9 @@ class Rage::FiberScheduler
       # the fiber to wrap a request in
       Fiber.new(blocking: false) do
         Fiber.current.__set_id
-        Fiber.current.__set_result(block.call)
+        Rage::Telemetry.tracer.span_core_fiber_dispatch do
+          Fiber.current.__set_result(block.call)
+        end
       end
     else
       # the fiber was created in the user code
@@ -128,7 +130,9 @@ class Rage::FiberScheduler
 
       Fiber.new(blocking: false) do
         Thread.current[:rage_logger] = logger
-        Fiber.current.__set_result(block.call)
+        Rage::Telemetry.tracer.span_core_fiber_spawn(parent:) do
+          Fiber.current.__set_result(block.call)
+        end
         # send a message for `Fiber.await` to work
         Iodine.publish(parent.__await_channel, "", Iodine::PubSub::PROCESS) if parent.alive?
       rescue Exception => e

data/lib/rage/logger/logger.rb

@@ -209,7 +209,13 @@ class Rage::Logger
         RUBY
       elsif @external_logger.is_a?(External::Dynamic)
         # a callable object is used as a logger
-        parameters = Rage::Internal.build_arguments(@external_logger.wrapped, {
+        call_method = if @external_logger.wrapped.is_a?(Proc)
+          @external_logger.wrapped
+        else
+          @external_logger.wrapped.method(:call)
+        end
+
+        parameters = Rage::Internal.build_arguments(call_method, {
           severity: ":#{level_name}",
           tags: "logger[:tags].freeze",
           context: "logger[:context].freeze",

data/lib/rage/middleware/body_finalizer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class Rage::BodyFinalizer
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    response = @app.call(env)
+    response[2].close
+
+    response
+  end
+end

data/lib/rage/response.rb

@@ -8,21 +8,26 @@ class Rage::Response
   LAST_MODIFIED_HEADER = "last-modified"
 
   # @private
-  def initialize(headers, body)
-    @headers = headers
-    @body = body
+  def initialize(controller)
+    @controller = controller
+  end
+
+  # Returns the HTTP status code of the response.
+  # @return [Integer]
+  def status
+    @controller.__status
   end
 
   # Returns the content of the response as a string. This contains the contents of any calls to `render`.
   # @return [String]
   def body
-    @body[0] || ""
+    @controller.__body[0] || ""
   end
 
   # Returns the headers for the response.
   # @return [Hash]
   def headers
-    @headers
+    @controller.__headers
   end
 
   # Returns ETag response header or +nil+ if it's empty.

data/lib/rage/rspec.rb

@@ -14,23 +14,6 @@ require_relative "#{Rage.root}/config/application"
 # verify the environment
 abort("The test suite is running in #{Rage.env} mode instead of 'test'!") unless Rage.env.test?
 
-# mock fiber methods as RSpec tests don't run concurrently
-class Fiber
-  def self.schedule(&block)
-    fiber = Fiber.new(blocking: true) do
-      Fiber.current.__set_id
-      Fiber.current.__set_result(block.call)
-    end
-    fiber.resume
-
-    fiber
-  end
-
-  def self.await(fibers)
-    Array(fibers).map(&:__get_result)
-  end
-end
-
 # define request helpers
 module RageRequestHelpers
   include Rack::Test::Methods
@@ -96,6 +79,23 @@ end
 # include request helpers
 RSpec.configure do |config|
   config.include(RageRequestHelpers, type: :request)
+
+  # mock fiber methods as RSpec tests don't run concurrently
+  config.before do
+    allow(Fiber).to receive(:schedule) do |&block|
+      fiber = Fiber.new(blocking: true) do
+        Fiber.current.__set_id
+        Fiber.current.__set_result(block.call)
+      end
+      fiber.resume
+
+      fiber
+    end
+
+    allow(Fiber).to receive(:await) do |fibers|
+      Array(fibers).map(&:__get_result)
+    end
+  end
 end
 
 # patch MockResponse class

data/lib/rage/setup.rb

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

data/lib/rage/telemetry/handler.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+##
+# The class allows developers to define telemetry handlers that observe and react to specific span executions.
+#
+# Handlers are defined by subclassing `Rage::Telemetry::Handler` and using the `handle` class method
+# to specify which spans to observe and which methods to invoke when those spans are executed.
+#
+# See {Rage::Telemetry::Spans} for a list of available spans and arguments passed to the handler methods.
+#
+# Each handler method is expected to call `yield` to pass control to the next handler in the stack or the framework's core logic.
+# The call to `yield` returns an instance of {Rage::Telemetry::SpanResult} which contains information about the span execution.
+#
+# @example
+#   class MyTelemetryHandler < Rage::Telemetry::Handler
+#     handle "controller.action.process", with: :create_span
+#
+#     def create_span(name:)
+#       MyObservabilitySDK.in_span(name) do
+#         yield
+#       end
+#     end
+#   end
+#
+class Rage::Telemetry::Handler
+  class << self
+    # @private
+    attr_accessor :handlers_map
+
+    # Defines which spans the handler will observe and which method to invoke for those spans.
+    #
+    # @param span_ids [Array<String>] one or more span IDs to observe; supports wildcards (`*`) to match multiple spans
+    # @param with [Symbol] the method name to invoke when the specified spans are executed
+    # @param except [String, Array<String>, nil] optional list of span IDs to exclude from observation; supports wildcards (`*`) to match multiple spans
+    # @raise [ArgumentError] if any specified span ID is unknown or if no spans match a wildcard ID
+    #
+    # @example Observe a specific span
+    #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #     handle "controller.action.process", with: :my_handler_method
+    #
+    #     def my_handler_method
+    #       # ...
+    #     end
+    #   end
+    #
+    # @example Observe multiple spans with wildcards
+    #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #     handle "cable.*", with: :my_handler_method
+    #
+    #     def my_handler_method
+    #       # ...
+    #     end
+    #   end
+    #
+    # @example Observe all spans except specific ones
+    #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #     handle "*", except: "core.fiber.dispatch", with: :my_handler_method
+    #
+    #     def my_handler_method
+    #       # ...
+    #     end
+    #   end
+    #
+    def handle(*span_ids, with:, except: nil)
+      resolved_span_ids = resolve_span_ids(span_ids)
+
+      if except
+        resolved_span_ids -= resolve_span_ids(Array(except))
+      end
+
+      if @handlers_map.nil?
+        @handlers_map = {}
+      elsif @handlers_map.frozen?
+        @handlers_map = @handlers_map.transform_values(&:dup)
+      end
+
+      resolved_span_ids.each do |span_id|
+        @handlers_map[span_id] ||= Set.new
+        @handlers_map[span_id] << with
+      end
+    end
+
+    # @private
+    def inherited(klass)
+      klass.handlers_map = @handlers_map.freeze
+    end
+
+    private
+
+    def resolve_span_ids(span_ids)
+      all_span_ids = Rage::Telemetry.__registry.keys
+      return all_span_ids if span_ids.include?("*")
+
+      exact_span_ids, wildcard_span_ids = [], []
+
+      # separate span IDs based on whether they contain wildcards
+      span_ids.each do |span_id|
+        if span_id.include?("*")
+          wildcard_span_ids << span_id
+        else
+          exact_span_ids << span_id
+        end
+      end
+
+      # validate exact span IDs
+      resolved_span_ids = []
+
+      exact_span_ids.each do |span_id|
+        unless all_span_ids.include?(span_id)
+          raise ArgumentError, "Unknown span ID '#{span_id}'"
+        end
+
+        resolved_span_ids << span_id
+      end
+
+      # validate and resolve wildcard span IDs
+      wildcard_span_ids.each do |span_id|
+        matcher = Regexp.new(span_id.gsub("*", "\\w+").gsub(".", "\\."))
+        matched_span_ids = all_span_ids.select { |id| id.match?(matcher) }
+
+        unless matched_span_ids.any?
+          raise ArgumentError, "No spans match the wildcard ID '#{span_id}'"
+        end
+
+        resolved_span_ids += matched_span_ids
+      end
+
+      resolved_span_ids
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+##
+# The **core.fiber.await** span wraps the processing of the {Fiber.await} call.
+#
+# This span is started when a fiber begins awaiting other fibers, and ends when all awaited fibers have completed.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::AwaitFiber
+  class << self
+    # @private
+    def id
+      "core.fiber.await"
+    end
+
+    # @private
+    def span_parameters
+      %w[fibers:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Fiber.await"',
+        fibers: "Array(fibers)"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["core.fiber.await"] ID of the span
+    #   # @param name ["Fiber.await"] human-readable name of the operation
+    #   # @param fibers [Array<Fiber>] the fibers the current fiber is awaiting
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "core.fiber.await", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, fibers:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, fibers:)
+    #   end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+##
+# The **cable.stream.broadcast** span wraps the process of broadcasting a message to a `Rage::Cable` stream.
+#
+# This span is started when {Rage::Cable.broadcast Rage::Cable.broadcast} is called, and ends when the broadcast operation is complete.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::BroadcastCableStream
+  class << self
+    # @private
+    def id
+      "cable.stream.broadcast"
+    end
+
+    # @private
+    def span_parameters
+      %w[stream:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Rage::Cable.broadcast"',
+        stream: "stream"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["cable.stream.broadcast"] ID of the span
+    #   # @param name ["Rage::Cable.broadcast"] human-readable name of the operation
+    #   # @param stream [String] the name of the stream to which the message is being broadcasted
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "cable.stream.broadcast", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, stream:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, stream:)
+    #   end
+  end
+end