imap-backup 16.4.1 → 16.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3ffe8d1bd32587d59e12a514b005d68175244e2cb73a9d138dd3a5d273c785f
-  data.tar.gz: 62d6364641799f1ce20466affc34052f8614a2a2d5633f53a05b4cac31a4e0f3
+  metadata.gz: fc471fce2bd514e0eee4cec922e8f368df0b2fb99f8b89b2d852e07799a2be77
+  data.tar.gz: fd563c2ee648d5e384a10cdfc79a7d1d5be128bdce5908711396d414c801173f
 SHA512:
-  metadata.gz: f4fdd4254948ef5dd7fba17e3683aa13bf84a19a77ffd935bad3f830355d4bf0d14ff48c731be2542ce56332ed8b4903b1b7971a16e7e947f4406ba4473b4a44
-  data.tar.gz: 4ca3ca9bb9eda64a9b8b9a6cc0889e5815f446e2a798f762f1d55e228928e99988c186bdaad4dfd7d033cd21667de7d906ea3cbd1f11d947dc77d68f4bbd1090
+  metadata.gz: 36088caab383a7ff2528d8ad83813f58918abda4d80a56b0f2b2f1f45d5fc840934d1bc31e1907de11cc665f5aecb5b12152bb8dee686fb656294eb55440897e
+  data.tar.gz: 389a82b7755342dd591fd0e2d45d760eb8350f697d46414d8d90776624bd0ee7263acfe163ab1e8dd42c869d12a544c2d5faa4656d4ef5c802f4991b9f33c1b4

data/imap-backup.gemspec

@@ -30,7 +30,7 @@ Gem::Specification.new do |gem|
   gem.add_dependency "rake"
   gem.add_dependency "sys-proctable"
   gem.add_dependency "thor", "~> 1.1"
-  gem.add_dependency "thunderbird", "0.3.0"
+  gem.add_dependency "thunderbird", "~> 0.6.0"
 
   gem.metadata = {
     "rubygems_mfa_required" => "true"

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

@@ -1,6 +1,5 @@
 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"
 
@@ -25,7 +24,7 @@ module Imap::Backup
       # start the connection so we get logging messages in the right order
       account.client.login
 
-      ensure_folder
+      ensure_directory
       delete_local_only_folders if account.mirror_mode
 
       if backup_folders.none?
@@ -53,8 +52,8 @@ module Imap::Backup
       Account::LocalOnlyFolderDeleter.new(account: account).run
     end
 
-    def ensure_folder
-      Account::FolderEnsurer.new(account: account).run
+    def ensure_directory
+      Serializer::DirectoryMaker.new(files_path: account.files_path).run
     end
 
     def locker

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

@@ -4,6 +4,7 @@ require "imap/backup/flag_refresher"
 require "imap/backup/local_only_message_deleter"
 require "imap/backup/logger"
 require "imap/backup/serializer"
+require "imap/backup/serializer/files/path"
 
 module Imap; end
 
@@ -86,7 +87,12 @@ module Imap::Backup
     end
 
     def raw_serializer
-      @raw_serializer ||= Serializer.new(account.local_path, folder.name)
+      @raw_serializer ||= begin
+        path = Serializer::Files::Path.new(
+          base_path: account.local_path, folder_name: folder.name
+        )
+        Serializer.new(files_path: path)
+      end
     end
   end
 end

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

@@ -3,6 +3,7 @@ require "pathname"
 
 require "imap/backup/account/folder"
 require "imap/backup/serializer"
+require "imap/backup/serializer/files/path"
 
 module Imap; end
 
@@ -44,7 +45,10 @@ module Imap::Backup
       glob = File.join(source_local_path, "**", "*.imap")
       Pathname.glob(glob) do |path|
         name = source_folder_name(path)
-        serializer = Serializer.new(source_local_path, name)
+        path = Serializer::Files::Path.new(
+          base_path: source_local_path, folder_name: name
+        )
+        serializer = Serializer.new(files_path: path)
         folder = destination_folder_for_path(name)
         block.call(serializer, folder)
       end

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

@@ -1,4 +1,3 @@
-require "imap/backup/account/folder_ensurer"
 require "imap/backup/lockfile"
 
 module Imap; end
@@ -25,7 +24,7 @@ module Imap::Backup
         Logger.logger.info("Stale lockfile '#{account.lockfile_path}' found. Removing it.")
         lockfile.remove
       else
-        Account::FolderEnsurer.new(account: account).run
+        Serializer::DirectoryMaker.new(files_path: account.files_path).run
       end
 
       begin

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

@@ -1,8 +1,9 @@
 require "pathname"
 
 require "imap/backup/account/folder"
-require "imap/backup/account/folder_ensurer"
 require "imap/backup/serializer"
+require "imap/backup/serializer/directory_maker"
+require "imap/backup/serializer/files/path"
 
 module Imap; end
 
@@ -27,7 +28,10 @@ module Imap::Backup
 
       glob.each do |path|
         name = path.relative_path_from(base).to_s[0..-6]
-        serializer = Serializer.new(account.local_path, name)
+        files_path = Serializer::Files::Path.new(
+          base_path: account.local_path, folder_name: name
+        )
+        serializer = Serializer.new(files_path: files_path)
         folder = Account::Folder.new(account.client, name)
         block.call(serializer, folder)
       end
@@ -41,7 +45,10 @@ module Imap::Backup
 
       glob.each do |path|
         name = path.relative_path_from(base).to_s[0..-6]
-        serializer = Serializer.new(account.local_path, name)
+        files_path = Serializer::Files::Path.new(
+          base_path: account.local_path, folder_name: name
+        )
+        serializer = Serializer.new(files_path: files_path)
         block.call(serializer)
       end
     end
@@ -69,7 +76,10 @@ module Imap::Backup
 
     def glob
       @glob ||= begin
-        Account::FolderEnsurer.new(account: account).run
+        files_path = Serializer::Files::Path.new(
+          base_path: account.local_path, folder_name: nil
+        )
+        Serializer::DirectoryMaker.new(files_path: files_path).run
 
         pattern = File.join(account.local_path, "**", "*.imap")
         Pathname.glob(pattern)

data/lib/imap/backup/account.rb

@@ -4,7 +4,6 @@ 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
@@ -188,6 +187,11 @@ module Imap::Backup
       update(:local_path, value)
     end
 
+    # @return [Serializer::Files::Path] the base files path for the account
+    def files_path
+      Serializer::Files::Path.new(base_path: local_path, folder_name: nil)
+    end
+
     # @raise [RuntimeError] if the local_path is not set
     # @return [String] the path to the lockfile for the account
     def lockfile_path

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

@@ -3,6 +3,7 @@ require "thor"
 require "imap/backup/account/backup_folders"
 require "imap/backup/cli/helpers"
 require "imap/backup/serializer"
+require "imap/backup/serializer/files/path"
 
 module Imap; end
 
@@ -63,7 +64,10 @@ module Imap::Backup
       backup_folders.map do |folder|
         next if !folder.exist?
 
-        serializer = Serializer.new(account.local_path, folder.name)
+        path = Serializer::Files::Path.new(
+          base_path: account.local_path, folder_name: folder.name
+        )
+        serializer = Serializer.new(files_path: path)
         local_uids = serializer.uids
         Logger.logger.debug("[Stats] fetching email list for '#{folder.name}'")
         remote_uids = folder.uids

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

@@ -7,6 +7,7 @@ require "imap/backup/cli/helpers"
 require "imap/backup/logger"
 require "imap/backup/serializer"
 require "imap/backup/thunderbird/mailbox_exporter"
+require "imap/backup/serializer/files/path"
 
 module Imap; end
 
@@ -103,7 +104,10 @@ module Imap::Backup
       backup_folders.each do |folder|
         next if !folder.exist?
 
-        serializer = Serializer.new(account.local_path, folder.name)
+        path = Serializer::Files::Path.new(
+          base_path: account.local_path, folder_name: folder.name
+        )
+        serializer = Serializer.new(files_path: path)
         ignore_folder_history(folder, serializer)
       end
     end
@@ -126,18 +130,41 @@ module Imap::Backup
     end
 
     def thunderbird_profile(name = nil)
+      Logger.logger.info("[CLI::Utils] Fetching Thunderbird profile")
       profiles = ::Thunderbird::Profiles.new
+      Logger.logger.debug("[CLI::Utils] Found #{profiles.installs.count} Thunderbird install(s)")
       if name
+        Logger.logger.debug("[CLI::Utils] Using profile name '#{name}'")
         profiles.profile(name)
       else
-        if profiles.installs.count > 1
-          raise <<~MESSAGE
-            Thunderbird has multiple installs, so no default profile exists.
-            Please supply a profile name
-          MESSAGE
-        end
-
-        profiles.installs[0].default
+        choose_default_profile(profiles)
+      end
+    end
+
+    def choose_default_profile(profiles)
+      Logger.logger.debug("[CLI::Utils] No profile name supplied, so looking for default profile")
+      case profiles.installs.count
+      when 0
+        raise "No Thunderbird installs found, so no default profile exists"
+      when 1
+        install = profiles.installs.first
+        Logger.logger.debug(
+          "[CLI::Utils] Only one Thunderbird install found '#{install.title}', " \
+          "so using its default profile"
+        )
+
+        profile = install.default_profile
+        raise "Thunderbird install '#{install.title}' does not have a default profile" if !profile
+
+        Logger.logger.debug(
+          "[CLI::Utils] Default profile '#{profile.title}' has path '#{profile.root}'"
+        )
+        profile
+      else
+        raise <<~MESSAGE
+          Thunderbird has multiple installs, so no default profile exists.
+          Please supply a profile name
+        MESSAGE
       end
     end
   end

data/lib/imap/backup/mirror.rb

@@ -106,7 +106,7 @@ module Imap::Backup
     end
 
     def map_pathname
-      "#{serializer.folder_path}.mirror"
+      "#{serializer.files_path}.mirror"
     end
 
     def destination_email

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

@@ -7,13 +7,9 @@ module Imap::Backup
 
   # Appends messages to the local store
   class Serializer::Appender
-    # @param folder [String] the name of the folder
-    # @param imap [Serializer::Imap] the metadata serializer for the folder
-    # @param mbox [Serializer::Mbox] the folder's mailbox
-    def initialize(folder:, imap:, mbox:)
-      @folder = folder
-      @imap = imap
-      @mbox = mbox
+    # @param files [Serializer::Files] the folder's files
+    def initialize(files:)
+      @files = files
     end
 
     # Adds a message to the metadata file and the mailbox.
@@ -31,7 +27,7 @@ module Imap::Backup
       existing = imap.get(uid)
       if existing
         Logger.logger.debug(
-          "[#{folder}] message #{uid} already downloaded - skipping"
+          "[#{files.files_path}] message #{uid} already downloaded - skipping"
         )
         return
       end
@@ -42,7 +38,7 @@ module Imap::Backup
         raise wrap_error(
           error: e,
           note: "failed to serialize message",
-          folder: folder,
+          files_path: files.files_path,
           uid: uid,
           message: message
         )
@@ -55,7 +51,7 @@ module Imap::Backup
         raise wrap_error(
           error: e,
           note: "failed to append message",
-          folder: folder,
+          files_path: files.files_path,
           uid: uid,
           message: message
         )
@@ -64,13 +60,19 @@ module Imap::Backup
 
     private
 
-    attr_reader :imap
-    attr_reader :folder
-    attr_reader :mbox
+    attr_reader :files
 
-    def wrap_error(error:, note:, folder:, uid:, message:)
+    def imap
+      files.imap
+    end
+
+    def mbox
+      files.mbox
+    end
+
+    def wrap_error(error:, note:, files_path:, uid:, message:)
       <<-ERROR.gsub(/^\s*/m, "")
-        [#{folder}] #{note} #{uid}: #{message}.
+        [#{files_path}] #{note} #{uid}: #{message}.
         #{error}:
         #{error.backtrace.join("\n")}"
       ERROR

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

@@ -104,11 +104,11 @@ module Imap::Backup
     end
 
     def mbox
-      @mbox ||= Serializer::Mbox.new(serializer.folder_path)
+      @mbox ||= Serializer::Mbox.new(files_path: serializer.files_path)
     end
 
     def imap
-      @imap ||= Serializer::Imap.new(serializer.folder_path)
+      @imap ||= Serializer::Imap.new(files_path: serializer.files_path)
     end
 
     def tsx

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

@@ -0,0 +1,43 @@
+require "fileutils"
+require "os"
+
+require "imap/backup/serializer/files/path"
+
+module Imap; end
+
+module Imap::Backup
+  class Serializer; end
+
+  # Creates any directories needed to store backups
+  class Serializer::DirectoryMaker
+    # @param files_path [Serializer::Files::Path] the folder path components
+    # @param permissions [Integer] The permissions to set on the folder
+    def initialize(files_path:)
+      @files_path = files_path
+    end
+
+    # Creates the containing directory and any missing parent directories,
+    # ensuring the required permissions (except on Windows).
+    # @return [void]
+    def run
+      directory = files_path.directory
+      FileUtils.mkdir_p(directory)
+
+      return if windows?
+
+      FileUtils.chmod DIRECTORY_PERMISSIONS, directory
+    end
+
+    private
+
+    attr_reader :files_path
+
+    # The desired permissions for all directories that store backups
+    DIRECTORY_PERMISSIONS = 0o700
+    private_constant :DIRECTORY_PERMISSIONS
+
+    def windows?
+      OS.windows?
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Imap; end
+
+module Imap::Backup
+  class Serializer; end
+  class Serializer::Files; end
+
+  # A Data class representing the path to a folder's serialized data
+  # it contains two elements: the base path and the folder name.
+  # The base path is the root path for an account's backup,
+  # and the folder name is the name of the folder within that account.
+  # If the folder name is nil, the path represents the base path only.
+  Serializer::Files::Path = Data.define(:base_path, :folder_name) do
+    # @return [String] the full path to the folder's serialized data
+    def to_s
+      File.join(base_path, folder_name)
+    end
+
+    # @return [String] the directory containing the folder's serialized data
+    def directory
+      if folder_name
+        File.dirname(to_s)
+      else
+        base_path
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+require "imap/backup/naming"
+require "imap/backup/serializer/directory_maker"
+require "imap/backup/serializer/imap"
+require "imap/backup/serializer/integrity_checker"
+require "imap/backup/serializer/mbox"
+require "imap/backup/serializer/files/path"
+
+module Imap; end
+
+module Imap::Backup
+  # Provides memoized file helpers for Serializer
+  class Serializer::Files
+    extend Forwardable
+
+    def_delegator :imap, :update
+
+    attr_reader :files_path
+
+    # @param files_path [Serializer::Files::Path] the path of the folder
+    def initialize(files_path:)
+      @files_path = files_path
+      @directory_ensured = false
+      @imap = nil
+      @mbox = nil
+      @sanitized_files_path = nil
+    end
+
+    def imap
+      @imap ||= begin
+        ensure_directory
+        Serializer::Imap.new(files_path: sanitized_files_path)
+      end
+    end
+
+    def mbox
+      @mbox ||= begin
+        ensure_directory
+        Serializer::Mbox.new(files_path: sanitized_files_path)
+      end
+    end
+
+    # Checks that the folder's data is stored correctly
+    # @return [void]
+    def check_integrity!
+      Serializer::IntegrityChecker.new(imap: imap, mbox: mbox).run
+    end
+
+    # Deletes the serialized data
+    # @return [void]
+    def delete
+      imap.delete
+      mbox.delete
+      reload
+    end
+
+    # Enumerates over a series of messages.
+    # When called without a block, returns an Enumerator
+    # @param required_uids [Array<Integer>] the UIDs of the message to enumerate over
+    # @return [Enumerator, void]
+    def each_message(required_uids = nil, &block)
+      return enum_for(:each_message, required_uids) if !block
+
+      required_uids ||= uids
+
+      validate!
+
+      enumerator = Serializer::MessageEnumerator.new(imap: imap)
+      enumerator.run(uids: required_uids, &block)
+    end
+
+    # Get message metadata
+    # @param uid [Integer] a message UID
+    # @return [Serializer::Message]
+    def get(uid)
+      validate!
+      imap.get(uid)
+    end
+
+    # @return [Array<Hash>]
+    def messages
+      validate!
+      imap.messages
+    end
+
+    # Forces a reload of the serialized files
+    # @return [void]
+    def reload
+      @imap = nil
+      @mbox = nil
+    end
+
+    # Renames the serialized files
+    # @param new_files_path [Serializer::Files::Path] the new path of the folder
+    # @return [void]
+    def rename(new_files_path)
+      Serializer::DirectoryMaker.new(files_path: new_files_path).run
+      mbox.rename new_files_path
+      imap.rename new_files_path
+    end
+
+    # @return [Integer] the UID validity for the folder
+    def uid_validity
+      validate!
+      imap.uid_validity
+    end
+
+    def uid_validity=(value)
+      validate!
+      imap.uid_validity = value
+      mbox.touch
+    end
+
+    # @return [Array<Integer>] The uids of all messages
+    def uids
+      validate!
+      imap.uids
+    end
+
+    # Update a message's metadata, replacing its UID
+    # @param old [Integer] the existing message UID
+    # @param new [Integer] the new UID to apply to the message
+    # @return [void]
+    def update_uid(old, new)
+      validate!
+      imap.update_uid(old, new)
+    end
+
+    # Checks that the metadata files are valid,
+    # or deletes any existing files if the pair are not valid.
+    # @return [Boolean] indicates whether there are existing, valid files
+    def validate!
+      return true if @validated
+
+      imap_valid = imap.valid?
+      mbox_valid = mbox.valid?
+      if imap_valid && mbox_valid
+        @validated = true
+        return true
+      end
+      warn_imap = !imap_valid && imap.exist?
+      Logger.logger.info("Metadata file '#{imap.pathname}' is invalid") if warn_imap
+
+      delete
+
+      false
+    end
+
+    private
+
+    def ensure_directory
+      return if @directory_ensured
+
+      Serializer::DirectoryMaker.new(files_path: sanitized_files_path).run
+      @directory_ensured = true
+    end
+
+    def sanitized
+      @sanitized ||= Naming.to_local_path(files_path.folder_name)
+    end
+
+    def sanitized_files_path
+      @sanitized_files_path ||= Serializer::Files::Path.new(
+        base_path: files_path.base_path, folder_name: sanitized
+      )
+    end
+  end
+end

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

@@ -14,12 +14,14 @@ module Imap::Backup
     # The version number to store in the metadata file
     CURRENT_VERSION = 3
 
-    # @return [String] The path of the imap metadata file, without the '.imap' extension
-    attr_reader :folder_path
-
-    # @param folder_path [String] The path of the imap metadata file, without the '.imap' extension
-    def initialize(folder_path)
-      @folder_path = folder_path
+    # @return [Serializer::Files::Path] The path of the imap metadata file, without the '.imap'
+    #   extension
+    attr_reader :files_path
+
+    # @param files_path [Serializer::Files::Path] The path of the imap metadata file, without
+    #   the '.imap' extension
+    def initialize(files_path:)
+      @files_path = files_path
       @loaded = false
       @uid_validity = nil
       @messages = nil
@@ -61,7 +63,7 @@ module Imap::Backup
 
     # @return [String] The full path name of the metadata file
     def pathname
-      "#{folder_path}.imap"
+      "#{files_path}.imap"
     end
 
     def exist?
@@ -136,15 +138,16 @@ module Imap::Backup
 
     # Renames the metadata file, if it exists,
     # otherwise, simply stores the new name
-    # @param new_path [String] the new path (without extension)
+    # @param new_path [Serializer::Files::Path] the new path
     # @return [void]
     def rename(new_path)
       if exist?
         old_pathname = pathname
-        @folder_path = new_path
-        File.rename(old_pathname, pathname)
+        @files_path = new_path
+        new_pathname = pathname
+        File.rename(old_pathname, new_pathname)
       else
-        @folder_path = new_path
+        @files_path = new_path
       end
     end
 
@@ -260,7 +263,7 @@ module Imap::Backup
     end
 
     def mbox
-      @mbox ||= Serializer::Mbox.new(folder_path)
+      @mbox ||= Serializer::Mbox.new(files_path: files_path)
     end
 
     def tsx