maintenance_on_steroids 0.2.0

data/lib/maintenance_on_steroids/engine.rb

@@ -0,0 +1,26 @@
+module MaintenanceOnSteroids
+  class Engine < ::Rails::Engine
+    isolate_namespace MaintenanceOnSteroids
+
+    initializer "maintenance_on_steroids.autoload_tasks", before: :set_autoload_paths do |app|
+      tasks_path = Rails.root.join("app/maintenance")
+      if tasks_path.exist?
+        app.config.autoload_paths += [tasks_path.to_s]
+        app.config.eager_load_paths += [tasks_path.to_s]
+      end
+    end
+
+    # Invalidate the registry on code reload in development so it never
+    # holds stale (unloaded) task class objects.
+    config.to_prepare do
+      MaintenanceOnSteroids::JobRegistry.reset!
+    end
+
+    # Access control is opt-in, so the dangerous configuration is the empty
+    # one -- and HTTP Basic left on its shipped password is the same thing
+    # wearing a badge. See MaintenanceOnSteroids.verify_access_control!.
+    config.after_initialize do
+      MaintenanceOnSteroids.verify_access_control!
+    end
+  end
+end

data/lib/maintenance_on_steroids/form_dsl.rb

@@ -0,0 +1,63 @@
+module MaintenanceOnSteroids
+  module FormDsl
+    extend ActiveSupport::Concern
+
+    class InputDefinition
+      attr_reader :name, :type, :required, :default, :options, :label, :placeholder, :help_text
+
+      def initialize(name, type: :string, required: false, default: nil, options: nil, label: nil, placeholder: nil, help_text: nil)
+        @name        = name.to_sym
+        @type        = type.to_sym
+        @required    = required
+        @default     = default
+        @options     = options
+        @label       = label || name.to_s.humanize
+        @placeholder = placeholder
+        @help_text   = help_text
+      end
+
+      def blob?
+        type == :blob
+      end
+
+      def html_input_type
+        case type
+        when :string   then "text"
+        when :integer  then "number"
+        when :float    then "number"
+        when :boolean  then "checkbox"
+        when :text     then "textarea"
+        when :date     then "date"
+        when :datetime then "datetime-local"
+        when :blob     then "file"
+        when :select   then "select"
+        else "text"
+        end
+      end
+    end
+
+    class FormBuilder
+      attr_reader :inputs
+
+      def initialize
+        @inputs = []
+      end
+
+      def input(name, **options)
+        @inputs << InputDefinition.new(name, **options)
+      end
+    end
+
+    class_methods do
+      def form(&block)
+        builder = FormBuilder.new
+        builder.instance_eval(&block)
+        @form_inputs = builder.inputs
+      end
+
+      def form_inputs
+        @form_inputs || []
+      end
+    end
+  end
+end

data/lib/maintenance_on_steroids/instrumentation.rb

@@ -0,0 +1,33 @@
+module MaintenanceOnSteroids
+  # Emits ActiveSupport::Notifications events for run lifecycle transitions.
+  #
+  #   ActiveSupport::Notifications.subscribe("enqueued.maintenance_on_steroids") do |event|
+  #     run = event.payload[:run]
+  #     Rails.logger.info "Enqueued #{event.payload[:task_name]} (run ##{run.id})"
+  #   end
+  #
+  # Events: enqueued, started, paused, resumed, cancelled, succeeded, errored.
+  # Payload: { run:, task_name: } plus { error: } for errored.
+  module Instrumentation
+    NAMESPACE = "maintenance_on_steroids"
+
+    def self.instrument(event, run, extra = {})
+      ActiveSupport::Notifications.instrument(
+        "#{event}.#{NAMESPACE}",
+        { run: run, task_name: run.task_class }.merge(extra)
+      )
+    end
+
+    # Best-effort instrumentation: AS::Notifications re-raises subscriber
+    # exceptions, so every lifecycle call routes through here. A raising
+    # subscriber must never affect run outcomes (corrupt status, 500 a
+    # controller, trigger a retry storm) -- the error is logged and swallowed.
+    # See docs/solutions/runtime-errors/unguarded-instrumentation-corrupts-run-status-2026-06-15.md
+    def self.safe_instrument(event, run, extra = {})
+      instrument(event, run, extra)
+    rescue => e
+      Rails.logger.error "[MaintenanceOnSteroids] Instrumentation error (#{event}): " \
+                         "#{e.class}: #{e.message}\n#{e.backtrace&.first(3)&.join("\n")}"
+    end
+  end
+end

data/lib/maintenance_on_steroids/job_dsl.rb

@@ -0,0 +1,61 @@
+module MaintenanceOnSteroids
+  module JobDsl
+    extend ActiveSupport::Concern
+
+    class JobConfig
+      attr_reader :queue_name
+
+      def initialize
+        @queue_name     = nil
+        @priority       = nil
+        @database_role  = nil
+        @concurrency    = nil
+      end
+
+      def queue(name)
+        @queue_name = name.to_s
+      end
+
+      # Acts as both DSL setter (priority 10) and reader (config.priority).
+      def priority(value = :__unset__)
+        return @priority if value == :__unset__
+
+        @priority = value
+      end
+
+      # Maximum number of runs of this task that may be active at once.
+      # `concurrency 1` is the usual choice for a destructive task: without it
+      # a double-click on New Run happily starts the same migration twice.
+      # nil (the default) means unlimited. Acts as setter and reader.
+      def concurrency(value = :__unset__)
+        return @concurrency if value == :__unset__
+
+        @concurrency = value&.to_i
+      end
+
+      # Database role the collection is read under, e.g. `database_role :reading`
+      # to scan a replica. Declared rather than block-scoped because a
+      # `collection` is a lazy Relation: wrapping the method body in
+      # connected_to switches back before the query ever runs. RunJob holds the
+      # role open for the whole scan instead, and runs `process` plus its own
+      # bookkeeping under :writing. Acts as setter and reader.
+      def database_role(value = :__unset__)
+        return @database_role if value == :__unset__
+
+        @database_role = MaintenanceOnSteroids::Task.normalize_database_role(value)
+      end
+    end
+
+    class_methods do
+      def job(&block)
+        config = JobConfig.new
+        config.instance_eval(&block)
+        @job_config = config
+      end
+
+      def job_config
+        @job_config || JobConfig.new
+      end
+    end
+  end
+end

data/lib/maintenance_on_steroids/job_registry.rb

@@ -0,0 +1,83 @@
+module MaintenanceOnSteroids
+  module JobRegistry
+    LOAD_MUTEX = Mutex.new
+
+    class << self
+      def register(task_class)
+        registry[task_class.name] = task_class
+      end
+
+      def unregister(task_class_name)
+        registry.delete(task_class_name)
+      end
+
+      def tasks
+        load_all!
+        registry.values.sort_by(&:name)
+      end
+
+      # Resolves a task class by name.
+      #
+      # Only returns registered tasks or already-loaded Task descendants.
+      # Request and persisted names never trigger arbitrary constant loading.
+      def find(class_name)
+        load_all!
+        class_name = class_name.to_s
+        return registry[class_name] if registry.key?(class_name)
+
+        # Never constantize request or persisted input. Descendants also cover
+        # tasks defined outside app/maintenance without loading arbitrary constants.
+        MaintenanceOnSteroids::Task.descendants.find do |klass|
+          klass.name == class_name && klass.name.safe_constantize.equal?(klass)
+        end
+      end
+
+      def load_all!
+        return if @loaded
+
+        LOAD_MUTEX.synchronize do
+          return if @loaded
+
+          begin
+            tasks_path = Rails.root.join("app/maintenance")
+            if tasks_path.exist?
+              Rails.autoloaders.main.eager_load_dir(tasks_path.to_s)
+            end
+          rescue => e
+            Rails.logger.warn "[MaintenanceOnSteroids] Failed to eager load tasks: #{e.message}"
+          end
+
+          # eager_load_dir is a no-op for constants Zeitwerk already loaded,
+          # so after a reset! (tests, code reload) the inherited-hook
+          # registrations are gone. Sweep descendants to re-register them.
+          #
+          # Only classes their own constant still resolves to: a class keeps the
+          # name it was first assigned even after the constant is removed or
+          # rebound, and it stays in descendants either way. Registering those
+          # blindly makes the dashboard list ghost tasks -- stale copies after a
+          # code reload in development, and every stubbed class a test ever
+          # defined.
+          MaintenanceOnSteroids::Task.descendants.each do |klass|
+            next if klass.name.blank?
+            next unless klass.name.safe_constantize.equal?(klass)
+
+            register(klass)
+          end
+
+          @loaded = true
+        end
+      end
+
+      def reset!
+        @loaded = false
+        @registry = {}
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end

data/lib/maintenance_on_steroids/jsonb_artifact.rb

@@ -0,0 +1,39 @@
+module MaintenanceOnSteroids
+  class JsonbArtifact < HashWithIndifferentAccess
+    # Accepts either an Artifact record (normal construction) or a plain
+    # hash. HashWithIndifferentAccess internals (dup/merge/except/...) build
+    # copies via `self.class.new(hash)`, so the hash form must be supported.
+    # Such copies are "detached": they behave like hashes but cannot save!.
+    def initialize(record_or_hash = {})
+      if record_or_hash.respond_to?(:data_jsonb)
+        @_record = record_or_hash
+        super(record_or_hash.data_jsonb || {})
+      else
+        @_record = nil
+        super(record_or_hash || {})
+      end
+    end
+
+    def save!
+      unless @_record
+        raise "Cannot save! a detached JsonbArtifact copy (created via dup/merge/except). Save the original artifact instead."
+      end
+
+      @_record.data_jsonb = to_h
+      @_record.refresh_metadata!
+      @_record.save!
+    end
+
+    # True when the in-memory contents differ from what's persisted (or from
+    # the lazy default for an unsaved record). Lets the proxy auto-flush only
+    # artifacts that were actually written, avoiding phantom rows for reads.
+    def dirty?
+      return false unless @_record
+      to_h != (@_record.data_jsonb || {})
+    end
+
+    def record
+      @_record
+    end
+  end
+end

data/lib/maintenance_on_steroids/params_proxy.rb

@@ -0,0 +1,93 @@
+module MaintenanceOnSteroids
+  class ParamsProxy
+    def initialize(run, form_inputs)
+      @run = run
+      @form_inputs = form_inputs.index_by(&:name)
+      @scalar_data = (run.params || {}).with_indifferent_access
+      @blob_cache = {}
+    end
+
+    def [](key)
+      key = key.to_sym
+      input = @form_inputs[key]
+
+      if input&.blob?
+        input_artifact(key)&.data_blob
+      else
+        value = @scalar_data[key]
+        value = input.default if value.nil? && input
+        cast_value(value, input&.type)
+      end
+    end
+
+    # Original filename of an uploaded file input (nil if none uploaded, or if
+    # the key isn't a declared blob input -- scalar inputs have no input
+    # artifact, so don't waste a query looking one up).
+    def file_name(key)
+      return nil unless @form_inputs[key.to_sym]&.blob?
+
+      input_artifact(key)&.file_name
+    end
+
+    # Declared MIME type of an uploaded file input (nil if none uploaded, or if
+    # the key isn't a declared blob input).
+    def content_type(key)
+      return nil unless @form_inputs[key.to_sym]&.blob?
+
+      input_artifact(key)&.content_type
+    end
+
+    def to_h
+      @scalar_data.to_h
+    end
+
+    def fetch(key, *args, &block)
+      value = self[key]
+      return value unless value.nil?
+
+      if args.any?
+        args.first
+      elsif block
+        block.call
+      else
+        raise KeyError, "key not found: #{key}"
+      end
+    end
+
+    private
+
+    # The "input" artifact backing a file input, looked up once and cached
+    # (including a nil result, so a missing upload isn't re-queried).
+    def input_artifact(key)
+      key = key.to_sym
+      return @blob_cache[key] if @blob_cache.key?(key)
+
+      @blob_cache[key] = @run.artifacts.find_by(name: key.to_s, kind: "input")
+    end
+
+    def cast_value(value, type)
+      return value if value.nil?
+
+      case type
+      when :integer  then value.to_i
+      when :float    then value.to_f
+      when :boolean  then ActiveModel::Type::Boolean.new.cast(value)
+      when :date     then parse_date(value)
+      when :datetime then parse_datetime(value)
+      else value
+      end
+    end
+
+    def parse_date(value)
+      value.is_a?(Date) ? value : Date.parse(value.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def parse_datetime(value)
+      value.is_a?(Time) ? value : Time.zone.parse(value.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+end

data/lib/maintenance_on_steroids/task.rb

@@ -0,0 +1,109 @@
+module MaintenanceOnSteroids
+  class Task
+    include FormDsl
+    include ArtifactDsl
+    include JobDsl
+    include AboutDsl
+    include CallbacksDsl
+
+    attr_accessor :run
+
+    def self.inherited(subclass)
+      super
+      JobRegistry.register(subclass) if subclass.name
+    end
+
+    def initialize(run = nil)
+      @run = run
+    end
+
+    # Set by RunJob so a task can honour pause/cancel mid-work.
+    attr_writer :checkpoint_handler
+
+    # Honour a pending pause or cancel at this point.
+    #
+    # A collection task gets this for free between records. A callable task is
+    # a single Continuable step, so without an explicit call here a long-running
+    # `call` ignores Pause until it returns. Sprinkle it through the slow parts:
+    #
+    #   def call
+    #     Account.find_each do |account|
+    #       checkpoint!
+    #       account.recalculate!
+    #     end
+    #   end
+    #
+    # When a stop is pending this does not return -- the job unwinds and the
+    # run lands in "paused" or "cancelled". Callable checkpoints also flush
+    # output and refresh the heartbeat; they do not persist a position in call.
+    # No-op outside a job.
+    def checkpoint!
+      @checkpoint_handler&.call
+    end
+
+    # Access typed form parameters
+    def params
+      @params_proxy ||= ParamsProxy.new(@run, self.class.form_inputs)
+    end
+
+    # Access artifacts (read/write)
+    def artifacts
+      @artifacts_proxy ||= ArtifactsProxy.new(@run, self.class.artifact_definitions)
+    end
+
+    # Maps the friendly :read/:write aliases onto Active Record's role names.
+    def self.normalize_database_role(role)
+      case role.to_sym
+      when :read, :reading  then :reading
+      when :write, :writing then :writing
+      else role.to_sym
+      end
+    end
+
+    # Switch database role for the block.
+    # Usage: with_database_role(:read) { User.where(active: true).count }
+    #
+    # The block must force whatever it reads. Returning a lazy Relation from
+    # here does nothing -- the role is restored on the way out and the query
+    # runs later on the primary. To scan a `collection` against a replica,
+    # declare it instead so RunJob can hold the role open for the whole scan:
+    #
+    #   job { database_role :reading }
+    def with_database_role(role, &block)
+      ActiveRecord::Base.connected_to(role: self.class.normalize_database_role(role), &block)
+    end
+
+    # Override in subclass: return an ActiveRecord::Relation for batch processing
+    # def collection
+    #   User.where(active: true)
+    # end
+
+    # Override in subclass: process a single record from collection
+    # def process(record)
+    #   record.update!(...)
+    # end
+
+    # Override in subclass: for one-off tasks (no collection)
+    # def call
+    #   SomeService.run
+    # end
+
+    def collection_task?
+      respond_to?(:collection) && respond_to?(:process)
+    end
+
+    def callable_task?
+      respond_to?(:call)
+    end
+
+    def task_type
+      if collection_task?
+        :collection
+      elsif callable_task?
+        :callable
+      else
+        raise "Task must define either collection+process or call"
+      end
+    end
+  end
+end

data/lib/maintenance_on_steroids/text_artifact.rb

@@ -0,0 +1,74 @@
+module MaintenanceOnSteroids
+  class TextArtifact
+    attr_reader :record
+
+    delegate :to_s, to: :value
+
+    def initialize(record)
+      @record = record
+      # dup so `<<`/`puts` don't mutate the record's own attribute string in
+      # place (that would make dirty? always false and corrupt the record).
+      @value = (record.data_text || "").dup
+    end
+
+    def value
+      @value
+    end
+
+    # Append text
+    def <<(text)
+      text = text.to_s
+      @record.check_buffer_size!(@value.bytesize + text.bytesize)
+      @value << text
+      self
+    end
+
+    # Append a line (adds newline)
+    def puts(text = "")
+      self << "#{text}\n"
+    end
+
+    # Replace all text
+    def replace(text)
+      @record.check_buffer_size!(text.to_s.bytesize)
+      @value = text.to_s
+      self
+    end
+
+    def save!
+      @record.data_text = @value
+      @record.refresh_metadata!
+      @record.save!
+    end
+
+    # True when buffered text differs from what's persisted. Lets the proxy
+    # auto-flush only artifacts that were actually written.
+    def dirty?
+      @value != (@record.data_text || "")
+    end
+
+    def blank?
+      @value.blank?
+    end
+
+    def present?
+      @value.present?
+    end
+
+    def length
+      @value.length
+    end
+
+    def ==(other)
+      case other
+      when TextArtifact then @value == other.value
+      when String then @value == other
+      else false
+      end
+    end
+
+    def inspect
+      "#<TextArtifact #{@value.truncate(60).inspect}>"
+    end
+  end
+end

data/lib/maintenance_on_steroids/version.rb

@@ -0,0 +1,3 @@
+module MaintenanceOnSteroids
+  VERSION = "0.2.0"
+end