imap-backup 16.3.0 → 16.4.1

data/lib/imap/backup/cli/remote.rb

@@ -109,9 +109,12 @@ module Imap::Backup
       Kernel.puts list.to_json
     end
 
+    NAMESPACE_TEMPLATE = "%-10<name>s %-10<prefix>s %<delim>s".freeze
+    private_constant :NAMESPACE_TEMPLATE
+
     def list_namespaces(namespaces)
       Kernel.puts format(
-        "%-10<name>s %-10<prefix>s %<delim>s",
+        NAMESPACE_TEMPLATE,
         {name: "Name", prefix: "Prefix", delim: "Delimiter"}
       )
       list_namespace namespaces, :personal
@@ -122,7 +125,7 @@ module Imap::Backup
     def list_namespace(namespaces, name)
       info = namespace_info(namespaces.send(name).first, quote: true)
       if info
-        Kernel.puts format("%-10<name>s %-10<prefix>s %<delim>s", name: name, **info)
+        Kernel.puts format(NAMESPACE_TEMPLATE, name: name, **info)
       else
         Kernel.puts format("%-10<name>s (Not defined)", name: name)
       end

data/lib/imap/backup/cli/restore.rb

@@ -14,6 +14,13 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    # @param email [String, nil] optional email address identifying the account to restore
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
+    # @option opts [Array<String>] :accounts (nil) the accounts to restore
+    # @option opts [String] :delimiter ("/") the destination folder delimiter
+    # @option opts [String] :prefix ("") a prefix applied to restored folder names
     def initialize(email = nil, options)
       super([])
       @email = email
@@ -30,9 +37,6 @@ module Imap::Backup
         when email && !options.key?(:accounts)
           account = account(config, email)
           restore(account, **restore_options)
-        when !email && !options.key?(:accounts)
-          Logger.logger.info "Calling restore without an EMAIL parameter is deprecated"
-          config.accounts.each { |a| restore(a) }
         when email && options.key?(:accounts)
           raise "Missing EMAIL parameter"
         when !email && options.key?(:accounts)
@@ -41,6 +45,9 @@ module Imap::Backup
             "please pass a single EMAIL parameter"
           )
           requested_accounts(config).each { |a| restore(a) }
+        else
+          Logger.logger.info "Calling restore without an EMAIL parameter is deprecated"
+          config.accounts.each { |a| restore(a) }
         end
       end
     end
@@ -50,8 +57,8 @@ module Imap::Backup
     attr_reader :email
     attr_reader :options
 
-    def restore(account, **options)
-      restore = Account::Restore.new(account: account, **options)
+    def restore(account, **)
+      restore = Account::Restore.new(account: account, **)
       restore.run
     end
 

data/lib/imap/backup/cli/setup.rb

@@ -13,6 +13,9 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
     def initialize(options)
       super([])
       @options = options

data/lib/imap/backup/cli/single/backup.rb

@@ -12,6 +12,26 @@ module Imap::Backup
 
   # Runs a backup without relying on existing configuration
   class CLI::Single::Backup
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
+    # @option opts [String] :email the email address identifying the account to backup
+    # @option opts [String] :password (nil) the password for the account
+    # @option opts [String] :password_environment_variable (nil) the name of an environment variable
+    #   containing the password
+    # @option opts [String] :password_file (nil) the path to a file containing the password
+    # @option opts [String] :server the IMAP server address
+    # @option opts [String] :download_strategy (nil) the download strategy to use, either "delay"
+    #   or "direct"
+    # @option opts [Boolean] :folder_blacklist (false) whether to treat folder list as a blacklist
+    # @option opts [Array<String>] :folder ([]) the folders to backup
+    # @option opts [String] :path (nil) the local path to store the backup
+    # @option opts [Boolean] :mirror (false) whether to run in mirror mode
+    # @option opts [Integer] :multi_fetch_size (nil) the number of messages to fetch in a single
+    #   operation
+    # @option opts [Boolean] :refresh (false) whether to force refresh of folder metadata
+    # @option opts [Boolean] :reset_seen_flags_after_fetch (false) whether to reset seen flags
+    #   after fetching messages
     def initialize(options)
       @options = options
       @password = nil

data/lib/imap/backup/cli/stats.rb

@@ -1,14 +1,24 @@
+require "thor"
+
 require "imap/backup/account/backup_folders"
+require "imap/backup/cli/helpers"
 require "imap/backup/serializer"
 
 module Imap; end
 
 module Imap::Backup
+  class CLI < Thor; end
+
   # Prints various statistics about an account and its backup
   class CLI::Stats < Thor
     include Thor::Actions
     include CLI::Helpers
 
+    # @param email [String] the email address identifying the account to inspect
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
+    # @option opts [String] :format ("text") the output format, either "text" or "json"
     def initialize(email, options)
       super([])
       @email = email
@@ -37,6 +47,7 @@ module Imap::Backup
       {name: :local, width: 8, alignment: :right}
     ].freeze
     ALIGNMENT_FORMAT_SYMBOL = {left: "-", right: " "}.freeze
+    private_constant :TEXT_COLUMNS, :ALIGNMENT_FORMAT_SYMBOL
 
     attr_reader :email
     attr_reader :options

data/lib/imap/backup/cli/transfer.rb

@@ -1,4 +1,5 @@
 require "imap/backup/account/folder_mapper"
+require "imap/backup/account/locker"
 require "imap/backup/cli/backup"
 require "imap/backup/cli/helpers"
 require "imap/backup/logger"
@@ -15,6 +16,9 @@ module Imap::Backup
     # The possible values for the action parameter
     ACTIONS = %i(copy migrate mirror).freeze
 
+    # @param action [Symbol] one of ACTIONS describing the transfer mode
+    # @param source_email [String] the email of the source account
+    # @param destination_email [String] the email of the destination account
     def initialize(action, source_email, destination_email, options)
       @action = action
       @source_email = source_email
@@ -23,9 +27,11 @@ module Imap::Backup
       @automatic_namespaces = nil
       @config_path = nil
       @destination_delimiter = nil
+      @destination_locker = nil
       @destination_prefix = nil
       @reset = nil
       @source_delimiter = nil
+      @source_locker = nil
       @source_prefix = nil
     end
 
@@ -34,22 +40,19 @@ module Imap::Backup
     #     or the source and destination accounts are the same,
     #     or either of the accounts is not configured,
     #     or incompatible namespace/delimiter parameters have been supplied
+    #     or one or both of the accounts is locked by another process.
     #   @return [void]
     def run
       raise "Unknown action '#{action}'" if !ACTIONS.include?(action)
 
       process_options!
       warn_if_source_account_is_not_in_mirror_mode if action == :mirror
+
       run_backup if %i(copy mirror).include?(action)
 
-      folders.each do |serializer, folder|
-        case action
-        when :copy
-          Mirror.new(serializer, folder, reset: false).run
-        when :migrate
-          Migrator.new(serializer, folder, reset: reset).run
-        when :mirror
-          Mirror.new(serializer, folder, reset: true).run
+      source_locker.with_lock do
+        destination_locker.with_lock do
+          perform_action_on_folders
         end
       end
     end
@@ -68,6 +71,19 @@ module Imap::Backup
     attr_reader :source_email
     attr_accessor :source_prefix
 
+    def perform_action_on_folders
+      folders.each do |serializer, folder|
+        case action
+        when :copy
+          Mirror.new(serializer, folder, reset: false).run
+        when :migrate
+          Migrator.new(serializer, folder, reset: reset).run
+        when :mirror
+          Mirror.new(serializer, folder, reset: true).run
+        end
+      end
+    end
+
     def process_options!
       self.automatic_namespaces = options[:automatic_namespaces] || false
       self.config_path = options[:config]
@@ -175,5 +191,13 @@ module Imap::Backup
     def source_account
       config.accounts.find { |a| a.username == source_email }
     end
+
+    def source_locker
+      @source_locker ||= Account::Locker.new(account: source_account)
+    end
+
+    def destination_locker
+      @destination_locker ||= Account::Locker.new(account: destination_account)
+    end
   end
 end

data/lib/imap/backup/cli/utils.rb

@@ -33,15 +33,10 @@ module Imap::Backup
       Logger.setup_logging options
       config = load_config(**options)
       account = account(config, email)
+      locker ||= Account::Locker.new(account: account)
 
-      backup_folders = Account::BackupFolders.new(
-        client: account.client, account: account
-      )
-      backup_folders.each do |folder|
-        next if !folder.exist?
-
-        serializer = Serializer.new(account.local_path, folder.name)
-        do_ignore_folder_history(folder, serializer)
+      locker.with_lock do
+        ignore_account_history(account)
       end
     end
 
@@ -99,8 +94,21 @@ module Imap::Backup
     private
 
     FAKE_EMAIL = "fake@email.com".freeze
+    private_constant :FAKE_EMAIL
+
+    def ignore_account_history(account)
+      backup_folders = Account::BackupFolders.new(
+        client: account.client, account: account
+      )
+      backup_folders.each do |folder|
+        next if !folder.exist?
+
+        serializer = Serializer.new(account.local_path, folder.name)
+        ignore_folder_history(folder, serializer)
+      end
+    end
 
-    def do_ignore_folder_history(folder, serializer)
+    def ignore_folder_history(folder, serializer)
       uids = folder.uids - serializer.uids
       Logger.logger.info "Folder '#{folder.name}' - #{uids.length} messages"
 

data/lib/imap/backup/client/automatic_login_wrapper.rb

@@ -15,6 +15,7 @@ module Imap::Backup
     # @return [Client]
     attr_reader :client
 
+    # @param client [Client::Default] the client to wrap and lazily log in
     def initialize(client:)
       @client = client
       @login_called = false

data/lib/imap/backup/client/default.rb

@@ -13,11 +13,13 @@ module Imap::Backup
   # Tracks the latest folder selection in order to avoid repeated calls
   class Client::Default
     extend Forwardable
+
     def_delegators :imap, *%i(
       append authenticate capability create expunge namespace
       responses uid_fetch uid_search uid_store
     )
 
+    # @param account [Account] the account whose server is accessed
     def initialize(account)
       @account = account
       @state = nil

data/lib/imap/backup/configuration.rb

@@ -32,6 +32,7 @@ module Imap::Backup
       File.exist?(path || default_pathname)
     end
 
+    # @param path [String, nil] optional path to the configuration file
     def initialize(path: nil)
       @pathname = path || self.class.default_pathname
       @download_strategy = nil
@@ -68,7 +69,10 @@ module Imap::Backup
         ensure_loaded!
         accounts = data[:accounts].map do |attr|
           Account.new(attr)
-        end
+        rescue ArgumentError => e
+          Logger.logger.error("Skipping invalid account in config: #{e.message}")
+          nil
+        end.compact
         inject_global_attributes(accounts)
       end
     end
@@ -108,8 +112,6 @@ module Imap::Backup
 
     private
 
-    VERSION_2_1 = "2.1".freeze
-
     attr_reader :pathname
 
     def ensure_loaded!

data/lib/imap/backup/downloader.rb

@@ -8,6 +8,10 @@ module Imap::Backup
     # @private
     class MultiFetchFailedError < StandardError; end
 
+    # @param folder [Account::Folder] the remote folder to download from
+    # @param serializer [Serializer] the local serializer that stores messages
+    # @param multi_fetch_size [Integer] how many messages to fetch per batch
+    # @param reset_seen_flags_after_fetch [Boolean] true to restore unseen flags after fetch
     def initialize(folder, serializer, multi_fetch_size: 1, reset_seen_flags_after_fetch: false)
       @folder = folder
       @serializer = serializer

data/lib/imap/backup/email/mboxrd/message.rb

@@ -35,6 +35,7 @@ module Imap::Backup
       # @return [String] the original message body
       attr_reader :supplied_body
 
+      # @param supplied_body [String] the original RFC 2822 message text
       def initialize(supplied_body)
         @supplied_body = supplied_body.clone
       end

data/lib/imap/backup/file_mode.rb

@@ -3,6 +3,7 @@ module Imap; end
 module Imap::Backup
   # Accesses a file's access permissions
   class FileMode
+    # @param filename [String] the file whose permissions will be checked
     def initialize(filename:)
       @filename = filename
     end

data/lib/imap/backup/flag_refresher.rb

@@ -6,6 +6,8 @@ module Imap::Backup
     # The number of messages to process at a time
     CHUNK_SIZE = 100
 
+    # @param folder [Account::Folder] the remote folder whose flags are refreshed
+    # @param serializer [Serializer] the local serializer providing stored UIDs
     def initialize(folder, serializer)
       @folder = folder
       @serializer = serializer

data/lib/imap/backup/local_only_message_deleter.rb

@@ -5,6 +5,8 @@ module Imap; end
 module Imap::Backup
   # Deletes locally backed-up emails that are no longer on the server
   class LocalOnlyMessageDeleter
+    # @param folder [Account::Folder] the remote folder used to detect missing UIDs
+    # @param serializer [Serializer] the local serializer that may contain stale messages
     def initialize(folder, serializer)
       @folder = folder
       @serializer = serializer

data/lib/imap/backup/lockfile.rb

@@ -0,0 +1,94 @@
+require "sys/proctable"
+require "json"
+
+module Imap; end
+
+module Imap::Backup
+  class Lockfile
+    # An error that is thrown if a lockfile already exists
+    class LockfileExistsError < StandardError; end
+    class ProcessStartTimeUnavailableError < StandardError; end
+
+    attr_reader :path
+
+    # Initializes a new Lockfile instance.
+    # @param path [String] the path to the lockfile
+    def initialize(path:)
+      @path = path
+    end
+
+    # Creates the lockfile, yields to the given block
+    # and ensures the lockfile is removed afterwards.
+    def with_lock(&block)
+      raise LockfileExistsError, "Lockfile already exists at #{path}" if exists?
+
+      begin
+        create
+        block.call
+      ensure
+        remove
+      end
+    end
+
+    # Checks if the lockfile exists.
+    # @return [Boolean] true if the lockfile exists, false otherwise
+    def exists?
+      File.exist?(path)
+    end
+
+    # Removes the lockfile.
+    def remove
+      FileUtils.rm_f(path)
+    end
+
+    # Checks if the lockfile is stale (i.e., the process that created it is no longer running).
+    # @return [Boolean] true if the lockfile is stale, false otherwise
+    def stale?
+      return false if !exists?
+
+      file_content = File.read(path)
+      data = JSON.parse(file_content, symbolize_names: true)
+      pid = data[:pid]
+      starttime = data[:starttime]
+      proc_table_entry = Sys::ProcTable.ps(pid: pid)
+
+      return true if proc_table_entry.nil?
+
+      other_starttime = starttime(proc_table_entry)
+
+      other_starttime != starttime
+    end
+
+    private
+
+    def create
+      pid = Process.pid
+      proc_table_entry = Sys::ProcTable.ps(pid: pid)
+
+      if proc_table_entry.nil?
+        raise ProcessStartTimeUnavailableError, "Unable to get process info for PID #{pid}"
+      end
+
+      starttime = starttime(proc_table_entry)
+
+      data = {
+        pid: pid,
+        starttime: starttime
+      }
+
+      json_data = JSON.generate(data)
+      File.write(path, json_data)
+    end
+
+    def starttime(proc_table_entry)
+      case
+      when proc_table_entry.respond_to?(:starttime)
+        proc_table_entry.starttime
+      when proc_table_entry.respond_to?(:start_tvsec)
+        proc_table_entry.start_tvsec
+      else
+        raise ProcessStartTimeUnavailableError, "Proctable entry structure unknown"
+      end
+    end
+  end
+end

data/lib/imap/backup/logger.rb

@@ -49,7 +49,7 @@ module Imap::Backup
     end
 
     # Wraps a block, filtering output to standard error,
-    # hidng passwords and outputs the results to standard out
+    # hiding passwords, and outputs the results to standard out
     # @return [void]
     def self.sanitize_stderr(&block)
       sanitizer = Text::Sanitizer.new($stdout)

data/lib/imap/backup/migrator.rb

@@ -5,6 +5,9 @@ module Imap; end
 module Imap::Backup
   # Copies a folder of backed-up emails to an online folder
   class Migrator
+    # @param serializer [Serializer] the local folder to migrate
+    # @param folder [Account::Folder] the destination folder on the server
+    # @param reset [Boolean] true to clear the destination before uploading
     def initialize(serializer, folder, reset: false)
       @folder = folder
       @reset = reset

data/lib/imap/backup/mirror/map.rb

@@ -7,6 +7,8 @@ module Imap::Backup
 
   # Keeps track of the mapping between source and destination UIDs
   class Mirror::Map
+    # @param pathname [String] the path to the on-disk UID map
+    # @param destination [String] the destination account identifier
     def initialize(pathname:, destination:)
       @pathname = pathname
       @destination = destination
@@ -18,7 +20,6 @@ module Imap::Backup
     end
 
     # @return [Boolean] whether the supplied values match the existing
-    #  UID validity values
     def check_uid_validities(source:, destination:)
       store
       return false if source != source_uid_validity

data/lib/imap/backup/mirror.rb

@@ -5,16 +5,19 @@ module Imap; end
 module Imap::Backup
   # Synchronises a folder between a source and destination
   class Mirror
+    # @param serializer [Serializer] the source of backed-up messages
+    # @param folder [Account::Folder] the destination folder to mirror into
+    # @param reset [Boolean] true to delete destination-only messages first
     def initialize(serializer, folder, reset: false)
       @serializer = serializer
       @folder = folder
       @reset = reset
     end
 
-    # If necessary, reates the destination folder,
+    # If necessary, creates the destination folder,
     # then deletes any messages in the destination folder
     # that are not in the local store,
-    # sets existing messages' flas
+    # sets existing messages' flags
     # then appends any missing messages
     # and saves the mapping file
     # @return [void]
@@ -29,6 +32,7 @@ module Imap::Backup
     private
 
     CHUNK_SIZE = 100
+    private_constant :CHUNK_SIZE
 
     attr_reader :serializer
     attr_reader :folder

data/lib/imap/backup/serializer/mbox.rb

@@ -109,7 +109,7 @@ module Imap::Backup
     # Sets the mailbox file's updated time to the current time
     # @return [void]
     def touch
-      File.open(pathname, "a") {}
+      FileUtils.touch(pathname)
     end
 
     private

data/lib/imap/backup/serializer/message.rb

@@ -12,7 +12,7 @@ module Imap::Backup
     # @return [Array[Symbol]] the message's flags
     attr_accessor :flags
     # @return [Integer] the length of the message (as stored on disk)
-    attr_reader :length
+    attr_accessor :length
     # @return [Integer] the start of the message inside the mailbox file
     attr_reader :offset
     # @return [Integer] the message's UID

data/lib/imap/backup/serializer/permission_checker.rb

@@ -22,7 +22,7 @@ module Imap::Backup
       return nil if actual.nil?
 
       mask = ~limit & 0o777
-      return if (actual & mask).zero?
+      return if actual.nobits?(mask)
 
       message = format(
         "Permissions on '%<filename>s' " \

data/lib/imap/backup/serializer/version2_migrator.rb

@@ -101,7 +101,7 @@ module Imap::Backup
           end
         end
 
-        next if lines.count.zero?
+        next if lines.none?
 
         message = {
           uid: uids[messages.count],

data/lib/imap/backup/setup/asker.rb

@@ -56,6 +56,7 @@ module Imap::Backup
     private
 
     EMAIL_MATCHER = /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]+$/i
+    private_constant :EMAIL_MATCHER
 
     attr_reader :highline
   end

data/lib/imap/backup/setup.rb

@@ -91,6 +91,7 @@ module Imap::Backup
       Imap::Backup::Account.new(
         username: username,
         password: "",
+        local_path: nil,
         folders: []
       ).tap do |a|
         provider = Imap::Backup::Email::Provider.for_address(username)

data/lib/imap/backup/thunderbird/mailbox_exporter.rb

@@ -51,6 +51,7 @@ module Imap::Backup
     private
 
     EXPORT_PREFIX = "imap-backup".freeze
+    private_constant :EXPORT_PREFIX
 
     attr_reader :email
     attr_reader :serializer

data/lib/imap/backup/version.rb

@@ -4,9 +4,9 @@ module Imap::Backup
   # @private
   MAJOR    = 16
   # @private
-  MINOR    = 3
+  MINOR    = 4
   # @private
-  REVISION = 0
+  REVISION = 1
   # @private
   PRE      = nil
   # The application version