rage-rb 1.23.0 → 1.25.0

data/lib/rage/fiber_scheduler.rb

@@ -5,14 +5,20 @@ require "resolv"
 class Rage::FiberScheduler
   MAX_READ = 65536
 
+  # Initialize the scheduler, storing the root fiber and an empty DNS cache.
   def initialize
     @root_fiber = Fiber.current
     @dns_cache = {}
   end
 
+  # Wait for I/O events on a file descriptor, yielding the fiber until ready or timeout.
   def io_wait(io, events, timeout = nil)
     f = Fiber.current
-    ::Iodine::Scheduler.attach(io.fileno, events, timeout&.ceil) { |err| f.resume(err) }
+    gen = (f.__wait_generation += 1)
+
+    ::Iodine::Scheduler.attach(io.fileno, events, timeout&.ceil) do |err|
+      f.resume(err) if f.alive? && gen == f.__wait_generation
+    end
 
     err = Fiber.defer(io.fileno)
     if err == false || (err && err < 0)
@@ -22,6 +28,7 @@ class Rage::FiberScheduler
     end
   end
 
+  # Read data from an I/O object into a buffer, pausing the fiber between reads.
   def io_read(io, buffer, length, offset = 0)
     length_to_read = if length == 0
       buffer.size > MAX_READ ? MAX_READ : buffer.size
@@ -51,6 +58,7 @@ class Rage::FiberScheduler
   end
 
   unless ENV["RAGE_DISABLE_IO_WRITE"]
+    # Write data from a buffer to an I/O object.
     def io_write(io, buffer, length, offset = 0)
       bytes_to_write = length
       bytes_to_write = buffer.size if length == 0
@@ -61,6 +69,7 @@ class Rage::FiberScheduler
     end
   end
 
+  # Pause the current fiber for the specified duration.
   def kernel_sleep(duration = nil)
     block(nil, duration || 0)
     Fiber.pause if duration.nil? || duration < 1
@@ -80,6 +89,7 @@ class Rage::FiberScheduler
   #   result
   # end
 
+  # Resolve a hostname to IP addresses, caching results for 60 seconds.
   def address_resolve(hostname)
     @dns_cache[hostname] ||= begin
       ::Iodine.run_after(60_000) do
@@ -90,14 +100,18 @@ class Rage::FiberScheduler
     end
   end
 
+  # Block the current fiber until unblocked or timeout.
   def block(_blocker, timeout = nil)
-    f, fulfilled, channel = Fiber.current, false, Fiber.current.__block_channel(true)
+    f, fulfilled = Fiber.current, false
+
+    gen = (f.__wait_generation += 1)
+    channel = f.__block_channel = "block:#{f.object_id}:#{gen}"
 
     resume_fiber_block = proc do
       unless fulfilled
         fulfilled = true
         ::Iodine.defer { ::Iodine.unsubscribe(channel) }
-        f.resume if f.alive?
+        f.resume if f.alive? && gen == f.__wait_generation
       end
     end
 
@@ -109,10 +123,38 @@ class Rage::FiberScheduler
     Fiber.yield
   end
 
+  # Unblock a fiber by publishing to its block channel.
   def unblock(_blocker, fiber)
-    ::Iodine.publish(fiber.__block_channel, "", Iodine::PubSub::PROCESS)
+    ::Iodine.publish(fiber.__block_channel, "", Iodine::PubSub::PROCESS) if fiber.__block_channel
+  end
+
+  # Interrupt a fiber by incrementing its generation and raising an exception.
+  def fiber_interrupt(fiber, exception)
+    fiber.__wait_generation += 1
+    fiber.raise(exception)
+  end
+
+  if defined?(Iodine::WorkerPool)
+    module BlockingOperationWait
+      # Offload a native call to the worker pool, yielding until complete.
+      def blocking_operation_wait(work)
+        f = Fiber.current
+        gen = (f.__wait_generation += 1)
+
+        worker_pool.enqueue(work) do
+          f.resume if f.alive? && gen == f.__wait_generation
+        end
+
+        Fiber.yield
+      end
+
+      private def worker_pool
+        @worker_pool ||= Iodine::WorkerPool.new(Rage.config.blocking_operation_pool.size)
+      end
+    end
   end
 
+  # Create and schedule a new non-blocking fiber, handling request and user-spawned fibers differently.
   def fiber(&block)
     parent = Fiber.current
 
@@ -131,19 +173,22 @@ class Rage::FiberScheduler
           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?
+        Iodine.publish(parent.__await_channel, "", Iodine::PubSub::PROCESS) if parent.__await_channel
       rescue Exception => e
         Fiber.current.__set_err(e)
-        Iodine.publish(parent.__await_channel, Fiber::AWAIT_ERROR_MESSAGE, Iodine::PubSub::PROCESS) if parent.alive?
+        Iodine.publish(parent.__await_channel, Fiber::AWAIT_ERROR_MESSAGE, Iodine::PubSub::PROCESS) if parent.__await_channel
       end
     end
 
+    fiber.__wait_generation = 0
     fiber.resume
 
     fiber
   end
 
+  # Clean up by closing the worker pool and Iodine scheduler.
   def close
+    @worker_pool&.close
     ::Iodine::Scheduler.close
   end
 end

data/lib/rage/internal.rb

@@ -64,24 +64,33 @@ class Rage::Internal
       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(&block)
-      @lock_file, lock_path = Tempfile.new.yield_self { |file| [file, file.path] }
+    def pick_a_worker(purpose:, &block)
+      attempt = proc do
+        lock_path = Pathname.new(Dir.tmpdir).join("rage-#{purpose}-lock-#{LOCK_FILE_SUFFIX}")
 
-      Iodine.on_state(:on_start) do
-        worker_lock = File.new(lock_path)
+        lock_file = File.open(lock_path, File::CREAT | File::WRONLY)
 
-        if worker_lock.flock(File::LOCK_EX | File::LOCK_NB)
-          @worker_lock = worker_lock
+        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/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

@@ -137,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
@@ -177,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,13 +120,44 @@ 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]
     end
   end
 
+  # @private
+  # @return [Array<Boolean, String, Hash>] a tuple of (is_collection, serializer, args)
+  def self.__parse_serializer_args(str)
+    is_collection, inner = __try_parse_collection(str)
+
+    if is_collection
+      # discard is_collection since we already know this is a collection from the outer call
+      _, clean_inner, args = __parse_serializer_args(inner)
+      if args.any?
+        [is_collection, clean_inner, args]
+      else
+        [is_collection, clean_inner, {}]
+      end
+    elsif str =~ /^([\w:]+)\(([^)]+)\)$/
+      [is_collection, $1, __parse_keywords($2)]
+    else
+      [is_collection, str, {}]
+    end
+  end
+
+  # @private
+  def self.__parse_keywords(str)
+    return {} if str.nil? || str.empty?
+
+    str.split(",").each_with_object({}) do |part, hash|
+      option = YAML.load(part)
+      return nil unless option.is_a?(Hash)
+      hash.merge!(option.transform_keys!(&:to_sym))
+    end
+  end
+
   # @private
   def self.__module_parent(klass)
     klass.name =~ /::[^:]+\z/ ? Object.const_get($`) : Object
@@ -191,6 +222,7 @@ require_relative "nodes/root"
 require_relative "nodes/parent"
 require_relative "nodes/method"
 require_relative "parsers/ext/alba"
+require_relative "parsers/ext/blueprinter"
 require_relative "parsers/ext/active_record"
 require_relative "parsers/yaml"
 require_relative "parsers/shared_reference"

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
 

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Parsers::Ext::Blueprinter
+  def initialize(namespace: Object, root: Rage::OpenAPI::Nodes::Root.new, **)
+    @namespace = namespace
+    @root = root
+  end
+
+  def known_definition?(str)
+    _, str, _ = Rage::OpenAPI.__parse_serializer_args(str)
+    defined?(Blueprinter::Base) && @namespace.const_get(str).ancestors.include?(Blueprinter::Base)
+  rescue NameError
+    false
+  end
+
+  def parse(klass_str)
+    visitor = __parse(klass_str)
+    visitor.build_schema
+  end
+
+  def __parse(klass_str)
+    is_collection, klass_str, _ = Rage::OpenAPI.__parse_serializer_args(klass_str)
+
+    klass = @namespace.const_get(klass_str)
+    source_path, _ = Object.const_source_location(klass.name)
+    ast = Prism.parse_file(source_path)
+
+    visitor = Visitor.new(self, is_collection)
+    ast.value.accept(visitor)
+
+    visitor
+  end
+
+  class VisitorContext
+    attr_accessor :symbols, :keywords, :strings
+
+    def initialize
+      @symbols = []
+      @strings = []
+      @keywords = {}
+    end
+  end
+
+  class Visitor < Prism::Visitor
+    attr_accessor :schema
+
+    def initialize(parser, is_collection)
+      @parser = parser
+      @is_collection = is_collection
+
+      @context = nil
+      @schema = {}
+      @segment = @schema
+      @identifier = {}
+    end
+
+    def build_schema
+      result = { "type" => "object" }
+
+      properties = {}
+      properties.merge!(@identifier)
+      properties.merge!(@schema.sort.to_h)
+
+      result["properties"] = properties if properties.any?
+      result = { "type" => "array", "items" => result } if @is_collection
+      result
+    end
+
+    def visit_call_node(node)
+      case node.name
+      when :identifier
+        context = with_context { visit(node.arguments) }
+        @identifier[context.symbols.first] = { "type" => "string" }
+
+      when :fields, :field
+        context = with_context { visit(node.arguments) }
+
+        if context.keywords["name"]
+          @segment[context.keywords["name"]] = { "type" => "string" }
+        elsif node.block
+          @segment[context.symbols.first] = { "type" => "string" } if context.symbols.first
+          @segment[context.strings.first] = { "type" => "string" } if context.strings.first
+        else
+          context.symbols.each { |symbol| @segment[symbol] = { "type" => "string" } }
+          context.strings.each { |string| @segment[string] = { "type" => "string" } }
+        end
+      end
+    end
+
+    def visit_assoc_node(node)
+      @context.keywords[node.key.value] = node.value.unescaped
+    end
+
+    def visit_symbol_node(node)
+      @context.symbols << node.value
+    end
+
+    def visit_string_node(node)
+      @context.strings << node.unescaped
+    end
+
+    private
+
+    def with_context
+      @context = VisitorContext.new
+      yield
+      @context
+    end
+  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
 

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

@@ -5,12 +5,13 @@ class Rage::OpenAPI::Parsers::Response
     Rage::OpenAPI::Parsers::SharedReference,
     Rage::OpenAPI::Parsers::Ext::ActiveRecord,
     Rage::OpenAPI::Parsers::Ext::Alba,
+    Rage::OpenAPI::Parsers::Ext::Blueprinter,
     Rage::OpenAPI::Parsers::YAML
   ]
 
-  def self.parse(response_tag, namespace:)
+  def self.parse(response_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?(response_tag)
     end
 

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

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
 class Rage::OpenAPI::Parsers::YAML
+  # @private
+  class OptionalParam < String
+  end
+
   def initialize(**)
   end
 
   def known_definition?(yaml)
-    object = YAML.safe_load(yaml) rescue nil
+    object = process_yaml(yaml) rescue nil
     !!object && object.is_a?(Enumerable)
   end
 
   def parse(yaml)
-    __parse(YAML.safe_load(yaml))
+    __parse(process_yaml(yaml))
   end
 
   private
@@ -22,6 +26,8 @@ class Rage::OpenAPI::Parsers::YAML
       spec = { "type" => "object", "properties" => {} }
 
       object.each do |key, value|
+        key = OptionalParam.new(key[0...-1]) if key.end_with?("?")
+
         spec["properties"][key] = if value.is_a?(Enumerable)
           __parse(value)
         else
@@ -29,6 +35,8 @@ class Rage::OpenAPI::Parsers::YAML
         end
       end
 
+      spec["required"] = spec["properties"].keys.select { |k| !k.is_a?(OptionalParam) }
+
     elsif object.is_a?(Array) && object.length == 1
       spec = { "type" => "array", "items" => object[0].is_a?(Enumerable) ? __parse(object[0]) : type_to_spec(object[0]) }
 
@@ -39,9 +47,23 @@ class Rage::OpenAPI::Parsers::YAML
     spec
   end
 
-  private
-
   def type_to_spec(type)
-    Rage::OpenAPI.__type_to_spec(type) || { "type" => "string", "enum" => [type] }
+    is_collection, type_str = if type.is_a?(String)
+      Rage::OpenAPI.__try_parse_collection(type)
+    else
+      [false, type]
+    end
+
+    spec = Rage::OpenAPI.__type_to_spec(type_str) || { "type" => "string", "enum" => [type_str] }
+
+    if is_collection
+      { "type" => "array", "items" => spec }
+    else
+      spec
+    end
+  end
+
+  def process_yaml(str)
+    YAML.safe_load(str.gsub(/Array<([^>]+)>/, '[\1]'))
   end
 end