easy_sync 0.0.5 → 2.0.0

data/lib/easy_sync/jbod/purger.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module EasySync
+  module Jbod
+    # Removes expired deletion candidates from the drives. This is the only
+    # code in the tool that deletes backup data, so it is deliberately narrow:
+    # a candidate is removed only if its folder's drive is mounted right now,
+    # the path resolves inside that folder's destination, and it has been
+    # missing on the NAS for both the day and run thresholds.
+    class Purger
+      Result = Struct.new(:purged, :would_purge, :skipped, keyword_init: true) do
+        def initialize(**)
+          super
+          members.each { |m| self[m] ||= [] }
+        end
+      end
+
+      def initialize(manifest, grace_days:, grace_runs:, clock: Time, out: $stdout)
+        @manifest = manifest
+        @grace_days = grace_days
+        @grace_runs = grace_runs
+        @clock = clock
+        @out = out
+      end
+
+      # +mounted+ are the MountedDrive structs for this run.
+      def run(mounted, dry_run: false)
+        by_serial = mounted.to_h { |m| [m.serial_number, m] }
+        result = Result.new
+        expired = @manifest.expired_deletions(now: @clock.now, grace_days: @grace_days, grace_runs: @grace_runs)
+                           .select { |p| ready?(p) }
+
+        # Whole folders first; their file-level candidates go with them.
+        folders, paths = expired.partition(&:whole_folder?)
+        folders.each do |pending|
+          root = @manifest.folder(pending.folder_path)&.root?
+          purge_one(pending, by_serial, result, dry_run: dry_run, root: root) do |dest, drive|
+            # A root unit is only a share's loose top-level files; the
+            # share's subfolders below dest belong to other folders.
+            root ? remove_top_level_files(dest) : FileUtils.rm_rf(dest)
+            remove_empty_dirs(root ? dest : File.dirname(dest), drive.mount_point)
+            # A 'reassigned' candidate is the OLD copy of a folder that still
+            # has a valid manifest row elsewhere (see #ready?); only the
+            # files come out, the folder record itself must survive. A
+            # 'missing_on_nas' candidate means the folder is gone entirely.
+            unless pending.reassigned?
+              @manifest.clear_pending(pending.folder_path)
+              @manifest.remove_folder(pending.folder_path, note: "deleted from #{drive.friendly_name}: " \
+                                                                 "missing on NAS since #{pending.first_missing_at}")
+            end
+          end
+        end
+
+        gone = folders.map(&:folder_path)
+        files, dirs = paths.reject { |p| gone.include?(p.folder_path) }.partition { |p| p.kind == 'file' }
+        files.each do |pending|
+          purge_one(pending, by_serial, result, dry_run: dry_run) { |dest, _| File.delete(dest) if File.exist?(dest) }
+        end
+        # Deepest directories first so parents empty out before we reach them.
+        dirs.sort_by { |p| -p.relative_path.count('/') }.each do |pending|
+          purge_one(pending, by_serial, result, dry_run: dry_run) do |dest, _|
+            if Dir.exist?(dest) && !Dir.empty?(dest)
+              @out.puts "  leaving #{dest}: not empty yet"
+              next false
+            end
+            Dir.rmdir(dest) if Dir.exist?(dest)
+          end
+        end
+        result
+      end
+
+      private
+
+      # A folder moved off a drive (cause 'reassigned') is only safe to purge
+      # from there once it has actually landed, verified, on its new drive:
+      # grace_days alone exists to protect against a flaky NAS probe and says
+      # nothing about whether the fresh copy elsewhere actually succeeded.
+      def ready?(pending)
+        return true unless pending.reassigned?
+
+        current = @manifest.folder(pending.folder_path)
+        !current.nil? && current.drive_serial != pending.drive_serial && current.last_sync_status == 'ok'
+      end
+
+      def purge_one(pending, by_serial, result, dry_run:, root: false)
+        drive = by_serial[pending.drive_serial]
+        unless drive
+          result.skipped << [pending, 'drive not mounted']
+          return
+        end
+        if pending.whole_folder? && !root && (live = overlapping_live_folder(pending, drive.serial_number))
+          result.skipped << [pending, "#{live} is a live folder that overlaps it on #{drive.friendly_name}; " \
+                                      'not deleting (resolve by hand)']
+          return
+        end
+
+        base = File.join(drive.mount_point, pending.folder_path)
+        dest = pending.whole_folder? ? base : File.join(base, pending.relative_path)
+        unless inside?(dest, base) && File.expand_path(base).start_with?("#{File.expand_path(drive.mount_point)}/")
+          result.skipped << [pending, 'path escapes its folder']
+          return
+        end
+
+        label = pending.whole_folder? ? "#{pending.folder_path} (whole folder)" : "#{pending.folder_path}/#{pending.relative_path}"
+        if dry_run
+          @out.puts "  would delete #{label} from #{drive.friendly_name}"
+          result.would_purge << [pending, drive.friendly_name]
+          return
+        end
+
+        @out.puts "  deleting #{label} from #{drive.friendly_name}"
+        return if yield(dest, drive) == false
+
+        @manifest.record_deletion(pending, drive_serial: drive.serial_number)
+        result.purged << [pending, drive.friendly_name]
+      end
+
+      # Another folder placed on the same drive that deleting this whole
+      # folder would take with it (it lives below the path), or whose tree
+      # this path is part of. Either means the manifest changed shape after
+      # the candidate was recorded, and an rm_rf would destroy live data.
+      def overlapping_live_folder(pending, serial)
+        prefix = "#{pending.folder_path}/"
+        @manifest.folders_on(serial).find do |f|
+          next false if f.folder_path == pending.folder_path
+
+          f.folder_path.start_with?(prefix) || (!f.root? && pending.folder_path.start_with?("#{f.folder_path}/"))
+        end&.folder_path
+      end
+
+      # The share directory a removed folder sat in (and the root unit's own
+      # directory) is removed once nothing is left in it, so a share that
+      # has left a drive entirely leaves no empty shell behind. Never goes
+      # above the share level, and never touches the drive root.
+      def remove_empty_dirs(dir, mount_point)
+        top = File.expand_path(mount_point)
+        dir = File.expand_path(dir)
+        while dir.start_with?("#{top}/") && Dir.exist?(dir) && Dir.empty?(dir)
+          Dir.rmdir(dir)
+          dir = File.dirname(dir)
+        end
+      end
+
+      def remove_top_level_files(dir)
+        return unless Dir.exist?(dir)
+
+        Dir.children(dir).each do |name|
+          path = File.join(dir, name)
+          File.delete(path) if File.file?(path) || File.symlink?(path)
+        end
+      end
+
+      def inside?(path, base)
+        expanded = File.expand_path(path)
+        expanded == File.expand_path(base) || expanded.start_with?("#{File.expand_path(base)}/")
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/restorer.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module EasySync
+  module Jbod
+    # `easy_sync restore`: the reverse of `sync`. Copies a folder (or every
+    # folder under a share, or everything) from wherever the manifest says it
+    # currently lives back onto its NAS share. For rebuilding a NAS after a
+    # wipe/reformat, the scenario the old single-drive drobo-sync restore
+    # scripts covered by hand; here the folders for one share can be spread
+    # across several drives, so this walks the manifest instead of assuming
+    # one source directory.
+    #
+    # Never deletes, exactly like those old scripts: only adds and updates
+    # files on the NAS. A drive with fewer files than the NAS already has
+    # leaves the extra NAS files alone.
+    class Restorer
+      class UnknownTarget < Error; end
+
+      Result = Struct.new(:restored, :skipped, :failed, keyword_init: true) do
+        def initialize(**)
+          super
+          members.each { |m| self[m] ||= [] }
+        end
+      end
+
+      def initialize(settings, manifest:, shell: Shell.new, out: $stdout)
+        @manifest = manifest
+        @shell = shell
+        @out = out
+        @excludes = Array(settings[:exclude_folders]).map { |e| "--exclude=#{e}" }
+        @share_paths = Array(settings[:sources]).to_h do |e|
+          path = e.is_a?(Hash) ? e[:path] : e.to_s
+          [File.basename(path), path]
+        end
+      end
+
+      # +targets+ are folder_paths ("tv/Breaking Bad") or share names ("tv"),
+      # expanded to every folder currently in the manifest under that share
+      # (including the share's root-files unit, which is keyed by its name).
+      # Raises if a name matches nothing placed.
+      def resolve(targets)
+        all = @manifest.folders
+        targets.flat_map do |t|
+          exact = all.find { |f| f.folder_path == t }
+          next [exact] if exact && !exact.root?
+
+          under_share = [exact].compact + all.select { |f| f.folder_path.start_with?("#{t}/") }
+          raise UnknownTarget, "#{t} matches no placed folder or share" if under_share.empty?
+
+          under_share
+        end.uniq(&:folder_path)
+      end
+
+      # +folders+ are Folder structs from the manifest; +mounted+ are this
+      # run's MountedDrive structs. Returns a Result.
+      def run(folders, mounted, dry_run: false)
+        result = Result.new
+        by_serial = mounted.to_h { |m| [m.serial_number, m] }
+        folders.each { |folder| restore_one(folder, by_serial, result, dry_run: dry_run) }
+        result
+      end
+
+      private
+
+      # A rotted file must not quietly go back to the NAS: warn and name
+      # every file `scrub` has flagged for this folder on its current drive,
+      # whatever its state (awaiting refetch, refetched, or unresolved).
+      def warn_about_flagged_files(folder, drive)
+        flagged = @manifest.scrub_findings_for(drive.serial_number, folder.folder_path)
+        return if flagged.empty?
+
+        @out.puts "WARNING: #{folder.folder_path}: #{flagged.size} file#{'s' if flagged.size != 1} on #{drive.friendly_name} " \
+                  "#{flagged.size == 1 ? 'is' : 'are'} flagged by scrub (#{flagged.map { |f| "#{f.relative_path}: #{f.status}" }.join(', ')}); " \
+                  'restoring may copy a rotted file onto the NAS.'
+      end
+
+      def restore_one(folder, by_serial, result, dry_run:)
+        drive = by_serial[folder.drive_serial]
+        if drive.nil?
+          name = @manifest.drive(folder.drive_serial)&.friendly_name || folder.drive_serial
+          return skip(result, folder.folder_path, "its drive #{name} is not mounted")
+        end
+
+        root = share_root(folder.folder_path)
+        if root.nil?
+          share = folder.folder_path.split('/').first
+          return skip(result, folder.folder_path, "#{share} is not a configured source; `add-source` it first")
+        end
+        return skip(result, folder.folder_path, "the NAS share is not mounted at #{root}") unless Dir.exist?(root)
+
+        destination = nas_destination(folder.folder_path)
+
+        source = File.join(drive.mount_point, folder.folder_path)
+        return skip(result, folder.folder_path, "nothing at #{source} on #{drive.friendly_name}") unless Dir.exist?(source)
+
+        warn_about_flagged_files(folder, drive)
+        @out.puts "\n------------------ #{folder.folder_path}: #{drive.friendly_name} -> NAS ------------------"
+        rsync_result = restore_copy(source, destination, dry_run: dry_run, root_only: folder.root?)
+        if rsync_result.success?
+          result.restored << folder.folder_path
+        else
+          @out.puts "WARNING: rsync for #{folder.folder_path} exited with status #{rsync_result.status}"
+          result.failed << folder.folder_path
+        end
+      end
+
+      # No --delete, ever: restoring must never remove anything already on the NAS.
+      # A root-files unit restores only its top-level files; the share's
+      # subfolders are folders of their own, possibly on other drives.
+      def restore_copy(source, destination, dry_run:, root_only: false)
+        FileUtils.mkdir_p(File.dirname(destination)) unless dry_run
+        argv = ['rsync', '-a', '--partial', '--stats', '--info=progress2', '--itemize-changes', *@excludes]
+        argv << Mirror::ROOT_ONLY if root_only
+        argv << '--dry-run' if dry_run
+        argv += [with_slash(source), with_slash(destination)]
+        @shell.run(argv)
+      end
+
+      def share_root(folder_path)
+        @share_paths[folder_path.split('/').first]
+      end
+
+      def nas_destination(folder_path)
+        share, rest = folder_path.split('/', 2)
+        root = @share_paths[share] or return nil
+
+        rest ? File.join(root, rest) : root
+      end
+
+      def skip(result, folder_path, why)
+        @out.puts "WARNING: skipping #{folder_path}: #{why}"
+        result.skipped << folder_path
+      end
+
+      def with_slash(path)
+        path.end_with?('/') ? path : "#{path}/"
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/run_lock.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module EasySync
+  module Jbod
+    # Prevents two long-running commands (sync, scrub, clean, restore) from
+    # overlapping: doubled NAS/drive load, and two processes racing over the
+    # same state. A PID file at +path+ is the lock; a stale one (its process
+    # no longer running) is reclaimed automatically rather than blocking
+    # forever. The file's second line names which command holds it, so
+    # `status`/the dashboard can say "Scrub running" instead of assuming sync;
+    # a lock file with no second line (written before this existed) reads as
+    # 'sync', its original and only kind. Every line from the third on is free
+    # text the holder can update as it goes (Jbod::ScrubPool uses one line per
+    # drive its workers are currently on) without disturbing the mtime that
+    # #status reads as the run's start time.
+    class RunLock
+      class AlreadyRunning < Error; end
+
+      # pid: the process holding the lock. started_at: the lock file's mtime,
+      # which is set once when it's written and never touched again for the
+      # life of the run, so it doubles as the run's start time. kind: 'sync',
+      # 'scrub', 'clean', or 'restore'. current: an Array of the holder's
+      # free-form progress notes (see #note), empty if it hasn't set any.
+      Status = Struct.new(:pid, :started_at, :kind, :current, keyword_init: true)
+
+      def initialize(path)
+        @path = path
+      end
+
+      # Runs the block while holding the lock. Raises AlreadyRunning instead of
+      # running the block if another live process already holds it.
+      def acquire(kind: 'sync')
+        if (pid = holder)
+          raise AlreadyRunning, "another easy_sync run is already running (pid #{pid}). " \
+                                "If that's wrong (the process really is gone), remove #{@path}."
+        end
+
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, "#{Process.pid}\n#{kind}\n")
+        begin
+          yield
+        ensure
+          File.delete(@path) if File.exist?(@path) && pid_in_file == Process.pid
+        end
+      end
+
+      # Replaces the free-form lines from the third on (one per +names+, empty
+      # to clear them) without touching the file's mtime (the run's recorded
+      # start time) or releasing the lock. A no-op unless this process is the
+      # one actually holding it.
+      def note(*names)
+        return unless File.exist?(@path) && pid_in_file == Process.pid
+
+        mtime = File.mtime(@path)
+        File.write(@path, "#{[Process.pid, kind_in_file, *names].join("\n")}\n")
+        File.utime(mtime, mtime, @path)
+      end
+
+      # The run currently holding the lock, or nil if none is (a stale lock
+      # left by a dead process counts as none).
+      def status
+        pid = holder or return nil
+
+        Status.new(pid: pid, started_at: File.mtime(@path), kind: kind_in_file, current: current_in_file)
+      end
+
+      private
+
+      # The PID holding the lock, or nil if there is none or it's stale.
+      def holder
+        pid = pid_in_file
+        return nil if pid.nil? || pid.zero?
+
+        Process.kill(0, pid)
+        pid
+      rescue Errno::ESRCH
+        nil # no such process: the lock is stale
+      end
+
+      def pid_in_file
+        return nil unless File.exist?(@path)
+
+        File.read(@path).lines.first.to_s.strip.to_i
+      end
+
+      def kind_in_file
+        line = File.read(@path).lines[1]
+        line ? line.strip : 'sync'
+      end
+
+      def current_in_file
+        File.read(@path).lines.drop(2).map(&:strip).reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/run_log.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'time'
+
+module EasySync
+  module Jbod
+    # Tees everything a sync prints into ~/.easy_sync/logs/sync-<timestamp>.log
+    # as it happens, so a multi-day run has a record even if the terminal is
+    # gone. rsync's in-place progress chunks (carriage-return updates) are kept
+    # off disk; the per-folder --stats block that follows them has the totals.
+    class RunLog
+      attr_reader :path
+
+      # +prefix+ names the run kind ('sync' or 'scrub'), so each is pruned
+      # separately: scrub-*.log files never push out sync-*.log files, or the
+      # other way around.
+      def self.open(dir, keep: 20, out: $stdout, clock: Time, prefix: 'sync')
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "#{prefix}-#{clock.now.strftime('%Y%m%d-%H%M%S')}.log")
+        prune(dir, keep: keep - 1, prefix: prefix)
+        new(File.open(path, 'a'), out: out, path: path)
+      end
+
+      # Keeps the newest +keep+ logs matching +prefix+ in +dir+.
+      def self.prune(dir, keep:, prefix: 'sync')
+        logs = Dir.glob(File.join(dir, "#{prefix}-*.log")).sort
+        (logs.size - [keep, 0].max).clamp(0, logs.size).times { |i| File.delete(logs[i]) }
+      end
+
+      def initialize(file, out:, path: nil)
+        @file = file
+        @out = out
+        @path = path
+        @file.sync = true
+        @mutex = Mutex.new   # Jbod::ScrubPool's workers all write through the same RunLog
+      end
+
+      def puts(*lines)
+        @mutex.synchronize do
+          @out.puts(*lines)
+          lines = [''] if lines.empty?
+          lines.flatten.each { |l| @file.puts(l) unless l.to_s.include?("\r") }
+        end
+      end
+
+      def print(*args)
+        @mutex.synchronize do
+          @out.print(*args)
+          @file.print(*args) unless args.join.include?("\r")
+        end
+      end
+
+      def close = @file.close
+    end
+  end
+end