maintenance_on_steroids 0.2.0

data/lib/generators/maintenance_on_steroids/install/install_generator.rb

@@ -0,0 +1,56 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module MaintenanceOnSteroids
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the migration and initializer for MaintenanceOnSteroids and mounts the engine."
+
+      def create_migration_file
+        migration_template(
+          "create_maintenance_on_steroids_tables.rb.erb",
+          "db/migrate/create_maintenance_on_steroids_tables.rb"
+        )
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/maintenance_on_steroids.rb"
+      end
+
+      def create_maintenance_directory
+        empty_directory "app/maintenance"
+        create_file "app/maintenance/.keep"
+      end
+
+      def mount_engine
+        route 'mount MaintenanceOnSteroids::Engine, at: "/maintenance"'
+      end
+
+      def show_post_install
+        say ""
+        say "MaintenanceOnSteroids installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run migrations: rails db:migrate"
+        say "  2. Configure access control in config/initializers/maintenance_on_steroids.rb"
+        say "  3. Create tasks in app/maintenance/"
+        say "  4. Visit /maintenance in your browser"
+        say ""
+        say "The dashboard is mounted WITHOUT access control until you configure it,", :yellow
+        say "and it can start any task against your database. In production the engine", :yellow
+        say "refuses to boot until one layer is set (or allow_insecure_dashboard = true).", :yellow
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/generators/maintenance_on_steroids/install/templates/create_maintenance_on_steroids_tables.rb.erb

@@ -0,0 +1,56 @@
+class CreateMaintenanceOnSteroidsTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :maintenance_on_steroids_runs do |t|
+      t.string  :task_class,       null: false
+      t.string  :status,           null: false, default: "enqueued"
+      t.public_send(json_type, :params, default: {})
+      t.string  :cursor
+      t.integer :progress_current, null: false, default: 0
+      t.integer :progress_total,   null: false, default: 0
+      t.text    :error_message
+      t.text    :error_backtrace
+      t.string  :active_job_id
+      t.string  :execution_token
+      t.string  :user_id
+      t.string  :user_type
+      t.string  :user_email
+
+      t.datetime :started_at
+      t.datetime :completed_at
+      t.timestamps
+    end
+
+    add_index :maintenance_on_steroids_runs, :task_class
+    add_index :maintenance_on_steroids_runs, :status
+    add_index :maintenance_on_steroids_runs, :created_at
+    add_index :maintenance_on_steroids_runs, [:task_class, :status]
+    add_index :maintenance_on_steroids_runs, [:task_class, :created_at]
+
+    create_table :maintenance_on_steroids_artifacts do |t|
+      t.references :run, null: false, foreign_key: { to_table: :maintenance_on_steroids_runs }
+
+      t.string  :name,          null: false
+      t.string  :kind,          null: false, default: "output"
+      t.string  :artifact_type, null: false, default: "jsonb"
+      t.public_send(json_type, :data_jsonb)
+      t.binary  :data_blob
+      t.text    :data_text
+      t.string  :file_name
+      t.string  :content_type
+      t.public_send(json_type, :metadata, default: {})
+
+      t.timestamps
+    end
+
+    add_index :maintenance_on_steroids_artifacts, [:run_id, :name, :kind], unique: true, name: "idx_mos_artifacts_run_name_kind"
+  end
+
+  private
+
+  # jsonb on PostgreSQL: it is the indexable, canonical form, and the columns
+  # are named for it. Resolved at migrate time rather than generate time, so
+  # the same migration is correct wherever it runs. Everything else gets json.
+  def json_type
+    connection.adapter_name.match?(/postgres/i) ? :jsonb : :json
+  end
+end

data/lib/generators/maintenance_on_steroids/install/templates/initializer.rb

@@ -0,0 +1,42 @@
+# Maintenance on Steroids
+#
+# The dashboard can start any task in app/maintenance/ against this database,
+# so it needs access control before it goes anywhere near production. Configure
+# at least one of the layers below -- in production the engine refuses to boot
+# until you do.
+
+MaintenanceOnSteroids.configure do |config|
+  # --- Access control (pick at least one) -------------------------------
+
+  # 1. HTTP Basic. Simplest option. The shipped password does NOT count as
+  #    configured -- change it, and keep it out of version control.
+  # config.http_basic_authentication_enabled   = true
+  # config.http_basic_authentication_user_name = "admin"
+  # config.http_basic_authentication_password  = Rails.application.credentials.maintenance_password
+
+  # 2. Your app's own authentication. instance_exec'd in the controller, so
+  #    Devise/Warden helpers are available.
+  # config.authentication = -> { authenticate_user! }
+
+  # 3. Authorization. Runs after the two above; returning false renders 403.
+  #    An `authentication` hook alone only proves *who* the user is.
+  # config.verify_access_proc = ->(controller) { controller.current_user&.admin? }
+
+  # Already gated elsewhere (reverse proxy, VPN, middleware)? Say so
+  # explicitly instead of leaving the layers above empty.
+  # config.allow_insecure_dashboard = true
+
+  # --- Optional ---------------------------------------------------------
+
+  # Who triggered a run; must respond to #id (and optionally #email).
+  # config.current_user_resolver = -> { Current.user }
+
+  # How that user is displayed in the UI.
+  # config.user_display_formatter = ->(run) { run.user_email }
+
+  # Max size for file inputs uploaded when starting a run (read into memory).
+  # config.max_upload_size = 50 * 1024 * 1024
+
+  # Base controller for the engine's controllers, resolved at load time.
+  # config.parent_controller = "ApplicationController"
+end

data/lib/generators/maintenance_on_steroids/job/job_generator.rb

@@ -0,0 +1,17 @@
+require "rails/generators"
+
+module MaintenanceOnSteroids
+  module Generators
+    class JobGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a new MaintenanceOnSteroids task in app/maintenance/"
+
+      class_option :collection, type: :boolean, default: true, desc: "Generate a collection-based task"
+
+      def create_task_file
+        template "job.rb.erb", "app/maintenance/#{file_name}.rb"
+      end
+    end
+  end
+end

data/lib/generators/maintenance_on_steroids/job/templates/job.rb.erb

@@ -0,0 +1,30 @@
+class <%= class_name %> < MaintenanceOnSteroids::Task
+  about do
+    title "<%= class_name.titleize %>"
+    description "TODO: Add description"
+  end
+
+<% if options[:collection] %>
+  # form do
+  #   input :name, type: :string, required: true
+  # end
+
+  # artifact :result, type: :jsonb, default: {}
+
+  def collection
+    # Return an ActiveRecord::Relation
+    # Example: User.where(active: true)
+    raise NotImplementedError, "Define the collection to process"
+  end
+
+  def process(record)
+    # Process a single record from the collection
+    raise NotImplementedError, "Define how to process each record"
+  end
+<% else %>
+  def call
+    # Implement your one-off task here
+    raise NotImplementedError, "Define the task logic"
+  end
+<% end %>
+end

data/lib/maintenance_on_steroids/about_dsl.rb

@@ -0,0 +1,51 @@
+module MaintenanceOnSteroids
+  module AboutDsl
+    extend ActiveSupport::Concern
+
+    class AboutConfig
+      attr_reader :title_text, :description_text, :owner_text
+
+      def initialize
+        @title_text       = nil
+        @description_text = nil
+        @owner_text       = nil
+      end
+
+      def title(value)
+        @title_text = value
+      end
+
+      def description(value)
+        @description_text = value
+      end
+
+      def owner(value)
+        @owner_text = value
+      end
+    end
+
+    class_methods do
+      def about(&block)
+        config = AboutConfig.new
+        config.instance_eval(&block)
+        @about_config = config
+      end
+
+      def about_config
+        @about_config || AboutConfig.new
+      end
+
+      def task_title
+        about_config.title_text || name.demodulize.titleize
+      end
+
+      def task_description
+        about_config.description_text
+      end
+
+      def task_owner
+        about_config.owner_text
+      end
+    end
+  end
+end

data/lib/maintenance_on_steroids/artifact_dsl.rb

@@ -0,0 +1,82 @@
+require "rack/mime"
+
+module MaintenanceOnSteroids
+  module ArtifactDsl
+    extend ActiveSupport::Concern
+
+    class ArtifactDefinition
+      VALID_TYPES = %i[jsonb file text csv].freeze
+
+      # Names that would collide with real ArtifactsProxy methods, breaking
+      # method-style access (`artifacts.<name>`). Derived from the proxy's own
+      # public methods (minus the `[]`/`[]=` operators, which can't be artifact
+      # names) so the guard can't drift as proxy methods are added or renamed.
+      def self.reserved_names
+        # Memoized: ArtifactsProxy is loaded before any task class declares an
+        # artifact (see lib/maintenance_on_steroids.rb require order), so this
+        # reflects once per process instead of on every `artifact :name`.
+        @reserved_names ||= ArtifactsProxy.public_instance_methods(false) - %i([] []=)
+      end
+
+      attr_reader :name, :type, :default, :file_name, :label, :description, :headers, :content_type
+
+      def initialize(name, type: :jsonb, default: nil, file_name: nil, label: nil,
+                     description: nil, headers: nil, content_type: nil)
+        @name = name.to_sym
+        @type = type.to_sym
+        unless VALID_TYPES.include?(@type)
+          raise ArgumentError,
+                "Unknown artifact type #{@type.inspect} for artifact #{@name.inspect}. " \
+                "Valid types: #{VALID_TYPES.join(', ')}"
+        end
+        if self.class.reserved_names.include?(@name)
+          raise ArgumentError,
+                "Artifact name #{@name.inspect} is reserved (conflicts with ArtifactsProxy##{@name}). " \
+                "Choose a different name."
+        end
+
+        @default      = default
+        @file_name    = file_name
+        @label        = label || name.to_s.humanize
+        @description  = description
+        @headers      = headers
+        @content_type = content_type
+      end
+
+      # DB artifact_type / which data_* column the value is stored in.
+      # :file is a friendly alias for binary blob storage; :csv keeps a
+      # distinct artifact_type (its bytes live in data_blob) so the UI can
+      # offer a table preview and a correctly-typed download.
+      def storage_type
+        type == :file ? :blob : type
+      end
+
+      # Resolved MIME type for downloads: explicit content_type wins, then
+      # inference from the file name extension, then a per-type default.
+      def resolved_content_type(fallback_file_name = nil)
+        return @content_type if @content_type.present?
+
+        name = file_name || fallback_file_name
+        return "text/csv" if type == :csv && name.blank?
+        return nil if name.blank?
+
+        Rack::Mime.mime_type(::File.extname(name), nil)
+      end
+
+      def default_file_name
+        type == :csv ? "#{name}.csv" : nil
+      end
+    end
+
+    class_methods do
+      def artifact(name, **options)
+        @artifact_definitions ||= []
+        @artifact_definitions << ArtifactDefinition.new(name, **options)
+      end
+
+      def artifact_definitions
+        @artifact_definitions || []
+      end
+    end
+  end
+end

data/lib/maintenance_on_steroids/artifacts_proxy.rb

@@ -0,0 +1,205 @@
+module MaintenanceOnSteroids
+  class ArtifactsProxy
+    def initialize(run, artifact_definitions)
+      @run = run
+      @definitions = artifact_definitions.index_by(&:name)
+      @cache = {}
+    end
+
+    def [](name)
+      name = name.to_sym
+      # key? rather than ||= : a :blob artifact wraps to the raw data_blob,
+      # which is nil until something is written, and ||= would re-run the
+      # find_by on every read -- once per record inside a collection task.
+      return @cache[name] if @cache.key?(name)
+
+      @cache[name] = load_artifact(name)
+    end
+
+    # Explicit, immediate persist of a full artifact value -- the primary write
+    # API. The type is taken from the artifact declaration, so one call covers
+    # every kind:
+    #   artifacts.save(:json_data, { name: "Igor", age: 40 })  # jsonb
+    #   artifacts.save(:export, rows)                           # csv (rows array or String)
+    #   artifacts.save(:log, "done")                            # text
+    # Returns the stored artifact wrapper. No auto-flush involved -- the write
+    # happens now. (`artifacts[name] = value` is an alias.)
+    def save(name, value)
+      write_and_persist(name, value)
+    end
+
+    def []=(name, value)
+      write_and_persist(name, value)
+      value
+    end
+
+    def save!(name)
+      name = name.to_sym
+      cached = @cache[name]
+      cached.save! if cached.respond_to?(:save!)
+    end
+
+    def save_all!
+      @cache.each_key { |name| save!(name) }
+    end
+
+    # Persists only artifacts whose in-memory contents were actually written
+    # (dirty), so merely reading an artifact never creates a phantom row.
+    # Called automatically by RunJob at completion and on pause/cancel.
+    def flush!
+      failure = nil
+      @cache.each_pair do |name, cached|
+        next unless cached.respond_to?(:dirty?) && cached.dirty?
+
+        begin
+          cached.save!
+        rescue => e
+          failure ||= e
+          # One artifact failing to persist must not strand the others -- log
+          # the declared name (always available) and keep flushing the rest.
+          Rails.logger.error "[MaintenanceOnSteroids] Artifact flush error (#{name}): #{e.class}: #{e.message}"
+        end
+      end
+      raise failure if failure
+    end
+
+    # Drop uncommitted buffers after a record/checkpoint transaction failed.
+    def discard!
+      @cache.clear
+    end
+
+    # Method-style access for declared artifacts so call sites read naturally:
+    #   artifacts.report << row      # instead of artifacts[:report] << row
+    #   artifacts.result["k"] = v
+    #   artifacts.summary = "..."
+    def method_missing(method, *args)
+      key = method.to_s.chomp("=").to_sym
+      return super unless @definitions.key?(key)
+
+      if method.to_s.end_with?("=")
+        self[key] = args.first
+      else
+        self[key]
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @definitions.key?(method.to_s.chomp("=").to_sym) || super
+    end
+
+    private
+
+    # Shared write path for save / []=: write the value into the record,
+    # persist immediately, and cache the wrapper. Handles the concurrent-create
+    # race on the unique (run_id, name, kind) index.
+    def write_and_persist(name, value)
+      name = name.to_sym
+      definition = @definitions[name]
+      raise ArgumentError, "Unknown artifact: #{name}" unless definition
+
+      record = find_or_create_record(name, definition)
+      write_value(record, definition, value)
+      record.refresh_metadata!
+      begin
+        record.save!
+      rescue ActiveRecord::RecordNotUnique
+        # A concurrent writer created the row first (unique index on
+        # run_id/name/kind) -- write into the existing record instead.
+        record = @run.artifacts.find_by!(name: name.to_s, kind: "output")
+        record.worker_token = @run.worker_token
+        record.artifact_type = definition.storage_type.to_s
+        write_value(record, definition, value)
+        record.refresh_metadata!
+        record.save!
+      end
+      @cache[name] = wrap(record, definition)
+    end
+
+    def load_artifact(name)
+      definition = @definitions[name]
+      return nil unless definition
+
+      storage = definition.storage_type
+
+      # Reads must not INSERT: build the record lazily and persist it only
+      # on first save! / assignment. (update! on a new record saves it.)
+      record = @run.artifacts.find_by(name: name.to_s, kind: "output")
+      record ||= build_record(name, definition, storage)
+      record.worker_token = @run.worker_token
+
+      wrap(record, definition)
+    end
+
+    def build_record(name, definition, storage)
+      record = @run.artifacts.new(
+        name: name.to_s,
+        kind: "output",
+        artifact_type: storage.to_s,
+        data_jsonb: storage == :jsonb ? (definition.default || {}) : nil,
+        data_text: storage == :text ? (definition.default || "") : nil,
+        data_blob: %i[blob csv].include?(storage) ? definition.default : nil,
+        file_name: definition.file_name || definition.default_file_name
+      )
+      record.content_type = definition.resolved_content_type if storage == :csv
+      record
+    end
+
+    def find_or_create_record(name, definition)
+      @run.artifacts.find_or_initialize_by(name: name.to_s, kind: "output").tap do |r|
+        r.artifact_type = definition.storage_type.to_s
+        r.worker_token = @run.worker_token
+      end
+    end
+
+    def write_value(record, definition, value)
+      case definition.storage_type
+      when :jsonb
+        record.data_jsonb = value.is_a?(Hash) ? value : { value: value }
+      when :blob
+        if value.respond_to?(:read)
+          record.data_blob = value.read
+          record.file_name ||= value.original_filename if value.respond_to?(:original_filename)
+          record.content_type = value.content_type if value.respond_to?(:content_type)
+        else
+          record.data_blob = value
+        end
+        # Set file_name: explicit from DSL > already set > auto-generated default
+        record.file_name ||= definition.file_name || default_file_name
+        record.content_type ||= definition.resolved_content_type(record.file_name)
+      when :csv
+        record.data_blob = value.is_a?(String) ? value : render_csv(definition, value)
+        record.file_name   ||= definition.file_name || definition.default_file_name
+        record.content_type ||= definition.resolved_content_type || "text/csv"
+      when :text
+        record.data_text = value.to_s
+      end
+    end
+
+    def render_csv(definition, rows)
+      require "csv"
+      CSV.generate do |csv|
+        csv << definition.headers if definition.headers
+        Array(rows).each { |row| csv << Array(row) }
+      end
+    end
+
+    def wrap(record, definition)
+      case definition.storage_type
+      when :jsonb
+        JsonbArtifact.new(record)
+      when :text
+        TextArtifact.new(record)
+      when :csv
+        CsvArtifact.new(record, headers: definition.headers)
+      when :blob
+        record.data_blob
+      end
+    end
+
+    def default_file_name
+      task_class = @run.task_class.to_s.underscore.gsub("/", "_")
+      timestamp = Time.current.strftime("%Y%m%d_%H%M%S")
+      "#{task_class}_#{timestamp}"
+    end
+  end
+end

data/lib/maintenance_on_steroids/callbacks_dsl.rb

@@ -0,0 +1,61 @@
+module MaintenanceOnSteroids
+  module CallbacksDsl
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveSupport::Callbacks
+
+      define_callbacks :start, :pause, :interrupt, :cancel, :complete, :error
+    end
+
+    class_methods do
+      def after_start(*methods, &block)
+        set_callback(:start, :after, *methods, &block)
+      end
+
+      def after_pause(*methods, &block)
+        set_callback(:pause, :after, *methods, &block)
+      end
+
+      def after_interrupt(*methods, &block)
+        set_callback(:interrupt, :after, *methods, &block)
+      end
+
+      def after_cancel(*methods, &block)
+        set_callback(:cancel, :after, *methods, &block)
+      end
+
+      def after_complete(*methods, &block)
+        set_callback(:complete, :after, *methods, &block)
+      end
+
+      def after_error(*methods, &block)
+        set_callback(:error, :after, *methods, &block)
+      end
+    end
+
+    def run_start_callbacks
+      run_callbacks(:start)
+    end
+
+    def run_pause_callbacks
+      run_callbacks(:pause)
+    end
+
+    def run_interrupt_callbacks
+      run_callbacks(:interrupt)
+    end
+
+    def run_cancel_callbacks
+      run_callbacks(:cancel)
+    end
+
+    def run_complete_callbacks
+      run_callbacks(:complete)
+    end
+
+    def run_error_callbacks
+      run_callbacks(:error)
+    end
+  end
+end

data/lib/maintenance_on_steroids/csv_artifact.rb

@@ -0,0 +1,88 @@
+require "csv"
+
+module MaintenanceOnSteroids
+  # Append-oriented CSV artifact. Buffers rows in memory and renders them to
+  # the record's data_blob on save. Rows are plain arrays:
+  #
+  #   artifacts[:report] << [user.id, user.name]
+  #
+  # Headers (when declared on the artifact) are written as the first line and
+  # transparently skipped when reloading an existing CSV (e.g. on resume).
+  class CsvArtifact
+    attr_reader :record, :headers, :rows
+
+    def initialize(record, headers: nil)
+      @record  = record
+      @headers = headers
+      @rows    = []
+      @dirty   = false
+      @buffer_bytes = record.data_blob&.bytesize || (headers ? CSV.generate_line(headers).bytesize : 0)
+
+      if record.data_blob.present?
+        # A corrupted/partially-written blob must not abort a resume -- start
+        # from an empty buffer instead of raising through RunJob#perform.
+        begin
+          parsed = CSV.parse(record.data_blob)
+          if @headers && parsed.first&.map(&:to_s) == @headers.map(&:to_s)
+            parsed = parsed.drop(1)
+          end
+          @rows = parsed
+        rescue CSV::MalformedCSVError => e
+          # Resume must proceed, so start from an empty buffer -- but a later
+          # append+save will overwrite the unparseable blob, so log how many
+          # bytes are being discarded rather than losing them silently.
+          Rails.logger.error "[MaintenanceOnSteroids] CSV artifact reload failed " \
+                             "(#{record.name}, discarding #{record.data_blob.bytesize} bytes): #{e.message}"
+          @rows = []
+        end
+      end
+    end
+
+    def <<(row)
+      row = Array(row)
+      bytes = CSV.generate_line(row).bytesize
+      @record.check_buffer_size!(@buffer_bytes + bytes)
+      @rows << row
+      @buffer_bytes += bytes
+      @dirty = true
+      self
+    end
+    alias add <<
+
+    def size
+      @rows.size
+    end
+
+    def blank?
+      @rows.empty?
+    end
+
+    def present?
+      !blank?
+    end
+
+    def to_csv
+      CSV.generate do |csv|
+        csv << @headers if @headers
+        @rows.each { |row| csv << row }
+      end
+    end
+
+    def save!
+      @record.data_blob = to_csv
+      @record.content_type ||= "text/csv"
+      @record.refresh_metadata!
+      @record.save!
+      @dirty = false
+      self
+    end
+
+    def dirty?
+      @dirty
+    end
+
+    def inspect
+      "#<MaintenanceOnSteroids::CsvArtifact rows=#{@rows.size}>"
+    end
+  end
+end