rage-rb 1.22.1 → 1.24.0

data/lib/rage/deferred/task.rb

@@ -31,15 +31,16 @@
 # ```
 #
 module Rage::Deferred::Task
-  MAX_ATTEMPTS = 5
+  MAX_ATTEMPTS = 20
   private_constant :MAX_ATTEMPTS
 
-  BACKOFF_INTERVAL = 5
-  private_constant :BACKOFF_INTERVAL
-
   # @private
   CONTEXT_KEY = :__rage_deferred_execution_context
 
+  # @private
+  RETRY_IN_CACHE_VAR = :@__rage_deferred_retry_in
+  private_constant :RETRY_IN_CACHE_VAR
+
   def perform
   end
 
@@ -80,12 +81,14 @@ module Rage::Deferred::Task
 
     true
   rescue Exception => e
+    Rage::Errors.report(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
+    e
   end
 
   private def restore_log_info(context)
@@ -105,6 +108,62 @@ module Rage::Deferred::Task
   end
 
   module ClassMethods
+    # Set the maximum number of retry attempts for this task.
+    #
+    # @param count [Integer] the maximum number of retry attempts
+    # @example
+    #   class SendWelcomeEmail
+    #     include Rage::Deferred::Task
+    #     max_retries 10
+    #
+    #     def perform(email)
+    #       # ...
+    #     end
+    #   end
+    def max_retries(count)
+      value = Integer(count)
+
+      if value.negative?
+        raise ArgumentError, "max_retries should be a valid non-negative integer"
+      end
+
+      @__max_retries = value
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "max_retries should be a valid non-negative integer"
+    end
+
+    # Override this method to customize retry behavior per exception.
+    #
+    # Return an Integer to retry in that many seconds.
+    # Return `super` to use the default exponential backoff.
+    # Return `false` or `nil` to abort retries.
+    #
+    # @param exception [Exception] the exception that caused the failure
+    # @param attempt [Integer] the current attempt number (1-indexed)
+    # @return [Integer, false, nil] the retry interval in seconds, or false/nil to abort
+    # @example
+    #   class ProcessPayment
+    #     include Rage::Deferred::Task
+    #
+    #     def self.retry_interval(exception, attempt:)
+    #       case exception
+    #       when TemporaryNetworkError
+    #         10 # Retry in 10 seconds
+    #       when InvalidDataError
+    #         false # Do not retry
+    #       else
+    #         super # Default backoff strategy
+    #       end
+    #     end
+    #
+    #     def perform(payment_id)
+    #       # ...
+    #     end
+    #   end
+    def retry_interval(exception, attempt:)
+      __default_backoff(attempt)
+    end
+
     def enqueue(*args, delay: nil, delay_until: nil, **kwargs)
       context = Rage::Deferred::Context.build(self, args, kwargs)
 
@@ -118,13 +177,35 @@ module Rage::Deferred::Task
     end
 
     # @private
-    def __should_retry?(attempts)
-      attempts < MAX_ATTEMPTS
+    def __next_retry_in(attempts, exception)
+      f = Fiber.current
+
+      if f.instance_variable_defined?(RETRY_IN_CACHE_VAR)
+        f.instance_variable_get(RETRY_IN_CACHE_VAR)
+      else
+        f.instance_variable_set(RETRY_IN_CACHE_VAR, __calculate_next_retry_in(attempts, exception))
+      end
+    end
+
+    # @private
+    def __calculate_next_retry_in(attempts, exception)
+      max = @__max_retries || MAX_ATTEMPTS
+      return if attempts > max
+
+      interval = retry_interval(exception, attempt: attempts)
+      return if !interval
+
+      unless interval.is_a?(Numeric)
+        Rage.logger.warn("#{name}.retry_interval returned #{interval.class}, expected Numeric, false, or nil; falling back to default backoff")
+        return __default_backoff(attempts)
+      end
+
+      interval
     end
 
     # @private
-    def __next_retry_in(attempts)
-      rand(BACKOFF_INTERVAL * 2**attempts.to_i) + 1
+    def __default_backoff(attempt)
+      (attempt**4) + 10 + (rand(15) * attempt)
     end
   end
 end

data/lib/rage/errors.rb

@@ -1,4 +1,87 @@
+# frozen_string_literal: true
+
 module Rage::Errors
+  ReporterEntry = Struct.new(:reporter, :method_name)
+  private_constant :ReporterEntry
+
+  @reporters = []
+  @next_reporter_id = 0
+
+  class << self
+    # Forward an exception to all registered reporters.
+    #
+    # @param exception [Exception]
+    # @param context [Hash]
+    # @return [nil]
+    def report(exception, context: {})
+      return if @reporters.empty?
+      return if exception.instance_variable_defined?(:@_rage_error_reported)
+
+      ensure_backtrace(exception)
+
+      @reporters.each do |entry|
+        __send__(entry.method_name, entry.reporter, exception, context)
+      rescue => e
+        Rage.logger.error("Error reporter #{entry.reporter.class} failed while reporting #{exception.class}: #{e.class} (#{e.message})")
+      end
+
+      exception.instance_variable_set(:@_rage_error_reported, true) unless exception.frozen?
+
+      nil
+    end
+
+    # @private
+    def __register_reporter(reporter)
+      raise ArgumentError, "error reporter must respond to #call" unless reporter.respond_to?(:call)
+
+      reporter_id = @next_reporter_id
+      @next_reporter_id += 1
+      method_name = :"__report_#{reporter_id}"
+
+      arguments = Rage::Internal.build_arguments(
+        reporter.method(:call),
+        { context: "context" }
+      )
+      call_arguments = arguments.empty? ? "" : ", #{arguments}"
+
+      singleton_class.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def #{method_name}(reporter, exception, context)
+          reporter.call(exception#{call_arguments})
+        end
+      RUBY
+
+      @reporters << ReporterEntry.new(reporter, method_name)
+
+      self
+    end
+
+    # @private
+    def __unregister_reporter(reporter)
+      @reporters.delete_if do |entry|
+        next false unless entry.reporter == reporter
+
+        singleton_class.remove_method(entry.method_name) if singleton_class.method_defined?(entry.method_name)
+        true
+      end
+
+      self
+    end
+
+    private
+
+    def ensure_backtrace(exception)
+      return if exception.frozen?
+      return unless exception.backtrace.nil?
+
+      begin
+        raise exception
+      rescue exception.class
+      end
+    end
+
+    private :__register_reporter, :__unregister_reporter
+  end
+
   class BadRequest < StandardError
   end
 
@@ -10,4 +93,7 @@ module Rage::Errors
 
   class InvalidCustomProxy < StandardError
   end
+
+  class AmbiguousRenderError < StandardError
+  end
 end

data/lib/rage/events/subscriber.rb

@@ -90,7 +90,12 @@ module Rage::Events::Subscriber
     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
+
+    if self.class.__is_deferred
+      raise e
+    else
+      Rage::Errors.report(e)
+    end
   end
 
   private

data/lib/rage/internal.rb

@@ -44,8 +44,53 @@ class Rage::Internal
       }.join(", ")
     end
 
+    # Generate a stream name based on the provided object.
+    # @param streamables [#id, String, Symbol, Numeric, Array] an object that will be used to generate the stream name
+    # @return [String] the generated stream name
+    # @raise [ArgumentError] if the provided object cannot be used to generate a stream name
+    def stream_name_for(streamables)
+      return streamables if streamables.is_a?(String)
+
+      name_segments = Array(streamables).map do |streamable|
+        if streamable.respond_to?(:id)
+          "#{streamable.class.name}:#{streamable.id}"
+        elsif streamable.is_a?(String) || streamable.is_a?(Symbol) || streamable.is_a?(Numeric)
+          streamable
+        else
+          raise ArgumentError, "Unable to generate stream name. Expected an object that responds to `id`, got: #{streamable.class}"
+        end
+      end
+
+      name_segments.join(":")
+    end
+
+    LOCK_FILE_SUFFIX = rand(0x100000000).to_s(36)
+
+    # Pick a worker process to execute a block of code.
+    # This is useful for ensuring that certain code is only executed by a single worker in a multi-worker setup, e.g. for broadcasting messages to known streams or for running periodic tasks.
+    # @yield The block of code to be executed by the picked worker
+    def pick_a_worker(purpose:, &block)
+      attempt = proc do
+        lock_path = Pathname.new(Dir.tmpdir).join("rage-#{purpose}-lock-#{LOCK_FILE_SUFFIX}")
+
+        lock_file = File.open(lock_path, File::CREAT | File::WRONLY)
+
+        if lock_file.flock(File::LOCK_EX | File::LOCK_NB)
+          Iodine.on_state(:on_finish) { File.unlink(lock_file) if File.exist?(lock_file) }
+          worker_locks << lock_file
+          block.call
+        end
+      end
+
+      Iodine.running? ? attempt.call : Iodine.on_state(:on_start) { attempt.call }
+    end
+
     private
 
+    def worker_locks
+      @worker_locks ||= []
+    end
+
     def dynamic_name_seed
       @dynamic_name_seed ||= ("a".."j").to_a.permutation
     end

data/lib/rage/logger/logger.rb

@@ -28,7 +28,7 @@ require "logger"
 # # => [fecbba0735355738] timestamp=2023-10-19T11:12:56+00:00 pid=1825 level=info cache_key=mykey message=cache miss
 # ```
 #
-# `Rage::Logger` also implements the interface of Ruby's native {https://ruby-doc.org/3.2.2/stdlibs/logger/Logger.html Logger}:
+# `Rage::Logger` also implements the interface of Ruby's native {https://ruby-doc.org/3.4.1/stdlibs/logger/Logger.html Logger}:
 # ```ruby
 # Rage.logger.info("Initializing")
 # Rage.logger.debug { "This is a " + potentially + " expensive operation" }

data/lib/rage/middleware/fiber_wrapper.rb

@@ -20,6 +20,7 @@ class Rage::FiberWrapper
     rescue Exception => e
       exception_str = "#{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}"
       Rage.logger << exception_str
+      Rage::Errors.report(e)
       if Rage.env.development?
         [500, {}, [exception_str]]
       else

data/lib/rage/openapi/builder.rb

@@ -21,7 +21,7 @@ class Rage::OpenAPI::Builder
   end
 
   def run
-    parser = Rage::OpenAPI::Parser.new
+    parser = Rage::OpenAPI::Parser.new(@nodes)
 
     @routes.each do |controller, routes|
       next if skip_controller?(controller)

data/lib/rage/openapi/converter.rb

@@ -56,7 +56,47 @@ class Rage::OpenAPI::Converter
       }
 
       if node.parameters.any?
-        memo[path][method]["parameters"] = build_parameters(node)
+        has_file_param = node.parameters.values.any? { |p| !p.key?(:ref) && p[:type] && p[:type]["format"] == "binary" }
+
+        if has_file_param
+          schema_properties = {}
+          schema_required = []
+          query_ref_parameters = []
+
+          # When file params are present, non-ref params become part of the multipart/form-data
+          # request body schema. Shared refs (e.g., #/components/parameters/...) are kept as
+          # regular parameter references since we can't inline their definitions into the schema.
+          node.parameters.each do |param_name, param_info|
+            if param_info.key?(:ref)
+              # shared parameter refs stay as top-level parameters
+              query_ref_parameters << param_info[:ref]
+            else
+              # inline params become properties in the multipart schema
+              property_schema = get_param_type_spec(param_name, param_info[:type]).dup
+              if param_info[:description] && !param_info[:description].empty?
+                property_schema["description"] = param_info[:description]
+              end
+
+              schema_properties[param_name] = property_schema
+              schema_required << param_name if param_info[:required]
+            end
+          end
+
+          memo[path][method]["requestBody"] = {
+            "content" => {
+              "multipart/form-data" => {
+                "schema" => {
+                  "type" => "object",
+                  "properties" => schema_properties
+                }.tap { |s| s["required"] = schema_required if schema_required.any? }
+              }
+            }
+          }
+
+          memo[path][method]["parameters"] = query_ref_parameters if query_ref_parameters.any?
+        else
+          memo[path][method]["parameters"] = build_parameters(node)
+        end
       end
 
       responses = node.parents.reverse.map(&:responses).reduce(&:merge).merge(node.responses)
@@ -79,7 +119,8 @@ class Rage::OpenAPI::Converter
         if node.request.key?("$ref") && node.request["$ref"].start_with?("#/components/requestBodies")
           memo[path][method]["requestBody"] = node.request
         else
-          memo[path][method]["requestBody"] = { "content" => { "application/json" => { "schema" => node.request } } }
+          memo[path][method]["requestBody"] ||= {}
+          (memo[path][method]["requestBody"]["content"] ||= {})["application/json"] = { "schema" => node.request }
         end
       end
     end
@@ -96,6 +137,10 @@ class Rage::OpenAPI::Converter
       end
     end
 
+    if (dynamic_schemas = @nodes.schema_registry).any?
+      (@spec["components"]["schemas"] ||= {}).merge!(dynamic_schemas)
+    end
+
     @spec["tags"] = @used_tags.sort.map { |tag| { "name" => tag } }
 
     @spec
@@ -136,7 +181,7 @@ class Rage::OpenAPI::Converter
           @used_security_schemes << auth_entry.merge(name: auth_name)
         end
 
-        { auth_name => [] }
+        { auth_name => node.auth_scopes.fetch(auth_name, []) }
       end
     end
   end

data/lib/rage/openapi/nodes/method.rb

@@ -3,7 +3,7 @@
 class Rage::OpenAPI::Nodes::Method
   attr_reader :controller, :action, :parents
   attr_accessor :http_method, :http_path, :summary, :tag, :deprecated, :private, :description,
-    :request, :responses, :parameters
+    :request, :responses, :parameters, :auth_scopes
 
   # @param controller [RageController::API]
   # @param action [String]
@@ -15,6 +15,7 @@ class Rage::OpenAPI::Nodes::Method
 
     @responses = {}
     @parameters = {}
+    @auth_scopes = {}
   end
 
   def root

data/lib/rage/openapi/nodes/root.rb

@@ -20,12 +20,13 @@
 #            Nodes::Method<index>   Nodes::Method<show>                  Nodes::Method<show>
 #
 class Rage::OpenAPI::Nodes::Root
-  attr_reader :leaves
+  attr_reader :leaves, :schema_registry
   attr_accessor :version, :title
 
   def initialize
     @parent_nodes_cache = {}
     @leaves = []
+    @schema_registry = {}
   end
 
   # @return [Array<Rage::OpenAPI::Nodes::Parent>]

data/lib/rage/openapi/openapi.rb

@@ -120,7 +120,7 @@ module Rage::OpenAPI
 
   # @private
   def self.__try_parse_collection(str)
-    if str =~ /^Array<([\w\s:\(\)]+)>$/ || str =~ /^\[([\w\s:\(\)]+)\]$/
+    if str =~ /^Array<([\w\s:\(\),]+)>$/ || str =~ /^\[([\w\s:\(\),]+)\]$/
       [true, $1]
     else
       [false, str]
@@ -153,11 +153,22 @@ module Rage::OpenAPI
       { "type" => "string", "format" => "date-time" }
     when "String"
       { "type" => "string" }
+    when "File"
+      { "type" => "string", "format" => "binary" }
     else
       { "type" => "string" } if default
     end
   end
 
+  # @private
+  def self.__resolve_resource(klass_str, namespace)
+    return nil if klass_str.nil?
+    namespace.const_get(klass_str)
+  rescue NameError
+    __log_warn("could not resolve resource: #{klass_str}")
+    nil
+  end
+
   # @private
   def self.__log_warn(log)
     puts "[OpenAPI] WARNING: #{log}"

data/lib/rage/openapi/parser.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 class Rage::OpenAPI::Parser
+  # @param root [Rage::OpenAPI::Nodes::Root]
+  def initialize(root)
+    @root = root
+  end
+
   # @param node [Rage::OpenAPI::Nodes::Parent]
   # @param comments [Array<Prism::InlineComment>]
   def parse_dangling_comments(node, comments)
@@ -125,7 +130,8 @@ class Rage::OpenAPI::Parser
         else
           parsed = Rage::OpenAPI::Parsers::Request.parse(
             request,
-            namespace: Rage::OpenAPI.__module_parent(node.controller)
+            namespace: Rage::OpenAPI.__module_parent(node.controller),
+            root: @root
           )
 
           if parsed
@@ -138,6 +144,9 @@ class Rage::OpenAPI::Parser
       elsif expression =~ /@param\s/
         parse_param_tag(expression, node, comments[i])
 
+      elsif expression =~ /@auth_scope\s/
+        parse_auth_scope_tag(expression, node, comments[i])
+
       elsif expression =~ /@internal\b/
         # no-op
         children = find_children(comments[i + 1..], node)
@@ -203,7 +212,8 @@ class Rage::OpenAPI::Parser
     else
       parsed = Rage::OpenAPI::Parsers::Response.parse(
         response_data,
-        namespace: Rage::OpenAPI.__module_parent(node.controller)
+        namespace: Rage::OpenAPI.__module_parent(node.controller),
+        root: @root
       )
 
       if parsed
@@ -256,6 +266,67 @@ class Rage::OpenAPI::Parser
     end
   end
 
+  def parse_auth_scope_tag(expression, node, comment)
+    content = expression.split(" ", 2)[1]
+
+    unless content
+      Rage::OpenAPI.__log_warn "invalid `@auth_scope` tag detected at #{location_msg(comment)}; expected [scope1, scope2] syntax"
+      return
+    end
+
+    parsed = YAML.safe_load(content)
+
+    if parsed.is_a?(Array)
+      scheme_name = nil
+      scopes = parsed.map(&:to_s)
+    elsif parsed.is_a?(String)
+      scheme_name = parsed.split(" ", 2)[0]
+      scopes_str = content.split(" ", 2)[1]
+
+      unless scopes_str
+        Rage::OpenAPI.__log_warn "invalid `@auth_scope` tag detected at #{location_msg(comment)}; expected [scope1, scope2] syntax"
+        return
+      end
+
+      scopes = YAML.safe_load(scopes_str)
+
+      unless scopes.is_a?(Array)
+        Rage::OpenAPI.__log_warn "invalid `@auth_scope` tag detected at #{location_msg(comment)}; expected [scope1, scope2] syntax"
+        return
+      end
+
+      scopes = scopes.map(&:to_s)
+    else
+      Rage::OpenAPI.__log_warn "invalid `@auth_scope` tag detected at #{location_msg(comment)}; expected [scope1, scope2] syntax"
+      return
+    end
+
+    if scheme_name.nil?
+      auth_entries = node.auth
+      if auth_entries.empty?
+        Rage::OpenAPI.__log_warn "no auth schemes found for `@auth_scope` shorthand at #{location_msg(comment)}; define an @auth tag on the controller first"
+        return
+      elsif auth_entries.length > 1
+        Rage::OpenAPI.__log_warn "ambiguous `@auth_scope` shorthand at #{location_msg(comment)}; multiple auth schemes found, specify the scheme name explicitly"
+        return
+      end
+      scheme_name = auth_entries[0][:name]
+    else
+      auth_names = node.auth.map { |e| e[:name] }
+      unless auth_names.include?(scheme_name)
+        Rage::OpenAPI.__log_warn "unknown scheme `#{scheme_name}` in `@auth_scope` tag at #{location_msg(comment)}; available schemes: #{auth_names.join(", ")}"
+        return
+      end
+    end
+
+    if node.auth_scopes.key?(scheme_name)
+      Rage::OpenAPI.__log_warn "duplicate `@auth_scope` tag for `#{scheme_name}` detected at #{location_msg(comment)}"
+      return
+    end
+
+    node.auth_scopes[scheme_name] = scopes
+  end
+
   def parse_param_tag(expression, node, comment)
     param = expression[7..].strip
 

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

@@ -3,8 +3,10 @@
 class Rage::OpenAPI::Parsers::Ext::Alba
   attr_reader :namespace
 
-  def initialize(namespace: Object, **)
+  def initialize(namespace: Object, root: Rage::OpenAPI::Nodes::Root.new, **)
     @namespace = namespace
+    @root = root
+    @parsing_stack = Set.new
   end
 
   def known_definition?(str)
@@ -15,10 +17,27 @@ class Rage::OpenAPI::Parsers::Ext::Alba
   end
 
   def parse(klass_str)
-    __parse(klass_str).build_schema
+    _, raw_klass_str = Rage::OpenAPI.__try_parse_collection(klass_str)
+    visitor = __parse(klass_str)
+
+    if @root.schema_registry.key?(raw_klass_str)
+      clean = { "type" => "object" }
+      clean["properties"] = visitor.schema if visitor.schema.any?
+      @root.schema_registry[raw_klass_str] = clean
+    end
+
+    visitor.build_schema
   end
 
   def __parse_nested(klass_str)
+    is_collection, raw_klass_str = Rage::OpenAPI.__try_parse_collection(klass_str)
+
+    if @parsing_stack.include?(raw_klass_str)
+      @root.schema_registry[raw_klass_str] ||= nil
+      ref = { "$ref" => "#/components/schemas/#{raw_klass_str}" }
+      return is_collection ? { "type" => "array", "items" => ref } : ref
+    end
+
     __parse(klass_str).tap { |visitor|
       visitor.root_key = visitor.root_key_for_collection = visitor.root_key_proc = visitor.key_transformer = nil
     }.build_schema
@@ -27,6 +46,13 @@ class Rage::OpenAPI::Parsers::Ext::Alba
   def __parse(klass_str)
     is_collection, klass_str = Rage::OpenAPI.__try_parse_collection(klass_str)
 
+    # return an empty visitor if we're already parsing this class;
+    # this serves as a recursion guard, specifically for the inheritance logic in `Visitor#visit_class_node`
+    if @parsing_stack.include?(klass_str)
+      return Visitor.new(self, is_collection)
+    end
+    @parsing_stack.add(klass_str)
+
     klass = @namespace.const_get(klass_str)
     source_path, _ = Object.const_source_location(klass.name)
     ast = Prism.parse_file(source_path)
@@ -34,6 +60,8 @@ class Rage::OpenAPI::Parsers::Ext::Alba
     visitor = Visitor.new(self, is_collection)
     ast.value.accept(visitor)
 
+    @parsing_stack.delete(klass_str)
+
     visitor
   end
 
@@ -151,12 +179,13 @@ class Rage::OpenAPI::Parsers::Ext::Alba
           with_inner_segment(key, is_array:) { visit(node.block) }
         else
           resource = context.keywords["resource"] || (::Alba.inflector && "#{::Alba.inflector.classify(association.to_s)}Resource")
-          is_valid_resource = @parser.namespace.const_get(resource) rescue false
+          resolved = Rage::OpenAPI.__resolve_resource(resource, @parser.namespace)
 
-          @segment[key] = if is_array
-            @parser.__parse_nested(is_valid_resource ? "[#{resource}]" : "[Rage]") # TODO
+          @segment[key] = if resolved
+            is_array ? @parser.__parse_nested("[#{resource}]") : @parser.__parse_nested(resource)
           else
-            @parser.__parse_nested(is_valid_resource ? resource : "Rage")
+            base = { "type" => "object" }
+            is_array ? { "type" => "array", "items" => base } : base
           end
         end
 

data/lib/rage/openapi/parsers/request.rb

@@ -7,9 +7,9 @@ class Rage::OpenAPI::Parsers::Request
     Rage::OpenAPI::Parsers::Ext::ActiveRecord
   ]
 
-  def self.parse(request_tag, namespace:)
+  def self.parse(request_tag, namespace:, root:)
     parser = AVAILABLE_PARSERS.find do |parser_class|
-      parser = parser_class.new(namespace:)
+      parser = parser_class.new(namespace:, root:)
       break parser if parser.known_definition?(request_tag)
     end