rage-rb 1.19.1 → 1.20.0

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+##
+# The **events.event.publish** span tracks the publishing of an event.
+#
+# This span is triggered whenever an event is published via {Rage::Events.publish Rage::Events.publish}.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::PublishEvent
+  class << self
+    # @private
+    def id
+      "events.event.publish"
+    end
+
+    # @private
+    def span_parameters
+      %w[event: context:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Events.publish(#{event.class})"',
+        event: "event",
+        context: "context",
+        subscriber_classes: "Rage::Events.__get_subscribers(event.class)"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["events.event.publish"] ID of the span
+    #   # @param name [String] human-readable name of the operation (e.g., `Events.publish(UpdateRecommendations)`)
+    #   # @param event [Object] the event being published
+    #   # @param context [Object, nil] the additional context passed along with the event
+    #   # @param subscriber_classes [Array<Rage::Events::Subscriber>] the list of subscriber classes that will receive the event
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "events.event.publish", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, event:, context:, subscriber_classes:)
+    #   #       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:, event:, context:, subscriber_classes:)
+    #   end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+##
+# The **core.fiber.spawn** span tracks the scheduling and processing of application-level fibers created via {Fiber.schedule}.
+#
+# This span is started when a fiber begins processing and ends when the fiber has completed processing.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::SpawnFiber
+  class << self
+    # @private
+    def id
+      "core.fiber.spawn"
+    end
+
+    # @private
+    def span_parameters
+      %w[parent:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Fiber.schedule"',
+        parent: "parent"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["core.fiber.spawn"] ID of the span
+    #   # @param name ["Fiber.schedule"] human-readable name of the operation
+    #   # @param parent [Fiber] the parent fiber that the current fiber was scheduled from
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "core.fiber.spawn", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, parent:)
+    #   #       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:, parent:)
+    #   end
+  end
+end

data/lib/rage/telemetry/telemetry.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+##
+# The `Rage::Telemetry` component provides an interface to monitor various operations and events within the Rage framework.
+#
+# To start using telemetry, define and register custom handlers that will process the telemetry data.
+#
+# 1. **Define Handlers**: Create custom telemetry handlers by subclassing {Rage::Telemetry::Handler Rage::Telemetry::Handler} and implementing the desired logic for processing telemetry data.
+#
+#     ```ruby
+#     class MyTelemetryHandler < Rage::Telemetry::Handler
+#       handle "controller.action.process", with: :log_action
+#
+#       def log_action(controller:)
+#         puts "Processing action: #{controller.action_name}"
+#         yield
+#       end
+#     end
+#     ```
+#
+# 2. **Register Handlers**: Register your custom handlers in the Rage configuration.
+#
+#     ```ruby
+#     Rage.configure do
+#       config.telemetry.use MyTelemetryHandler.new
+#     end
+#     ```
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+# @see Rage::Telemetry::Spans Rage::Telemetry::Spans
+#
+module Rage::Telemetry
+  # Returns the list of all available telemetry spans.
+  # @return [Array<String>] the list of available telemetry spans
+  def self.available_spans
+    __registry.keys
+  end
+
+  # @private
+  def self.__registry
+    @__registry ||= Spans.constants.each_with_object({}) do |const, memo|
+      span = Spans.const_get(const)
+      memo[span.id] = span
+    end
+  end
+
+  # @private
+  def self.tracer
+    @tracer ||= Tracer.new(__registry, Rage.config.telemetry.handlers_map)
+  end
+
+  # @private
+  def self.__setup
+    tracer.setup
+  end
+
+  ##
+  # The namespace contains all telemetry span definitions.
+  # Each span represents a specific operation or event within the framework that can be monitored and traced.
+  #
+  # Spans always pass two standard keyword arguments to their handlers:
+  #
+  # * `:id` - The unique identifier of the span.
+  # * `:name` - The human-readable name of the operation.
+  #
+  # Handlers can also receive additional context-specific keyword arguments as defined by each span.
+  #
+  # # Available Spans
+  #
+  # | ID | Reference | Description |
+  # | --- | --- |
+  # | `core.fiber.dispatch` | {DispatchFiber} | Wraps the scheduling and processing of system-level fibers created by the framework to process requests and deferred tasks |
+  # | `core.fiber.spawn` | {SpawnFiber} | Wraps the scheduling and processing of application-level fibers created via {Fiber.schedule} |
+  # | `core.fiber.await` | {AwaitFiber} | Wraps the processing of the {Fiber.await} calls |
+  # | `controller.action.process` | {ProcessControllerAction} | Wraps the processing of controller actions |
+  # | `cable.websocket.handshake` | {CreateWebsocketConnection} | Wraps the WebSocket connection handshake process |
+  # | `cable.connection.process` | {ProcessCableConnection} | Wraps the processing of connect actions in {Rage::Cable Rage::Cable} |
+  # | `cable.action.process` | {ProcessCableAction} | Wraps the processing of {Rage::Cable Rage::Cable} channel actions |
+  # | `cable.stream.broadcast` | {BroadcastCableStream} | Wraps the broadcasting of messages to {Rage::Cable Rage::Cable} streams |
+  # | `deferred.task.enqueue` | {EnqueueDeferredTask} | Wraps the enqueuing of deferred tasks |
+  # | `deferred.task.process` | {ProcessDeferredTask} | Wraps the processing of deferred tasks |
+  # | `events.event.publish` | {PublishEvent} | Wraps the publishing of events via {Rage::Events Rage::Events} |
+  # | `events.subscriber.process` | {ProcessEventSubscriber} | Wraps the processing of events by subscribers |
+  #
+  module Spans
+  end
+
+  # @private
+  HandlerRef = Data.define(:instance, :method_name)
+
+  # Contains the result of a span execution.
+  # @!attribute [r] exception
+  #   @return [Exception, nil] The exception raised during the span execution, if any.
+  # @example
+  #   class MyTelemetryHandler < Rage::Telemetry::Handler
+  #     handle "controller.action.process", with: :monitor_500
+  #
+  #     def monitor_500
+  #       result = yield
+  #
+  #       if result.error?
+  #         MyObservabilitySDK.notify("500 Error Detected", result.exception)
+  #       end
+  #     end
+  #   end
+  SpanResult = Struct.new(:exception) do
+    # Returns `true` if the span resulted in an error.
+    def error?
+      !!exception
+    end
+
+    # Returns `true` if the span executed successfully.
+    def success?
+      !error?
+    end
+  end
+end
+
+require_relative "tracer"
+require_relative "handler"
+Dir["#{__dir__}/spans/*.rb"].each { |span| require_relative span }

data/lib/rage/telemetry/tracer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+class Rage::Telemetry::Tracer
+  DEFAULT_SPAN_RESULT = Rage::Telemetry::SpanResult.new.freeze
+  private_constant :DEFAULT_SPAN_RESULT
+
+  # @param spans_registry [Hash{String => Rage::Telemetry::Spans}]
+  # @param handlers_map [Hash{String => Array<Rage::Telemetry::HandlerRef>}]
+  def initialize(spans_registry, handlers_map)
+    @spans_registry = spans_registry
+    @handlers_map = handlers_map
+
+    @all_handler_refs = handlers_map.values.flatten
+
+    @spans_registry.each do |_, span|
+      setup_noop(span)
+    end
+  end
+
+  def setup
+    @handlers_map.each do |span_id, handler_refs|
+      setup_tracer(@spans_registry[span_id], handler_refs)
+    end
+  end
+
+  private
+
+  # @param span [Rage::Telemetry::Spans]
+  def setup_noop(span)
+    parameters = span.span_parameters.join(", ")
+
+    self.class.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def #{tracer_name(span.id)}(#{parameters})
+        yield
+      end
+    RUBY
+  end
+
+  # @param span [Rage::Telemetry::Spans]
+  # @param handler_refs [Array<Rage::Telemetry::HandlerRef>]
+  def setup_tracer(span, handler_refs)
+    yield_call = <<~RUBY
+        yield_called = true
+        yield_result = yield
+        span_result = DEFAULT_SPAN_RESULT
+      rescue Exception => e
+        yield_error = e
+        span_result = Rage::Telemetry::SpanResult.new(e).freeze
+    RUBY
+
+    calls_chain = handler_refs.reverse.inject(yield_call) do |memo, handler_ref|
+      handler_index = @all_handler_refs.index(handler_ref)
+
+      handler_method = handler_ref.instance.method(handler_ref.method_name)
+      handler_arguments = Rage::Internal.build_arguments(
+        handler_method,
+        { **span.handler_arguments, id: "\"#{span.id}\".freeze" }
+      )
+
+      <<~RUBY
+        @all_handler_refs[#{handler_index}].instance.#{handler_ref.method_name}(#{handler_arguments}) do
+          #{memo}
+          span_result
+        end
+      RUBY
+    end
+
+    parameters = span.span_parameters.join(", ")
+
+    self.class.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def #{tracer_name(span.id)}(#{parameters})
+        span_result = yield_called = yield_result = yield_error = nil
+
+        begin
+          #{calls_chain}
+        rescue Exception => e
+          Rage.logger.error("Telemetry handler failed with error \#{e}:\\n\#{e.backtrace.join("\\n")}")
+        end
+
+        unless yield_called
+          Rage.logger.warn("Telemetry handler didn't call `yield` when processing span '#{span.id}'\\n\#{caller.join("\\n")}")
+          yield_result = yield
+        end
+
+        if yield_error
+          raise yield_error
+        else
+          yield_result
+        end
+      end
+    RUBY
+  end
+
+  def tracer_name(span_id)
+    "span_#{span_id.gsub(".", "_")}"
+  end
+end

data/lib/rage/version.rb

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

data/rage.gemspec

@@ -6,10 +6,10 @@ Gem::Specification.new do |spec|
   spec.name = "rage-rb"
   spec.version = Rage::VERSION
   spec.authors = ["Roman Samoilov"]
-  spec.email = ["rsamoi@icloud.com"]
+  spec.email = ["developers@rage-rb.dev"]
 
   spec.summary = "Fast web framework compatible with Rails."
-  spec.homepage = "https://github.com/rage-rb/rage"
+  spec.homepage = "https://rage-rb.dev"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2.0"
 
@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor .rubocop])
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ gemfiles/ test/ spec/ features/ .git .circleci appveyor .rubocop])
     end
   end
   spec.bindir = "exe"
@@ -28,10 +28,11 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "thor", "~> 1.0"
-  spec.add_dependency "rack", "~> 2.0"
+  spec.add_dependency "rack", "< 4"
   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"
   spec.add_dependency "logger"
+  spec.add_dependency "irb"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 1.19.1
+  version: 1.20.0
 platform: ruby
 authors:
 - Roman Samoilov
 bindir: exe
 cert_chain: []
-date: 2025-12-26 00:00:00.000000000 Z
+date: 2026-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -27,16 +27,16 @@ dependencies:
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: rage-iodine
   requirement: !ruby/object:Gem::Requirement
@@ -107,8 +107,22 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
-- rsamoi@icloud.com
+- developers@rage-rb.dev
 executables:
 - rage
 extensions: []
@@ -117,6 +131,7 @@ files:
 - ".rspec"
 - ".yardopts"
 - ARCHITECTURE.md
+- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -146,6 +161,8 @@ files:
 - lib/rage/deferred/backends/nil.rb
 - lib/rage/deferred/context.rb
 - lib/rage/deferred/deferred.rb
+- lib/rage/deferred/metadata.rb
+- lib/rage/deferred/middleware_chain.rb
 - lib/rage/deferred/proxy.rb
 - lib/rage/deferred/queue.rb
 - lib/rage/deferred/task.rb
@@ -163,6 +180,7 @@ files:
 - lib/rage/logger/json_formatter.rb
 - lib/rage/logger/logger.rb
 - lib/rage/logger/text_formatter.rb
+- lib/rage/middleware/body_finalizer.rb
 - lib/rage/middleware/cors.rb
 - lib/rage/middleware/fiber_wrapper.rb
 - lib/rage/middleware/origin_validator.rb
@@ -204,6 +222,21 @@ files:
 - lib/rage/setup.rb
 - lib/rage/sidekiq_session.rb
 - lib/rage/tasks.rb
+- lib/rage/telemetry/handler.rb
+- lib/rage/telemetry/spans/await_fiber.rb
+- lib/rage/telemetry/spans/broadcast_cable_stream.rb
+- lib/rage/telemetry/spans/create_websocket_connection.rb
+- lib/rage/telemetry/spans/dispatch_fiber.rb
+- lib/rage/telemetry/spans/enqueue_deferred_task.rb
+- lib/rage/telemetry/spans/process_cable_action.rb
+- lib/rage/telemetry/spans/process_cable_connection.rb
+- lib/rage/telemetry/spans/process_controller_action.rb
+- lib/rage/telemetry/spans/process_deferred_task.rb
+- lib/rage/telemetry/spans/process_event_subscriber.rb
+- lib/rage/telemetry/spans/publish_event.rb
+- lib/rage/telemetry/spans/spawn_fiber.rb
+- lib/rage/telemetry/telemetry.rb
+- lib/rage/telemetry/tracer.rb
 - lib/rage/templates/Gemfile
 - lib/rage/templates/Rakefile
 - lib/rage/templates/app-controllers-application_controller.rb
@@ -229,11 +262,11 @@ files:
 - lib/rage/uploaded_file.rb
 - lib/rage/version.rb
 - rage.gemspec
-homepage: https://github.com/rage-rb/rage
+homepage: https://rage-rb.dev
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/rage-rb/rage
+  homepage_uri: https://rage-rb.dev
   source_code_uri: https://github.com/rage-rb/rage
 rdoc_options: []
 require_paths: