backup_nexus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8eb79bf4aa85274b82292897294246021d89ee85ae8c5f09e080ae82bd526129
+  data.tar.gz: a087f50f451ca3e635830042c04e7ccaa56c541b75d0dbbf88f3a27717bea340
+SHA512:
+  metadata.gz: 8b2338600d937308f2ca82d7bdf7b1c3d769bbf339b40800a1535a9f65e3cf5a7d1658e14cd0aa6f25a10669c73cd04b29912f0060ee02ef18b0b84fa7478871
+  data.tar.gz: 37829dbe4fa5b948f9c00fff551b15d67d6ae27a6bbecf841af7ee43170d0d83342d272b915808930ef5197e8afc9b68f2c58d8b5d2476c7f4d75000cc5e909d

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Extract backup management from RailsNexus into the BackupNexus engine.
+- Preserve the RailsNexus layout and stylesheet.
+- Add safe environment-based seed examples, migrations, generators, CI, and release automation.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Tamiru Hailu
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# BackupNexus
+
+Backup management for Rails applications, extracted from RailsNexus.
+
+BackupNexus keeps the same RailsNexus layout and stylesheet while owning the
+backup dashboard, database models, backup runner, generators, migrations, and
+rake tasks in a separate gem.
+
+## Installation
+
+```ruby
+gem "rails_nexus"
+gem "backup_nexus"
+```
+
+Run the installer:
+
+```bash
+bin/rails generate backup_nexus:install
+bin/rails db:migrate
+```
+
+The installer mounts the engine at `/backup_nexus`. Configure authorization
+through `RailsNexus.configure`, then enable the backup dashboard:
+
+```ruby
+BackupNexus.configure do |config|
+  config.enabled = true
+end
+```
+
+Run the safe example seed with:
+
+```bash
+bundle exec rake backup_nexus:seed_backups
+```
+
+The migration renames legacy `rails_nexus_backups` and
+`rails_nexus_backup_configs` tables when they exist, preserving existing
+backup records during the extraction.
+
+## Official Backup gem integration
+
+BackupNexus includes its existing safe native runner by default and also
+generates models compatible with the official [Backup](https://github.com/backup/backup)
+DSL. The upstream project is not currently under active development and
+targets older Rails dependencies, so it remains optional instead of being a
+hard runtime dependency.
+
+To use the DSL templates:
+
+```ruby
+gem "backup", "~> 4.4"
+```
+
+Then run:
+
+```bash
+bin/rails generate backup_nexus:backup
+bundle exec backup perform -t daily_backup
+```
+
+## Development
+
+```bash
+bundle exec rails test
+bundle exec rake test
+gem build backup_nexus.gemspec
+```
+
+## CI/CD
+
+GitHub Actions runs the test suite on pushes and pull requests. A matching
+version tag publishes the gem to RubyGems and creates a GitHub release.
+
+Create a scoped RubyGems API key that can push only the `backup_nexus` gem,
+then add it to the GitHub repository (or its `release` environment) as an
+Actions secret named `RUBYGEMS_API_KEY`. Never commit the key to the
+repository.
+
+To release a version, update `lib/backup_nexus/version.rb`, merge the change to
+`main`, and push a matching tag such as `v0.1.0`.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/setup"
+
+require "rails"
+require "bundler/gem_tasks"
+
+task default: :test
+
+task :test do
+  ruby "-Itest", "-e", "ARGV.each { |file| require File.expand_path(file) }", *Dir["test/**/*_test.rb"]
+end

data/app/controllers/backup_nexus/application_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module BackupNexus
+  class ApplicationController < RailsNexus::ApplicationController
+    include BackupNexus::ApplicationHelper
+
+    layout "layouts/rails_nexus/application"
+
+    helper BackupNexus::ApplicationHelper
+    helper BackupNexus::Engine.helpers
+    helper BackupNexus::Engine.routes.url_helpers
+    helper RailsNexus::Engine.helpers
+    helper RailsNexus::Engine.routes.url_helpers
+
+    helper_method :rails_nexus
+
+    before_action :backup_nexus_require_enabled
+
+    private
+
+    def rails_nexus
+      RailsNexus::Engine.routes.url_helpers
+    end
+
+    def backup_nexus_require_enabled
+      return if BackupNexus.configuration.enabled
+
+      render plain: "Backup management not enabled", status: :forbidden
+    end
+  end
+end

data/app/controllers/backup_nexus/backup_controller.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module BackupNexus
+  class BackupController < ApplicationController
+    before_action :check_backup_enabled
+    before_action :set_config, only: %i[edit update destroy trigger]
+
+    # GET /backup_nexus/backup
+    def index
+      @configs = BackupNexus::BackupConfig.order(:name)
+    end
+
+    # GET /backup_nexus/backup/new
+    def new
+      @config = BackupNexus::BackupConfig.new(
+        adapter: "mysql",
+        host: "localhost",
+        port: 3306,
+        storage_path: "~/dumps",
+        keep_count: 30,
+        compress: true
+      )
+    end
+
+    # POST /backup_nexus/backup
+    def create
+      @config = BackupNexus::BackupConfig.new(config_params)
+
+      if @config.save
+        redirect_to backup_path, notice: "Backup config '#{@config.name}' created."
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    # GET /backup_nexus/backup/:id/edit
+    def edit; end
+
+    # PATCH /backup_nexus/backup/:id
+    def update
+      # Strip blank password fields so they don't overwrite stored values
+      filtered = config_params
+      %w[password encryption_password gpg_password].each do |attr|
+        filtered = filtered.except(attr) if filtered[attr].blank?
+      end
+
+      if @config.update(filtered)
+        redirect_to backup_path, notice: "Backup config '#{@config.name}' updated."
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    # DELETE /backup_nexus/backup/:id
+    def destroy
+      name = @config.name
+      @config.destroy
+      redirect_to backup_path, notice: "Backup config '#{name}' deleted."
+    end
+
+    # POST /backup_nexus/backup/:id/trigger
+    def trigger
+      begin
+        BackupNexus::BackupJob.perform_later(@config.id)
+        redirect_to backup_path, notice: "Backup '#{@config.name}' started in background."
+      rescue
+        # Fallback to synchronous if Active Job is not configured
+        result = BackupNexus::BackupService.run(@config)
+        if result[:success]
+          redirect_to backup_path, notice: "Backup '#{@config.name}' completed successfully."
+        else
+          redirect_to backup_path, alert: "Backup failed: #{result[:error]}"
+        end
+      end
+    end
+
+    # GET /backup_nexus/backup/:id/history
+    def history
+      @config = BackupNexus::BackupConfig.find(params[:id])
+      @records = BackupNexus::Backup.where(config_name: @config.name)
+        .order(started_at: :desc)
+        .limit(50)
+    end
+
+    # GET /backup_nexus/backup/history
+    def all_history
+      @records = BackupNexus::Backup.order(started_at: :desc).limit(100)
+      render :history
+    end
+
+    private
+
+    def set_config
+      @config = BackupNexus::BackupConfig.find(params[:id])
+    end
+
+    def config_params
+      params.require(:backup_config).permit(
+        :name, :description, :database_name, :adapter, :host, :port,
+        :username, :password, :storage_path, :keep_count,
+        :compress, :encrypted, :encryption_password,
+        :rsync_enabled, :rsync_host, :rsync_port, :rsync_user, :rsync_path, :rsync_mirror, :rsync_archive, :rsync_directories, :rsync_excludes,
+        :notify_command, :notify_on_success, :notify_on_failure,
+        :schedule_cron, :enabled,
+        :s3_enabled, :s3_access_key, :s3_secret_key, :s3_bucket, :s3_region, :s3_prefix,
+        :gpg_enabled, :gpg_password,
+        :email_notify, :email_to,
+        :archive_enabled, :bzip2_compress, :split_chunks, :encrypt_base64, :mysql_additional_options,
+        skip_tables: [], archive_paths: [], archive_excludes: []
+      )
+    end
+
+    def check_backup_enabled
+      unless BackupNexus.configuration.enabled
+        render plain: "Backup management not enabled", status: :forbidden
+      end
+    end
+  end
+end

data/app/helpers/backup_nexus/application_helper.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module BackupNexus
+  module ApplicationHelper
+    include RailsNexus::ApplicationHelper
+    include BackupNexus::Engine.routes.url_helpers
+
+    def backup_path(_resource = nil)
+      backup_nexus_route_path("/backup")
+    end
+
+    def new_backup_path
+      backup_nexus_route_path("/backup/new")
+    end
+
+    def backup_history_path
+      backup_nexus_route_path("/backup/history")
+    end
+
+    def edit_backup_path(resource)
+      backup_nexus_route_path("/backup/#{backup_nexus_param(resource)}/edit")
+    end
+
+    def backup_destroy_path(resource)
+      backup_nexus_route_path("/backup/#{backup_nexus_param(resource)}")
+    end
+
+    def backup_trigger_path(resource)
+      backup_nexus_route_path("/backup/#{backup_nexus_param(resource)}/trigger")
+    end
+
+    def backup_config_history_path(resource)
+      backup_nexus_route_path("/backup/#{backup_nexus_param(resource)}/history")
+    end
+
+    def backup_update_path(resource)
+      backup_nexus_route_path("/backup/#{backup_nexus_param(resource)}")
+    end
+
+    private
+
+    def backup_nexus_route_path(path)
+      prefix = request.respond_to?(:script_name) && request.script_name.present? ? request.script_name.chomp("/") : "/backup_nexus"
+      "#{prefix}#{path}"
+    end
+
+    def backup_nexus_param(resource)
+      resource.respond_to?(:to_param) ? resource.to_param : resource
+    end
+  end
+end

data/app/jobs/backup_nexus/backup_job.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BackupNexus
+  class BackupJob < ApplicationJob
+    queue_as :backup_nexus_backups
+
+    # Accept either a BackupConfig record ID or a BackupConfig record
+    def perform(backup_config_id_or_record)
+      config = if backup_config_id_or_record.is_a?(BackupNexus::BackupConfig)
+        backup_config_id_or_record
+      else
+        BackupNexus::BackupConfig.find(backup_config_id_or_record)
+      end
+
+      BackupNexus::BackupService.run(config)
+    end
+  end
+end

data/app/models/backup_nexus/backup.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module BackupNexus
+  class Backup < BaseRecord
+    self.table_name = "backup_nexus_backups"
+
+    validates :config_name, presence: true
+    validates :status, presence: true, inclusion: { in: %w[running success failed] }
+    validates :started_at, presence: true
+
+    scope :recent, ->(hours = 24) { where("started_at >= ?", hours.hours.ago) }
+    scope :successful, -> { where(status: "success") }
+    scope :failed, -> { where(status: "failed") }
+    scope :running, -> { where(status: "running") }
+    scope :by_config, ->(name) { where(config_name: name) }
+    scope :latest_first, -> { order(started_at: :desc) }
+
+    # Start tracking a backup run
+    def self.start!(config_name:, triggered_by: "system")
+      create!(
+        config_name: config_name,
+        status: "running",
+        triggered_by: triggered_by,
+        started_at: Time.current
+      )
+    end
+
+    # Mark backup as completed
+    def succeed!(file_path: nil, file_size: nil)
+      update!(
+        status: "success",
+        file_path: file_path,
+        file_size: file_size,
+        duration: (Time.current - started_at).round(2),
+        completed_at: Time.current
+      )
+    end
+
+    # Mark backup as failed
+    def fail!(error_message:)
+      update!(
+        status: "failed",
+        error_message: error_message,
+        duration: (Time.current - started_at).round(2),
+        completed_at: Time.current
+      )
+    end
+
+    # Get success rate for a model over the last N days
+    def self.success_rate(config_name:, days: 7)
+      records = by_config(config_name).where("started_at >= ?", days.days.ago).where.not(status: "running")
+      return 0 if records.empty?
+      (records.successful.count.to_f / records.count * 100).round(1)
+    end
+
+    # Get backup health summary
+    def self.health_summary(alert_threshold_hours: 24)
+      configs = BackupNexus::BackupConfig.pluck(:name)
+      results = configs.map do |config_name|
+        latest = by_config(config_name).successful.latest_first.first
+        age_hours = latest ? ((Time.current - latest.started_at) / 3600).round(1) : nil
+
+        {
+          config_name: config_name,
+          last_backup: latest&.started_at,
+          age_hours: age_hours,
+          status: age_hours.nil? ? "unknown" : (age_hours < alert_threshold_hours ? "healthy" : "stale"),
+          success_rate: success_rate(config_name: config_name),
+          last_file_size: latest&.file_size
+        }
+      end
+
+      {
+        healthy: results.all? { |r| r[:status] == "healthy" },
+        models: results,
+        alerts: results.select { |r| r[:status] == "stale" || r[:status] == "unknown" }
+      }
+    end
+
+    # Cleanup old backup records
+    def self.cleanup!(retention_days: 30)
+      where("started_at < ?", retention_days.days.ago).delete_all
+    end
+
+    # Format file size
+    def file_size_human
+      return "—" unless file_size
+      units = ["B", "KB", "MB", "GB"]
+      size = file_size.to_f
+      units.each do |unit|
+        return "#{size.round(1)} #{unit}" if size < 1024
+        size /= 1024
+      end
+      "#{size.round(1)} TB"
+    end
+
+    # Duration formatted
+    def duration_human
+      return "—" unless duration
+      if duration < 60
+        "#{duration.round(1)}s"
+      else
+        "#{(duration / 60).floor}m #{(duration % 60).round}s"
+      end
+    end
+  end
+end

data/app/models/backup_nexus/backup_config.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module BackupNexus
+  class BackupConfig < BaseRecord
+    self.table_name = "backup_nexus_backup_configs"
+
+    ADAPTERS = %w[mysql postgresql sqlite mongodb redis].freeze
+
+    # ─── Boolean defaults ──────────────────────────────────────────
+    # Rails doesn't apply DB defaults to new in-memory records, so
+    # check_box helpers in form_for render unchecked. These declarations
+    # ensure the form reflects the intended defaults.
+    attribute :enabled,            :boolean, default: true
+    attribute :compress,           :boolean, default: true
+    attribute :encrypted,          :boolean, default: false
+    attribute :encrypt_base64,     :boolean, default: false
+    attribute :rsync_enabled,      :boolean, default: false
+    attribute :rsync_mirror,       :boolean, default: false
+    attribute :notify_on_success,  :boolean, default: true
+    attribute :notify_on_failure,  :boolean, default: true
+    attribute :s3_enabled,         :boolean, default: false
+    attribute :gpg_enabled,        :boolean, default: false
+    attribute :email_notify,       :boolean, default: false
+    attribute :archive_enabled,    :boolean, default: false
+    attribute :bzip2_compress,     :boolean, default: false
+    attribute :split_chunks,       :boolean, default: false
+
+    validates :name, presence: true, uniqueness: true
+    validates :name, format: {
+      with: /\A[a-zA-Z0-9_$][a-zA-Z0-9_$.-]*\z/,
+      message: "may contain only letters, numbers, dots, underscores, dollar signs, and hyphens"
+    }
+    validates :database_name, presence: true, if: -> { adapter != "redis" }
+    validates :adapter, presence: true, inclusion: { in: ADAPTERS }
+    validates :storage_path, presence: true
+    validates :keep_count, numericality: { greater_than: 0 }
+    validates :encryption_password, presence: true, if: :encrypted?
+    validates :rsync_host, presence: true, if: :rsync_enabled?
+    validates :rsync_user, presence: true, if: :rsync_enabled?
+    validates :s3_bucket, presence: true, if: :s3_enabled?
+    validates :s3_access_key, presence: true, if: :s3_enabled?
+    validates :s3_secret_key, presence: true, if: :s3_enabled?
+    validates :gpg_password, presence: true, if: :gpg_enabled?
+    validates :email_to, presence: true, if: :email_notify?
+    validates :port, :rsync_port,
+      numericality: { only_integer: true, greater_than: 0, less_than_or_equal_to: 65_535 },
+      allow_nil: true
+    validate :database_identifier_is_safe
+    validate :remote_sync_values_are_safe
+
+    scope :enabled,  -> { where(enabled: true) }
+    scope :disabled, -> { where(enabled: false) }
+
+    serialize :skip_tables, coder: JSON
+    serialize :archive_paths, coder: JSON
+    serialize :archive_excludes, coder: JSON
+
+    # ─── Skip Tables ───────────────────────────────────────────────
+    def skip_tables_list
+      return [] if skip_tables.blank?
+      skip_tables.is_a?(Array) ? skip_tables : JSON.parse(skip_tables.to_s) rescue []
+    end
+
+    def skip_tables_list=(value)
+      return if value.blank?
+      self.skip_tables = if value.is_a?(String)
+        value.split(",").map(&:strip).reject(&:blank?)
+      else
+        value
+      end
+    end
+
+    # ─── Archive Paths ─────────────────────────────────────────────
+    def archive_paths_list
+      return [] if archive_paths.blank?
+      archive_paths.is_a?(Array) ? archive_paths : JSON.parse(archive_paths.to_s) rescue []
+    end
+
+    def archive_paths_list=(value)
+      return if value.blank?
+      self.archive_paths = if value.is_a?(String)
+        value.split(",").map(&:strip).reject(&:blank?)
+      else
+        value
+      end
+    end
+
+    def archive_excludes_list
+      return [] if archive_excludes.blank?
+      archive_excludes.is_a?(Array) ? archive_excludes : JSON.parse(archive_excludes.to_s) rescue []
+    end
+
+    def archive_excludes_list=(value)
+      return if value.blank?
+      self.archive_excludes = if value.is_a?(String)
+        value.split(",").map(&:strip).reject(&:blank?)
+      else
+        value
+      end
+    end
+
+    # ─── Adapter checks ────────────────────────────────────────────
+    def mysql?;         adapter == "mysql";        end
+    def postgresql?;    adapter == "postgresql";    end
+    def sqlite?;        adapter == "sqlite";        end
+    def mongodb?;       adapter == "mongodb";       end
+    def redis?;         adapter == "redis";         end
+
+    # ─── Path helpers ──────────────────────────────────────────────
+    def storage_path_expanded
+      storage_path.gsub("~", Dir.home)
+    end
+
+    def dump_filename
+      timestamp = Time.current.strftime("%Y%m%d_%H%M%S")
+      ext = dump_extension
+      "#{name}_#{timestamp}.#{ext}"
+    end
+
+    def dump_filepath
+      File.join(storage_path_expanded, dump_filename)
+    end
+
+    # ─── Stats ─────────────────────────────────────────────────────
+    def recent_backups(limit: 10)
+      BackupNexus::Backup.where(config_name: name).order(started_at: :desc).limit(limit)
+    end
+
+    def last_failure
+      BackupNexus::Backup.where(config_name: name, status: "failed").order(started_at: :desc).first
+    end
+
+    def stats
+      backups = BackupNexus::Backup.where(config_name: name)
+      recent = backups.where("started_at >= ?", 7.days.ago)
+      {
+        total: backups.count,
+        successful: backups.successful.count,
+        failed: backups.failed.count,
+        recent_count: recent.count,
+        recent_success: recent.successful.count,
+        recent_failed: recent.failed.count,
+        last_backup: backups.successful.latest_first.first,
+        total_size: backups.sum(:file_size).to_i,
+        total_size_human: human_size(backups.sum(:file_size).to_i)
+      }
+    end
+
+    private
+
+    def database_identifier_is_safe
+      return if database_name.blank? || sqlite?
+
+      unless database_name.match?(/\A[a-zA-Z0-9_$][a-zA-Z0-9_$.-]*\z/) && !database_name.include?("..")
+        errors.add(:database_name, "contains unsupported characters")
+      end
+    end
+
+    def remote_sync_values_are_safe
+      return unless rsync_enabled?
+
+      unless rsync_host.to_s.match?(/\A[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?\z/)
+        errors.add(:rsync_host, "is not a valid hostname")
+      end
+      unless rsync_user.to_s.match?(/\A[a-zA-Z0-9_][a-zA-Z0-9_.-]*\z/)
+        errors.add(:rsync_user, "contains unsupported characters")
+      end
+      unless rsync_path.to_s.start_with?("/") && !rsync_path.to_s.match?(/[\0\r\n]/)
+        errors.add(:rsync_path, "must be an absolute remote path")
+      end
+    end
+
+    def dump_extension
+      parts = ["sql"]
+      parts << "gz" if compress? && !bzip2_compress?
+      parts << "bz2" if bzip2_compress?
+      parts << "enc" if encrypted?
+      parts.join(".")
+    end
+
+    def human_size(bytes)
+      return "0 B" if bytes.zero?
+      units = %w[B KB MB GB TB]
+      exp = (Math.log(bytes) / Math.log(1024)).to_i
+      exp = units.size - 1 if exp >= units.size
+      "%.1f %s" % [bytes.to_f / (1024**exp), units[exp]]
+    end
+  end
+end