Add Rage::Deferred

Author: rsamoilov

lib/rage-rb.rb

@@ -22,6 +22,10 @@ def self.openapi
     Rage::OpenAPI
   end
 
+  def self.deferred
+    Rage::Deferred
+  end
+
   def self.routes
     Rage::Router::DSL.new(__router)
   end
@@ -130,6 +134,7 @@ module ActiveRecord
   autoload :Session, "rage/session"
   autoload :Cable, "rage/cable/cable"
   autoload :OpenAPI, "rage/openapi/openapi"
+  autoload :Deferred, "rage/deferred/deferred"
 end
 
 module RageController

lib/rage/code_loader.rb

@@ -22,6 +22,8 @@ def setup
     @loader.enable_reloading if enable_reloading
     @loader.setup
     @loader.eager_load if enable_eager_loading
+
+    configure_components
   end
 
   # in standalone mode - reload the code and the routes
@@ -34,13 +36,7 @@ def 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
-
-    unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
-      Rage::OpenAPI.__reset_data_cache
-    end
+    reload_components
   end
 
   # in Rails mode - reset the routes; everything else will be done by Rails
@@ -50,13 +46,7 @@ def rails_mode_reload
     @reloading = true
     Rage.__router.reset_routes
 
-    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
+    reload_components
   end
 
   def reloading?
@@ -73,4 +63,25 @@ def check_updated!
   ensure
     @last_watched, @last_update_at = current_watched, current_update_at
   end
+
+  private
+
+  def configure_components
+    if Rage.env.development? && (Rage.config.deferred.configured? || Rage.config.deferred.has_default_disk_storage?)
+      # if there's at least one task, `Rage::Deferred` will be automatically loaded in production;
+      # in development, however, eager loading is disabled, and we want to automatically load
+      # the module in case it was explicitly configured or if a disk storage exists
+      Rage::Deferred
+    end
+  end
+
+  def reload_components
+    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
 end

lib/rage/configuration.rb

@@ -145,6 +145,20 @@
 # end
 # > ```
 #
+# # Deferred Configuration
+# • _config.deferred.backend_
+#
+# > Specifies the backend for deferred tasks. Supported values are `:disk`, which uses disk storage, or `nil`, which disables persistence of deferred tasks.
+# > The `:disk` backend accepts the following options:
+# >
+# > - `:path` - the path to the directory where deferred tasks will be stored. Defaults to `storage`.
+# > - `:prefix` - the prefix for the deferred task files. Defaults to `deferred-`.
+# > - `:fsync_frequency` - the frequency of `fsync` calls in seconds. Defaults to `0.5`.
+#
+# > ```ruby
+# config.deferred.backend = :disk, { path: "storage" }
+# > ```
+#
 # # 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.
@@ -208,6 +222,10 @@ def openapi
     @openapi ||= OpenAPI.new
   end
 
+  def deferred
+    @deferred ||= Deferred.new
+  end
+
   def internal
     @internal ||= Internal.new
   end
@@ -347,6 +365,85 @@ class OpenAPI
     attr_accessor :tag_resolver
   end
 
+  class Deferred
+    def initialize
+      @backend_class = Rage::Deferred::Backends::Disk
+      @backend_options = parse_disk_backend_options({})
+
+      @configured = false
+    end
+
+    def backend
+      @backend_class.new(**@backend_options)
+    end
+
+    def backend=(config)
+      @configured = true
+
+      backend_id, opts = if config.is_a?(Array)
+        [config[0], config[1]]
+      else
+        [config, {}]
+      end
+
+      @backend_class = case backend_id
+      when :disk
+        @backend_options = parse_disk_backend_options(opts)
+        Rage::Deferred::Backends::Disk
+      when nil
+        Rage::Deferred::Backends::Nil
+      else
+        raise ArgumentError, "unsupported backend value; supported values are `:disk` and `nil`"
+      end
+    end
+
+    def default_disk_storage_path
+      Pathname.new("storage")
+    end
+
+    def default_disk_storage_prefix
+      "deferred-"
+    end
+
+    def has_default_disk_storage?
+      default_disk_storage_path.glob("#{default_disk_storage_prefix}*").any?
+    end
+
+    def configured?
+      @configured
+    end
+
+    private
+
+    def parse_disk_backend_options(opts)
+      if opts.except(:path, :prefix, :fsync_frequency).any?
+        raise ArgumentError, "unsupported backend options; supported values are `:path`, `:prefix`, `:fsync_frequency`"
+      end
+
+      parsed_options = {}
+
+      parsed_options[:path] = if opts[:path]
+        opts[:path].is_a?(Pathname) ? opts[:path] : Pathname.new(opts[:path])
+      else
+        default_disk_storage_path
+      end
+
+      parsed_options[:prefix] = if opts[:prefix]
+        opts[:prefix].end_with?("-") ? opts[:prefix] : "#{opts[:prefix]}-"
+      else
+        default_disk_storage_prefix
+      end
+
+      parsed_options[:fsync_frequency] = if opts[:fsync_frequency]
+        (opts[:fsync_frequency].to_i * 1_000).round
+      else
+        500
+      end
+
+      parsed_options
+    end
+  end
+
   # @private
   class Internal
     attr_accessor :rails_mode