imap-backup 15.0.3.rc1 → 16.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef0c787a6f2a954caddfc9a5c329333781ad650bf1782feb28cc69e74aeba077
-  data.tar.gz: 23387da9df55557ab56dd46bdeef6608f7af4e80434a02c21767d080598583cb
+  metadata.gz: ac22de1cd99aab34b9d478d2ad8727faf67bbac635cf6ef80335d27012328a29
+  data.tar.gz: 7b74833c6e1752c1a25a201d3e3f40a05f8b966bebe38796843ee4f133191aff
 SHA512:
-  metadata.gz: 7432a214ec8dd20758786550785be876f208f1bc9b76f7f60f75b30abf800b2bc4c9fca655370576fff0dea4675d1a298c4c3e8743449774ae90d914aa635805
-  data.tar.gz: 461488fe00ea29917415845c2fd7a231ffc6f3646638c1ad64c23f74f96acc5c2581f7fb3adc04a3410d5dbec67eb36a417d4b02b31e827ab95870172ab52922
+  metadata.gz: b0147bfef559ef12c9f6b3e41eced66cade0de85fa418bafb81eed6cfa06bd6e751d818cb8d058768a8259e69526c2a90aa504389a188146722f66f2d2671b2c
+  data.tar.gz: 6b48724665aa1383094053164de511e2bcfd1b3bf2b32d28bf659740e96e1e5f32a9dc37af32ec6cb0fd23fb06bd863d567ca78135bac27bb2662d6b6b6f5118

data/docs/performance.md

@@ -1,14 +1,12 @@
-# Performace
+# Performance
 
-The two performance-related settings are "Download strategy",
-which is a global setting,
-and "Multi-fetch size", which is an Account-level setting.
+The two performance-related settings are "Download strategy", which is a global setting, and "Multi-fetch size", which is an Account-level setting.
 
 As with all performance tweaks, there are trade-offs.
 
 # Overview
 
-The defaults, which suit most machines and plays nice with servers is:
+The defaults, which suit most machines and play nice with servers are:
 
 * Download strategy: "delay writing metadata",
 * Multi-fetch size: 1.
@@ -18,7 +16,7 @@ a small virtual server or Raspberry Pi
 to run your backups, you can change "Download strategy".
 
 If your email provider supports it,
-and you don't have tight memeory limits,
+and you don't have tight memory limits,
 increase "Multi-fetch size" for faster backups.
 
 # Delay download writes
@@ -45,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 *will* mean that the backup process will use
+Using multi-fetch mean that the backup process *will* use
 more memory - equivalent to the size of the groups of messages
 that are downloaded.
 

data/imap-backup.gemspec

@@ -21,10 +21,12 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = ">= 3.0"
 
   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"

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

@@ -67,7 +67,10 @@ module Imap::Backup
     def uids
       Logger.logger.debug "Fetching UIDs for folder '#{name}'"
       examine
-      result = client.uid_search(["ALL"]).sort
+      result =
+        retry_on_error(errors: UID_SEARCH_RETRY_CLASSES) do
+          client.uid_search(["ALL"]).sort
+        end
       Logger.logger.debug "#{result.count} UIDs found for folder '#{name}'"
       result
     rescue FolderNotFound
@@ -177,6 +180,7 @@ module Imap::Backup
 
     BODY_ATTRIBUTE = "BODY[]".freeze
     UID_FETCH_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::IOError].freeze
+    UID_SEARCH_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::IOError].freeze
     APPEND_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
     CREATE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
     EXAMINE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze

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

@@ -16,6 +16,28 @@ module Imap::Backup
       options.define_options
     end
 
+    # @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
+      with a charater ("delimiter") other than "/".
+
+      In these cases there are two choices.
+
+      You can use the `--automatic-namespaces` option.
+      This will query the source and detination servers for their
+      namespace configuration and will adapt paths accordingly.
+      This option requires that both the source and destination
+      servers are available and work with the provided parameters
+      and authentication.
+
+      If automatic configuration does not work as desired, there are the
+      `--source-prefix=`, `--source-delimiter=`,
+      `--destination-prefix=` and `--destination-delimiter=` parameters.
+      To check what values you should use, check the output of the
+      `imap-backup remote namespaces EMAIL` command.
+    DESC
+
     # Processes command-line parameters
     # @return [Hash] the supplied command-line parameters with
     #   with hyphens in keys replaced by underscores

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

@@ -0,0 +1,79 @@
+module Imap; end
+
+module Imap::Backup
+  # Processes parameters to run the `migrate` command via command-line parameters
+  module CLI::Migrate
+    include Thor::Actions
+    include CLI::Helpers
+
+    LONG_DESCRIPTION = <<~DESC.freeze
+      This command is deprecated and will be removed in a future version.
+      Use 'copy' instead.
+
+      All emails which have been backed up for the "source account" (SOURCE_EMAIL) are
+      uploaded to the "destination account" (DESTINATION_EMAIL).
+
+      Some configuration may be necessary, as follows:
+
+      #{CLI::Helpers::NAMESPACE_CONFIGURATION_DESCRIPTION}
+
+      Finally, if you want to delete existing emails in destination folders,
+      use the `--reset` option. In this case, all existing emails are
+      deleted before uploading the migrated emails.
+    DESC
+
+    def self.included(base)
+      base.class_eval do
+        desc(
+          "migrate SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
+          "(Deprecated) Uploads backed-up emails from account SOURCE_EMAIL " \
+          "to account DESTINATION_EMAIL"
+        )
+        long_desc LONG_DESCRIPTION
+        config_option
+        quiet_option
+        verbose_option
+        method_option(
+          "automatic-namespaces",
+          type: :boolean,
+          desc: "automatically choose delimiters and prefixes"
+        )
+        method_option(
+          "destination-delimiter",
+          type: :string,
+          desc: "the delimiter for destination folder names"
+        )
+        method_option(
+          "destination-prefix",
+          type: :string,
+          desc: "the prefix (namespace) to add to destination folder names",
+          aliases: ["-d"]
+        )
+        method_option(
+          "reset",
+          type: :boolean,
+          desc: "DANGER! This option deletes all messages from destination " \
+                "folders before uploading",
+          aliases: ["-r"]
+        )
+        method_option(
+          "source-delimiter",
+          type: :string,
+          desc: "the delimiter for source folder names"
+        )
+        method_option(
+          "source-prefix",
+          type: :string,
+          desc: "the prefix (namespace) to strip from source folder names",
+          aliases: ["-s"]
+        )
+        # Migrates emails from one account to another
+        # @return [void]
+        def migrate(source_email, destination_email)
+          non_logging_options = Imap::Backup::Logger.setup_logging(options)
+          CLI::Transfer.new(:migrate, source_email, destination_email, non_logging_options).run
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+module Imap; end
+
+module Imap::Backup
+  # Processes parameters to run the `mirror` command via command-line parameters
+  module CLI::Mirror
+    include Thor::Actions
+    include CLI::Helpers
+
+    LONG_DESCRIPTION = <<~DESC.freeze
+      This command is deprecated and will be removed in a future version.
+      Use 'copy' instead.
+
+      This command updates the DESTINATION_EMAIL account's folders to have the same contents
+      as those on the SOURCE_EMAIL account.
+
+      If a folder list is configured for the SOURCE_EMAIL account,
+      only the folders indicated by the setting are copied.
+
+      First, it runs the download of the SOURCE_EMAIL account.
+      If the SOURCE_EMAIL account is **not** configured to be in 'mirror' mode,
+      a warning is printed.
+
+      When the mirror command is used, for each folder that is processed,
+      a new file is created alongside the normal backup files (.imap and .mbox)
+      This file has a '.mirror' extension. This file contains a mapping of
+      the known UIDs on the source account to those on the destination account.
+
+      Some configuration may be necessary, as follows:
+
+      #{CLI::Helpers::NAMESPACE_CONFIGURATION_DESCRIPTION}
+    DESC
+
+    def self.included(base)
+      base.class_eval do
+        desc(
+          "mirror SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
+          "(Deprecated) Keeps the DESTINATION_EMAIL account aligned with the SOURCE_EMAIL account"
+        )
+        long_desc LONG_DESCRIPTION
+        config_option
+        quiet_option
+        verbose_option
+        method_option(
+          "automatic-namespaces",
+          type: :boolean,
+          desc: "automatically choose delimiters and prefixes"
+        )
+        method_option(
+          "destination-delimiter",
+          type: :string,
+          desc: "the delimiter for destination folder names"
+        )
+        method_option(
+          "destination-prefix",
+          type: :string,
+          desc: "the prefix (namespace) to add to destination folder names",
+          aliases: ["-d"]
+        )
+        method_option(
+          "source-delimiter",
+          type: :string,
+          desc: "the delimiter for source folder names"
+        )
+        method_option(
+          "source-prefix",
+          type: :string,
+          desc: "the prefix (namespace) to strip from source folder names",
+          aliases: ["-s"]
+        )
+        # Keeps one email account in line with another
+        # @return [void]
+        def mirror(source_email, destination_email)
+          non_logging_options = Imap::Backup::Logger.setup_logging(options)
+          CLI::Transfer.new(:mirror, source_email, destination_email, non_logging_options).run
+        end
+      end
+    end
+  end
+end

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

@@ -88,7 +88,7 @@ module Imap::Backup
       "password-environment-variable",
       type: :string,
       desc: "an environment variable that is set to your password",
-      aliases: ["-e"]
+      aliases: ["-w"]
     )
     method_option(
       "password-file",
@@ -137,7 +137,7 @@ module Imap::Backup
       "mirror",
       type: :boolean,
       desc: "if this option is given, " \
-            "emails that are removed from the server " \
+            "existing backed-up emails that are no longer on the server " \
             "will be removed from the local backup.",
       aliases: ["-m"]
     )

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

@@ -13,7 +13,7 @@ module Imap::Backup
     include CLI::Helpers
 
     # The possible values for the action parameter
-    ACTIONS = %i(migrate mirror).freeze
+    ACTIONS = %i(copy migrate mirror).freeze
 
     def initialize(action, source_email, destination_email, options)
       @action = action
@@ -39,14 +39,17 @@ module Imap::Backup
       raise "Unknown action '#{action}'" if !ACTIONS.include?(action)
 
       process_options!
-      prepare_mirror if action == :mirror
+      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).run
+          Mirror.new(serializer, folder, reset: true).run
         end
       end
     end
@@ -123,9 +126,7 @@ module Imap::Backup
       self.source_prefix ||= ""
     end
 
-    def prepare_mirror
-      warn_if_source_account_is_not_in_mirror_mode
-
+    def run_backup
       CLI::Backup.new(config: config_path, accounts: source_email).run
     end
 

data/lib/imap/backup/cli.rb

@@ -12,6 +12,8 @@ module Imap::Backup
 
     autoload :Backup, "imap/backup/cli/backup"
     autoload :Local, "imap/backup/cli/local"
+    autoload :Migrate, "imap/backup/cli/migrate"
+    autoload :Mirror, "imap/backup/cli/mirror"
     autoload :Remote, "imap/backup/cli/remote"
     autoload :Restore, "imap/backup/cli/restore"
     autoload :Setup, "imap/backup/cli/setup"
@@ -22,28 +24,6 @@ module Imap::Backup
 
     include Helpers
 
-    NAMESPACE_CONFIGURATION_DESCRIPTION = <<~DESC.freeze
-      Some IMAP servers use namespaces (i.e. prefixes like "INBOX"),
-      while others, while others concatenate the names of subfolders
-      with a charater ("delimiter") other than "/".
-
-      In these cases there are two choices.
-
-      You can use the `--automatic-namespaces` option.
-      This will query the source and detination servers for their
-      namespace configuration and will adapt paths accordingly.
-      This option requires that both the source and destination
-      servers are available and work with the provided parameters
-      and authentication.
-
-      If automatic configuration does not work as desired, there are the
-      `--source-prefix=`, `--source-delimiter=`,
-      `--destination-prefix=` and `--destination-delimiter=` parameters.
-      To check what values you should use, check the output of the
-      `imap-backup remote namespaces EMAIL` command.
-    DESC
-    private_constant :NAMESPACE_CONFIGURATION_DESCRIPTION
-
     default_task :backup
 
     # Overrides {https://www.rubydoc.info/gems/thor/Thor%2FBase%2FClassMethods:start Thor's method}
@@ -94,91 +74,31 @@ module Imap::Backup
       Backup.new(non_logging_options).run
     end
 
-    desc "local SUBCOMMAND [OPTIONS]", "View local info"
-    subcommand "local", Local
-
     desc(
-      "migrate SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
-      "Uploads backed-up emails from account SOURCE_EMAIL to account DESTINATION_EMAIL"
+      "copy SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
+      "Copies emails from the SOURCE account to the DESTINATION account, avoiding duplicates"
     )
     long_desc <<~DESC
-      All emails which have been backed up for the "source account" (SOURCE_EMAIL) are
-      uploaded to the "destination account" (DESTINATION_EMAIL).
-
-      Some configuration may be necessary, as follows:
-
-      #{NAMESPACE_CONFIGURATION_DESCRIPTION}
-
-      Finally, if you want to delete existing emails in destination folders,
-      use the `--reset` option. In this case, all existing emails are
-      deleted before uploading the migrated emails.
-    DESC
-    config_option
-    quiet_option
-    verbose_option
-    method_option(
-      "automatic-namespaces",
-      type: :boolean,
-      desc: "automatically choose delimiters and prefixes"
-    )
-    method_option(
-      "destination-delimiter",
-      type: :string,
-      desc: "the delimiter for destination folder names"
-    )
-    method_option(
-      "destination-prefix",
-      type: :string,
-      desc: "the prefix (namespace) to add to destination folder names",
-      aliases: ["-d"]
-    )
-    method_option(
-      "reset",
-      type: :boolean,
-      desc: "DANGER! This option deletes all messages from destination folders before uploading",
-      aliases: ["-r"]
-    )
-    method_option(
-      "source-delimiter",
-      type: :string,
-      desc: "the delimiter for source folder names"
-    )
-    method_option(
-      "source-prefix",
-      type: :string,
-      desc: "the prefix (namespace) to strip from source folder names",
-      aliases: ["-s"]
-    )
-    # Migrates emails from one account to another
-    # @return [void]
-    def migrate(source_email, destination_email)
-      non_logging_options = Imap::Backup::Logger.setup_logging(options)
-      Transfer.new(:migrate, source_email, destination_email, non_logging_options).run
-    end
+      This command copies messages from the SOURCE_EMAIL account
+      to the DESTINATION_EMAIL account. It keeps track of copied
+      messages and avoids duplicate copies.
 
-    desc(
-      "mirror SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
-      "Keeps the DESTINATION_EMAIL account aligned with the SOURCE_EMAIL account"
-    )
-    long_desc <<~DESC
-      This command updates the DESTINATION_EMAIL account's folders to have the same contents
-      as those on the SOURCE_EMAIL account.
+      Any other messages that are present on the DESTINATION_EMAIL account
+      are not affected.
 
       If a folder list is configured for the SOURCE_EMAIL account,
       only the folders indicated by the setting are copied.
 
       First, it runs the download of the SOURCE_EMAIL account.
-      If the SOURCE_EMAIL account is **not** configured to be in 'mirror' mode,
-      a warning is printed.
 
-      When the mirror command is used, for each folder that is processed,
+      When the copy command is used, for each folder that is processed,
       a new file is created alongside the normal backup files (.imap and .mbox)
       This file has a '.mirror' extension. This file contains a mapping of
       the known UIDs on the source account to those on the destination account.
 
       Some configuration may be necessary, as follows:
 
-      #{NAMESPACE_CONFIGURATION_DESCRIPTION}
+      #{Helpers::NAMESPACE_CONFIGURATION_DESCRIPTION}
     DESC
     config_option
     quiet_option
@@ -210,13 +130,19 @@ module Imap::Backup
       desc: "the prefix (namespace) to strip from source folder names",
       aliases: ["-s"]
     )
-    # Keeps one email account in line with another
+    # Copies messages from one email account to another
     # @return [void]
-    def mirror(source_email, destination_email)
+    def copy(source_email, destination_email)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
-      Transfer.new(:mirror, source_email, destination_email, non_logging_options).run
+      Transfer.new(:copy, source_email, destination_email, non_logging_options).run
     end
 
+    desc "local SUBCOMMAND [OPTIONS]", "View local info"
+    subcommand "local", Local
+
+    include Migrate
+    include Mirror
+
     desc "remote SUBCOMMAND [OPTIONS]", "View info about online accounts"
     subcommand "remote", Remote
 

data/lib/imap/backup/mirror.rb

@@ -5,9 +5,10 @@ module Imap; end
 module Imap::Backup
   # Synchronises a folder between a source and destination
   class Mirror
-    def initialize(serializer, folder)
+    def initialize(serializer, folder, reset: false)
       @serializer = serializer
       @folder = folder
+      @reset = reset
     end
 
     # If necessary, reates the destination folder,
@@ -19,7 +20,7 @@ module Imap::Backup
     # @return [void]
     def run
       ensure_destination_folder
-      delete_destination_only_emails
+      delete_destination_only_emails if reset
       update_flags
       append_emails
       map.save
@@ -31,6 +32,7 @@ module Imap::Backup
 
     attr_reader :serializer
     attr_reader :folder
+    attr_reader :reset
 
     def ensure_destination_folder
       return if folder.exist?
@@ -90,7 +92,7 @@ module Imap::Backup
             destination: folder.uid_validity
           )
           if !map_ok
-            folder.clear
+            folder.clear if reset
             map.reset(
               source_uid_validity: serializer.uid_validity,
               destination_uid_validity: folder.uid_validity

data/lib/imap/backup/version.rb

@@ -2,13 +2,13 @@ module Imap; end
 
 module Imap::Backup
   # @private
-  MAJOR    = 15
+  MAJOR    = 16
   # @private
   MINOR    = 0
   # @private
-  REVISION = 3
+  REVISION = 0
   # @private
-  PRE      = "rc1".freeze
+  PRE      = nil
   # The application version
   VERSION  = [MAJOR, MINOR, REVISION, PRE].compact.map(&:to_s).join(".")
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 15.0.3.rc1
+  version: 16.0.0
 platform: ruby
 authors:
 - Joe Yates
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-15 00:00:00.000000000 Z
+date: 2025-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  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: mail
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  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: rake
   requirement: !ruby/object:Gem::Requirement
@@ -153,6 +181,8 @@ files:
 - lib/imap/backup/cli/helpers.rb
 - lib/imap/backup/cli/local.rb
 - lib/imap/backup/cli/local/check.rb
+- lib/imap/backup/cli/migrate.rb
+- lib/imap/backup/cli/mirror.rb
 - lib/imap/backup/cli/options.rb
 - lib/imap/backup/cli/remote.rb
 - lib/imap/backup/cli/restore.rb
@@ -234,7 +264,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Backup GMail (or other IMAP) accounts to disk