imap-backup 16.2.0 → 16.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 773e831319b208a930da663eae601d32236281104f4712960bfdb42dbc9d7794
-  data.tar.gz: 0da5b5f25c8e89022b387f08e5a5bee101284067fa6c5b9db7b35c95890e92da
+  metadata.gz: 9ec15a683d70eadabab4271afcd2231c723344e79dde55fadeea091056201fc8
+  data.tar.gz: 946f1074220df2af38c92a5ff7f5dda8bcdcef3dc20f48d9f2c8206e29a8cd6e
 SHA512:
-  metadata.gz: ccd49d19ec804c70c5aaaadcc40129ad8fcccf129c8de01c2c9e74cec0068bd2268fe6ea4e79f1d313539069e727891da9d0fc16e91a9e64c2301b00248204d8
-  data.tar.gz: 92553f44cf28d9c3a19b4cc3ff63fbd5a2dae59056663e9222ba0481ac6768d77f91c33e6d2aec652e451fbc1a5c9ae8f3933fcc2b9d601a5d3ce04865720af3
+  metadata.gz: 7c33112eb20f168c453f0cc52e86497c7a44459afa718ac12ff1ca71cf990d9566514598aae25fc22117fb30478db649bb76a1aff697d40dabb788cc54fa1508
+  data.tar.gz: ea2dd0c673c603c71708ba550cbdf98c218c51b8ff076ba031d40a7ae33f80ff830ada659b7cc300e8511cc3da207665e6f2114c231e985a0b716e2844f7fe7a

data/docs/performance.md

@@ -43,7 +43,7 @@ By default, during backup, each message is downloaded one-by-one.
 Using this setting, you can download chunks of emails at a time,
 potentially speeding up the process.
 
-Using multi-fetch mean that the backup process *will* use
+Using multi-fetch means that the backup process *will* use
 more memory - equivalent to the size of the groups of messages
 that are downloaded.
 

data/imap-backup.gemspec

@@ -18,18 +18,19 @@ Gem::Specification.new do |gem|
 
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.require_paths = ["lib"]
-  gem.required_ruby_version = ">= 3.0"
+  gem.required_ruby_version = ">= 3.2"
 
-  gem.add_runtime_dependency "highline"
-  gem.add_runtime_dependency "logger"
-  gem.add_runtime_dependency "mail", "2.7.1"
-  gem.add_runtime_dependency "net-imap", ">= 0.3.2"
-  gem.add_runtime_dependency "net-smtp"
-  gem.add_runtime_dependency "os"
-  gem.add_runtime_dependency "ostruct"
-  gem.add_runtime_dependency "rake"
-  gem.add_runtime_dependency "thor", "~> 1.1"
-  gem.add_runtime_dependency "thunderbird", "0.3.0"
+  gem.add_dependency "highline"
+  gem.add_dependency "logger"
+  gem.add_dependency "mail", "2.7.1"
+  gem.add_dependency "net-imap", ">= 0.3.2"
+  gem.add_dependency "net-smtp"
+  gem.add_dependency "os"
+  gem.add_dependency "ostruct"
+  gem.add_dependency "rake"
+  gem.add_dependency "sys-proctable"
+  gem.add_dependency "thor", "~> 1.1"
+  gem.add_dependency "thunderbird", "0.3.0"
 
   gem.metadata = {
     "rubygems_mfa_required" => "true"

data/lib/imap/backup/account/backup.rb

@@ -2,6 +2,7 @@ require "imap/backup/account/backup_folders"
 require "imap/backup/account/folder_backup"
 require "imap/backup/account/folder_ensurer"
 require "imap/backup/account/local_only_folder_deleter"
+require "imap/backup/account/locker"
 
 module Imap; end
 
@@ -22,19 +23,17 @@ module Imap::Backup
       # start the connection so we get logging messages in the right order
       account.client.login
 
-      run_pre_backup_tasks
-      backup_folders = Account::BackupFolders.new(
-        client: account.client, account: account
-      ).to_a
+      ensure_folder
+      delete_local_only_folders if account.mirror_mode
+
       if backup_folders.none?
         Logger.logger.warn "No folders found to backup for account '#{account.username}'"
         return
       end
-      Logger.logger.debug "Starting backup of #{backup_folders.count} folders"
-      backup_folders.each do |folder|
-        Account::FolderBackup.new(account: account, folder: folder, refresh: refresh).run
+
+      locker.with_lock do
+        perform_backup
       end
-      Logger.logger.debug "Backup of account '#{account.username}' complete"
     end
 
     private
@@ -42,9 +41,30 @@ module Imap::Backup
     attr_reader :account
     attr_reader :refresh
 
-    def run_pre_backup_tasks
+    def backup_folders
+      @backup_folders ||= Account::BackupFolders.new(
+        client: account.client, account: account
+      ).to_a
+    end
+
+    def delete_local_only_folders
+      Account::LocalOnlyFolderDeleter.new(account: account).run
+    end
+
+    def ensure_folder
       Account::FolderEnsurer.new(account: account).run
-      Account::LocalOnlyFolderDeleter.new(account: account).run if account.mirror_mode
+    end
+
+    def locker
+      @locker ||= Account::Locker.new(account: account)
+    end
+
+    def perform_backup
+      Logger.logger.debug "Starting backup of #{backup_folders.count} folders"
+      backup_folders.each do |folder|
+        Account::FolderBackup.new(account: account, folder: folder, refresh: refresh).run
+      end
+      Logger.logger.debug "Backup of account '#{account.username}' complete"
     end
   end
 end

data/lib/imap/backup/account/folder.rb

@@ -184,6 +184,13 @@ module Imap::Backup
     CREATE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
     EXAMINE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
     PERMITTED_FLAGS = %i(Answered Draft Flagged Seen).freeze
+    private_constant :BODY_ATTRIBUTE,
+                     :UID_FETCH_RETRY_CLASSES,
+                     :UID_SEARCH_RETRY_CLASSES,
+                     :APPEND_RETRY_CLASSES,
+                     :CREATE_RETRY_CLASSES,
+                     :EXAMINE_RETRY_CLASSES,
+                     :PERMITTED_FLAGS
 
     def examine
       client.examine(utf7_encoded_name)
@@ -196,7 +203,9 @@ module Imap::Backup
     def extract_uid(response)
       uid_data = response.data.code.data
       @uid_validity = uid_data.uidvalidity
-      uid_data.assigned_uids.first
+      # With net-imap >= 0.6, assigned_uids is a `Net::IMAP::SequenceSet`
+      uids = uid_data.assigned_uids.to_a
+      uids.to_a.first
     end
 
     def utf7_encoded_name

data/lib/imap/backup/account/locker.rb

@@ -0,0 +1,35 @@
+require "imap/backup/account/folder_ensurer"
+require "imap/backup/lockfile"
+
+module Imap; end
+
+module Imap::Backup
+  class Account; end
+
+  class Account::Locker
+    attr_reader :account
+
+    def initialize(account:)
+      @account = account
+    end
+
+    def with_lock(&block)
+      lockfile = Lockfile.new(path: account.lockfile_path)
+      if lockfile.exists?
+        if !lockfile.stale?
+          raise Lockfile::LockfileExistsError,
+                "Lockfile '#{account.lockfile_path}' exists and is not stale."
+        end
+
+        Logger.logger.info("Stale lockfile '#{account.lockfile_path}' found. Removing it.")
+        lockfile.remove
+      else
+        Account::FolderEnsurer.new(account: account).run
+      end
+
+      lockfile.with_lock do
+        block.call
+      end
+    end
+  end
+end

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

@@ -1,4 +1,5 @@
 require "imap/backup/account/folder_mapper"
+require "imap/backup/account/locker"
 require "imap/backup/uploader"
 
 module Imap; end
@@ -12,13 +13,16 @@ module Imap::Backup
       @account = account
       @destination_delimiter = delimiter
       @destination_prefix = prefix
+      @locker = nil
     end
 
     # Runs the restore operation
     # @return [void]
     def run
-      folders.each do |serializer, folder|
-        Uploader.new(folder, serializer).run
+      locker.with_lock do
+        folders.each do |serializer, folder|
+          Uploader.new(folder, serializer).run
+        end
       end
     end
 
@@ -40,5 +44,9 @@ module Imap::Backup
     def folders
       Account::FolderMapper.new(**enumerator_options)
     end
+
+    def locker
+      @locker ||= Account::Locker.new(account: account)
+    end
   end
 end

data/lib/imap/backup/account.rb

@@ -4,6 +4,7 @@ require "imap/backup/account/client_factory"
 
 module Imap; end
 
+# rubocop:disable Metrics/ClassLength
 module Imap::Backup
   # Contains the attributes relating to an email account.
   class Account
@@ -57,7 +58,7 @@ module Imap::Backup
     # mark messages as '\Seen' when accessed).
     # @return [Boolean]
     attr_reader :reset_seen_flags_after_fetch
-    # The status of the account - controls backup and migration behavior
+    # The status of the account - controls backup and migration behaviour
     # "active" - the account is available for backup and migration,
     # "archived" - the account is available for migration, but not backup,
     # "offline" - the account is not available for backup or migration.
@@ -168,6 +169,14 @@ module Imap::Backup
       update(:local_path, value)
     end
 
+    # @raise [RuntimeError] if the local_path is not set
+    # @return [String] the path to the lockfile for the account
+    def lockfile_path
+      raise "local_path is not set" if !local_path
+
+      File.join(local_path, "imap-backup.lock")
+    end
+
     # @raise [RuntimeError] if the supplied value is not an Array
     # @return [void]
     def folders=(value)
@@ -283,14 +292,19 @@ module Imap::Backup
 
     attr_reader :changes
 
-    REQUIRED_ATTRIBUTES = %i[password username].freeze
+    REQUIRED_ATTRIBUTES = %i[password username local_path].freeze
     OPTIONAL_ATTRIBUTES = %i[
-      connection_options download_strategy folders folder_blacklist local_path mirror_mode
+      connection_options download_strategy folders folder_blacklist mirror_mode
       multi_fetch_size reset_seen_flags_after_fetch server status
     ].freeze
     KNOWN_ATTRIBUTES = REQUIRED_ATTRIBUTES + OPTIONAL_ATTRIBUTES
     VALID_STATUSES = %w[active archived offline].freeze
     DEFAULT_STATUS = "active".freeze
+    private_constant :REQUIRED_ATTRIBUTES,
+                     :OPTIONAL_ATTRIBUTES,
+                     :KNOWN_ATTRIBUTES,
+                     :VALID_STATUSES,
+                     :DEFAULT_STATUS
 
     def check_options!(options)
       missing_required = REQUIRED_ATTRIBUTES - options.keys

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

@@ -64,6 +64,8 @@ module Imap::Backup
       case exception
       when Net::IMAP::NoResponseError, Errno::ECONNREFUSED
         111
+      when Lockfile::LockfileExistsError
+        112
       else
         1
       end

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

@@ -1,3 +1,6 @@
+require "erb"
+require "json"
+require "tempfile"
 require "thor"
 
 require "imap/backup/cli/options"
@@ -19,7 +22,7 @@ module Imap::Backup
     # @return [String] a description of the namespace configuration
     NAMESPACE_CONFIGURATION_DESCRIPTION = <<~DESC.freeze
       Some IMAP servers use namespaces (i.e. prefixes like "INBOX"),
-      while others, while others concatenate the names of subfolders
+      while others concatenate the names of subfolders
       with a charater ("delimiter") other than "/".
 
       In these cases there are two choices.
@@ -60,9 +63,24 @@ module Imap::Backup
 
     # Loads the application configuration
     # @raise [ConfigurationNotFound] if the configuration file does not exist
+    # @raise [RuntimeError] if both config and erb_configuration are provided
+    # @raise [RuntimeError] if ERB template has syntax errors
+    # @raise [RuntimeError] if ERB template renders invalid JSON
     # @return [Configuration]
     def load_config(**options)
-      path = options[:config]
+      config_path = options[:config]
+      erb_config_path = options[:erb_configuration]
+
+      # Check mutual exclusivity
+      if config_path && erb_config_path
+        raise "Cannot specify both --config and --erb-configuration options"
+      end
+
+      # Handle ERB configuration
+      return load_erb_config(erb_config_path, options) if erb_config_path
+
+      # Handle regular JSON configuration
+      path = config_path
       require_exists = options.key?(:require_exists) ? options[:require_exists] : true
       if require_exists
         exists = Configuration.exist?(path: path)
@@ -94,5 +112,54 @@ module Imap::Backup
         config.accounts
       end
     end
+
+    private
+
+    # Processes an ERB template and loads it as configuration
+    # @raise [ConfigurationNotFound] if the ERB file does not exist
+    # @raise [RuntimeError] if ERB processing fails
+    # @raise [RuntimeError] if rendered output is invalid JSON
+    # @return [Configuration]
+    def load_erb_config(erb_path, _options)
+      # Check if file exists
+      unless File.exist?(erb_path)
+        raise ConfigurationNotFound, "ERB configuration file '#{erb_path}' not found"
+      end
+
+      begin
+        # Read and process ERB template
+        erb_content = File.read(erb_path)
+        erb = ERB.new(erb_content)
+        rendered_json = erb.result
+      rescue SyntaxError => e
+        raise "ERB template has syntax error: #{e.message}"
+      rescue StandardError => e
+        raise "Error processing ERB template: #{e.message}"
+      end
+
+      # Validate rendered JSON
+      begin
+        JSON.parse(rendered_json)
+      rescue JSON::ParserError => e
+        raise "ERB template rendered invalid JSON: #{e.message}"
+      end
+
+      # Create temporary file with rendered JSON
+      temp_file = Tempfile.new(["config", ".json"])
+      begin
+        temp_file.write(rendered_json)
+        temp_file.flush
+        temp_file.close
+
+        # Load configuration from temporary file
+        config = Configuration.new(path: temp_file.path)
+        # Force loading of data before temp file is deleted
+        config.accounts
+        config
+      ensure
+        # Clean up temporary file
+        temp_file&.unlink
+      end
+    end
   end
 end

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

@@ -17,6 +17,7 @@ module Imap::Backup
 
     desc "accounts [OPTIONS]", "List locally backed-up accounts"
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option
@@ -44,6 +45,7 @@ module Imap::Backup
     )
     accounts_option
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option
@@ -56,6 +58,7 @@ module Imap::Backup
 
     desc "folders EMAIL [OPTIONS]", "List backed up folders"
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option
@@ -78,6 +81,7 @@ module Imap::Backup
 
     desc "list EMAIL FOLDER [OPTIONS]", "List emails in a folder"
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option
@@ -108,6 +112,7 @@ module Imap::Backup
       the UID.
     DESC
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option
@@ -136,6 +141,7 @@ module Imap::Backup
     private
 
     MAX_SUBJECT = 60
+    private_constant :MAX_SUBJECT
 
     def list_emails_as_json(serializer)
       emails = serializer.each_message.map do |message|

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

@@ -31,6 +31,7 @@ module Imap::Backup
         )
         long_desc LONG_DESCRIPTION
         config_option
+        erb_configuration_option
         quiet_option
         verbose_option
         method_option(

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

@@ -38,6 +38,7 @@ module Imap::Backup
         )
         long_desc LONG_DESCRIPTION
         config_option
+        erb_configuration_option
         quiet_option
         verbose_option
         method_option(

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

@@ -25,6 +25,19 @@ module Imap::Backup
           desc: "supply the configuration file path (default: ~/.imap-backup/config.json)"
         }
       },
+      {
+        name: "erb_configuration",
+        parameters: {
+          type: :string,
+          desc:
+          "supply an ERB template file path for configuration. " \
+          "This is an alternative to the --config option. " \
+          "The file will be processed with ERB before being parsed as JSON. " \
+          "This allows use of environment variables and other dynamic content. " \
+          "Note that using this option is a potential security risk as it allows " \
+          "execution of arbitrary code."
+        }
+      },
       {
         name: "format",
         parameters: {

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

@@ -15,6 +15,7 @@ module Imap::Backup
 
     desc "folders EMAIL [OPTIONS]", "List account folders"
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option
@@ -36,6 +37,7 @@ module Imap::Backup
       Lists the IMAP capabilities supported by the IMAP server.
     DESC
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option
@@ -57,6 +59,7 @@ module Imap::Backup
       the `imap-backup migrate` and `imap-backup mirror` commands.
     DESC
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option
@@ -106,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
@@ -119,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

@@ -50,8 +50,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/single.rb

@@ -105,7 +105,7 @@ module Imap::Backup
       type: "string",
       desc: "the path of the directory where backups are to be saved. " \
             "If the directory does not exist, it will be created. " \
-            "If not set, this is set to a diretory under the current path " \
+            "If not set, this is set to a directory under the current path " \
             "which is derived from the username, by replacing '@' with '_'." \
             "If this path parameter is not indicated, " \
             "the default is the current directory plus the email " \

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

@@ -37,6 +37,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"
@@ -23,9 +24,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 +37,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 +68,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 +188,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

@@ -23,6 +23,7 @@ module Imap::Backup
       "Skip downloading emails up to today for all configured folders"
     )
     config_option
+    erb_configuration_option
     quiet_option
     verbose_option
     # Creates fake downloaded emails so that only the account's future emails
@@ -32,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
 
@@ -52,6 +48,7 @@ module Imap::Backup
       DOC
     )
     config_option
+    erb_configuration_option
     quiet_option
     verbose_option
     method_option(
@@ -97,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/cli.rb

@@ -64,6 +64,7 @@ module Imap::Backup
     DESC
     accounts_option
     config_option
+    erb_configuration_option
     quiet_option
     refresh_option
     verbose_option
@@ -101,6 +102,7 @@ module Imap::Backup
       #{Helpers::NAMESPACE_CONFIGURATION_DESCRIPTION}
     DESC
     config_option
+    erb_configuration_option
     quiet_option
     verbose_option
     method_option(
@@ -153,6 +155,7 @@ module Imap::Backup
     DESC
     accounts_option
     config_option
+    erb_configuration_option
     quiet_option
     verbose_option
     method_option(
@@ -203,6 +206,7 @@ module Imap::Backup
         on the server).
     DESC
     config_option
+    erb_configuration_option
     format_option
     quiet_option
     verbose_option

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

@@ -13,6 +13,7 @@ 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

data/lib/imap/backup/configuration.rb

@@ -68,7 +68,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 +111,6 @@ module Imap::Backup
 
     private
 
-    VERSION_2_1 = "2.1".freeze
-
     attr_reader :pathname
 
     def ensure_loaded!

data/lib/imap/backup/lockfile.rb

@@ -0,0 +1,78 @@
+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
+
+    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?
+
+      proc_table_entry.starttime != starttime
+    end
+
+    private
+
+    def create
+      pid = Process.pid
+      proc_table_entry = Sys::ProcTable.ps(pid: pid)
+
+      raise "Unable to get process info for PID #{pid}" if proc_table_entry.nil?
+
+      starttime = proc_table_entry.starttime
+
+      data = {
+        pid: pid,
+        starttime: starttime
+      }
+
+      json_data = JSON.generate(data)
+      File.write(path, json_data)
+    end
+  end
+end

data/lib/imap/backup/mirror.rb

@@ -11,10 +11,10 @@ module Imap::Backup
       @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 +29,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/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,7 +4,7 @@ module Imap::Backup
   # @private
   MAJOR    = 16
   # @private
-  MINOR    = 2
+  MINOR    = 4
   # @private
   REVISION = 0
   # @private

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 16.2.0
+  version: 16.4.0
 platform: ruby
 authors:
 - Joe Yates
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -122,6 +121,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: sys-proctable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -174,6 +187,7 @@ files:
 - lib/imap/backup/account/folder_ensurer.rb
 - lib/imap/backup/account/folder_mapper.rb
 - lib/imap/backup/account/local_only_folder_deleter.rb
+- lib/imap/backup/account/locker.rb
 - lib/imap/backup/account/restore.rb
 - lib/imap/backup/account/serialized_folders.rb
 - lib/imap/backup/cli.rb
@@ -208,6 +222,7 @@ files:
 - lib/imap/backup/file_mode.rb
 - lib/imap/backup/flag_refresher.rb
 - lib/imap/backup/local_only_message_deleter.rb
+- lib/imap/backup/lockfile.rb
 - lib/imap/backup/logger.rb
 - lib/imap/backup/migrator.rb
 - lib/imap/backup/mirror.rb
@@ -248,7 +263,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -256,15 +270,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Backup GMail (or other IMAP) accounts to disk
 test_files: []