backup-buddy 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 551ed4281803d9740f6a86a062db1b2eaa3902501833876c98bc9306000beb36
+  data.tar.gz: 47a1432ee75a7af44f8575885f9609981f3dc1963a873f289abbbb33621527bc
+SHA512:
+  metadata.gz: decd8a7182028a4e376b300bdae79d10e75fdce40096621d2ff074a923ba4eb21498fcd8af1b76136ec3f131f7964b76e05633515ca1ca3574178d410651aa52
+  data.tar.gz: 107c6461c017ae6e72dc6c25714242a619c3a0f54cbfc82a7622b6b3f1834d085ecdc47de81b0eacfbea8ce4a26b16f7a0cf47db6d505a605b7d4b61509fdc56

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egee
+
+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,72 @@
+# Backup-Buddy
+
+Backup (or restore) your things with Rsync and Ruby!
+
+Backup-Buddy is a dumb harness around rsync. It parses a YAML manifest, spawns lightweight rsync tasks, and runs them through a thread pool. The Ruby GIL releases during I/O, so all rsync processes genuinely run in parallel!
+
+## What It Does
+
+Backup-buddy reads in a YAML manifest and feeds the paths into a worker thread pool. If you got 10 folders and a concurrency of 3, it runs 3 rsyncs at a time until all 10 are done.
+
+Since rsync is symmetric, you can also use Backup-buddy as a **restore tool** — just swap the source and destination in your manifest!
+
+From this:
+
+```yaml
+---
+name: "My Backup"
+backupDestination: "your@nas.local:/path/to/backup_destination"
+backupPaths:
+  - "/path/to/dir_or_file"
+```
+
+To this:
+
+```yaml
+---
+name: "My Restore"
+backupDestination: "/path/to/restore_destination"
+backupPaths:
+  - "your@nas.local:/path/to/backup_dir"
+```
+
+Canonically, it is a backup tool. Semantically, whether it's a "backup" or a "restore" is up to the eyes of the beholder.
+
+## What It Doesn't
+
+Backup-Buddy is designed specifically to be a dumb harness that spawns rsync workers using a yaml manifest and a cli as the entry point.
+
+It does **not** manage SSH connections, users, or permissions - it simply invokes rsync and gets out of the way. Configure your remote hosts in `~/.ssh/config` and rsync will pick them up automatically.
+
+It also does not compress or otherwise archive files - it simply copies them from one place to another. The previous version had a compression feature but it was complicated and I never used it so I removed it.
+
+## How It Started
+
+Every once in a while, I back up all my files. I got tired of doing it manually so I started using rsync. Then, I got tired of typing rsync so I scripted it. Then, I got tired of the script so I wrote a program to do it all for me.
+
+The first version was written in NodeJS so we got async for free. However, I quickly learned that without concurrency limits, rsync will happily take your system down. I like Ruby a bit better than JavaScript so I rewrote it to use a thread pool.
+
+## Requirements
+
+- **Ruby** >= 3.1
+- **rsync** available to your system
+
+## SSH Configuration
+
+Backup-Buddy delegates all connection handling to rsync, which reads your `~/.ssh/config`. Set up your hosts there and then reference the host in your manifest paths.
+
+## Installation
+
+```bash
+gem install backup-buddy
+```
+
+## Usage
+
+```bash
+backup-buddy manifests/my_backup.yaml
+```
+
+## License
+
+MIT

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/backup-buddy

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative '../lib/backup_buddy'
+
+version = File.read(File.expand_path('../VERSION', __dir__)).strip
+dry_run = false
+
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: backup-buddy [options] <manifest.yml>'
+
+  opts.on('-n', '--dry-run', 'Show what would be transferred without doing it') do
+    dry_run = true
+  end
+
+  opts.on('-d', '--debug', 'Print rsync commands and enable verbose logging') do
+    require 'foghorn'
+    Foghorn.level = :debug
+  end
+
+  opts.on('-v', '--version', 'Print version') do
+    puts "backup-buddy #{version}"
+    exit
+  end
+
+  opts.on('-h', '--help', 'Show this help') do
+    puts opts
+    exit
+  end
+end
+
+parser.parse!
+manifest_path = ARGV[0]
+
+if manifest_path.nil?
+  puts parser
+  exit 1
+end
+
+unless File.exist?(manifest_path)
+  warn "Error: '#{manifest_path}' not found."
+  exit 1
+end
+
+manager = BackupBuddy::BackupManager.new(manifest_path, dry_run: dry_run)
+manager.run

data/lib/backup_buddy/backup_manager.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'open3'
+require 'foghorn'
+require_relative 'rsync_factory'
+
+module BackupBuddy
+  # Reads manifest, uses RsyncFactory to spawn tasks, and runs em
+  # through a thread pool with configurable concurrency.
+  class BackupManager
+    DEFAULT_CONCURRENCY = 3
+
+    attr_reader :name, :destination, :paths,
+                :concurrency, :excludes, :dry_run
+
+    def initialize(manifest_path, dry_run: false)
+      manifest = YAML.load_file(manifest_path)
+
+      @name        = manifest['name']
+      @destination = manifest['backupDestination']
+      @paths       = manifest['backupPaths'] || []
+      @concurrency = manifest.fetch('concurrency', DEFAULT_CONCURRENCY)
+      @excludes    = build_excludes(manifest['ignorePatterns'])
+      @dry_run     = dry_run
+
+      rsync_bin = manifest.fetch('rsync_path', '/usr/bin/rsync')
+      @factory  = RsyncFactory.new(bin: rsync_bin)
+    end
+
+    def run
+      valid_paths = validate_paths(@paths)
+      return if valid_paths.empty?
+      return unless valid_destination?(@destination)
+
+      print_header(valid_paths)
+
+      tasks = valid_paths.map { |path| spawn_task(path) } # Spawn tasks from the factory
+      results = run_pool(tasks)                           # Run on thread pool w/concurrency control!
+
+      print_summary(tasks, results)
+    end
+
+    private
+
+    def valid_destination?(dest)
+      return true unless dest.start_with?('/')
+      return true if File.directory?(dest)
+
+      Foghorn.error("Destination '#{dest}' does not exist or is not a directory. Please create it first.")
+      false
+    end
+
+    def build_excludes(patterns)
+      return '' unless patterns.is_a?(Array)
+
+      patterns.map { |p| "--exclude='#{p}'" }.join(' ')
+    end
+
+    def validate_paths(paths)
+      valid = []
+      paths.each do |path|
+        if valid_path?(path)
+          valid << path
+        else
+          Foghorn.warn("Skipping '#{path}' — local paths must start with /, remote paths must be host:/absolute/path")
+        end
+      end
+      valid
+    end
+
+    def valid_path?(path)
+      return true if path.start_with?('/')
+
+      # Remote rsync path: host:/absolute/path
+      if path.include?(':')
+        _host, remote_path = path.split(':', 2)
+        return remote_path.start_with?('/')
+      end
+
+      false
+    end
+
+    def spawn_task(src_path)
+      @factory.spawn(
+        src: src_path,
+        dest: @destination,
+        excludes: @excludes,
+        dry_run: @dry_run
+      )
+    end
+
+    def run_pool(tasks)
+      queue = Queue.new
+      tasks.each { |t| queue << t }
+
+      results = Array.new(tasks.length)
+      mutex = Mutex.new
+
+      # Spawn worker threads up to concurrency limit
+      workers = @concurrency.times.map do
+        Thread.new do
+          loop do
+            task, index = mutex.synchronize do
+              break nil if queue.empty?
+
+              t = queue.pop
+              i = tasks.index(t)
+              [t, i]
+            end
+            break unless task
+
+            exit_code = execute_task(task)
+            mutex.synchronize { results[index] = exit_code }
+          end
+        end
+      end
+
+      workers.each(&:join)
+      results
+    end
+
+    def execute_task(task)
+      prefix = "[#{task.label}]"
+      Foghorn.debug("#{prefix} #{task.command}")
+
+      status = nil
+      Open3.popen3(task.command) do |_stdin, stdout, stderr, wait_thr|
+        stdout_reader = Thread.new do
+          stdout.each_line { |line| Foghorn.info("#{prefix} #{line.chomp}") }
+        end
+
+        stderr_reader = Thread.new do
+          stderr.each_line { |line| Foghorn.warn("#{prefix} #{line.chomp}") }
+        end
+
+        stdout_reader.join
+        stderr_reader.join
+        status = wait_thr.value
+      end
+
+      code = status&.exitstatus || 1
+      if code.zero?
+        Foghorn.success("#{prefix} completed")
+      else
+        Foghorn.error("#{prefix} failed (exit #{code})")
+      end
+      code
+    end
+
+    def print_header(valid_paths)
+      Foghorn.warn('DRY RUN — no files will be modified') if @dry_run
+      Foghorn.info("Starting Job: #{@name}")
+      Foghorn.info("Destination: #{@destination}")
+      Foghorn.debug("Paths: #{valid_paths.length} | Concurrency: #{@concurrency}")
+    end
+
+    def print_summary(tasks, exit_codes)
+      puts
+      Foghorn.info('≈≈ Backup Summary ≈≈')
+
+      tasks.each_with_index do |task, i|
+        code = exit_codes[i] || 1
+        if code.zero?
+          Foghorn.success("  OK #{task.label}")
+        else
+          Foghorn.error("  FAILED (exit #{code}) #{task.label}")
+        end
+      end
+
+      failures = exit_codes.count { |c| c.nil? || !c.zero? }
+      if failures.zero?
+        Foghorn.success("All #{tasks.length} paths completed successfully.")
+      else
+        Foghorn.error("#{failures}/#{tasks.length} paths failed.")
+      end
+    end
+  end
+end

data/lib/backup_buddy/rsync_factory.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative 'rsync_task'
+
+module BackupBuddy
+  # Factory that validates rsync availability and spawns lightweight
+  # RsyncTask instances with the default rsync arguments.
+  class RsyncFactory
+    DEFAULT_ARGS = '-avzP --no-links'
+    attr_reader :bin
+
+    def initialize(bin: '/usr/bin/rsync')
+      @bin = bin
+      validate_rsync!
+    end
+
+    def spawn(src:, dest:, excludes: '', dry_run: false)
+      args = DEFAULT_ARGS
+      args = "--dry-run #{args}" if dry_run
+      escaped_src = Shellwords.shellescape(src)
+      escaped_dest = Shellwords.shellescape(dest)
+      cmd = "#{@bin} #{args} #{excludes} #{escaped_src} #{escaped_dest}".squeeze(' ').strip
+
+      RsyncTask.new(
+        command: cmd,
+        label: src
+      )
+    end
+
+    private
+
+    def validate_rsync!
+      rsync_path = `which #{@bin} 2>/dev/null`.strip
+      return unless rsync_path.empty?
+
+      # Fall back to checking the exact path
+      return if File.executable?(@bin)
+
+      raise "rsync not found at '#{@bin}'. Install it first."
+    end
+  end
+end

data/lib/backup_buddy/rsync_task.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BackupBuddy
+  # Immutable data object representing a single rsync invocation.
+  # The factory spawns these; the manager runs them.
+  class RsyncTask
+    attr_reader :command, :label
+
+    def initialize(command:, label:)
+      @command = command
+      @label = label
+      freeze
+    end
+  end
+end

data/lib/backup_buddy.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'backup_buddy/rsync_task'
+require_relative 'backup_buddy/rsync_factory'
+require_relative 'backup_buddy/backup_manager'
+
+module BackupBuddy
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: backup-buddy
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Egee
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: foghorn-logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A Ruby harness around rsync to back up files and folders in parallel
+  with threads.
+email:
+executables:
+- backup-buddy
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- VERSION
+- bin/backup-buddy
+- lib/backup_buddy.rb
+- lib/backup_buddy/backup_manager.rb
+- lib/backup_buddy/rsync_factory.rb
+- lib/backup_buddy/rsync_task.rb
+homepage: https://github.com/egeexyz/backup-buddy
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Back up your things with rsync!
+test_files: []