rage-rb 1.7.0 → 1.8.0

data/lib/rage/cable/connection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class Rage::Cable::Connection
+  # @private
+  attr_reader :__identified_by_map
+
+  # Mark a key as being a connection identifier index that can then be used to find the specific connection again later.
+  # Common identifiers are `current_user` and `current_account`, but could be anything.
+  #
+  # @param identifiers [Symbol,Array<Symbol>]
+  def self.identified_by(*identifiers)
+    identifiers.each do |method_name|
+      define_method(method_name) do
+        @__identified_by_map[method_name]
+      end
+
+      define_method("#{method_name}=") do |data|
+        @__identified_by_map[method_name] = data
+      end
+
+      Rage::Cable::Channel.__prepare_id_method(method_name)
+    end
+  end
+
+  # @private
+  def initialize(env, identified_by = {})
+    @__env = env
+    @__identified_by_map = identified_by
+  end
+
+  # @private
+  def connect
+  end
+
+  # Reject the WebSocket connection.
+  def reject_unauthorized_connection
+    @rejected = true
+  end
+
+  def rejected?
+    !!@rejected
+  end
+
+  # Get the request object. See {Rage::Request}.
+  #
+  # @return [Rage::Request]
+  def request
+    @__request ||= Rage::Request.new(@__env)
+  end
+
+  # Get the cookie object. See {Rage::Cookies}.
+  #
+  # @return [Rage::Cookies]
+  def cookies
+    @__cookies ||= Rage::Cookies.new(@__env, ReadOnlyHash.new)
+  end
+
+  # Get the session object. See {Rage::Session}.
+  #
+  # @return [Rage::Session]
+  def session
+    @__session ||= Rage::Session.new(cookies)
+  end
+
+  # Get URL query parameters.
+  #
+  # @return [Hash{Symbol=>String,Array,Hash}]
+  def params
+    @__params ||= Iodine::Rack::Utils.parse_nested_query(@__env["QUERY_STRING"])
+  end
+
+  # @private
+  class ReadOnlyHash < Hash
+    def []=(_, _)
+      raise "Cookies cannot be set for WebSocket clients"
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+##
+# 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:
+#
+# * `protocol_definition`
+# * `init`
+# * `on_open`
+# * `on_message`
+# * `serialize`
+# * `subscribe`
+# * `broadcast`
+#
+# The two optional methods are:
+#
+# * `on_shutdown`
+# * `on_close`
+#
+class Rage::Cable::Protocol::ActioncableV1Json
+  module TYPE
+    WELCOME = "welcome"
+    DISCONNECT = "disconnect"
+    PING = "ping"
+    CONFIRM = "confirm_subscription"
+    REJECT = "reject_subscription"
+  end
+
+  module REASON
+    UNAUTHORIZED = "unauthorized"
+    INVALID = "invalid_request"
+  end
+
+  module COMMAND
+    SUBSCRIBE = "subscribe"
+    MESSAGE = "message"
+  end
+
+  module MESSAGES
+    WELCOME = { type: TYPE::WELCOME }.to_json
+    UNAUTHORIZED = { type: TYPE::DISCONNECT, reason: REASON::UNAUTHORIZED, reconnect: false }.to_json
+    INVALID = { type: TYPE::DISCONNECT, reason: REASON::INVALID, reconnect: true }.to_json
+  end
+
+  HANDSHAKE_HEADERS = { "Sec-WebSocket-Protocol" => "actioncable-v1-json" }
+
+  # The method defines the headers to send to the client after the handshake process.
+  def self.protocol_definition
+    HANDSHAKE_HEADERS
+  end
+
+  # This method serves as a constructor to prepare the object or set up recurring tasks (e.g. heartbeats).
+  #
+  # @param router [Rage::Cable::Router]
+  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)
+    end
+
+    # Hash<String(stream name) => Array<Hash>(subscription params)>
+    @subscription_identifiers = Hash.new { |hash, key| hash[key] = [] }
+  end
+
+  # The method is called any time a new WebSocket connection is established.
+  # It is expected to call {Rage::Cable::Router#process_connection} and handle its return value.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @see Rage::Cable::Router
+  def self.on_open(connection)
+    accepted = @router.process_connection(connection)
+
+    if accepted
+      connection.subscribe("cable:ping")
+      connection.write(MESSAGES::WELCOME)
+    else
+      connection.write(MESSAGES::UNAUTHORIZED)
+      connection.close
+    end
+  end
+
+  # The method processes messages from existing connections. It should parse the message, call either
+  # {Rage::Cable::Router#process_subscription} or {Rage::Cable::Router#process_message}, and handle its return value.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @param raw_data [String] the message body
+  # @see Rage::Cable::Router
+  def self.on_message(connection, raw_data)
+    parsed_data = Rage::ParamsParser.json_parse(raw_data)
+
+    command, identifier = parsed_data[:command], parsed_data[:identifier]
+    params = Rage::ParamsParser.json_parse(identifier)
+
+    # process subscription messages
+    if command == COMMAND::SUBSCRIBE
+      status = @router.process_subscription(connection, identifier, params[:channel], params)
+      if status == :subscribed
+        connection.write({ identifier: identifier, type: TYPE::CONFIRM }.to_json)
+      elsif status == :rejected
+        connection.write({ identifier: identifier, type: TYPE::REJECT }.to_json)
+      elsif status == :invalid
+        connection.write(MESSAGES::INVALID)
+      end
+
+      return
+    end
+
+    # process data messages;
+    # plain `JSON` is used here to conform with the ActionCable API that passes `data` as a Hash with string keys;
+    data = JSON.parse(parsed_data[:data])
+
+    message_status = if command == COMMAND::MESSAGE && data.has_key?("action")
+      @router.process_message(connection, identifier, data["action"].to_sym, data)
+
+    elsif command == COMMAND::MESSAGE
+      @router.process_message(connection, identifier, :receive, data)
+    end
+
+    unless message_status == :processed
+      connection.write(MESSAGES::INVALID)
+    end
+  end
+
+  # The method should process client disconnections and call {Rage::Cable::Router#process_message}.
+  #
+  # @note This method is optional.
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @see Rage::Cable::Router
+  def self.on_close(connection)
+    @router.process_disconnection(connection)
+  end
+
+  # Serialize a Ruby object into the format the client would understand.
+  #
+  # @param params [Hash] parameters associated with the client
+  # @param data [Object] the object to serialize
+  def self.serialize(params, data)
+    { identifier: params.to_json, message: data }.to_json
+  end
+
+  # Subscribe to a stream.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @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)
+  end
+
+  # Broadcast data to all clients connected to a stream.
+  #
+  # @param name [String] the stream name
+  # @param data [Object] the data to send
+  def self.broadcast(name, data)
+    i, identifiers = 0, @subscription_identifiers[name]
+
+    while i < identifiers.length
+      params = identifiers[i]
+      ::Iodine.publish("cable:#{name}:#{params.hash}", serialize(params, data))
+      i += 1
+    end
+  end
+end

data/lib/rage/cable/router.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+class Rage::Cable::Router
+  # @private
+  def initialize
+    # Hash<String(channel name) => Proc(new channel instance)>
+    @channels_map = {}
+    init_connection_class
+  end
+
+  # Calls the `connect` method on the `Connection` class to handle authentication.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @return [true] if the connection was accepted
+  # @return [false] if the connection was rejected
+  def process_connection(connection)
+    cable_connection = @connection_class.new(connection.env)
+    cable_connection.connect
+
+    if cable_connection.rejected?
+      Rage.logger.debug { "An unauthorized connection attempt was rejected" }
+    else
+      connection.env["rage.identified_by"] = cable_connection.__identified_by_map
+      connection.env["rage.cable"] = {}
+    end
+
+    !cable_connection.rejected?
+  end
+
+  # Calls the `subscribed` method on the specified channel.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @param identifier [String] the identifier of the subscription
+  # @param channel_name [String] the name of the channel class
+  # @param params [Hash] the params hash associated with the subscription
+  #
+  # @return [:invalid] if the subscription class does not exist
+  # @return [:rejected] if the subscription was rejected
+  # @return [:subscribed] if the subscription was accepted
+  def process_subscription(connection, identifier, channel_name, params)
+    channel_class = @channels_map[channel_name] || begin
+      begin
+        klass = Object.const_get(channel_name)
+      rescue NameError
+        nil
+      end
+
+      if klass.nil? || !klass.ancestors.include?(Rage::Cable::Channel)
+        Rage.logger.debug { "Subscription class not found: #{channel_name}" }
+        return :invalid
+      end
+
+      klass.__register_actions.tap do |available_actions|
+        Rage.logger.debug { "Compiled #{channel_name}. Available remote actions: #{available_actions}." }
+      end
+
+      @channels_map[channel_name] = klass
+    end
+
+    channel = channel_class.new(connection, params, connection.env["rage.identified_by"])
+    channel.__run_action(:subscribed)
+
+    if channel.subscription_rejected?
+      Rage.logger.debug { "#{channel_name} is transmitting the subscription rejection" }
+      # if the subscription is rejected in the `subscribed` method, ActionCable will additionally run
+      # the `unsubscribed` method; this makes little sense to me as the client was never subscribed in
+      # the first place; additionally, I don't think this behaviour is documented anywhere;
+      # so, I'm going to leave this line commented out for now;
+      # channel.__run_action(:unsubscribed)
+      :rejected
+    else
+      Rage.logger.debug { "#{channel_name} is transmitting the subscription confirmation" }
+      connection.env["rage.cable"][identifier] = channel
+      :subscribed
+    end
+  end
+
+  # Calls the handler method on the specified channel.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  # @param identifier [String] the identifier of the subscription
+  # @param action_name [Symbol] the name of the handler method
+  # @param data [Object] the data sent by the client
+  #
+  # @return [:no_subscription] if the client is not subscribed to the specified channel
+  # @return [:unknown_action] if the action does not exist on the specified channel
+  # @return [:processed] if the message has been successfully processed
+  def process_message(connection, identifier, action_name, data)
+    channel = connection.env["rage.cable"][identifier]
+    unless channel
+      Rage.logger.debug { "Unable to find the subscription" }
+      return :no_subscription
+    end
+
+    if channel.__has_action?(action_name)
+      channel.__run_action(action_name, data)
+      :processed
+    else
+      Rage.logger.debug { "Unable to process #{channel.class.name}##{action_name}" }
+      :unknown_action
+    end
+  end
+
+  # Runs the `unsubscribed` methods on all the channels the client is subscribed to.
+  #
+  # @param connection [Rage::Cable::WebSocketConnection] the connection object
+  def process_disconnection(connection)
+    connection.env["rage.cable"]&.each do |_, channel|
+      channel.__run_action(:unsubscribed)
+    end
+
+    if @connection_can_disconnect
+      cable_connection = @connection_class.new(connection.env, connection.env["rage.identified_by"])
+      cable_connection.disconnect
+    end
+  end
+
+  # @private
+  def reset
+    @channels_map.clear
+    init_connection_class
+  end
+
+  private
+
+  def init_connection_class
+    @connection_class = if Object.const_defined?("RageCable::Connection")
+      RageCable::Connection
+    elsif Object.const_defined?("ApplicationCable::Connection")
+      ApplicationCable::Connection
+    else
+      puts "WARNING: Could not find the RageCable connection class! All connections will be accepted by default."
+      Rage::Cable::Connection
+    end
+
+    @connection_can_disconnect = @connection_class.method_defined?(:disconnect)
+  end
+end

data/lib/rage/code_loader.rb

@@ -30,8 +30,13 @@ class Rage::CodeLoader
 
     @reloading = true
     @loader.reload
+
     Rage.__router.reset_routes
     load("#{Rage.root}/config/routes.rb")
+
+    unless Rage.autoload?(:Cable) # the `Cable` component is loaded
+      Rage::Cable.__router.reset
+    end
   end
 
   # in Rails mode - reset the routes; everything else will be done by Rails
@@ -40,6 +45,10 @@ class Rage::CodeLoader
 
     @reloading = true
     Rage.__router.reset_routes
+
+    unless Rage.autoload?(:Cable) # the `Cable` component is loaded
+      Rage::Cable.__router.reset
+    end
   end
 
   def reloading?

data/lib/rage/configuration.rb

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 
 ##
+# `Rage.configure` can be used to adjust the behavior of your Rage application:
+#
+# ```ruby
+# Rage.configure do
+#   config.logger = Rage::Logger.new(STDOUT)
+#   config.server.workers_count = 2
+# end
+# ```
+#
 # # General Configuration
 #
 # • _config.logger_
@@ -93,6 +102,20 @@
 #
 # > Specifies connection timeout.
 #
+# # Cable Configuration
+#
+# • _config.cable.protocol_
+#
+# > Specifies the protocol the server will use. The only value currently supported is `Rage::Cable::Protocol::ActioncableV1Json`. The client application will need to use [@rails/actioncable](https://www.npmjs.com/package/@rails/actioncable) to talk to the server.
+#
+# • _config.cable.allowed_request_origins_
+#
+# > Restricts the server to only accept requests from specified origins. The origins can be instances of strings or regular expressions, against which a check for the match will be performed.
+#
+# • _config.cable.disable_request_forgery_protection_
+#
+# > Allows requests from any origin.
+#
 # # 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.
@@ -138,6 +161,10 @@ class Rage::Configuration
     @middleware ||= Middleware.new
   end
 
+  def cable
+    @cable ||= Cable.new
+  end
+
   def internal
     @internal ||= Internal.new
   end
@@ -193,6 +220,32 @@ class Rage::Configuration
     end
   end
 
+  class Cable
+    attr_accessor :protocol, :allowed_request_origins, :disable_request_forgery_protection
+
+    def initialize
+      @protocol = Rage::Cable::Protocol::ActioncableV1Json
+      @allowed_request_origins = if Rage.env.development? || Rage.env.test?
+        /localhost/
+      end
+    end
+
+    # @private
+    def middlewares
+      @middlewares ||= begin
+        origin_middleware = if @disable_request_forgery_protection
+          []
+        else
+          [[Rage::OriginValidator, Array(@allowed_request_origins), nil]]
+        end
+
+        origin_middleware + Rage.config.middleware.middlewares.reject do |middleware, _, _|
+          middleware == Rage::FiberWrapper
+        end
+      end
+    end
+  end
+
   # @private
   class Internal
     attr_accessor :rails_mode

data/lib/rage/controller/api.rb

@@ -142,6 +142,7 @@ class RageController::API
 
     # @private
     attr_writer :__before_actions, :__after_actions, :__rescue_handlers
+    # @private
     attr_accessor :__wrap_parameters_key, :__wrap_parameters_options
 
     # @private
@@ -299,14 +300,12 @@ class RageController::API
       @__before_actions[i] = action
     end
 
-    # Initialize controller params wrapping into a nested hash.
-    # If initialized, params wrapping logic will be added to the controller.
-    # Params get wrapped only if the CONTENT_TYPE header is present and params hash doesn't contain a param that
-    # has the same name as the wrapper key.
+    # Wraps the parameters hash into a nested hash. This will allow clients to submit requests without having to specify any root elements.
+    # Params get wrapped only if the `Content-Type` header is present and the `params` hash doesn't contain a param with the same name as the wrapper key.
     #
-    # @param key [Symbol] key that the wrapped params hash will nested under
-    # @param include [Array] array of params that should be included to the wrapped params hash
-    # @param exclude [Array] array of params that should be excluded from the wrapped params hash
+    # @param key [Symbol] the wrapper key
+    # @param include [Symbol, Array<Symbol>] the list of attribute names which parameters wrapper will wrap into a nested hash
+    # @param exclude [Symbol, Array<Symbol>] the list of attribute names which parameters wrapper will exclude from a nested hash
     # @example
     #   wrap_parameters :user, include: %i[name age]
     # @example
@@ -366,13 +365,13 @@ class RageController::API
   # Get the cookie object. See {Rage::Cookies}.
   # @return [Rage::Cookies]
   def cookies
-    @cookies ||= Rage::Cookies.new(@__env, self)
+    @cookies ||= Rage::Cookies.new(@__env, @__headers)
   end
 
   # Get the session object. See {Rage::Session}.
   # @return [Rage::Session]
   def session
-    @session ||= Rage::Session.new(self)
+    @session ||= Rage::Session.new(cookies)
   end
 
   # Send a response to the client.

data/lib/rage/cookies.rb

@@ -14,9 +14,9 @@ end
 
 class Rage::Cookies
   # @private
-  def initialize(env, controller)
+  def initialize(env, headers)
     @env = env
-    @headers = controller.headers
+    @headers = headers
     @request_cookies = {}
     @parsed = false
 

data/lib/rage/middleware/fiber_wrapper.rb

@@ -7,7 +7,9 @@
 class Rage::FiberWrapper
   def initialize(app)
     Iodine.on_state(:on_start) do
-      Fiber.set_scheduler(Rage::FiberScheduler.new)
+      unless Fiber.scheduler
+        Fiber.set_scheduler(Rage::FiberScheduler.new)
+      end
     end
     @app = app
   end

data/lib/rage/middleware/origin_validator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class Rage::OriginValidator
+  def initialize(app, *allowed_origins)
+    @app = app
+    @validator = build_validator(allowed_origins)
+  end
+
+  def call(env)
+    if @validator.call(env)
+      @app.call(env)
+    else
+      Rage.logger.error("Request origin not allowed: #{env["HTTP_ORIGIN"]}")
+      [404, {}, ["Not Found"]]
+    end
+  end
+
+  private
+
+  def build_validator(allowed_origins)
+    if allowed_origins.empty?
+      ->(env) { false }
+    else
+      origins_eval = allowed_origins.map { |origin|
+        origin.is_a?(Regexp) ?
+          "origin =~ /#{origin.source}/.freeze" :
+          "origin == '#{origin}'.freeze"
+      }.join(" || ")
+
+      eval <<-RUBY
+        ->(env) do
+          origin = env["HTTP_ORIGIN".freeze]
+          #{origins_eval}
+        end
+      RUBY
+    end
+  end
+end

data/lib/rage/router/dsl.rb

@@ -17,7 +17,7 @@ class Rage::Router::DSL
   end
 
   ##
-  # This class implements routing logic for your application, providing API similar to Rails.
+  # This class implements routing logic for your application, providing an API similar to Rails.
   #
   # Compared to the Rails router, the most notable difference is that a wildcard segment can only be in the last section of the path and cannot be named.
   # Example:

data/lib/rage/session.rb

@@ -7,8 +7,8 @@ class Rage::Session
   KEY = Rack::RACK_SESSION.to_sym
 
   # @private
-  def initialize(controller)
-    @cookies = controller.cookies.encrypted
+  def initialize(cookies)
+    @cookies = cookies.encrypted
   end
 
   # Writes the value to the session.

data/lib/rage/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rage
-  VERSION = "1.7.0"
+  VERSION = "1.8.0"
 end

data/lib/rage-rb.rb

@@ -7,27 +7,17 @@ require "pathname"
 
 module Rage
   def self.application
-    app = Application.new(__router)
-
-    config.middleware.middlewares.reverse.inject(app) do |next_in_chain, (middleware, args, block)|
-      # in Rails compatibility mode we first check if the middleware is a part of the Rails middleware stack;
-      # if it is - it is expected to be built using `ActionDispatch::MiddlewareStack::Middleware#build`
-      if Rage.config.internal.rails_mode
-        rails_middleware = Rails.application.config.middleware.middlewares.find { |m| m.name == middleware.name }
-      end
-
-      if rails_middleware
-        rails_middleware.build(next_in_chain)
-      else
-        middleware.new(next_in_chain, *args, &block)
-      end
-    end
+    with_middlewares(Application.new(__router), config.middleware.middlewares)
   end
 
   def self.multi_application
     Rage::Router::Util::Cascade.new(application, Rails.application)
   end
 
+  def self.cable
+    Rage::Cable
+  end
+
   def self.routes
     Rage::Router::DSL.new(__router)
   end
@@ -90,6 +80,23 @@ module Rage
     end
   end
 
+  # @private
+  def self.with_middlewares(app, middlewares)
+    middlewares.reverse.inject(app) do |next_in_chain, (middleware, args, block)|
+      # in Rails compatibility mode we first check if the middleware is a part of the Rails middleware stack;
+      # if it is - it is expected to be built using `ActionDispatch::MiddlewareStack::Middleware#build`
+      if Rage.config.internal.rails_mode
+        rails_middleware = Rails.application.config.middleware.middlewares.find { |m| m.name == middleware.name }
+      end
+
+      if rails_middleware
+        rails_middleware.build(next_in_chain)
+      else
+        middleware.new(next_in_chain, *args, &block)
+      end
+    end
+  end
+
   module Router
     module Strategies
     end
@@ -106,6 +113,7 @@ module Rage
 
   autoload :Cookies, "rage/cookies"
   autoload :Session, "rage/session"
+  autoload :Cable, "rage/cable/cable"
 end
 
 module RageController