imap-backup 9.2.0 → 9.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2817e61358b848f7dbef08e1a16562def8cd364e66d317e4dac56c1f5e62f958
-  data.tar.gz: ec0e2d2963e863b204b0529ca3746492703486e8f77a9e7c08bc301b203249de
+  metadata.gz: 0f01e9469da5b4990bdcc90f5e019b0cf5e9cf06203f29980503edabdec4abb8
+  data.tar.gz: 93501685a083a9b3edc8f1bb606decf7bcac965773063eb9e59863f3afa43113
 SHA512:
-  metadata.gz: 66871fce3faebbcbd87737fef230803b46f32025b28753fe4f83813e652ef14817fce302da0570000f0d0ecb582862589a84f535a94aa1fa7cc1578eaf30591c
-  data.tar.gz: 274cfc47767322e31eb1e7206c3d1d449b2098ba1a65073c80aa5010c06924abfc7a952aeace01436715a7f95599503d86bcecbbdf210f7c8b5529bf7bee4fdf
+  metadata.gz: 494089b738a8ca9080c1057b4bdc5a8ebe8d2900e756fbd2c16445d856e3939da759bd8bc644585f8d6591055a79656b92a44b60cb0a522a87023d30f6b49ca9
+  data.tar.gz: fa3e100e307103808360797853953cfec677bbd6ee3b9b36330f2449ef065a5e128660154e6d3593a34652f6753a553bf4697e145c60a3e728645acb67477de3

data/README.md

@@ -76,6 +76,7 @@ and exported via [utils export-to-thunderbird](docs/commands/utils-export-to-thu
 
 * [backup](docs/commands/backup.md)
 * [local accounts](docs/commands/local-accounts.md)
+* [local check](docs/commands/local-check.md)
 * [local folders](docs/commands/local-folders.md)
 * [local list](docs/commands/local-list.md)
 * [local show](docs/commands/local-show.md)

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

@@ -0,0 +1,29 @@
+# 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!
+
+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. 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": "..."
+		}
+		```
+
+	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:
+
+		imap-backup migrate mymail-old@domain.com mymail@domain.com [options]

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

@@ -14,6 +14,8 @@ module Imap::Backup
     BODY_ATTRIBUTE = "BODY[]".freeze
     UID_FETCH_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
     PERMITTED_FLAGS = %i(Answered Draft Flagged Seen).freeze
 
     attr_reader :connection
@@ -33,7 +35,9 @@ module Imap::Backup
     end
 
     def exist?
-      examine
+      retry_on_error(errors: EXAMINE_RETRY_CLASSES) do
+        examine
+      end
       true
     rescue FolderNotFound
       false
@@ -42,7 +46,9 @@ module Imap::Backup
     def create
       return if exist?
 
-      client.create(utf7_encoded_name)
+      retry_on_error(errors: CREATE_RETRY_CLASSES) do
+        client.create(utf7_encoded_name)
+      end
     end
 
     def uid_validity

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

@@ -85,6 +85,8 @@ module Imap::Backup
     end
 
     def each_connection(config, names)
+      return enum_for(:each_connection, config, names) if !block_given?
+
       config.accounts.each do |account|
         next if names.any? && !names.include?(account.username)
 

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

@@ -20,6 +20,47 @@ module Imap::Backup
       end
     end
 
+    desc(
+      "check",
+      "Check the integrity of backups for all accounts (or the selected account(s))"
+    )
+    method_option(
+      "delete_corrupt",
+      type: :boolean,
+      desc: "deletes any corrupted folders - USE WITH CAUTION!"
+    )
+    config_option
+    format_option
+    def check
+      config = load_config(**options)
+      results = each_connection(config, emails).map do |connection|
+        folders = connection.local_folders
+        folder_results = folders.map do |serializer|
+          serializer.check_integrity!
+          {name: serializer.folder, result: "OK"}
+        rescue Serializer::FolderIntegrityError => e
+          message = e.to_s
+          if options[:delete_corrupt]
+            serializer.delete
+            message << " and has been deleted"
+          end
+
+          {
+            name: serializer.folder,
+            result: message
+          }
+        end
+        {account: connection.account.username, folders: folder_results}
+      end
+
+      case options[:format]
+      when "json"
+        print_check_results_as_json(results)
+      else
+        print_check_results_as_text(results)
+      end
+    end
+
     desc "folders EMAIL", "List backed up folders"
     config_option
     format_option
@@ -87,6 +128,19 @@ module Imap::Backup
     end
 
     no_commands do
+      def print_check_results_as_json(results)
+        Kernel.puts results.to_json
+      end
+
+      def print_check_results_as_text(results)
+        results.each do |account_results|
+          Kernel.puts "Account: #{account_results[:account]}"
+          account_results[:folders].each do |folder_results|
+            Kernel.puts "\t#{folder_results[:name]}: #{folder_results[:result]}"
+          end
+        end
+      end
+
       def list_emails_as_json(serializer)
         emails = serializer.each_message.map do |message|
           {
@@ -142,6 +196,10 @@ module Imap::Backup
           Kernel.puts message.body
         end
       end
+
+      def emails
+        (options[:accounts] || "").split(",")
+      end
     end
   end
 end

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

@@ -12,7 +12,7 @@ module Imap::Backup
     quiet_option
     verbose_option
     def ignore_history(email)
-      Imap::Backup::Logger.setup_logging options
+      Logger.setup_logging options
       config = load_config(**options)
       connection = connection(config, email)
 

data/lib/imap/backup/cli.rb

@@ -22,6 +22,21 @@ module Imap::Backup
 
     default_task :backup
 
+    def self.start(*args)
+      # By default, commands like `imap-backup help foo bar`
+      # are handled by listing all `foo` methods, whereas the user
+      # probably wants the detailed help for the `bar` method.
+      # Move initial "help" argument to after any subcommand,
+      # so we get help for the requested subcommand method.
+      first_argument_is_help = ARGV[0] == "help"
+      second_argument_is_subcommand = subcommands.include?(ARGV[1])
+      if first_argument_is_help && second_argument_is_subcommand
+        help, subcommand = ARGV.shift(2)
+        ARGV.unshift(subcommand, help)
+      end
+      super
+    end
+
     def self.exit_on_failure?
       true
     end

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

@@ -15,6 +15,14 @@ module Imap::Backup
       @version = nil
     end
 
+    def pathname
+      "#{folder_path}.imap"
+    end
+
+    def exist?
+      File.exist?(pathname)
+    end
+
     def valid?
       return false if !exist?
       return false if version != CURRENT_VERSION
@@ -114,14 +122,6 @@ module Imap::Backup
 
     private
 
-    def pathname
-      "#{folder_path}.imap"
-    end
-
-    def exist?
-      File.exist?(pathname)
-    end
-
     def ensure_loaded
       return if loaded
 

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

@@ -59,8 +59,6 @@ module Imap::Backup
       File.open(pathname, "a") {}
     end
 
-    private
-
     def exist?
       File.exist?(pathname)
     end

data/lib/imap/backup/serializer.rb

@@ -19,6 +19,8 @@ module Imap::Backup
 
     extend Forwardable
 
+    class FolderIntegrityError < StandardError; end
+
     def_delegator :mbox, :pathname, :mbox_pathname
     def_delegators :imap, :get, :messages, :uid_validity, :uids, :update_uid
 
@@ -42,6 +44,57 @@ module Imap::Backup
       false
     end
 
+    def check_integrity!
+      if !imap.valid?
+        message = ".imap file '#{imap.pathname}' is corrupt"
+        raise FolderIntegrityError, message
+      end
+
+      if !mbox.exist?
+        message = ".mbox file '#{mbox.pathname}' is missing"
+        raise FolderIntegrityError, message
+      end
+
+      return if imap.messages.empty?
+
+      offsets = imap.messages.map(&:offset)
+
+      if offsets != offsets.sort
+        message = ".imap file '#{imap.pathname}' has offset data which is out of order"
+        raise FolderIntegrityError, message
+      end
+
+      if mbox.length < offsets[-1]
+        message =
+          ".imap file '#{imap.pathname}' has offsets past the end " \
+          "of .mbox file '#{mbox.pathname}'"
+        raise FolderIntegrityError, message
+      end
+
+      imap.messages.each do |m|
+        text = mbox.read(m.offset, m.length)
+        if text.length < m.length
+          message = "Message #{m.uid} is incomplete in file '#{mbox.pathname}'"
+          raise FolderIntegrityError, message
+        end
+
+        next if text.start_with?("From ")
+
+        message =
+          "Message #{m.uid} not found at expected offset #{m.offset} " \
+          "in file '#{mbox.pathname}'"
+        raise FolderIntegrityError, message
+      end
+
+      last = imap.messages.last
+      expected_length = last.offset + last.length
+      actual_length = mbox.length
+      return if actual_length == expected_length
+
+      message = "Mbox file '#{mbox.pathname}' contains unexpected trailing data"
+      raise FolderIntegrityError, message
+    end
+
     def delete
       imap.delete
       @imap = nil

data/lib/imap/backup/version.rb

@@ -2,8 +2,8 @@ module Imap; end
 
 module Imap::Backup
   MAJOR    = 9
-  MINOR    = 2
-  REVISION = 0
+  MINOR    = 3
+  REVISION = 1
   PRE      = nil
   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: 9.2.0
+  version: 9.3.1
 platform: ruby
 authors:
 - Joe Yates
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-01 00:00:00.000000000 Z
+date: 2023-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -219,6 +219,7 @@ files:
 - bin/imap-backup
 - docs/delimiters-and-prefixes.md
 - docs/development.md
+- docs/migrate-server-keep-address.md
 - imap-backup.gemspec
 - lib/cli_coverage.rb
 - lib/email/mboxrd/message.rb