imap-backup 14.4.0 → 14.4.3

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

@@ -17,8 +17,6 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
-    FAKE_EMAIL = "fake@email.com".freeze
-
     desc "ignore-history EMAIL", "Skip downloading emails up to today for all configured folders"
     config_option
     quiet_option
@@ -87,38 +85,40 @@ module Imap::Backup
       end
     end
 
-    no_commands do
-      def do_ignore_folder_history(folder, serializer)
-        uids = folder.uids - serializer.uids
-        Logger.logger.info "Folder '#{folder.name}' - #{uids.length} messages"
+    private
 
-        serializer.apply_uid_validity(folder.uid_validity)
+    FAKE_EMAIL = "fake@email.com".freeze
 
-        uids.each do |uid|
-          message = <<~MESSAGE
-            From: #{FAKE_EMAIL}
-            Subject: Message #{uid} not backed up
-            Skipped #{uid}
-          MESSAGE
+    def do_ignore_folder_history(folder, serializer)
+      uids = folder.uids - serializer.uids
+      Logger.logger.info "Folder '#{folder.name}' - #{uids.length} messages"
 
-          serializer.append uid, message, []
-        end
+      serializer.apply_uid_validity(folder.uid_validity)
+
+      uids.each do |uid|
+        message = <<~MESSAGE
+          From: #{FAKE_EMAIL}
+          Subject: Message #{uid} not backed up
+          Skipped #{uid}
+        MESSAGE
+
+        serializer.append uid, message, []
       end
+    end
 
-      def thunderbird_profile(name = nil)
-        profiles = Thunderbird::Profiles.new
-        if 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
+    def thunderbird_profile(name = nil)
+      profiles = ::Thunderbird::Profiles.new
+      if 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
       end
     end
   end

data/lib/imap/backup/cli.rb

@@ -6,6 +6,7 @@ require "imap/backup/version"
 module Imap; end
 
 module Imap::Backup
+  # Top-level cli call handler
   class CLI < Thor
     require "imap/backup/cli/helpers"
 
@@ -41,9 +42,12 @@ module Imap::Backup
       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}
+    # to handle '--version' and rearrange parameters if 'help' is passed
     def self.start(args)
       if args.include?("--version")
         new.version
@@ -64,6 +68,7 @@ module Imap::Backup
       super
     end
 
+    # see {https://www.rubydoc.info/gems/thor/Thor/Base/ClassMethods#exit_on_failure%3F-instance_method Thor documentation}
     def self.exit_on_failure?
       true
     end
@@ -81,6 +86,7 @@ module Imap::Backup
     quiet_option
     refresh_option
     verbose_option
+    # Runs account backups
     def backup
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Backup.new(non_logging_options).run
@@ -141,6 +147,7 @@ module Imap::Backup
       desc: "the prefix (namespace) to strip from source folder names",
       aliases: ["-s"]
     )
+    # Migrates emails from one account to another
     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
@@ -200,6 +207,7 @@ module Imap::Backup
       desc: "the prefix (namespace) to strip from source folder names",
       aliases: ["-s"]
     )
+    # Keeps one email account in line with another
     def mirror(source_email, destination_email)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Transfer.new(:mirror, source_email, destination_email, non_logging_options).run
@@ -217,6 +225,7 @@ module Imap::Backup
     config_option
     quiet_option
     verbose_option
+    # Restores backed up meails to an account
     def restore(email = nil)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Restore.new(email, non_logging_options).run
@@ -230,6 +239,7 @@ module Imap::Backup
     config_option
     quiet_option
     verbose_option
+    # Runs the menu-driven setup program
     def setup
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       CLI::Setup.new(non_logging_options).run
@@ -253,6 +263,7 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Prints various statistics about a configured account
     def stats(email)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Stats.new(email, non_logging_options).run
@@ -262,6 +273,7 @@ module Imap::Backup
     subcommand "utils", Utils
 
     desc "version", "Print the imap-backup version"
+    # Prints the program version
     def version
       Kernel.puts "imap-backup #{Imap::Backup::VERSION}"
     end

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

@@ -15,11 +15,6 @@ module Imap::Backup
       responses uid_fetch uid_search uid_store
     )
 
-    attr_reader :account
-    attr_reader :options
-    attr_reader :server
-    attr_accessor :state
-
     def initialize(server, account, options)
       @account = account
       @options = options
@@ -75,6 +70,11 @@ module Imap::Backup
 
     private
 
+    attr_reader :account
+    attr_reader :options
+    attr_reader :server
+    attr_accessor :state
+
     def imap
       @imap ||= Net::IMAP.new(server, options)
     end

data/lib/imap/backup/configuration.rb

@@ -11,15 +11,12 @@ module Imap; end
 module Imap::Backup
   class Configuration
     CONFIGURATION_DIRECTORY = File.expand_path("~/.imap-backup")
-    VERSION_2_1 = "2.1".freeze
-    VERSION = "2.2".freeze
     DEFAULT_STRATEGY = "delay_metadata".freeze
     DOWNLOAD_STRATEGIES = [
       {key: "direct", description: "write straight to disk"},
       {key: DEFAULT_STRATEGY, description: "delay writing metadata"}
     ].freeze
-
-    attr_reader :pathname
+    VERSION = "2.2".freeze
 
     def self.default_pathname
       File.join(CONFIGURATION_DIRECTORY, "config.json")
@@ -98,6 +95,10 @@ module Imap::Backup
 
     private
 
+    VERSION_2_1 = "2.1".freeze
+
+    attr_reader :pathname
+
     def ensure_loaded!
       return true if @data
 

data/lib/imap/backup/downloader.rb

@@ -3,21 +3,8 @@ require "net/imap"
 module Imap; end
 
 module Imap::Backup
-  class MultiFetchFailedError < StandardError; end
-
   class Downloader
-    attr_reader :folder
-    attr_reader :serializer
-    attr_reader :multi_fetch_size
-    # Some IMAP providers, notably Apple Mail, set the '\Seen' flag
-    # on emails when they are fetched. By setting `:reset_seen_flags_after_fetch`,
-    # a workaround is activated which checks which emails are 'unseen' before
-    # and after the fetch, and removes the '\Seen' flag from those which have changed.
-    # As this check is susceptible to 'race conditions', i.e. when a different
-    # client sets the '\Seen' flag while imap-backup is fetching, it is best
-    # to only use it when required (i.e. for IMAP providers which always
-    # mark messages as '\Seen' when accessed).
-    attr_reader :reset_seen_flags_after_fetch
+    class MultiFetchFailedError < StandardError; end
 
     def initialize(folder, serializer, multi_fetch_size: 1, reset_seen_flags_after_fetch: false)
       @folder = folder
@@ -46,6 +33,11 @@ module Imap::Backup
 
     private
 
+    attr_reader :folder
+    attr_reader :serializer
+    attr_reader :multi_fetch_size
+    attr_reader :reset_seen_flags_after_fetch
+
     def download_block(block, index)
       uids_and_bodies =
         if reset_seen_flags_after_fetch

data/lib/imap/backup/email/mboxrd/message.rb

@@ -1,4 +1,3 @@
-require "forwardable"
 require "mail"
 
 module Imap; end
@@ -8,8 +7,6 @@ module Imap::Backup
 
   module Email::Mboxrd
     class Message
-      attr_reader :supplied_body
-
       def self.clean_serialized(serialized)
         cleaned = serialized.gsub(/^>(>*From)/, "\\1")
         # Serialized messages in this format *should* start with a line
@@ -26,6 +23,8 @@ module Imap::Backup
         new(clean_serialized(serialized))
       end
 
+      attr_reader :supplied_body
+
       def initialize(supplied_body)
         @supplied_body = supplied_body.clone
       end

data/lib/imap/backup/file_mode.rb

@@ -2,8 +2,6 @@ module Imap; end
 
 module Imap::Backup
   class FileMode
-    attr_reader :filename
-
     def initialize(filename:)
       @filename = filename
     end
@@ -14,5 +12,9 @@ module Imap::Backup
       stat = File.stat(filename)
       stat.mode & 0o777
     end
+
+    private
+
+    attr_reader :filename
   end
 end

data/lib/imap/backup/flag_refresher.rb

@@ -2,9 +2,6 @@ module Imap; end
 
 module Imap::Backup
   class FlagRefresher
-    attr_reader :folder
-    attr_reader :serializer
-
     CHUNK_SIZE = 100
 
     def initialize(folder, serializer)
@@ -22,6 +19,9 @@ module Imap::Backup
 
     private
 
+    attr_reader :folder
+    attr_reader :serializer
+
     def refresh_block(uids)
       uids_and_flags = folder.fetch_multi(uids, ["FLAGS"])
       uids_and_flags.each do |uid_and_flags|

data/lib/imap/backup/local_only_message_deleter.rb

@@ -4,9 +4,6 @@ module Imap; end
 
 module Imap::Backup
   class LocalOnlyMessageDeleter
-    attr_reader :folder
-    attr_reader :serializer
-
     def initialize(folder, serializer)
       @folder = folder
       @serializer = serializer
@@ -29,5 +26,10 @@ module Imap::Backup
         !local_only_uids.include?(message.uid)
       end
     end
+
+    private
+
+    attr_reader :folder
+    attr_reader :serializer
   end
 end

data/lib/imap/backup/migrator.rb

@@ -4,10 +4,6 @@ module Imap; end
 
 module Imap::Backup
   class Migrator
-    attr_reader :folder
-    attr_reader :reset
-    attr_reader :serializer
-
     def initialize(serializer, folder, reset: false)
       @folder = folder
       @reset = reset
@@ -35,5 +31,11 @@ module Imap::Backup
         end
       end
     end
+
+    private
+
+    attr_reader :folder
+    attr_reader :reset
+    attr_reader :serializer
   end
 end

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

@@ -6,9 +6,6 @@ module Imap::Backup
   class Mirror; end
 
   class Mirror::Map
-    attr_reader :pathname
-    attr_reader :destination
-
     def initialize(pathname:, destination:)
       @pathname = pathname
       @destination = destination
@@ -64,6 +61,9 @@ module Imap::Backup
 
     private
 
+    attr_reader :pathname
+    attr_reader :destination
+
     def store
       @store ||=
         if File.exist?(pathname)

data/lib/imap/backup/mirror.rb

@@ -4,11 +4,6 @@ module Imap; end
 
 module Imap::Backup
   class Mirror
-    attr_reader :serializer
-    attr_reader :folder
-
-    CHUNK_SIZE = 100
-
     def initialize(serializer, folder)
       @serializer = serializer
       @folder = folder
@@ -24,6 +19,11 @@ module Imap::Backup
 
     private
 
+    CHUNK_SIZE = 100
+
+    attr_reader :serializer
+    attr_reader :folder
+
     def ensure_destination_folder
       return if folder.exist?
 

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

@@ -5,17 +5,16 @@ module Imap; end
 module Imap::Backup
   class Serializer; end
 
+  # Appends messages to the local store
   class Serializer::Appender
-    attr_reader :imap
-    attr_reader :folder
-    attr_reader :mbox
-
     def initialize(folder:, imap:, mbox:)
       @folder = folder
       @imap = imap
       @mbox = mbox
     end
 
+    # Adds a message to the metadata file and the mailbox.
+    # Wraps any errors with information about the message that caused them.
     def append(uid:, message:, flags:)
       raise "Can't add messages without uid_validity" if !imap.uid_validity
 
@@ -56,6 +55,10 @@ module Imap::Backup
 
     private
 
+    attr_reader :imap
+    attr_reader :folder
+    attr_reader :mbox
+
     def wrap_error(error:, note:, folder:, uid:, message:)
       <<-ERROR.gsub(/^\s*/m, "")
         [#{folder}] #{note} #{uid}: #{message}.

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

@@ -1,3 +1,5 @@
+require "forwardable"
+
 require "imap/backup/email/mboxrd/message"
 require "imap/backup/serializer/imap"
 require "imap/backup/serializer/mbox"
@@ -9,8 +11,6 @@ module Imap::Backup
   class Serializer::DelayedMetadataSerializer
     extend Forwardable
 
-    attr_reader :serializer
-
     def_delegator :serializer, :uids
 
     def initialize(serializer:)
@@ -18,6 +18,10 @@ module Imap::Backup
       @tsx = nil
     end
 
+    # Initializes the metadata and mailbox transactions, then calls the supplied block.
+    # Once the block has finished, commits changes to metadata
+    #
+    # @return [void]
     def transaction(&block)
       tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")
 
@@ -32,6 +36,13 @@ module Imap::Backup
       end
     end
 
+    # Appends a message to the mbox file and adds the metadata
+    # to the transaction
+    #
+    # @param uid [Integer] the UID of the message
+    # @param message [String] the message
+    # @param flags [Array<Symbol>] the flags for the message
+    # @return [void]
     def append(uid, message, flags)
       tsx.fail_outside_transaction!(:append)
       mboxrd_message = Email::Mboxrd::Message.new(message)
@@ -42,6 +53,8 @@ module Imap::Backup
 
     private
 
+    attr_reader :serializer
+
     def commit
       # rubocop:disable Lint/RescueException
       imap.transaction do

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

@@ -8,17 +8,23 @@ module Imap; end
 module Imap::Backup
   class Serializer; end
 
+  # Ensures that serialization directories exist and have the correct permissions.
   class Serializer::Directory
+    # The desired permissions for all directories that store backups
     DIRECTORY_PERMISSIONS = 0o700
 
-    attr_reader :relative
-    attr_reader :path
-
+    # @param path [String] The base path of the account backup
+    # @param relative [String] The path relative from the base
+    #
+    # @return [void]
     def initialize(path, relative)
       @path = path
       @relative = relative
     end
 
+    # Creates the directory, if present and sets it's access permissions
+    #
+    # @return [void]
     def ensure_exists
       if !File.directory?(full_path)
         Serializer::FolderMaker.new(
@@ -34,6 +40,9 @@ module Imap::Backup
 
     private
 
+    attr_reader :relative
+    attr_reader :path
+
     def full_path
       containing_directory = File.join(path, relative)
       File.expand_path(containing_directory)

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

@@ -5,17 +5,19 @@ module Imap; end
 module Imap::Backup
   class Serializer; end
 
+  # Creates directories
   class Serializer::FolderMaker
-    attr_reader :base
-    attr_reader :path
-    attr_reader :permissions
-
+    # @param base [String] The base directory of the account
+    # @param path [String] The path to the folder, relative to the base
+    # @param permissions [Integer] The permissions to set on the folder
     def initialize(base:, path:, permissions:)
       @base = base
       @path = path
       @permissions = permissions
     end
 
+    # Creates the directory and any missing parent directories,
+    # ensuring the desired permissions.
     def run
       parts = path.split("/")
       return if parts.empty?
@@ -28,6 +30,12 @@ module Imap::Backup
       end
     end
 
+    private
+
+    attr_reader :base
+    attr_reader :path
+    attr_reader :permissions
+
     def full_path
       File.join(base, path)
     end

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

@@ -7,12 +7,14 @@ require "imap/backup/serializer/transaction"
 module Imap; end
 
 module Imap::Backup
+  # Stores message metadata
   class Serializer::Imap
+    # The version number to store in the metadata file
     CURRENT_VERSION = 3
 
     attr_reader :folder_path
-    attr_reader :loaded
 
+    # @param folder_path [String] The path of the imap metadata file, without the '.imap' extension
     def initialize(folder_path)
       @folder_path = folder_path
       @loaded = false
@@ -149,6 +151,8 @@ module Imap::Backup
 
     private
 
+    attr_reader :loaded
+
     def save_internal(version:, uid_validity:, messages:)
       raise "Cannot save metadata without a uid_validity" if !uid_validity
 

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

@@ -5,15 +5,19 @@ module Imap::Backup
 
   class Serializer::FolderIntegrityError < StandardError; end
 
+  # Checks that both the mailbox and its associated metadata file match
   class Serializer::IntegrityChecker
-    attr_reader :imap
-    attr_reader :mbox
-
+    # @param imap [Imap]
+    # @param mbox [Mbox]
     def initialize(imap:, mbox:)
       @imap = imap
       @mbox = mbox
     end
 
+    # Runs the integrity check
+    #
+    # @raise [FolderIntegrityError] if the files do not match
+    # @return [void]
     def run
       Logger.logger.debug(
         "[IntegrityChecker] checking '#{imap.pathname}' against '#{mbox.pathname}'"
@@ -47,6 +51,9 @@ module Imap::Backup
 
     private
 
+    attr_reader :imap
+    attr_reader :mbox
+
     def check_offset_ordering!
       offsets = imap.messages.map(&:offset)
 

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

@@ -5,7 +5,6 @@ module Imap; end
 module Imap::Backup
   class Serializer::Mbox
     attr_reader :folder_path
-    attr_reader :savepoint
 
     def initialize(folder_path)
       @folder_path = folder_path
@@ -86,6 +85,8 @@ module Imap::Backup
 
     private
 
+    attr_reader :savepoint
+
     def rewind(length)
       File.open(pathname, File::RDWR | File::CREAT, 0o644) do |f|
         f.truncate(length)

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

@@ -1,16 +1,20 @@
+require "forwardable"
+
 require "imap/backup/email/mboxrd/message"
 
 module Imap; end
 
 module Imap::Backup
   class Serializer::Message
-    attr_accessor :uid
     attr_accessor :flags
-    attr_reader :offset
     attr_reader :length
-    attr_reader :mbox
+    attr_reader :offset
+    attr_accessor :uid
+
+    extend Forwardable
 
-    # TODO: delegate to Mboxrd::Message
+    def_delegator :message, :supplied_body, :body
+    def_delegators :message, :imap_body, :date, :subject
 
     def initialize(uid:, offset:, length:, mbox:, flags: [])
       @uid = uid
@@ -37,20 +41,8 @@ module Imap::Backup
         end
     end
 
-    def body
-      @body ||= message.supplied_body
-    end
-
-    def imap_body
-      @imap_body ||= message.imap_body
-    end
+    private
 
-    def date
-      @date ||= message.date
-    end
-
-    def subject
-      @subject ||= message.subject
-    end
+    attr_reader :mbox
   end
 end