rage-rb 1.10.1 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87a1aecc1f62917581dee82c9efe0d56cebc69046500eeaf7f2e73aa7f35f809
-  data.tar.gz: 6e890b8641f214b2cfbebc2fd56bc1f5a32f2f8c2281cbf8f62d3a607d05c4ad
+  metadata.gz: 8c42516bec6fabfb0b06d9f11a5156298474a48f7988edba746122ae4ec172dc
+  data.tar.gz: 3b6b5b7692bb693ba53137d11bc1d7883ace69e496b5a99ec367da9a78ec4675
 SHA512:
-  metadata.gz: c659a925cd991c383714d48e803a93edec1703c5e99aacd73d7c4748be00e77ec8077f6c86ec31c13c8fab373c9ef22bc11fec647b0bc233abec710967a827f4
-  data.tar.gz: a0085405ad42e00730128e942b72abf9944f9344d2e9d5b178b393f8f019b517b430a0b3bf3ac7dd8b8e575392e4f79f7c0cc8531093be3d8100a549f13583f2
+  metadata.gz: b72d88f12c3608006637d822c7d3f955ef549e61ee644fc3d7748f507381cfe4917d3eea7f6cb75cf49f053f7ba34ce407a8ed06033a06e89e95208a15b6144e
+  data.tar.gz: f60d1950bce78665acfe6af71aeff1694692b6063cbf76e6c39a0af5dbcf8a79672b8603c0a39ce5d2b0beb0ecf61edfba310d6140fb94b899d85dbad0dd2c21

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [1.12.0] - 2025-01-21
+
+### Added
+
+- Add Redis adapter (#114).
+- Add global response tags (#110).
+- Implement around_action callbacks (#107).
+
+### Fixed
+
+- Support date types in Alba serializers (#112).
+
+## [1.11.0] - 2024-12-18
+
+### Added
+
+- `Rage::OpenAPI` (#109).
+
+### Fixed
+
+- Correctly handle ActiveRecord connections in the environments with `legacy_connection_handling == false` (#108).
+
 ## [1.10.1] - 2024-09-17
 
 ### Fixed

data/Gemfile

@@ -19,4 +19,6 @@ group :test do
   gem "rbnacl"
   gem "domain_name"
   gem "websocket-client-simple"
+  gem "prism"
+  gem "redis-client"
 end

data/README.md

@@ -6,8 +6,7 @@
 ![Tests](https://github.com/rage-rb/rage/actions/workflows/main.yml/badge.svg)
 ![Ruby Requirement](https://img.shields.io/badge/Ruby-3.1%2B-%23f40000)
 
-
-Inspired by [Deno](https://deno.com) and built on top of [Iodine](https://github.com/rage-rb/iodine), this is a Ruby web framework that is based on the following design principles:
+Rage is a high-performance framework compatible with Rails, featuring [WebSocket](https://github.com/rage-rb/rage/wiki/WebSockets-guide) support and automatic generation of [OpenAPI](https://github.com/rage-rb/rage/wiki/OpenAPI-Guide) documentation for your APIs. The framework is built on top of [Iodine](https://github.com/rage-rb/iodine) and is based on the following design principles:
 
 * **Rails compatible API** - Rails' API is clean, straightforward, and simply makes sense. It was one of the reasons why Rails was so successful in the past.
 
@@ -46,6 +45,11 @@ Start coding!
 
 This gem is designed to be a drop-in replacement for Rails in API mode. Public API is expected to fully match Rails.
 
+A Rage application can operate in two modes:
+
+* **Rails Mode**: Integrate Rage into an existing Rails application to improve throughput and better handle traffic spikes. For more information, see [Rails Integration](https://github.com/rage-rb/rage/wiki/Rails-integration).
+* **Standalone Mode**: Build high-performance services with minimal setup using Rage. To get started, run `rage new --help` for more details.
+
 Check out in-depth API docs for more information:
 
 - [Controller API](https://rage-rb.pages.dev/RageController/API)

data/lib/rage/cable/adapters/base.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Rage::Cable::Adapters::Base
+  def pick_a_worker(&block)
+    _lock, lock_path = Tempfile.new.yield_self { |file| [file, file.path] }
+
+    Iodine.on_state(:on_start) do
+      if File.new(lock_path).flock(File::LOCK_EX | File::LOCK_NB)
+        if Rage.logger.debug?
+          puts "INFO: #{Process.pid} is managing #{self.class.name.split("::").last} subscriptions."
+        end
+        block.call
+      end
+    end
+  end
+end

data/lib/rage/cable/adapters/redis.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+if !defined?(RedisClient)
+  fail <<~ERR
+
+    Redis adapter depends on the `redis-client` gem. Add the following line to your Gemfile:
+    gem "redis-client"
+
+  ERR
+end
+
+class Rage::Cable::Adapters::Redis < Rage::Cable::Adapters::Base
+  REDIS_STREAM_NAME = "rage:cable:messages"
+  DEFAULT_REDIS_OPTIONS = { reconnect_attempts: [0.05, 0.1, 0.5] }
+
+  def initialize(config)
+    @redis_stream = if (prefix = config.delete(:channel_prefix))
+      "#{prefix}:#{REDIS_STREAM_NAME}"
+    else
+      REDIS_STREAM_NAME
+    end
+
+    @redis_config = RedisClient.config(**DEFAULT_REDIS_OPTIONS.merge(config))
+    @server_uuid = SecureRandom.uuid
+
+    redis_version = get_redis_version
+    if redis_version < Gem::Version.create(5)
+      raise "Redis adapter only supports Redis 5+. Detected Redis version: #{redis_version}."
+    end
+
+    @trimming_strategy = redis_version < Gem::Version.create("6.2.0") ? :maxlen : :minid
+
+    pick_a_worker { poll }
+  end
+
+  def publish(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
+    )
+  end
+
+  private
+
+  def publish_redis
+    @publish_redis ||= @redis_config.new_client
+  end
+
+  def trimming_method
+    @trimming_strategy == :maxlen ? "MAXLEN" : "MINID"
+  end
+
+  def trimming_value
+    @trimming_strategy == :maxlen ? "10000" : ((Time.now.to_f - 5 * 60) * 1000).to_i
+  end
+
+  def get_redis_version
+    service_redis = @redis_config.new_client
+    version = service_redis.call("INFO").match(/redis_version:([[:graph:]]+)/)[1]
+
+    Gem::Version.create(version)
+
+  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")
+    Gem::Version.create(5)
+
+  ensure
+    service_redis.close
+  end
+
+  def error_backoff_intervals
+    @error_backoff_intervals ||= Enumerator.new do |y|
+      y << 0.2 << 0.5 << 1 << 2 << 5
+      loop { y << 10 }
+    end
+  end
+
+  def poll
+    unless Fiber.scheduler
+      Fiber.set_scheduler(Rage::FiberScheduler.new)
+    end
+
+    Iodine.on_state(:start_shutdown) do
+      @stopping = true
+    end
+
+    Fiber.schedule do
+      read_redis = @redis_config.new_client
+      last_id = (Time.now.to_f * 1000).to_i
+      last_message_uuid = nil
+
+      loop do
+        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.config.cable.protocol.broadcast(stream_name, JSON.parse(serialized_data))
+            end
+
+            last_id = id
+            last_message_uuid = message_uuid
+          end
+        end
+
+      rescue RedisClient::Error => e
+        Rage.logger.error("Subscriber error: #{e.message} (#{e.class})")
+        sleep error_backoff_intervals.next
+      rescue => e
+        @stopping ? break : raise(e)
+      else
+        error_backoff_intervals.rewind
+      end
+    end
+  end
+end

data/lib/rage/cable/cable.rb

@@ -8,11 +8,11 @@ module Rage::Cable
   #     run Rage.cable.application
   #   end
   def self.application
-    protocol = Rage.config.cable.protocol
-    protocol.init(__router)
+    # explicitly initialize the adapter
+    __adapter
 
-    handler = __build_handler(protocol)
-    accept_response = [0, protocol.protocol_definition, []]
+    handler = __build_handler(__protocol)
+    accept_response = [0, __protocol.protocol_definition, []]
 
     application = ->(env) do
       if env["rack.upgrade?"] == :websocket
@@ -31,6 +31,15 @@ module Rage::Cable
     @__router ||= Router.new
   end
 
+  # @private
+  def self.__protocol
+    @__protocol ||= Rage.config.cable.protocol.tap { |protocol| protocol.init(__router) }
+  end
+
+  def self.__adapter
+    @__adapter ||= Rage.config.cable.adapter
+  end
+
   # @private
   def self.__build_handler(protocol)
     klass = Class.new do
@@ -94,10 +103,14 @@ module Rage::Cable
   #
   # @param stream [String] the name of the stream
   # @param data [Object] the object to send to the clients. This will later be encoded according to the protocol used.
+  # @return [true]
   # @example
   #   Rage.cable.broadcast("chat", { message: "A new member has joined!" })
   def self.broadcast(stream, data)
-    Rage.config.cable.protocol.broadcast(stream, data)
+    __protocol.broadcast(stream, data)
+    __adapter&.publish(stream, data)
+
+    true
   end
 
   # @!parse [ruby]
@@ -120,6 +133,11 @@ module Rage::Cable
   #     end
   #   end
 
+  module Adapters
+    autoload :Base, "rage/cable/adapters/base"
+    autoload :Redis, "rage/cable/adapters/redis"
+  end
+
   module Protocol
   end
 end

data/lib/rage/cable/channel.rb

@@ -418,7 +418,7 @@ class Rage::Cable::Channel
   #     broadcast("notifications", { message: "A new member has joined!" })
   #   end
   def broadcast(stream, data)
-    Rage.config.cable.protocol.broadcast(stream, data)
+    Rage.cable.broadcast(stream, data)
   end
 
   # Transmit data to the current client.

data/lib/rage/cable/protocol/actioncable_v1_json.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "zlib"
+
 ##
 # A protocol defines the structure, rules and semantics for exchanging data between the client and the server.
 # The class that defines a protocol should respond to the following methods:
@@ -17,6 +19,9 @@
 # * `on_shutdown`
 # * `on_close`
 #
+# It is likely that all logic around `@subscription_identifiers` has nothing to do with the protocol itself and
+# should be extracted into another class. We'll refactor this once we start working on a new protocol.
+#
 class Rage::Cable::Protocol::ActioncableV1Json
   module TYPE
     WELCOME = "welcome"
@@ -55,14 +60,30 @@ class Rage::Cable::Protocol::ActioncableV1Json
   def self.init(router)
     @router = router
 
-    ping_counter = Time.now.to_i
-    ::Iodine.run_every(3000) do
-      ping_counter += 1
-      ::Iodine.publish("cable:ping", { type: TYPE::PING, message: ping_counter }.to_json)
+    Iodine.on_state(:on_start) do
+      ping_counter = Time.now.to_i
+
+      Iodine.run_every(3000) do
+        ping_counter += 1
+        Iodine.publish("cable:ping", { type: TYPE::PING, message: ping_counter }.to_json, Iodine::PubSub::PROCESS)
+      end
     end
 
     # Hash<String(stream name) => Array<Hash>(subscription params)>
     @subscription_identifiers = Hash.new { |hash, key| hash[key] = [] }
+
+    # this is a fallback to synchronize subscription identifiers across different worker processes;
+    # we expect connections to be distributed among all workers, so this code will almost never be called;
+    # we also synchronize subscriptions with the master process so that the forks that are spun up instead
+    # of the crashed ones also had access to the identifiers;
+    Iodine.subscribe("cable:synchronize") do |_, subscription_msg|
+      stream_name, params = Rage::ParamsParser.json_parse(subscription_msg)
+      @subscription_identifiers[stream_name] << params unless @subscription_identifiers[stream_name].include?(params)
+    end
+
+    Iodine.on_state(:on_finish) do
+      Iodine.unsubscribe("cable:synchronize")
+    end
   end
 
   # The method is called any time a new WebSocket connection is established.
@@ -147,8 +168,12 @@ class Rage::Cable::Protocol::ActioncableV1Json
   # @param name [String] the stream name
   # @param params [Hash] parameters associated with the client
   def self.subscribe(connection, name, params)
-    connection.subscribe("cable:#{name}:#{params.hash}")
-    @subscription_identifiers[name] << params unless @subscription_identifiers[name].include?(params)
+    connection.subscribe("cable:#{name}:#{Zlib.crc32(params.to_s)}")
+
+    unless @subscription_identifiers[name].include?(params)
+      @subscription_identifiers[name] << params
+      ::Iodine.publish("cable:synchronize", [name, params].to_json)
+    end
   end
 
   # Broadcast data to all clients connected to a stream.
@@ -160,7 +185,7 @@ class Rage::Cable::Protocol::ActioncableV1Json
 
     while i < identifiers.length
       params = identifiers[i]
-      ::Iodine.publish("cable:#{name}:#{params.hash}", serialize(params, data))
+      ::Iodine.publish("cable:#{name}:#{Zlib.crc32(params.to_s)}", serialize(params, data))
       i += 1
     end
   end

data/lib/rage/code_loader.rb

@@ -37,6 +37,10 @@ class Rage::CodeLoader
     unless Rage.autoload?(:Cable) # the `Cable` component is loaded
       Rage::Cable.__router.reset
     end
+
+    unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
+      Rage::OpenAPI.__reset_data_cache
+    end
   end
 
   # in Rails mode - reset the routes; everything else will be done by Rails
@@ -49,6 +53,10 @@ class Rage::CodeLoader
     unless Rage.autoload?(:Cable) # the `Cable` component is loaded
       Rage::Cable.__router.reset
     end
+
+    unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
+      Rage::OpenAPI.__reset_data_cache
+    end
   end
 
   def reloading?

data/lib/rage/configuration.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "yaml"
+require "erb"
+
 ##
 # `Rage.configure` can be used to adjust the behavior of your Rage application:
 #
@@ -122,6 +125,17 @@
 #
 # > Allows requests from any origin.
 #
+# # OpenAPI Configuration
+# • _config.openapi.tag_resolver_
+#
+# > Specifies the proc to build tags for API operations. The proc accepts the controller class, the symbol name of the action, and the default tag built by Rage.
+#
+# > ```ruby
+# config.openapi.tag_resolver = proc do |controller, action, default_tag|
+#    # ...
+# end
+# > ```
+#
 # # Transient Settings
 #
 # The settings described in this section should be configured using **environment variables** and are either temporary or will become the default in the future.
@@ -179,6 +193,10 @@ class Rage::Configuration
     @public_file_server ||= PublicFileServer.new
   end
 
+  def openapi
+    @openapi ||= OpenAPI.new
+  end
+
   def internal
     @internal ||= Internal.new
   end
@@ -218,6 +236,10 @@ class Rage::Configuration
       @middlewares = (@middlewares[0..index] + [[new_middleware, args, block]] + @middlewares[index + 1..]).uniq(&:first)
     end
 
+    def include?(middleware)
+      !!find_middleware_index(middleware) rescue false
+    end
+
     private
 
     def find_middleware_index(middleware)
@@ -258,12 +280,40 @@ class Rage::Configuration
         end
       end
     end
+
+    def config
+      @config ||= begin
+        config_file = Rage.root.join("config/cable.yml")
+
+        if config_file.exist?
+          yaml = ERB.new(config_file.read).result
+          YAML.safe_load(yaml, aliases: true, symbolize_names: true)[Rage.env.to_sym] || {}
+        else
+          {}
+        end
+      end
+    end
+
+    def adapter_config
+      config.except(:adapter)
+    end
+
+    def adapter
+      case config[:adapter]
+      when "redis"
+        Rage::Cable::Adapters::Redis.new(adapter_config)
+      end
+    end
   end
 
   class PublicFileServer
     attr_accessor :enabled
   end
 
+  class OpenAPI
+    attr_accessor :tag_resolver
+  end
+
   # @private
   class Internal
     attr_accessor :rails_mode