rage-rb 1.22.1 → 1.24.0

data/lib/rage/configuration.rb

@@ -139,6 +139,52 @@ class Rage::Configuration
   def after_initialize(&block)
     push_hook(block, :after_initialize)
   end
+
+  # Register a custom renderer that generates overloads `render` on all controllers.
+  # The block receives the object passed to `render` together with any additional keyword arguments.
+  # The code inside the block is executed in the context of the controller instance, so you can access all usual controller methods in it.
+  # The return value of the block is used as the response body.
+  #
+  # @param name [Symbol, String] the name of the renderer
+  # @param block [Proc] the rendering logic. The block is executed in the controller's context and its return value becomes the response body
+  # @raise [ArgumentError] if no block is given or if a renderer with the same name is already registered
+  #
+  # @example Register an ERB renderer
+  #   Rage.configure do
+  #     config.renderer(:erb) do |path, trim_mode: nil|
+  #       headers["content-type"] = "text/html"
+  #       template = File.read("app/views/#{path}.html.erb")
+  #
+  #       ERB.new(template, trim_mode:).result(binding)
+  #     end
+  #   end
+  # @example Use in a controller
+  #   class ReportsController < RageController::API
+  #     def index
+  #       render erb: "reports/index"
+  #     end
+  #   end
+  # @example Pass arguments
+  #   class ReportsController < RageController::API
+  #     def index
+  #       render erb: "reports/index", trim_mode: "%<>"
+  #     end
+  #   end
+  # @example Set response status
+  #   class ReportsController < RageController::API
+  #     def index
+  #       render erb: "reports/index", status: 202
+  #     end
+  #   end
+  def renderer(name, &block)
+    @renderers ||= {}
+    raise ArgumentError, "renderer requires a block" unless block_given?
+    name = name.to_sym
+    if @renderers.key?(name)
+      raise ArgumentError, "a renderer named :#{name} is already registered"
+    end
+    @renderers[name] = RendererEntry.new(block)
+  end
   # @!endgroup
 
   # @!group Middleware Configuration
@@ -173,6 +219,14 @@ class Rage::Configuration
   end
   # @!endgroup
 
+  # @!group Error Reporter Configuration
+  # Allows configuring error reporters.
+  # @return [Rage::Configuration::ErrorReporters]
+  def error_reporters
+    @error_reporters ||= ErrorReporters.new
+  end
+  # @!endgroup
+
   # @!group OpenAPI Configuration
   # Allows configuring OpenAPI settings.
   # @return [Rage::Configuration::OpenAPI]
@@ -219,6 +273,19 @@ class Rage::Configuration
   end
   # @!endgroup
 
+  # @!group Router Configuration
+  # Allows configuring router settings.
+  # @return [Rage::Configuration::Router]
+  def router
+    @router ||= Router.new
+  end
+  # @!endgroup
+
+  # @private
+  def pubsub
+    @pubsub ||= PubSub.new
+  end
+
   # @private
   def internal
     @internal ||= Internal.new
@@ -327,6 +394,60 @@ class Rage::Configuration
     end
   end
 
+  class ErrorReporters
+    # @private
+    def initialize
+      @objects = []
+    end
+
+    # @private
+    def objects
+      @objects.dup
+    end
+
+    # Add a new error reporter.
+    # Error reporters should respond to `#call` and accept one of:
+    # - `call(exception)`
+    # - `call(exception, context: {})`
+    #
+    # @param reporter [#call]
+    # @return [self]
+    # @example
+    #   Rage.configure do
+    #     config.error_reporters << SentryReporter.new
+    #   end
+    def <<(reporter)
+      validate_input!(reporter)
+      return self if @objects.include?(reporter)
+
+      @objects << reporter
+      Rage::Errors.__send__(:__register_reporter, reporter)
+
+      self
+    end
+
+    alias_method :push, :<<
+
+    # Remove an error reporter.
+    # @param reporter [#call] the reporter to remove
+    # @example
+    #   reporter = SentryReporter.new
+    #   Rage.configure do
+    #     config.error_reporters.delete(reporter)
+    #   end
+    def delete(reporter)
+      deleted = @objects.delete(reporter)
+      Rage::Errors.__send__(:__unregister_reporter, reporter) if deleted
+      deleted
+    end
+
+    private
+
+    def validate_input!(reporter)
+      raise ArgumentError, "error reporter must respond to #call" unless reporter.respond_to?(:call)
+    end
+  end
+
   class Server
     # @!attribute port
     #   Specify the port the server will listen on.
@@ -581,33 +702,6 @@ class Rage::Configuration
         end
       end
     end
-
-    # @private
-    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
-
-    # @private
-    def adapter_config
-      config.except(:adapter)
-    end
-
-    # @private
-    def adapter
-      case config[:adapter]
-      when "redis"
-        Rage::Cable::Adapters::Redis.new(adapter_config)
-      end
-    end
   end
 
   class PublicFileServer
@@ -656,6 +750,46 @@ class Rage::Configuration
     # @private
     def initialize
       @configured = false
+      @schedule_blocks = []
+    end
+
+    # Schedule a periodic task to run at a fixed interval.
+    # @example
+    #   Rage.configure do
+    #     config.deferred.schedule do
+    #       every 5.minutes, task: ClearCache
+    #     end
+    #   end
+    def schedule(&block)
+      @schedule_blocks << block
+    end
+
+    # @private
+    # Evaluates all stored schedule blocks and returns the collected tasks.
+    # Called at boot time after all app constants are loaded.
+    def scheduled_tasks
+      @schedule_blocks.flat_map do |block|
+        dsl = ScheduleDSL.new
+        dsl.instance_eval(&block)
+        dsl.tasks
+      end
+    end
+
+    # @private
+    class ScheduleDSL
+      attr_reader :tasks
+
+      def initialize
+        @tasks = []
+      end
+
+      # Registers a task to run on a fixed interval (in seconds)
+      def every(interval, task:)
+        unless task.is_a?(Class) && task.include?(Rage::Deferred::Task)
+          raise ArgumentError, "#{task} must be a class that includes Rage::Deferred::Task"
+        end
+        @tasks << { interval:, task: }
+      end
     end
 
     # Returns the backend instance used by `Rage::Deferred`.
@@ -937,6 +1071,49 @@ class Rage::Configuration
     attr_accessor :key
   end
 
+  class Router
+    # @!attribute form_actions
+    #   Enable the automatic generation of `new` and `edit` routes via resource helpers.
+    #   @return [Boolean]
+    #   @example Enable form actions
+    #     Rage.configure do
+    #       config.router.form_actions = true
+    #     end
+    attr_accessor :form_actions
+  end
+
+  # @private
+  class PubSub
+    attr_reader :adapter
+
+    def initialize
+      @adapter = if config.any?
+        case config[:adapter]
+        when "redis"
+          Rage::PubSub::Adapters::Redis.new(adapter_config)
+        end
+      end
+    end
+
+    def config
+      @config ||= begin
+        config_file = Rage.root.join("config/pubsub.yml")
+        config_file = Rage.root.join("config/cable.yml") unless config_file.exist?
+
+        config = if config_file.exist?
+          yaml = ERB.new(config_file.read).result
+          YAML.safe_load(yaml, aliases: true, symbolize_names: true)&.dig(Rage.env.to_sym)
+        end
+
+        config || {}
+      end
+    end
+
+    def adapter_config
+      config.except(:adapter)
+    end
+  end
+
   # @private
   class Internal
     attr_accessor :rails_mode
@@ -999,7 +1176,32 @@ class Rage::Configuration
     end
 
     Rage::Telemetry.__setup(@telemetry.handlers_map) if @telemetry
+
+    __define_custom_renderers if @renderers
+  end
+
+  # @private
+  class RendererEntry
+    attr_reader :block
+
+    def initialize(block)
+      @block = block
+      @applied = false
+    end
+
+    def applied? = @applied
+    def applied! = (@applied = true)
+  end
+  private_constant :RendererEntry
+
+  def __define_custom_renderers
+    @renderers.each do |name, entry|
+      next if entry.applied?
+      RageController::API.__register_renderer(name, entry.block)
+      entry.applied!
+    end
   end
+  private :__define_custom_renderers
 end
 
 # @!parse [ruby]

data/lib/rage/controller/api.rb

@@ -186,29 +186,9 @@ class RageController::API
     end
 
     # @private
-    @@__dynamic_name_seed = ("a".."i").to_a.permutation
-
-    # @private
-    # define a method based on a block
-    def define_dynamic_method(block)
-      name = @@__dynamic_name_seed.next.join
-      define_method("__rage_dynamic_#{name}", block)
-    end
-
-    # @private
-    # define a method that will call a specified method if a condition is `true` or yield if `false`
-    def define_maybe_yield(method_name)
-      name = @@__dynamic_name_seed.next.join
-
-      class_eval <<~RUBY, __FILE__, __LINE__ + 1
-        def __rage_dynamic_#{name}(condition)
-          if condition
-            #{method_name} { yield }
-          else
-            yield
-          end
-        end
-      RUBY
+    def __register_renderer(name, block)
+      prepend(RageController::Renderers) unless ancestors.include?(RageController::Renderers)
+      RageController::Renderers.__register(name, block)
     end
 
     ############
@@ -234,7 +214,7 @@ class RageController::API
     def rescue_from(*klasses, with: nil, &block)
       unless with
         if block_given?
-          with = define_dynamic_method(block)
+          with = Rage::Internal.define_dynamic_method(self, block)
         else
           raise ArgumentError, "No handler provided. Pass the `with` keyword argument or provide a block."
         end
@@ -308,7 +288,7 @@ class RageController::API
     #   end
     def around_action(action_name = nil, **opts, &block)
       action = prepare_action_params(action_name, **opts, &block)
-      action.merge!(around: true, wrapper: define_maybe_yield(action[:name]))
+      action.merge!(around: true, wrapper: Rage::Internal.define_maybe_yield(self, action[:name]))
 
       if @__before_actions && @__before_actions.frozen?
         @__before_actions = @__before_actions.dup
@@ -423,7 +403,7 @@ class RageController::API
     # used by `before_action` and `after_action`
     def prepare_action_params(action_name = nil, **opts, &block)
       if block_given?
-        action_name = define_dynamic_method(block)
+        action_name = Rage::Internal.define_dynamic_method(self, block)
       elsif action_name.nil?
         raise ArgumentError, "No handler provided. Pass the `action_name` parameter or provide a block."
       end
@@ -438,18 +418,21 @@ class RageController::API
         unless: _unless
       }
 
-      action[:if] = define_dynamic_method(action[:if]) if action[:if].is_a?(Proc)
-      action[:unless] = define_dynamic_method(action[:unless]) if action[:unless].is_a?(Proc)
+      action[:if] = Rage::Internal.define_dynamic_method(self, action[:if]) if action[:if].is_a?(Proc)
+      action[:unless] = Rage::Internal.define_dynamic_method(self, action[:unless]) if action[:unless].is_a?(Proc)
 
       action
     end
   end # class << self
 
+  DEFAULT_CONTENT_TYPE = "application/json; charset=utf-8"
+  private_constant :DEFAULT_CONTENT_TYPE
+
   # @private
   def initialize(env, params)
     @__env = env
     @__params = params
-    @__status, @__headers, @__body = 204, { "content-type" => "application/json; charset=utf-8" }, []
+    @__status, @__headers, @__body = 204, { "content-type" => DEFAULT_CONTENT_TYPE }, []
     @__rendered = false
   end
 
@@ -480,10 +463,10 @@ class RageController::API
     @session ||= Rage::Session.new(cookies)
   end
 
-  # Send a response to the client.
+  # Send a response to the client. Keywords corresponding to custom renderers (see {Rage::Configuration#renderer}) will be delegated automatically.
   #
-  # @param json [String, Object] send a json response to the client; objects like arrays will be serialized automatically
-  # @param plain [String] send a text response to the client
+  # @param json [String, #to_json] send a json response to the client; objects will be serialized automatically
+  # @param plain [#to_s] send a text response to the client
   # @param sse [#each, Proc, #to_json] send an SSE response to the client
   # @param status [Integer, Symbol] set a response status
   # @example Render a JSON object
@@ -508,7 +491,8 @@ class RageController::API
       @__body << if json
         json.is_a?(String) ? json : json.to_json
       else
-        @__headers["content-type"] = "text/plain; charset=utf-8"
+        ct = @__headers["content-type"]
+        @__headers["content-type"] = "text/plain; charset=utf-8" if ct.nil? || ct == DEFAULT_CONTENT_TYPE
         plain.to_s
       end
 

data/lib/rage/controller/renderers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+##
+# This module overloads the `render` method on {RageController::API RageController::API} to enable the usage of custom renderers defined using {Rage::Configuration#renderer}.
+#
+module RageController::Renderers
+  # @private
+  def self.prepended(_)
+    @__renderers = {}
+  end
+
+  # @private
+  # rubocop:disable Layout/IndentationWidth, Layout/EndAlignment, Layout/HeredocIndentation
+  def self.__register(name, block)
+    @__renderers[name] = Rage::Internal.define_dynamic_method(self, block)
+
+    render_args = @__renderers.keys.map { |key| "#{key}: nil" }.join(", ")
+
+    class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def render(#{render_args}, status: nil, **)
+        raise "Render was called multiple times in this action." if @__rendered
+
+        active_renderers = []
+        #{@__renderers.keys.map { |key| "active_renderers << :#{key} if #{key}" }.join("\n")}
+
+        return super(status:, **) if active_renderers.empty?
+
+        if active_renderers.size > 1
+          raise Rage::Errors::AmbiguousRenderError, "Only one renderer can be used per 'render' call, but multiple were provided: \#{active_renderers.join(", ")}"
+        end
+
+        result = case active_renderers.first
+          #{@__renderers.map do |renderer_name, method_name|
+            <<~RUBY
+              when :#{renderer_name}
+                #{method_name}(#{renderer_name}, **)
+            RUBY
+          end.join("\n")}
+        end
+
+        return if @__rendered
+        render plain: result.to_s, status: (status || 200)
+      end
+    RUBY
+  end
+  # rubocop:enable all
+end

data/lib/rage/deferred/backends/disk.rb

@@ -44,8 +44,24 @@ class Rage::Deferred::Backends::Disk
       @recovered_storages = storage_files[1..] if storage_files.length > 1
     end
 
-    # create seed value for the task IDs
-    task_id_seed = Time.now.to_i # TODO: ensure timestamps in the file are not higher
+    # include recovered storages from crashed/previous workers
+    all_storages = [@storage, *@recovered_storages].compact
+
+    # find the highest task timestamp across all storage files
+    storage_file_max_timestamp = all_storages.map do |storage|
+      max_timestamp = 0
+      storage.tap(&:rewind).each_line(chomp: true) do |entry|
+        next unless entry[9...12] == "add"
+        timestamp = entry[13..].split("-").first.to_i
+        max_timestamp = timestamp if timestamp > max_timestamp
+      end
+      max_timestamp
+    end.max.to_i
+
+    # apply Lamport IR2(b) From time, clocks and the ordering of
+    # events in a distributed system to guard against clock skew
+    task_id_seed = [Time.now.to_i, storage_file_max_timestamp].max + 1
+
     @task_id_base, @task_id_i = "#{task_id_seed}-#{Process.pid}", 0
     Iodine.run_every(1_000) do
       task_id_seed += 1
@@ -117,7 +133,7 @@ class Rage::Deferred::Backends::Disk
       # `@recovered_storages` will only be present if the server has previously crashed and left
       # some storage files behind, or if the new cluster is started with fewer workers than before;
       # TLDR: this code is expected to execute very rarely
-      @recovered_storages.each { |storage| recover_tasks(storage) }
+      @recovered_storages.each { |storage| recover_tasks(storage.tap(&:rewind)) }
     end
 
     tasks = {}

data/lib/rage/deferred/deferred.rb

@@ -82,10 +82,16 @@ module Rage::Deferred
     )
   end
 
+  # @private
+  def self.__start_scheduler
+    Rage::Deferred::Scheduler.start(Rage.config.deferred.scheduled_tasks)
+  end
+
   # @private
   def self.__initialize
     __middleware_chain
     __load_tasks
+    __start_scheduler
   end
 
   module Backends
@@ -96,6 +102,7 @@ module Rage::Deferred
 end
 
 require_relative "task"
+require_relative "scheduler"
 require_relative "queue"
 require_relative "proxy"
 require_relative "context"

data/lib/rage/deferred/metadata.rb

@@ -27,7 +27,15 @@ class Rage::Deferred::Metadata
     # @return [Boolean] `true` if a failure will schedule another attempt, `false` otherwise
     def will_retry?
       task = Rage::Deferred::Context.get_task(context)
-      task.__should_retry?(attempts)
+      !!task.__next_retry_in(attempts, nil)
+    end
+
+    # Returns the number of seconds until the next retry, or `nil` if no retry will occur.
+    # The result is memoized per attempt so that the value reported here matches what the queue uses to schedule the retry.
+    # @return [Numeric, nil] retry delay in seconds, or `nil` if the task won't be retried
+    def will_retry_in
+      task = Rage::Deferred::Context.get_task(context)
+      task.__next_retry_in(attempts, nil)
     end
 
     private

data/lib/rage/deferred/queue.rb

@@ -38,14 +38,15 @@ class Rage::Deferred::Queue
         Fiber.schedule do
           Iodine.task_inc!
 
-          is_completed = task.new.__perform(context)
+          result = task.new.__perform(context)
 
-          if is_completed
+          if result == true
             @backend.remove(task_id)
           else
             attempts = Rage::Deferred::Context.inc_attempts(context)
-            if task.__should_retry?(attempts)
-              enqueue(context, delay: task.__next_retry_in(attempts), task_id:)
+            retry_in = task.__next_retry_in(attempts, result)
+            if retry_in
+              enqueue(context, delay: retry_in, task_id:)
             else
               @backend.remove(task_id)
             end

data/lib/rage/deferred/scheduler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# @private
+class Rage::Deferred::Scheduler
+  def self.start(tasks)
+    return if tasks.empty?
+
+    Rage::Internal.pick_a_worker(purpose: "deferred-scheduler") do
+      puts("INFO: #{Process.pid} is managing scheduled tasks.") if Rage.logger.info?
+      register_timers(tasks)
+    end
+  end
+
+  def self.register_timers(tasks)
+    tasks.each do |entry|
+      interval = (entry[:interval] * 1000).to_i
+
+      if Rage.env.development?
+        Iodine.run_every(interval) { Object.const_get(entry[:task].name).enqueue }
+      else
+        Iodine.run_every(interval) { entry[:task].enqueue }
+      end
+    end
+  end
+end