rage-rb 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61d3c256494b63668809f556d221c9dd86b1542ce30051c689e1f30a7b1aca00
-  data.tar.gz: 268fc8606e772b06985effe6918270f2ecb1c21b191bfa59ae9a74c0eeb8f459
+  metadata.gz: 4adc4048bfa84558a6b86b15cbcab8e6153858878425bde66db78a975fa46f46
+  data.tar.gz: 46bef9f42fdd681bdf593f037a73ca8ae2d435acad9eed5ddf4b3740bf61b601
 SHA512:
-  metadata.gz: 0136a9c93cb94dc161367ecac78b3d106404e4450fb1f4c6df8d6e38400da242fdaeebf54a7ed18ae5fc0037bea9e62ae94b5870883a2adb493e5721059a9eb8
-  data.tar.gz: c10509dbc8ae25ae0f1c19b35903664863fb07fb81409fd6cc16b962bde35d46f7bb552562994757b74fcc4d32f6ef9970a66f0893d0c36f11da5c27a7f2b4df
+  metadata.gz: 754b954d46d065020e0c2184c04f1a13d0c0a64ddf11d1b034062df4cc669460c259032a8bf40a61c876579f1774e50e9b57181d4d3e1301c4610577e11c6734
+  data.tar.gz: 4207556922f8fd2c82d07ba8664f53847dc1e5afb6bb5d38260ac0ccd428dd011fd8c6bf34f69aa75af97044a838df23c6c36b5baae1ae7cd3d4c08455fc699b

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [1.8.0] - 2024-08-06
+
+### Added
+
+- Support WebSockets (#88).
+
 ## [1.7.0] - 2024-07-30
 
 ### Added

data/Gemfile

@@ -18,4 +18,5 @@ group :test do
   gem "connection_pool", "~> 2.0"
   gem "rbnacl"
   gem "domain_name"
+  gem "websocket-client-simple"
 end

data/OVERVIEW.md

@@ -31,7 +31,7 @@ class UsersController < RageController::API
 end
 ```
 
-Before processing requests to `UsersController#show`, Rage has to [register](https://github.com/rage-rb/rage/blob/master/lib/rage/controller/api.rb#L10) the show action. Registering means defining a new method that will look like this:
+Before processing requests to `UsersController#show`, Rage has to [register](https://github.com/rage-rb/rage/blob/master/lib/rage/controller/api.rb#L11) the show action. Registering means defining a new method that will look like this:
 
 ```ruby
 class UsersController

data/README.md

@@ -44,7 +44,7 @@ Start coding!
 
 ## Getting Started
 
-This gem is designed to be a drop-in replacement for Rails in API mode. Public API is mostly expected to match Rails, however, sometimes it's a little bit more strict.
+This gem is designed to be a drop-in replacement for Rails in API mode. Public API is expected to fully match Rails.
 
 Check out in-depth API docs for more information:
 
@@ -60,6 +60,8 @@ Also, see the following integration guides:
 - [Rails integration](https://github.com/rage-rb/rage/wiki/Rails-integration)
 - [RSpec integration](https://github.com/rage-rb/rage/wiki/RSpec-integration)
 
+If you are a first-time contributor, make sure to check the [overview doc](https://github.com/rage-rb/rage/blob/master/OVERVIEW.md) that shows how Rage's core components interact with each other.
+
 ### Example
 
 A sample controller could look like this:
@@ -157,7 +159,7 @@ class BenchmarksController < ApplicationController
 end
 ```
 
-![Requests per second-2](https://github.com/user-attachments/assets/b7ee0bff-e7c8-4fd4-a565-ce0b67a6320e)
+![Requests per second](https://github.com/user-attachments/assets/04678788-0034-4db4-9582-d0bc16fd9e28)
 
 ## Upcoming releases
 

data/lib/rage/all.rb

@@ -26,6 +26,7 @@ require_relative "logger/text_formatter"
 require_relative "logger/json_formatter"
 require_relative "logger/logger"
 
+require_relative "middleware/origin_validator"
 require_relative "middleware/fiber_wrapper"
 require_relative "middleware/cors"
 require_relative "middleware/reloader"

data/lib/rage/cable/cable.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Rage::Cable
+  # Create a new Cable application.
+  #
+  # @example
+  #   map "/cable" do
+  #     run Rage.cable.application
+  #   end
+  def self.application
+    protocol = Rage.config.cable.protocol
+    protocol.init(__router)
+
+    handler = __build_handler(protocol)
+    accept_response = [0, protocol.protocol_definition, []]
+
+    application = ->(env) do
+      if env["rack.upgrade?"] == :websocket
+        env["rack.upgrade"] = handler
+        accept_response
+      else
+        [426, { "Connection" => "Upgrade", "Upgrade" => "websocket" }, []]
+      end
+    end
+
+    Rage.with_middlewares(application, Rage.config.cable.middlewares)
+  end
+
+  # @private
+  def self.__router
+    @__router ||= Router.new
+  end
+
+  # @private
+  def self.__build_handler(protocol)
+    klass = Class.new do
+      def initialize(protocol)
+        Iodine.on_state(:on_start) do
+          unless Fiber.scheduler
+            Fiber.set_scheduler(Rage::FiberScheduler.new)
+          end
+        end
+
+        @protocol = protocol
+      end
+
+      def on_open(connection)
+        Fiber.schedule do
+          @protocol.on_open(connection)
+        rescue => e
+          log_error(e)
+        end
+      end
+
+      def on_message(connection, data)
+        Fiber.schedule do
+          @protocol.on_message(connection, data)
+        rescue => e
+          log_error(e)
+        end
+      end
+
+      if protocol.respond_to?(:on_close)
+        def on_close(connection)
+          return unless ::Iodine.running?
+
+          Fiber.schedule do
+            @protocol.on_close(connection)
+          rescue => e
+            log_error(e)
+          end
+        end
+      end
+
+      if protocol.respond_to?(:on_shutdown)
+        def on_shutdown(connection)
+          @protocol.on_shutdown(connection)
+        rescue => e
+          log_error(e)
+        end
+      end
+
+      private
+
+      def log_error(e)
+        Rage.logger.error("Unhandled exception has occured - #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+      end
+    end
+
+    klass.new(protocol)
+  end
+
+  # Broadcast data directly to a named stream.
+  #
+  # @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.
+  # @example
+  #   Rage.cable.broadcast("chat", { message: "A new member has joined!" })
+  def self.broadcast(stream, data)
+    Rage.config.cable.protocol.broadcast(stream, data)
+  end
+
+  # @!parse [ruby]
+  #   # @abstract
+  #   class WebSocketConnection
+  #     # Write data to the connection.
+  #     #
+  #     # @param data [String] the data to write
+  #     def write(data)
+  #     end
+  #
+  #     # Subscribe to a channel.
+  #     #
+  #     # @param name [String] the channel name
+  #     def subscribe(name)
+  #     end
+  #
+  #     # Close the connection.
+  #     def close
+  #     end
+  #   end
+
+  module Protocol
+  end
+end
+
+require_relative "protocol/actioncable_v1_json"
+require_relative "channel"
+require_relative "connection"
+require_relative "router"

data/lib/rage/cable/channel.rb

@@ -0,0 +1,452 @@
+require "set"
+
+class Rage::Cable::Channel
+  # @private
+  INTERNAL_ACTIONS = [:subscribed, :unsubscribed]
+
+  class << self
+    # @private
+    attr_reader :__prepared_actions
+
+    # @private
+    attr_reader :__channels
+
+    # @private
+    # returns a list of actions that can be called remotely
+    def __register_actions
+      actions = (
+        public_instance_methods(true) - Rage::Cable::Channel.public_instance_methods(true)
+      ).reject { |m| m.start_with?("__rage_tmp") || m.start_with?("__run") }
+
+      @__prepared_actions = (INTERNAL_ACTIONS + actions).each_with_object({}) do |action_name, memo|
+        memo[action_name] = __register_action_proc(action_name)
+      end
+
+      actions - INTERNAL_ACTIONS
+    end
+
+    # @private
+    # rubocop:disable Layout/HeredocIndentation, Layout/IndentationWidth, Layout/EndAlignment, Layout/ElseAlignment
+    def __register_action_proc(action_name)
+      if action_name == :subscribed && @__hooks
+        before_subscribe_chunk = if @__hooks[:before_subscribe]
+          lines = @__hooks[:before_subscribe].map do |h|
+            condition = if h[:if] && h[:unless]
+              "if #{h[:if]} && !#{h[:unless]}"
+            elsif h[:if]
+              "if #{h[:if]}"
+            elsif h[:unless]
+              "unless #{h[:unless]}"
+            end
+
+            <<~RUBY
+              #{h[:name]} #{condition}
+              return if @__subscription_rejected
+            RUBY
+          end
+
+          lines.join("\n")
+        end
+
+        after_subscribe_chunk = if @__hooks[:after_subscribe]
+          lines = @__hooks[:after_subscribe].map do |h|
+            condition = if h[:if] && h[:unless]
+              "if #{h[:if]} && !#{h[:unless]}"
+            elsif h[:if]
+              "if #{h[:if]}"
+            elsif h[:unless]
+              "unless #{h[:unless]}"
+            end
+
+            <<~RUBY
+              #{h[:name]} #{condition}
+            RUBY
+          end
+
+          lines.join("\n")
+        end
+      end
+
+      if action_name == :unsubscribed && @__hooks
+        before_unsubscribe_chunk = if @__hooks[:before_unsubscribe]
+          lines = @__hooks[:before_unsubscribe].map do |h|
+            condition = if h[:if] && h[:unless]
+              "if #{h[:if]} && !#{h[:unless]}"
+            elsif h[:if]
+              "if #{h[:if]}"
+            elsif h[:unless]
+              "unless #{h[:unless]}"
+            end
+
+            <<~RUBY
+              #{h[:name]} #{condition}
+            RUBY
+          end
+
+          lines.join("\n")
+        end
+
+        after_unsubscribe_chunk = if @__hooks[:after_unsubscribe]
+          lines = @__hooks[:after_unsubscribe].map do |h|
+            condition = if h[:if] && h[:unless]
+              "if #{h[:if]} && !#{h[:unless]}"
+            elsif h[:if]
+              "if #{h[:if]}"
+            elsif h[:unless]
+              "unless #{h[:unless]}"
+            end
+
+            <<~RUBY
+              #{h[:name]} #{condition}
+            RUBY
+          end
+
+          lines.join("\n")
+        end
+      end
+
+      rescue_handlers_chunk = if @__rescue_handlers
+        lines = @__rescue_handlers.map do |klasses, handler|
+          <<~RUBY
+          rescue #{klasses.join(", ")} => __e
+            #{instance_method(handler).arity == 0 ? handler : "#{handler}(__e)"}
+          RUBY
+        end
+
+        lines.join("\n")
+      else
+        ""
+      end
+
+      periodic_timers_chunk = if @__periodic_timers
+        set_up_periodic_timers
+
+        if action_name == :subscribed
+          <<~RUBY
+            self.class.__channels << self unless subscription_rejected?
+          RUBY
+        elsif action_name == :unsubscribed
+          <<~RUBY
+            self.class.__channels.delete(self)
+          RUBY
+        end
+      else
+        ""
+      end
+
+      is_subscribing = action_name == :subscribed
+      activerecord_loaded = defined?(::ActiveRecord)
+
+      method_name = class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def __run_#{action_name}(data)
+          #{if is_subscribing
+            <<~RUBY
+              @__is_subscribing = true
+            RUBY
+          end}
+
+          #{before_subscribe_chunk}
+          #{before_unsubscribe_chunk}
+
+          #{if instance_method(action_name).arity == 0
+            <<~RUBY
+              #{action_name}
+            RUBY
+          else
+            <<~RUBY
+              #{action_name}(data)
+            RUBY
+          end}
+
+          #{after_subscribe_chunk}
+          #{after_unsubscribe_chunk}
+          #{periodic_timers_chunk}
+          #{rescue_handlers_chunk}
+
+          #{if activerecord_loaded
+            <<~RUBY
+            ensure
+              if ActiveRecord::Base.connection_pool.active_connection?
+                ActiveRecord::Base.connection_handler.clear_active_connections!
+              end
+            RUBY
+          end}
+        end
+      RUBY
+
+      eval("->(channel, data) { channel.#{method_name}(data) }")
+    end
+    # rubocop:enable all
+
+    # @private
+    def __prepare_id_method(method_name)
+      define_method(method_name) do
+        @__identified_by[method_name]
+      end
+    end
+
+    # Register a new `before_subscribe` hook that will be called before the {subscribed} method.
+    #
+    # @example
+    #   before_subscribe :my_method
+    # @example
+    #   before_subscribe do
+    #     ...
+    #   end
+    # @example
+    #   before_subscribe :my_method, if: -> { ... }
+    def before_subscribe(action_name = nil, **opts, &block)
+      add_action(:before_subscribe, action_name, **opts, &block)
+    end
+
+    # Register a new `after_subscribe` hook that will be called after the {subscribed} method.
+    #
+    # @example
+    #   after_subscribe do
+    #     ...
+    #   end
+    # @example
+    #   after_subscribe :my_method, unless: :subscription_rejected?
+    # @note This callback will be triggered even if the subscription was rejected with the {reject} method.
+    def after_subscribe(action_name = nil, **opts, &block)
+      add_action(:after_subscribe, action_name, **opts, &block)
+    end
+
+    # Register a new `before_unsubscribe` hook that will be called before the {unsubscribed} method.
+    def before_unsubscribe(action_name = nil, **opts, &block)
+      add_action(:before_unsubscribe, action_name, **opts, &block)
+    end
+
+    # Register a new `after_unsubscribe` hook that will be called after the {unsubscribed} method.
+    def after_unsubscribe(action_name = nil, **opts, &block)
+      add_action(:after_unsubscribe, action_name, **opts, &block)
+    end
+
+    # Register an exception handler.
+    #
+    # @param klasses [Class, Array<Class>] exception classes to watch on
+    # @param with [Symbol] the name of a handler method. The method can take one argument, which is the raised exception. Alternatively, you can pass a block, which can also take one argument.
+    # @example
+    #   rescue_from StandardError, with: :report_error
+    #
+    #   private
+    #
+    #   def report_error(e)
+    #     SomeExternalBugtrackingService.notify(e)
+    #   end
+    # @example
+    #   rescue_from StandardError do |e|
+    #     SomeExternalBugtrackingService.notify(e)
+    #   end
+    def rescue_from(*klasses, with: nil, &block)
+      unless with
+        if block_given?
+          with = define_tmp_method(block)
+        else
+          raise ArgumentError, "No handler provided. Pass the `with` keyword argument or provide a block."
+        end
+      end
+
+      if @__rescue_handlers.nil?
+        @__rescue_handlers = []
+      elsif @__rescue_handlers.frozen?
+        @__rescue_handlers = @__rescue_handlers.dup
+      end
+
+      @__rescue_handlers.unshift([klasses, with])
+    end
+
+    # Set up a timer to periodically perform a task on the channel. Accepts a method name or a block.
+    #
+    # @param method_name [Symbol, nil] the name of the method to call
+    # @param every [Integer] the calling period in seconds
+    # @example
+    #   periodically every: 3.minutes do
+    #     transmit({ action: :update_count, count: current_count })
+    #   end
+    # @example
+    #   periodically :update_count, every: 3.minutes
+    def periodically(method_name = nil, every:, &block)
+      callback_name = if block_given?
+        raise ArgumentError, "Pass the `method_name` argument or provide a block, not both" if method_name
+        define_tmp_method(block)
+      elsif method_name.is_a?(Symbol)
+        define_tmp_method(eval("-> { #{method_name} }"))
+      else
+        raise ArgumentError, "Expected a Symbol method name, got #{method_name.inspect}"
+      end
+
+      unless every.is_a?(Numeric) && every > 0
+        raise ArgumentError, "Expected every: to be a positive number of seconds, got #{every.inspect}"
+      end
+
+      callback = eval("->(channel) { channel.#{callback_name} }")
+
+      if @__periodic_timers.nil?
+        @__periodic_timers = []
+      elsif @__periodic_timers.frozen?
+        @__periodic_timers = @__periodic_timers.dup
+      end
+
+      @__periodic_timers << [callback, every]
+    end
+
+    protected
+
+    def set_up_periodic_timers
+      return if @__periodic_timers_set_up
+
+      @__channels = Set.new
+
+      @__periodic_timers.each do |callback, every|
+        ::Iodine.run_every((every * 1000).to_i) do
+          slice_length = (@__channels.length / 20.0).ceil
+
+          if slice_length != 0
+            @__channels.each_slice(slice_length) do |slice|
+              Fiber.schedule do
+                slice.each { |channel| callback.call(channel) }
+              rescue => e
+                Rage.logger.error("Unhandled exception has occured - #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+              end
+            end
+          end
+        end
+      end
+
+      @__periodic_timers_set_up = true
+    end
+
+    def add_action(action_type, action_name = nil, **opts, &block)
+      if block_given?
+        action_name = define_tmp_method(block)
+      elsif action_name.nil?
+        raise ArgumentError, "No handler provided. Pass the `action_name` parameter or provide a block."
+      end
+
+      _if, _unless = opts.values_at(:if, :unless)
+
+      action = {
+        name: action_name,
+        if: _if,
+        unless: _unless
+      }
+
+      action[:if] = define_tmp_method(action[:if]) if action[:if].is_a?(Proc)
+      action[:unless] = define_tmp_method(action[:unless]) if action[:unless].is_a?(Proc)
+
+      if @__hooks.nil?
+        @__hooks = {}
+      elsif @__hooks[action_type] && @__hooks.frozen?
+        @__hooks = @__hooks.dup
+        @__hooks[action_type] = @__hooks[action_type].dup
+      end
+
+      if @__hooks[action_type].nil?
+        @__hooks[action_type] = [action]
+      elsif (i = @__hooks[action_type].find_index { |a| a[:name] == action_name })
+        @__hooks[action_type][i] = action
+      else
+        @__hooks[action_type] << action
+      end
+    end
+
+    attr_writer :__hooks, :__rescue_handlers, :__periodic_timers
+
+    def inherited(klass)
+      klass.__hooks = @__hooks.freeze
+      klass.__rescue_handlers = @__rescue_handlers.freeze
+      klass.__periodic_timers = @__periodic_timers.freeze
+    end
+
+    @@__tmp_name_seed = ("a".."i").to_a.permutation
+
+    def define_tmp_method(block)
+      name = @@__tmp_name_seed.next.join
+      define_method("__rage_tmp_#{name}", block)
+    end
+  end # class << self
+
+  # @private
+  def __has_action?(action_name)
+    !INTERNAL_ACTIONS.include?(action_name) && self.class.__prepared_actions.has_key?(action_name)
+  end
+
+  # @private
+  def __run_action(action_name, data = nil)
+    self.class.__prepared_actions[action_name].call(self, data)
+  end
+
+  # @private
+  def initialize(connection, params, identified_by)
+    @__connection = connection
+    @__params = params
+    @__identified_by = identified_by
+  end
+
+  # Get the params hash passed in during the subscription process.
+  #
+  # @return [Hash{Symbol=>String,Array,Hash,Numeric,NilClass,TrueClass,FalseClass}]
+  def params
+    @__params
+  end
+
+  # Reject the subscription request. The method should only be called during the subscription
+  # process (i.e. inside the {subscribed} method or {before_subscribe}/{after_subscribe} hooks).
+  def reject
+    @__subscription_rejected = true
+  end
+
+  # Checks whether the {reject} method has been called.
+  #
+  # @return [Boolean]
+  def subscription_rejected?
+    !!@__subscription_rejected
+  end
+
+  # Subscribe to a stream.
+  #
+  # @param stream [String] the name of the stream
+  def stream_from(stream)
+    Rage.config.cable.protocol.subscribe(@__connection, stream, @__params)
+  end
+
+  # Broadcast data to all the clients subscribed to a stream.
+  #
+  # @param stream [String] the name of the stream
+  # @param data [Object] the data to send to the clients
+  # @example
+  #   def subscribed
+  #     broadcast("notifications", { message: "A new member has joined!" })
+  #   end
+  def broadcast(stream, data)
+    Rage.config.cable.protocol.broadcast(stream, data)
+  end
+
+  # Transmit data to the current client.
+  #
+  # @param data [Object] the data to send to the client
+  # @example
+  #   def subscribed
+  #     transmit({ message: "Hello!" })
+  #   end
+  def transmit(data)
+    message = Rage.config.cable.protocol.serialize(@__params, data)
+
+    if @__is_subscribing
+      # we expect a confirmation message to be sent as a result of a successful subscribe call;
+      # this will make sure `transmit` calls send data after the confirmation;
+      ::Iodine.defer { @__connection.write(message) }
+    else
+      @__connection.write(message)
+    end
+  end
+
+  # Called once a client has become a subscriber of the channel.
+  def subscribed
+  end
+
+  # Called once a client unsubscribes from the channel.
+  def unsubscribed
+  end
+end