imap-backup 11.1.0 → 12.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdcbbac2458c28626fdf8be328db6f949be5cf981fde3438df03356b28849ebf
-  data.tar.gz: 1ed5fc6db436f57c30e03a5036a61c2fa21853cd2d7ae08b861b491b04b6d12b
+  metadata.gz: 22cd34d9d0940821677b2007473b2608421dda521dd47f212346385eba4ea6de
+  data.tar.gz: 3f249c818af7260fa15f8ed1509f2151876bddb28544f401c5264d9c74be1f74
 SHA512:
-  metadata.gz: a60997a5fdee3274d726e54c413c7b0e38df97246f4619358128a6786f5a148414d7050a6d498b805cb5376fca3d555f232e90c10d15d092ea49dce6007272e7
-  data.tar.gz: 41b3038e096c34486670e423e6231cb4dd6eb8c39b035f8ce7580fb406bc6210ba8e436a51d51c61e67f9b5c3af3a971ad6ce016e1904850bdb14bc52e150f9c
+  metadata.gz: 8773c5878b741fb116bfc617b79b91f536c10c2406668f6ad0f544f2383e9215d163d37b7e8beec6e237310b72455bac63561e3d03b171cb4b11ca37624d6851
+  data.tar.gz: 3f6113d064ef19931eb32e1c71876e704ec3898f5657154fabe5626f13805ec1b209e3ff56ec2bd4c407f54cb22e0a590064f2ee9713b0dddfd5836c0371e1f9

data/docs/migrate-server-keep-address.md

@@ -1,29 +1,47 @@
 # Migrate to a new e-mail server while keeping your existing address
 
-While switching e-mail provider (from provider `A` to `B`), you might want to keep the same address (`mymail@domain.com`), and restrieve all your existing e-mails on your new server `B`. `imap-backup` can do that too!
+While switching e-mail provider (from provider `A` to `B`),
+you might want to keep the same address (`mymail@domain.com`),
+and copy all your existing e-mails to your new server `B`.
+`imap-backup` can do that too!
 
-1. Backup your e-mails: use [`imap-backup setup`](/docs/commands/setup.md) to setup connection to your old provider `A`, then launch [`imap-backup backup`](/docs/commands/backup.md). 
+It is best to use [`imap-backup migrate`](/docs/commands/migrate.md)
+and not [`imap-backup restore`](/docs/commands/restore.md) here because
+`migrate` simply copies emails to folders with the same name as the ones
+they were downloaded from, while `restore` changes the names of restored
+folders if folders with the same name already exist on the destination server.
+
+1. Backup your e-mails: use [`imap-backup setup`](/docs/commands/setup.md)
+  to setup connection to your old provider `A`,
+  then launch [`imap-backup backup`](/docs/commands/backup.md).
 1. Actually switch your e-mail service provider (update your DNS MX and all that...).
-1. It is best to use [`imap-backup migrate`](/docs/commands/migrate.md) and not [`imap-backup restore`](/docs/commands/restore.md) here, but both the source and the destination have the same address... You need to manually rename your old account first:
+1. As both the source and the destination have the same address,
+  you need to manually rename your old account first:
 
-	1. Modify your configuration file manually (i.e. not via `imap-backup setup`) and rename your account to `mymail-old@domain.com`:
+    1. Modify your configuration file manually
+      (i.e. not via `imap-backup setup`) and
+      rename your account to `mymail-old@domain.com`:
 
-		```diff
-		"accounts": [
-		{
-		-	"username": "mymail@domain.com",
-		+	"username": "mymail-old@domain.com",
-			"password": "...",
-		-	"local_path": "/some/path/.imap-backup/mymail_domain.com",
-		+	"local_path": "/some/path/.imap-backup/mymail-old_domain.com",
-			"folders": [...],
-			"server": "..."
-		}
-		```
+        ```diff
+          "accounts": [
+            {
+        -     "username": "mymail@domain.com",
+        +     "username": "mymail-old@domain.com",
+              "password": "...",
+        -     "local_path": "/some/path/.imap-backup/mymail_domain.com",
+        +     "local_path": "/some/path/.imap-backup/mymail-old_domain.com",
+              "folders": [...],
+              "server": "..."
+            }
+        ```
 
-	1. Rename the backup directory from `mymail_domain.com` to `mymail-old_domain.com`.
+    1. Rename the backup directory from `mymail_domain.com`
+      to `mymail-old_domain.com`.
 
-1. Set up a new account giving access to the new provider `B` using `imap-backup setup`.
-1. Now you can use `imap-backup migrate`, optionnally adapting [delimiters and prefixes configuration](/docs/delimiters-and-prefixes.md) if need be:
+1. Set up a new account giving access to the new provider `B`
+  using `imap-backup setup`.
+1. Now you can use `imap-backup migrate`, optionally adapting
+  [delimiters and prefixes configuration](/docs/delimiters-and-prefixes.md)
+  if need be:
 
-		imap-backup migrate mymail-old@domain.com mymail@domain.com [options]
+		imap-backup migrate mymail-old@domain.com mymail@domain.com [options]

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

@@ -20,7 +20,7 @@ module Imap::Backup
     def run
       Logger.logger.info "Running backup of account: #{account.username}"
       # start the connection so we get logging messages in the right order
-      account.client
+      account.client.login
 
       Account::FolderEnsurer.new(account: account).run
       Account::LocalOnlyFolderDeleter.new(account: account).run if account.mirror_mode

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

@@ -2,8 +2,8 @@ require "socket"
 
 require "email/provider"
 require "imap/backup/client/apple_mail"
+require "imap/backup/client/automatic_login_wrapper"
 require "imap/backup/client/default"
-require "retry_on_error"
 
 module Imap; end
 
@@ -11,10 +11,6 @@ module Imap::Backup
   class Account; end
 
   class Account::ClientFactory
-    include RetryOnError
-
-    LOGIN_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::SocketError].freeze
-
     attr_reader :account
 
     def initialize(account:)
@@ -24,20 +20,17 @@ module Imap::Backup
     end
 
     def run
-      retry_on_error(errors: LOGIN_RETRY_CLASSES) do
-        options = provider_options
-        Logger.logger.debug(
-          "Creating IMAP instance: #{server}, options: #{options.inspect}"
-        )
-        client =
-          if provider.is_a?(Email::Provider::AppleMail)
-            Client::AppleMail.new(server, account, options)
-          else
-            Client::Default.new(server, account, options)
-          end
-        client.login
-        client
-      end
+      options = provider_options
+      Logger.logger.debug(
+        "Creating IMAP instance: #{server}, options: #{options.inspect}"
+      )
+      client =
+        if provider.is_a?(Email::Provider::AppleMail)
+          Client::AppleMail.new(server, account, options)
+        else
+          Client::Default.new(server, account, options)
+        end
+      Client::AutomaticLoginWrapper.new(client: client)
     end
 
     private

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

@@ -35,6 +35,7 @@ module Imap::Backup
       end
 
       def stats
+        Logger.logger.debug("[Stats] loading configuration")
         config = load_config(**options)
         account = account(config, email)
 
@@ -46,6 +47,7 @@ module Imap::Backup
 
           serializer = Serializer.new(account.local_path, folder.name)
           local_uids = serializer.uids
+          Logger.logger.debug("[Stats] fetching email list for '#{folder.name}'")
           remote_uids = folder.uids
           {
             folder: folder.name,

data/lib/imap/backup/cli.rb

@@ -211,9 +211,14 @@ module Imap::Backup
 
     desc "stats EMAIL [OPTIONS]", "Print stats for each account folder"
     long_desc <<~DESC
-      For each account folder, lists emails that are yet to be downloaded "server",
-      are downloaded (exist on server and locally) "both" and those which
-      are only present in the backup (as they have been deleted on the server) "local".
+      For each account folder, lists three counts of emails:
+
+      1. "server" - those yet to be downloaded,
+
+      2. "both" - those that exist on server and are backed up,
+
+      3. "local" - those which are only present in the backup (as they have been deleted
+        on the server).
     DESC
     config_option
     format_option

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

@@ -0,0 +1,43 @@
+require "retry_on_error"
+
+module Imap; end
+
+module Imap::Backup
+  module Client; end
+
+  class Client::AutomaticLoginWrapper
+    include RetryOnError
+
+    LOGIN_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::SocketError].freeze
+
+    attr_reader :client
+    attr_reader :login_called
+
+    def initialize(client:)
+      @client = client
+      @login_called = false
+    end
+
+    def method_missing(method_name, *arguments, &block)
+      if login_called
+        client.send(method_name, *arguments, &block)
+      else
+        do_first_login
+        client.send(method_name, *arguments, &block) if method_name != :login
+      end
+    end
+
+    def respond_to_missing?(method_name, _include_private = false)
+      client.respond_to?(method_name)
+    end
+
+    private
+
+    def do_first_login
+      retry_on_error(errors: LOGIN_RETRY_CLASSES) do
+        client.login
+        @login_called = true
+      end
+    end
+  end
+end

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

@@ -29,7 +29,7 @@ module Imap::Backup
       rollback_on_error do
         serialized = to_serialized(message)
         mbox.append serialized
-        imap.append uid, serialized.length, flags: flags
+        imap.append uid, serialized.bytesize, flags: flags
       rescue StandardError => e
         raise <<-ERROR.gsub(/^\s*/m, "")
           [#{folder}] failed to append message #{uid}: #{message}.

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

@@ -33,7 +33,7 @@ module Imap::Backup
       tsx.fail_outside_transaction!(:append)
       mboxrd_message = Email::Mboxrd::Message.new(message)
       serialized = mboxrd_message.to_serialized
-      tsx.data[:metadata] << {uid: uid, length: serialized.length, flags: flags}
+      tsx.data[:metadata] << {uid: uid, length: serialized.bytesize, flags: flags}
       mbox.append(serialized)
     end
 

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

@@ -15,6 +15,9 @@ module Imap::Backup
     end
 
     def run
+      Logger.logger.debug(
+        "[IntegrityChecker] checking '#{imap.pathname}' against '#{mbox.pathname}'"
+      )
       if !imap.valid?
         message = ".imap file '#{imap.pathname}' is corrupt"
         raise Serializer::FolderIntegrityError, message
@@ -56,14 +59,18 @@ module Imap::Backup
     def check_mbox_length!
       last = imap.messages[-1]
 
-      if mbox.length < last.offset + last.length
+      expected = last.offset + last.length
+      Logger.logger.debug(
+        "[IntegrityChecker] mbox length is #{mbox.length}, expected length is #{expected}"
+      )
+      if mbox.length < expected
         message =
           ".mbox file '#{mbox.pathname}' is shorter than indicated by " \
           ".imap file '#{imap.pathname}'"
         raise Serializer::FolderIntegrityError, message
       end
 
-      if mbox.length > last.offset + last.length
+      if mbox.length > expected
         message =
           ".mbox file '#{mbox.pathname}' is longer than indicated by " \
           ".imap file '#{imap.pathname}'"
@@ -77,6 +84,11 @@ module Imap::Backup
 
         next if text.start_with?("From ")
 
+        Logger.logger.debug(
+          "[IntegrityChecker] looking for message with UID #{m.uid} " \
+          "at offset #{m.offset}, " \
+          "mbox starts with '#{text[0..200]}', expecting 'From '"
+        )
         message =
           "Message #{m.uid} not found at expected offset #{m.offset} " \
           "in file '#{mbox.pathname}'"

data/lib/imap/backup/setup/global_options/download_strategy_chooser.rb

@@ -7,11 +7,9 @@ class Imap::Backup::Setup; end
 class Imap::Backup::Setup::GlobalOptions
   class DownloadStrategyChooser
     attr_reader :config
-    attr_reader :highline
 
-    def initialize(config:, highline:)
+    def initialize(config:)
       @config = config
-      @highline = highline
     end
 
     def run
@@ -81,5 +79,9 @@ class Imap::Backup::Setup::GlobalOptions
         highline.ask "Press a key "
       end
     end
+
+    def highline
+      Imap::Backup::Setup.highline
+    end
   end
 end

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

@@ -8,11 +8,9 @@ module Imap::Backup
 
   class Setup::GlobalOptions
     attr_reader :config
-    attr_reader :highline
 
-    def initialize(config:, highline:)
+    def initialize(config:)
       @config = config
-      @highline = highline
     end
 
     def run
@@ -46,8 +44,12 @@ module Imap::Backup
       current = strategies.find { |s| s[:key] == config.download_strategy }
       changed = config.download_strategy_modified ? " *" : ""
       menu.choice("change download strategy (currently: '#{current[:description]}')#{changed}") do
-        DownloadStrategyChooser.new(config: config, highline: Setup.highline).run
+        DownloadStrategyChooser.new(config: config).run
       end
     end
+
+    def highline
+      Imap::Backup::Setup.highline
+    end
   end
 end

data/lib/imap/backup/setup.rb

@@ -76,7 +76,7 @@ module Imap::Backup
     def modify_global_options(menu)
       changed = config.modified? ? " *" : ""
       menu.choice("modify global options#{changed}") do
-        GlobalOptions.new(config: config, highline: Setup.highline).run
+        GlobalOptions.new(config: config).run
       end
     end
 

data/lib/imap/backup/version.rb

@@ -1,8 +1,8 @@
 module Imap; end
 
 module Imap::Backup
-  MAJOR    = 11
-  MINOR    = 1
+  MAJOR    = 12
+  MINOR    = 0
   REVISION = 0
   PRE      = nil
   VERSION  = [MAJOR, MINOR, REVISION, PRE].compact.map(&:to_s).join(".")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 11.1.0
+  version: 12.0.0
 platform: ruby
 authors:
 - Joe Yates
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-31 00:00:00.000000000 Z
+date: 2023-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -255,6 +255,7 @@ files:
 - lib/imap/backup/cli/stats.rb
 - lib/imap/backup/cli/utils.rb
 - lib/imap/backup/client/apple_mail.rb
+- lib/imap/backup/client/automatic_login_wrapper.rb
 - lib/imap/backup/client/default.rb
 - lib/imap/backup/configuration.rb
 - lib/imap/backup/downloader.rb