rage-rb 1.22.1 → 1.24.0

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

@@ -8,9 +8,9 @@ class Rage::OpenAPI::Parsers::Response
     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

data/lib/rage/params_parser.rb

@@ -14,9 +14,9 @@ class Rage::ParamsParser
     end
 
     request_params = if content_type.start_with?("application/json")
-      json_parse(env["rack.input"].read)
+      json_parse(env["rack.input"].tap { |io| io.rewind }.read)
     elsif content_type.start_with?("application/x-www-form-urlencoded")
-      Iodine::Rack::Utils.parse_urlencoded_nested_query(env["rack.input"].read)
+      Iodine::Rack::Utils.parse_urlencoded_nested_query(env["rack.input"].tap { |io| io.rewind }.read)
     elsif content_type.start_with?("multipart/form-data")
       Iodine::Rack::Utils.parse_multipart(env["rack.input"], content_type)
     end

data/lib/rage/{cable → pubsub}/adapters/redis.rb

@@ -5,15 +5,17 @@ require "securerandom"
 if !defined?(RedisClient)
   fail <<~ERR
 
-    Redis adapter depends on the `redis-client` gem. Add the following line to your Gemfile:
+    Redis adapter depends on the `redis-client` gem. Ensure the following line is added to your Gemfile:
     gem "redis-client"
 
   ERR
 end
 
-class Rage::Cable::Adapters::Redis < Rage::Cable::Adapters::Base
-  REDIS_STREAM_NAME = "rage:cable:messages"
+class Rage::PubSub::Adapters::Redis
+  REDIS_STREAM_NAME = "rage:pubsub:messages"
   DEFAULT_REDIS_OPTIONS = { reconnect_attempts: [0.05, 0.1, 0.5] }
+  DEFAULT_POOL_SIZE = 10
+  DEFAULT_POOL_TIMEOUT = 1
   REDIS_MIN_VERSION_SUPPORTED = Gem::Version.create(6)
 
   def initialize(config)
@@ -23,38 +25,53 @@ class Rage::Cable::Adapters::Redis < Rage::Cable::Adapters::Base
       REDIS_STREAM_NAME
     end
 
+    @pool_size = (config.delete(:pool_size) || DEFAULT_POOL_SIZE).to_i
+    @pool_timeout = (config.delete(:pool_timeout) || DEFAULT_POOL_TIMEOUT).to_f
     @redis_config = RedisClient.config(**DEFAULT_REDIS_OPTIONS.merge(config))
     @server_uuid = SecureRandom.uuid
+    @broadcasters = {}
 
     redis_version = get_redis_version
-    if redis_version < REDIS_MIN_VERSION_SUPPORTED
+    if redis_version.nil?
+      return
+    elsif redis_version < REDIS_MIN_VERSION_SUPPORTED
       raise "Redis adapter only supports Redis 6+. Detected Redis version: #{redis_version}."
     end
 
     @trimming_strategy = redis_version < Gem::Version.create("6.2.0") ? :maxlen : :minid
 
-    pick_a_worker { poll }
+    Rage::Internal.pick_a_worker(purpose: "redis-pubsub") do
+      puts("INFO: #{Process.pid} is managing Redis subscriptions.") if Rage.logger.info?
+      poll
+    end
+  end
+
+  def add_broadcaster(broadcaster_id, broadcaster)
+    @broadcasters[broadcaster_id] = broadcaster
   end
 
-  def publish(stream_name, data)
+  def publish(broadcaster_id, stream_name, data)
     message_uuid = SecureRandom.uuid
 
-    publish_redis.call(
-      "XADD",
-      @redis_stream,
-      trimming_method, "~", trimming_value,
-      "*",
-      "1", stream_name,
-      "2", data.to_json,
-      "3", @server_uuid,
-      "4", message_uuid
-    )
+    redis_pool.with do |redis|
+      redis.call(
+        "XADD",
+        @redis_stream,
+        trimming_method, "~", trimming_value,
+        "*",
+        "1", stream_name,
+        "2", data.to_json,
+        "3", @server_uuid,
+        "4", message_uuid,
+        "5", broadcaster_id
+      )
+    end
   end
 
   private
 
-  def publish_redis
-    @publish_redis ||= @redis_config.new_client
+  def redis_pool
+    @redis_pool ||= @redis_config.new_pool(size: @pool_size, timeout: @pool_timeout)
   end
 
   def trimming_method
@@ -74,7 +91,7 @@ class Rage::Cable::Adapters::Redis < Rage::Cable::Adapters::Base
   rescue RedisClient::Error => e
     puts "FATAL: Couldn't connect to Redis - all broadcasts will be limited to the current server."
     puts e.backtrace.join("\n")
-    REDIS_MIN_VERSION_SUPPORTED
+    nil
 
   ensure
     service_redis.close
@@ -105,9 +122,9 @@ class Rage::Cable::Adapters::Redis < Rage::Cable::Adapters::Base
         data = read_redis.blocking_call(5, "XREAD", "COUNT", "100", "BLOCK", "5000", "STREAMS", @redis_stream, last_id)
 
         if data
-          data[@redis_stream].each do |id, (_, stream_name, _, serialized_data, _, broadcaster_uuid, _, message_uuid)|
-            if broadcaster_uuid != @server_uuid && message_uuid != last_message_uuid
-              Rage.cable.__protocol.broadcast(stream_name, JSON.parse(serialized_data))
+          data[@redis_stream].each do |id, (_, stream_name, _, serialized_data, _, server_uuid, _, message_uuid, _, broadcaster_id)|
+            if server_uuid != @server_uuid && message_uuid != last_message_uuid
+              @broadcasters[broadcaster_id]&.broadcast(stream_name, JSON.parse(serialized_data))
             end
 
             last_id = id
@@ -115,10 +132,13 @@ class Rage::Cable::Adapters::Redis < Rage::Cable::Adapters::Base
           end
         end
 
+        break if @stopping
+
       rescue RedisClient::Error => e
         Rage.logger.error("Subscriber error: #{e.message} (#{e.class})")
+        Rage::Errors.report(e)
         sleep error_backoff_intervals.next
-      rescue => e
+      rescue SystemCallError => e
         @stopping ? break : raise(e)
       else
         error_backoff_intervals.rewind

data/lib/rage/pubsub/pubsub.rb

@@ -0,0 +1,25 @@
+##
+# The module provides the support for multi-server setups for `Rage::Cable` and `Rage::SSE`. It allows for broadcasting messages across multiple servers or from different runtimes, e.g. Sidekiq.
+#
+# To use the module, add the `redis-client` gem to your Gemfile and create the environment-specific configuration in `config/pubsub.yml`:
+#
+# ```yaml
+# production:
+#   adapter: redis
+#   url: <%= ENV["REDIS_URL"] %>
+# ```
+#
+# The configuration supports the following options:
+#
+# - `adapter` (required): The adapter to use for Pub/Sub. The only supported value is `redis`.
+# - `channel_prefix` (optional): A prefix to use for the Redis stream name. This can be useful if you want to share a Redis instance with other applications or services.
+# - `pool_size` (optional): The size of the Redis connection pool. Default is 10.
+# - `pool_timeout` (optional): The timeout in seconds for acquiring a connection from the pool. Default is 1 second.
+#
+# The rest of the options are passed directly to `redis-client`.
+#
+module Rage::PubSub
+  module Adapters
+    autoload :Redis, "rage/pubsub/adapters/redis"
+  end
+end

data/lib/rage/rails.rb

@@ -54,4 +54,20 @@ Rails.configuration.after_initialize do
   end
 end
 
+# load deferred routes in Rails 8+
+if Rails::VERSION::MAJOR >= 8
+  # reset Rage routes before Rails reloads routes
+  routes_reloader_patch = Module.new do
+    def reload!
+      Rage.__router.reset_routes
+      super
+    end
+  end
+  Rails::Application::RoutesReloader.prepend(routes_reloader_patch)
+
+  Rails.application.config.after_initialize do
+    Rails.application.reload_routes!
+  end
+end
+
 require "rage/ext/setup"

data/lib/rage/router/README.md

@@ -1,6 +1,6 @@
 This is an almost complete rewrite of https://github.com/delvedor/find-my-way.
 
-Currrently, the only constraint supported is the `host` constraint. Regexp constraints are likely to be added. Custom/lambda constraints are unlikely to be added.
+Currently, the only constraint supported is the `host` constraint. Regexp constraints are likely to be added. Custom/lambda constraints are unlikely to be added.
 
 Compared to the Rails router, the most notable difference except constraints is that a wildcard segment can only be in the last section of the path and cannot be named.
 

data/lib/rage/router/dsl.rb

@@ -62,6 +62,8 @@ class Rage::Router::DSL
       @router = router
 
       @default_actions = %i(index create show update destroy)
+      @default_actions += %i(new edit) if Rage.config.router.form_actions
+
       @default_match_methods = %i(get post put patch delete head)
       @scope_opts = %i(module path controller)
 
@@ -348,31 +350,65 @@ class Rage::Router::DSL
       _module, _path, _only, _except, _param = opts.values_at(:module, :path, :only, :except, :param)
       raise ArgumentError, ":param option can't contain colons" if _param.to_s.include?(":")
 
-      _only = Array(_only) if _only
-      _except = Array(_except) if _except
-      actions = @default_actions.select do |action|
-        (_only.nil? || _only.include?(action)) && (_except.nil? || !_except.include?(action))
-      end
+      actions = __filter_actions(@default_actions, _only, _except)
 
       resource = _resources[0].to_s
-      _path ||= resource
       _param ||= "id"
 
-      scope_opts = { path: _path }
-      scope_opts[:module] = _module if _module
-
-      scope(scope_opts) do
+      __resource_scope(resource, _path, _module) do
         get("/", to: "#{resource}#index") if actions.include?(:index)
         post("/", to: "#{resource}#create") if actions.include?(:create)
         get("/:#{_param}", to: "#{resource}#show") if actions.include?(:show)
         patch("/:#{_param}", to: "#{resource}#update") if actions.include?(:update)
         put("/:#{_param}", to: "#{resource}#update") if actions.include?(:update)
+        get("/new", to: "#{resource}#new") if actions.include?(:new)
+        get("/:#{_param}/edit", to: "#{resource}#edit") if actions.include?(:edit)
         delete("/:#{_param}", to: "#{resource}#destroy") if actions.include?(:destroy)
 
         scope(path: ":#{to_singular(resource)}_#{_param}", controller: resource, &block) if block
       end
     end
 
+    # Automatically create REST routes for a singular resource.
+    #
+    # @param [Hash] opts resource options
+    # @option opts [String] :module the namespace for the controller
+    # @option opts [String] :path the path prefix for the routes
+    # @option opts [Symbol, Array<Symbol>] :only only generate routes for the given actions
+    # @option opts [Symbol, Array<Symbol>] :except generate all routes except for the given actions
+    # @example Create singular routes mapped to a plural controller:
+    #   resource :photo
+    #   # POST   /photo => photos#create
+    #   # GET    /photo => photos#show
+    #   # PATCH  /photo => photos#update
+    #   # PUT    /photo => photos#update
+    #   # DELETE /photo => photos#destroy
+    # @note :param is not supported for singular resources.
+    def resource(*_resources, **opts, &block)
+      if _resources.length > 1
+        _resources.each { |_resource| resource(_resource, **opts, &block) }
+        return
+      end
+
+      _module, _path, _only, _except = opts.values_at(:module, :path, :only, :except)
+
+      actions = __filter_actions(@default_actions - [:index], _only, _except)
+
+      resource_name = _resources[0].to_s
+      controller_name = to_plural(resource_name)
+      __resource_scope(resource_name, _path, _module) do
+        post("/", to: "#{controller_name}#create") if actions.include?(:create)
+        get("/", to: "#{controller_name}#show") if actions.include?(:show)
+        patch("/", to: "#{controller_name}#update") if actions.include?(:update)
+        put("/", to: "#{controller_name}#update") if actions.include?(:update)
+        get("/new", to: "#{controller_name}#new") if actions.include?(:new)
+        get("/edit", to: "#{controller_name}#edit") if actions.include?(:edit)
+        delete("/", to: "#{controller_name}#destroy") if actions.include?(:destroy)
+
+        scope(controller: controller_name, &block) if block
+      end
+    end
+
     # Mount a Rack-based application to be used within the application.
     #
     # @example
@@ -445,6 +481,25 @@ class Rage::Router::DSL
       end
     end
 
+    # Filters a list of actions based on :only and :except options
+    def __filter_actions(default_actions, only, except)
+      only = Array(only) if only
+      except = Array(except) if except
+
+      default_actions.select do |action|
+        (only.nil? || only.include?(action)) &&
+          (except.nil? || !except.include?(action))
+      end
+    end
+
+    # Wraps route definitions in the correct path/module scope
+    def __resource_scope(resource, path, mod, &block)
+      path ||= resource
+      scope_opts = { path: path }
+      scope_opts[:module] = mod if mod
+      scope(scope_opts, &block)
+    end
+
     def to_singular(str)
       @active_support_loaded ||= str.respond_to?(:singularize) || :false
       return str.singularize if @active_support_loaded != :false
@@ -462,5 +517,12 @@ class Rage::Router::DSL
 
       str.sub(@regexp, @endings)
     end
+
+    def to_plural(str)
+      @active_support_loaded ||= str.respond_to?(:pluralize) || :false
+      return str.pluralize if @active_support_loaded != :false
+
+      str.end_with?("s") ? str : "#{str}s"
+    end
   end
 end

data/lib/rage/sse/application.rb

@@ -12,6 +12,8 @@ class Rage::SSE::Application
       :stream
     elsif @stream.is_a?(Proc)
       :manual
+    elsif @stream.is_a?(Rage::SSE::Stream)
+      :broadcast
     else
       :single
     end
@@ -20,7 +22,13 @@ class Rage::SSE::Application
   end
 
   def on_open(connection)
-    @type == :single ? send_data(connection) : start_stream(connection)
+    if @type == :single
+      send_data(connection)
+    elsif @type == :broadcast
+      start_broadcast_stream(connection)
+    else
+      start_stream(connection)
+    end
   end
 
   private
@@ -28,18 +36,36 @@ class Rage::SSE::Application
   def send_data(connection)
     Rage::Telemetry.tracer.span_sse_stream_process(connection:, type: @type) do
       connection.write(Rage::SSE.__serialize(@stream))
-      connection.close
+    end
+  ensure
+    connection.close
+  end
+
+  def start_broadcast_stream(connection)
+    channel = "sse:#{@stream.name}"
+
+    connection.subscribe(channel) do |_, msg|
+      msg == Rage::SSE::CLOSE_STREAM_MSG ? connection.close : connection.write(msg)
+    end
+
+    buffered_messages = Rage::SSE::Stream.__claim_buffered_messages(@stream)
+    buffered_messages&.each do |msg|
+      msg == Rage::SSE::CLOSE_STREAM_MSG ? connection.close : connection.write(msg)
     end
   end
 
   def start_stream(connection)
     Fiber.schedule do
+      Iodine.task_inc!
       Fiber[:__rage_logger_tags], Fiber[:__rage_logger_context] = @log_tags, @log_context
       Rage::Telemetry.tracer.span_sse_stream_process(connection:, type: @type) do
         @type == :stream ? start_formatted_stream(connection) : start_raw_stream(connection)
       end
     rescue => e
       Rage.logger.error("SSE stream failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+      Rage::Errors.report(e)
+    ensure
+      Iodine.task_dec!
     end
   end
 
@@ -54,5 +80,8 @@ class Rage::SSE::Application
 
   def start_raw_stream(connection)
     @stream.call(Rage::SSE::ConnectionProxy.new(connection))
+  rescue => e
+    connection.close if connection.open?
+    raise e
   end
 end

data/lib/rage/sse/sse.rb

@@ -14,6 +14,18 @@ module Rage::SSE
     Message.new(data:, id:, event:, retry:)
   end
 
+  # A factory method for creating unbounded SSE streams.
+  #
+  # @param streamable [#id, String, Symbol, Numeric, Array] An object to generate the stream name from.
+  # @return [Stream] A new SSE stream instance.
+  # @example
+  #   render sse: Rage::SSE.stream("#{current_user.id}-notifications")
+  # @example
+  #   render sse: Rage::SSE.stream([current_user.id, "notifications"])
+  def self.stream(streamable)
+    Stream.new(streamable:)
+  end
+
   # @private
   def self.__serialize(data)
     if data.is_a?(String)
@@ -24,8 +36,92 @@ module Rage::SSE
       "data: #{data.to_json}\n\n"
     end
   end
+
+  # @private
+  def self.__adapter=(adapter)
+    @__adapter = adapter
+  end
+
+  # @private
+  CLOSE_STREAM_MSG = "rage-close-stream"
+
+  # @private
+  PUBSUB_BROADCASTER_ID = "sse"
+
+  # Close an unbounded SSE stream. Unbounded streams will remain open until either the client disconnects or the server explicitly closes them.
+  #
+  # @param streamable [#id, String, Symbol, Numeric, Array] The identifier of the stream to close.
+  # @example
+  #   Rage::SSE.close_stream("#{current_user.id}-notifications")
+  # @example
+  #   Rage::SSE.close_stream([current_user.id, "notifications"])
+  def self.close_stream(streamable)
+    stream_name = Rage::Internal.stream_name_for(streamable)
+
+    InternalBroadcast.broadcast(stream_name, CLOSE_STREAM_MSG, Iodine::PubSub::CLUSTER) if Iodine.running?
+    @__adapter&.publish(PUBSUB_BROADCASTER_ID, stream_name, CLOSE_STREAM_MSG)
+
+    true
+  end
+
+  # Broadcast a message to all clients subscribed to a given stream.
+  #
+  # @param streamable [#id, String, Symbol, Numeric, Array] The identifier of the stream to broadcast to.
+  # @param data [String, #to_json, Message] The message to broadcast.
+  # @example
+  #   Rage::SSE.broadcast("#{current_user.id}-notifications", "You have a new notification!")
+  # @example
+  #   Rage::SSE.broadcast([current_user.id, "notifications"], { title: "New Notification", body: "You have a new notification!" })
+  def self.broadcast(streamable, data)
+    Rage::Telemetry.tracer.span_sse_stream_broadcast(stream: streamable) do
+      stream_name = Rage::Internal.stream_name_for(streamable)
+      serialized_data = __serialize(data)
+
+      InternalBroadcast.broadcast(stream_name, serialized_data, Iodine::PubSub::CLUSTER) if Iodine.running?
+      @__adapter&.publish(PUBSUB_BROADCASTER_ID, stream_name, serialized_data)
+    end
+
+    true
+  end
+
+  # @private
+  module InternalBroadcast
+    def self.broadcast(stream_name, data, engine)
+      if Rage::SSE::Stream.__message_buffer.has_key?(stream_name)
+        Rage::SSE::Stream.__store_message(stream_name, data)
+      end
+
+      Iodine.publish("sse:#{stream_name}", data, engine)
+    end
+  end
+
+  # @private
+  module Relay
+    def self.broadcast(stream_name, data)
+      Iodine.publish("sse-relay", "#{stream_name}\x00#{data}")
+    end
+  end
 end
 
 require_relative "application"
 require_relative "connection_proxy"
 require_relative "message"
+require_relative "stream"
+
+Rage.config.after_initialize do
+  if (adapter = Rage.config.pubsub.adapter)
+    Iodine.on_state(:on_start) do
+      Iodine.subscribe("sse-relay") do |_, msg|
+        stream_name, data = msg.split("\x00", 2)
+        Rage::SSE::InternalBroadcast.broadcast(stream_name, data, Iodine::PubSub::PROCESS)
+      end
+    end
+
+    Iodine.on_state(:on_finish) do
+      Iodine.unsubscribe("sse-relay")
+    end
+
+    adapter.add_broadcaster(Rage::SSE::PUBSUB_BROADCASTER_ID, Rage::SSE::Relay)
+    Rage::SSE.__adapter = adapter
+  end
+end

data/lib/rage/sse/stream.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+##
+# The class representing an unbounded Server-Sent Events stream. It allows for broadcasting messages to all connected clients subscribed to the stream.
+#
+# Create a stream:
+#
+# ```ruby
+# render sse: Rage::SSE.stream([current_user, "notifications"])
+# ```
+#
+# Broadcast a message to all connections subscribed to the stream:
+# ```ruby
+# Rage::SSE.broadcast([current_user, "notifications"], "You have a new notification!")
+# ```
+#
+# Close the stream:
+# ```ruby
+# Rage::SSE.close_stream([current_user, "notifications"])
+# ```
+#
+# Messages to known streams are buffered until a connection is fully established:
+# ```ruby
+# # Create a stream first
+# stream = Rage::SSE.stream([current_user, "notifications"])
+#
+# # No connection yet, but the message is buffered
+# Rage::SSE.broadcast([current_user, "notifications"], "You have a new notification!")
+#
+# # Establish a connection, which will claim the buffered message
+# render sse: stream
+# ```
+#
+class Rage::SSE::Stream
+  class << self
+    # @private
+    def __message_buffer
+      @__message_buffer ||= Hash.new { |h, k| h[k] = {} }
+    end
+
+    # @private
+    def __store_message(stream, message)
+      __message_buffer[stream].transform_values! do |buffer|
+        buffer.frozen? ? [message] : buffer.push(message)
+      end
+    end
+
+    # @private
+    def __claim_buffered_messages(stream)
+      messages = __message_buffer[stream.name][stream.owner] if __message_buffer.has_key?(stream.name)
+      cleanup_message_buffer
+
+      messages
+    end
+
+    private
+
+    def cleanup_message_buffer
+      __message_buffer.delete_if do |_, connection_buffers|
+        connection_buffers.keys.none?(&:alive?)
+      end
+    end
+  end
+
+  DEFAULT_BUFFER = [].freeze
+  private_constant :DEFAULT_BUFFER
+
+  # @private
+  attr_reader :name, :owner
+
+  # @param streamable [#id, String, Symbol, Numeric, Array] an object that will be used to generate the stream name
+  def initialize(streamable:)
+    @name = Rage::Internal.stream_name_for(streamable)
+    @owner = Fiber.current
+
+    self.class.__message_buffer[@name][@owner] ||= DEFAULT_BUFFER
+  end
+end