imap-backup 14.4.4 → 14.5.0

data/lib/imap/backup/configuration.rb

@@ -9,15 +9,21 @@ require "imap/backup/serializer/permission_checker"
 module Imap; end
 
 module Imap::Backup
+  # Handles the application's configuration file
   class Configuration
+    # The default directory of the configuration file
     CONFIGURATION_DIRECTORY = File.expand_path("~/.imap-backup")
+    # The default download strategy key
     DEFAULT_STRATEGY = "delay_metadata".freeze
+    # The available download strategies
     DOWNLOAD_STRATEGIES = [
       {key: "direct", description: "write straight to disk"},
       {key: DEFAULT_STRATEGY, description: "delay writing metadata"}
     ].freeze
+    # The current file version
     VERSION = "2.2".freeze
 
+    # @return [String] the default configuration file path
     def self.default_pathname
       File.join(CONFIGURATION_DIRECTORY, "config.json")
     end
@@ -33,10 +39,13 @@ module Imap::Backup
       @download_strategy_modified = false
     end
 
+    # @return [String] the directory containing the configuration file
     def path
       File.dirname(pathname)
     end
 
+    # Saves the configuration file in JSON format
+    # @return [void]
     def save
       ensure_loaded!
       FileUtils.mkdir_p(path) if !File.directory?(path)
@@ -53,6 +62,7 @@ module Imap::Backup
       @data = nil
     end
 
+    # @return [Array<Account>] the configured accounts
     def accounts
       @accounts ||= begin
         ensure_loaded!
@@ -63,12 +73,15 @@ module Imap::Backup
       end
     end
 
+    # @return [String] the cofigured download strategy
     def download_strategy
       ensure_loaded!
 
       @download_strategy
     end
 
+    # @param value [String] the new strategy
+    # @return [void]
     def download_strategy=(value)
       raise "Unknown strategy '#{value}'" if !DOWNLOAD_STRATEGIES.find { |s| s[:key] == value }
 

data/lib/imap/backup/configuration_not_found.rb

@@ -1,5 +1,6 @@
 module Imap; end
 
 module Imap::Backup
+  # Thrown when no configuration file is found
   class ConfigurationNotFound < StandardError; end
 end

data/lib/imap/backup/downloader.rb

@@ -3,7 +3,9 @@ require "net/imap"
 module Imap; end
 
 module Imap::Backup
+  # Downloads as yet undownloaded emails from an account's server
   class Downloader
+    # @private
     class MultiFetchFailedError < StandardError; end
 
     def initialize(folder, serializer, multi_fetch_size: 1, reset_seen_flags_after_fetch: false)
@@ -14,6 +16,8 @@ module Imap::Backup
       @uids = nil
     end
 
+    # Runs the downloader
+    # @return [void]
     def run
       info("#{uids.count} new messages") if uids.any?
 

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

@@ -6,7 +6,13 @@ module Imap::Backup
   module Email; end
 
   module Email::Mboxrd
+    # Handles serialization and deserialization of messages
     class Message
+      # @param serialized [String] an email message
+      #
+      # @return [String] The message without the initial 'From ' line
+      #   and with one level of '>' quoting removed from other lines
+      #   that start with 'From'
       def self.clean_serialized(serialized)
         cleaned = serialized.gsub(/^>(>*From)/, "\\1")
         # Serialized messages in this format *should* start with a line
@@ -19,32 +25,40 @@ module Imap::Backup
         cleaned
       end
 
+      # @param serialized [String] the on-disk version of the message
+      #
+      # @return [Message] the original message
       def self.from_serialized(serialized)
         new(clean_serialized(serialized))
       end
 
+      # @return [String] the original message body
       attr_reader :supplied_body
 
       def initialize(supplied_body)
         @supplied_body = supplied_body.clone
       end
 
+      # @return [String] the message with an initial 'From ADDRESS' line
       def to_serialized
         from_line = "From #{from}\n"
         body = mboxrd_body.dup.force_encoding(Encoding::UTF_8)
         from_line + body
       end
 
+      # @return [Date, nil] the date of the message
       def date
         parsed.date
       rescue StandardError
         nil
       end
 
+      # @return [String] the message's subject line
       def subject
         parsed.subject
       end
 
+      # @return [String] the original message ready for transmission to an IMAP server
       def imap_body
         supplied_body.gsub(/(?<!\r)\n/, "\r\n")
       end

data/lib/imap/backup/email/provider/apple_mail.rb

@@ -3,7 +3,9 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides for Apple mail accounts
   class Email::Provider::AppleMail < Email::Provider::Base
+    # @return [String] the Apple Mail IMAP server host name
     def host
       "imap.mail.me.com"
     end

data/lib/imap/backup/email/provider/base.rb

@@ -4,11 +4,11 @@ module Imap::Backup
   module Email; end
   class Email::Provider; end
 
+  # Supplies defaults for email provider behaviour
   class Email::Provider::Base
+    # @return [Hash] defaults for the Net::IMAP connection
     def options
-      # rubocop:disable Naming/VariableNumber
-      {port: 993, ssl: {ssl_version: :TLSv1_2}}
-      # rubocop:enable Naming/VariableNumber
+      {port: 993, ssl: {min_version: OpenSSL::SSL::TLS1_2_VERSION}}
     end
 
     def sets_seen_flags_on_fetch?

data/lib/imap/backup/email/provider/fastmail.rb

@@ -3,7 +3,9 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides for Fastmail accounts
   class Email::Provider::Fastmail < Email::Provider::Base
+    # @return [String] the Fastmail IMAP server host name
     def host
       "imap.fastmail.com"
     end

data/lib/imap/backup/email/provider/gmail.rb

@@ -3,7 +3,9 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides for GMail accounts
   class Email::Provider::GMail < Email::Provider::Base
+    # @return [String] the GMail IMAP server host name
     def host
       "imap.gmail.com"
     end

data/lib/imap/backup/email/provider/purelymail.rb

@@ -3,7 +3,9 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides for Purelymail accounts
   class Email::Provider::Purelymail < Email::Provider::Base
+    # @return [String] The Purelymail IMAP server host name
     def host
       "mailserver.purelymail.com"
     end

data/lib/imap/backup/email/provider/unknown.rb

@@ -3,15 +3,11 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides when the IMAP provider is not known
   class Email::Provider::Unknown < Email::Provider::Base
     # We don't know how to guess the IMAP server
+    # @return [nil]
     def host
     end
-
-    def options
-      # rubocop:disable Naming/VariableNumber
-      {port: 993, ssl: {ssl_version: :TLSv1_2}}
-      # rubocop:enable Naming/VariableNumber
-    end
   end
 end

data/lib/imap/backup/email/provider.rb

@@ -9,7 +9,12 @@ module Imap; end
 module Imap::Backup
   module Email; end
 
+  # Provides a class factory for email account providers
   class Email::Provider
+    # @param address [String] an email address
+    # @return [Email::Provider::Fastmail, Email::Provider::GMail, Email::Provider::AppleMail,
+    #   Email::Provider::Purelymail, Email::Provider::Unknown]
+    #   an instance supplying default values for the email's account set up
     def self.for_address(address)
       # rubocop:disable Lint/DuplicateBranch
       case

data/lib/imap/backup/file_mode.rb

@@ -1,11 +1,13 @@
 module Imap; end
 
 module Imap::Backup
+  # Accesses a file's access permissions
   class FileMode
     def initialize(filename:)
       @filename = filename
     end
 
+    # @return [Integer, nil] The user, group and "other" part of the file's "mode"
     def mode
       return nil if !File.exist?(filename)
 

data/lib/imap/backup/flag_refresher.rb

@@ -1,7 +1,9 @@
 module Imap; end
 
 module Imap::Backup
+  # Updates the flags on backed-up emails
   class FlagRefresher
+    # The number of messages to process at a time
     CHUNK_SIZE = 100
 
     def initialize(folder, serializer)
@@ -9,6 +11,8 @@ module Imap::Backup
       @serializer = serializer
     end
 
+    # Runs the update
+    # @return [void]
     def run
       uids = serializer.uids.clone
 

data/lib/imap/backup/local_only_message_deleter.rb

@@ -3,6 +3,7 @@ require "imap/backup/logger"
 module Imap; end
 
 module Imap::Backup
+  # Deletes locally backed-up emails that are no longer on the server
   class LocalOnlyMessageDeleter
     def initialize(folder, serializer)
       @folder = folder
@@ -12,6 +13,7 @@ module Imap::Backup
     # TODO: this method is very slow as it copies all messages.
     # A quicker method would only remove UIDs from the .imap file,
     # but that would require a garbage collection later.
+    # @return [void]
     def run
       local_only_uids = serializer.uids - folder.uids
       if local_only_uids.empty?

data/lib/imap/backup/logger.rb

@@ -7,13 +7,26 @@ require "imap/backup/text/sanitizer"
 module Imap; end
 
 module Imap::Backup
+  # Wraps the standard logger, providing configuration and sanitization
   class Logger
     include Singleton
 
+    # @return [Imap::Backup::Logger] the singleton instance of this class
     def self.logger
       Logger.instance.logger
     end
 
+    # @param options [Hash] command-line options
+    # @option options [Boolean] :quiet (false) if true, no output will be written
+    # @option options [Array<Boolean>] :verbose ([]) counts how many `--verbose`
+    #   parameters were passed (and, potentially subtracts the number of
+    #   `--no-verbose` parameters).
+    #   If the result is 0, does normal info-level logging,
+    #   If the result is 1, does debug logging,
+    #   If the result is 2, does debug logging and client-server debug logging.
+    #   This option is overridden by the `:verbose` option.
+    #
+    # @return [Hash] the options without the :quiet and :verbose keys
     def self.setup_logging(options = {})
       copy = options.clone
       quiet = copy.delete(:quiet)
@@ -35,6 +48,9 @@ module Imap::Backup
       copy
     end
 
+    # Wraps a block, filtering output to standard error,
+    # hidng passwords and outputs the results to standard out
+    # @return [void]
     def self.sanitize_stderr
       sanitizer = Text::Sanitizer.new($stdout)
       previous_stderr = $stderr
@@ -45,10 +61,12 @@ module Imap::Backup
       $stderr = previous_stderr
     end
 
+    # @private
     def self.count(verbose)
       verbose.reduce(1) { |acc, v| acc + (v ? 1 : -1) }
     end
 
+    # @return [Logger] the configured Logger
     attr_reader :logger
 
     def initialize

data/lib/imap/backup/migrator.rb

@@ -3,6 +3,7 @@ require "imap/backup/logger"
 module Imap; end
 
 module Imap::Backup
+  # Copies a folder of backed-up emails to an online folder
   class Migrator
     def initialize(serializer, folder, reset: false)
       @folder = folder
@@ -10,6 +11,8 @@ module Imap::Backup
       @serializer = serializer
     end
 
+    # Runs the migration
+    # @return [void]
     def run
       count = serializer.uids.count
       folder.create

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

@@ -5,6 +5,7 @@ module Imap; end
 module Imap::Backup
   class Mirror; end
 
+  # Keeps track of the mapping between source and destination UIDs
   class Mirror::Map
     def initialize(pathname:, destination:)
       @pathname = pathname
@@ -16,6 +17,8 @@ module Imap::Backup
       @map = nil
     end
 
+    # @return [Boolean] whether the supplied values match the existing
+    #  UID validity values
     def check_uid_validities(source:, destination:)
       store
       return false if source != source_uid_validity
@@ -24,6 +27,8 @@ module Imap::Backup
       true
     end
 
+    # Sets, or resets to an empty state
+    # @return [void]
     def reset(source_uid_validity:, destination_uid_validity:)
       destination_store["source_uid_validity"] = source_uid_validity
       @source_uid_validity = nil
@@ -33,6 +38,11 @@ module Imap::Backup
       @map = nil
     end
 
+    # @param destination_uid [Integer] a message UID from the destination server
+    #
+    # @raise [RuntimeError] if the UID validity is not set
+    # @return [Integer, nil] the source UID that is equivalent to the given destination UID
+    #   or nil if it is not found
     def source_uid(destination_uid)
       if destination_store == {}
         raise "Assign UID validities with #reset before calling #source_uid"
@@ -41,6 +51,11 @@ module Imap::Backup
       map.key(destination_uid)
     end
 
+    # @param source_uid [Integer] a message UID from the source server
+    #
+    # @raise [RuntimeError] if the UID validity is not set
+    # @return [Integer, nil] the destination UID that is equivalent to the given source UID
+    #   or nil if it is not found
     def destination_uid(source_uid)
       if destination_store == {}
         raise "Assign UID validities with #reset before calling #destination_uid"
@@ -49,12 +64,18 @@ module Imap::Backup
       map[source_uid]
     end
 
+    # Creates a mapping between message UIDs on the source
+    # and destination servers
+    # @raise [RuntimeError] if the UID validity is not set
+    # @return [void]
     def map_uids(source:, destination:)
       raise "Assign UID validities with #reset before calling #map_uids" if destination_store == {}
 
       map[source] = destination
     end
 
+    # Saves the map to disk as JSON
+    # @return [void]
     def save
       File.write(pathname, store.to_json)
     end

data/lib/imap/backup/mirror.rb

@@ -3,12 +3,20 @@ require "imap/backup/mirror/map"
 module Imap; end
 
 module Imap::Backup
+  # Synchronises a folder between a source and destination
   class Mirror
     def initialize(serializer, folder)
       @serializer = serializer
       @folder = folder
     end
 
+    # If necessary, reates the destination folder,
+    # then deletes any messages in the destination folder
+    # that are not in the local store,
+    # sets existing messages' flas
+    # then appends any missing messages
+    # and saves the mapping file
+    # @return [void]
     def run
       ensure_destination_folder
       delete_destination_only_emails

data/lib/imap/backup/naming.rb

@@ -1,11 +1,17 @@
 module Imap; end
 
 module Imap::Backup
+  # Maps between server and file system folder names
+  # `/` is treated as an acceptable character
   class Naming
+    # The characters that cannot be used in file names
     INVALID_FILENAME_CHARACTERS = ":%;".freeze
+    # A regular expression that captures each disallowed character
     INVALID_FILENAME_CHARACTER_MATCH = /([#{INVALID_FILENAME_CHARACTERS}])/.freeze
 
-    # `*_path` functions treat `/` as an acceptable character
+    # @param name [String] a folder name
+    # @return [String] the supplied string iwth disallowed characters replaced
+    #   by their hexadecimal representation
     def self.to_local_path(name)
       name.gsub(INVALID_FILENAME_CHARACTER_MATCH) do |character|
         hex =
@@ -16,6 +22,9 @@ module Imap::Backup
       end
     end
 
+    # @param name [String] a serialized folder name
+    # @return the supplied string with hexadecimal codes ('%xx') replaced with
+    #   the characters they represent
     def self.from_local_path(name)
       name.gsub(/%(.*?);/) do
         ::Regexp.last_match(1).

data/lib/imap/backup/retry_on_error.rb

@@ -3,7 +3,16 @@ require "imap/backup/logger"
 module Imap; end
 
 module Imap::Backup
+  # Provides a mechanism for retrying blocks of code which often throw errors
   module RetryOnError
+    # Calls the supplied block,
+    # traps the given types of errors
+    # retrying up to a given number of times
+    # @param errors [Array<Exception>] the exceptions to trap
+    # @param limit [Integer] the maximum number of retries
+    # @param on_error [Proc] a block to call when an error occurs
+    # @raise any error ocurring more than `limit` times
+    # @return the result of any successful completion of the block
     def retry_on_error(errors:, limit: 10, on_error: nil)
       tries ||= 1
       yield

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

@@ -7,6 +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
@@ -15,6 +18,12 @@ module Imap::Backup
 
     # Adds a message to the metadata file and the mailbox.
     # Wraps any errors with information about the message that caused them.
+    # @raise [RuntimeError] if the UID validity is not set
+    #   or when an error occurs during serialization
+    # @param uid [Integer] the message's UID
+    # @param message [String] the on-disk version of the message
+    # @param flags [Array[Symbol]] the message's flags
+    # @return [void]
     def append(uid:, message:, flags:)
       raise "Can't add messages without uid_validity" if !imap.uid_validity
 

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

@@ -8,11 +8,13 @@ require "imap/backup/serializer/transaction"
 module Imap; end
 
 module Imap::Backup
+  # Wraps the Serializer, delaying metadata appends
   class Serializer::DelayedMetadataSerializer
     extend Forwardable
 
     def_delegator :serializer, :uids
 
+    # @param serializer [Serializer] the serializer for a folder
     def initialize(serializer:)
       @serializer = serializer
       @tsx = nil
@@ -20,7 +22,9 @@ module Imap::Backup
 
     # Initializes the metadata and mailbox transactions, then calls the supplied block.
     # Once the block has finished, commits changes to metadata
+    # @param block [block] the block that is wrapped by the transaction
     #
+    # @raise any error ocurring during the commit phase
     # @return [void]
     def transaction(&block)
       tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")

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

@@ -18,6 +18,7 @@ module Imap::Backup
 
     # Creates the directory and any missing parent directories,
     # ensuring the desired permissions.
+    # @return [void]
     def run
       parts = path.split("/")
       return if parts.empty?

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

@@ -12,6 +12,7 @@ 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
@@ -24,6 +25,10 @@ module Imap::Backup
       @tsx = nil
     end
 
+    # Opens a transaction
+    # @param block [block] the block that is wrapped by the transaction
+    # @raise any exception ocurring in the block
+    # @return [void]
     def transaction(&block)
       tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")
 
@@ -41,6 +46,8 @@ module Imap::Backup
       # rubocop:enable Lint/RescueException
     end
 
+    # Discards stored changes to the data
+    # @return [void]
     def rollback
       tsx.fail_outside_transaction!(:rollback)
 
@@ -50,6 +57,7 @@ module Imap::Backup
       tsx.clear
     end
 
+    # @return [String] The full path name of the metadata file
     def pathname
       "#{folder_path}.imap"
     end
@@ -66,6 +74,11 @@ module Imap::Backup
       true
     end
 
+    # Append message metadata
+    # @param uid [Integer] the message's UID
+    # @param length [Integer] the length of the message (as stored on disk)
+    # @param flags [Array[Symbol]] the message's flags
+    # @return [void]
     def append(uid, length, flags: [])
       offset =
         if messages.empty?
@@ -82,10 +95,16 @@ module Imap::Backup
       save
     end
 
+    # Get message metadata
+    # @param uid [Integer] a message UID
+    # @return [Serializer::Message]
     def get(uid)
       messages.find { |m| m.uid == uid }
     end
 
+    # Deletes the metadata file
+    # and discards stored attributes
+    # @return [void]
     def delete
       return if !exist?
 
@@ -96,6 +115,10 @@ module Imap::Backup
       @version = nil
     end
 
+    # Renames the metadata file, if it exists,
+    # otherwise, simply stores the new name
+    # @param new_path [String] the new path (without extension)
+    # @return [void]
     def rename(new_path)
       if exist?
         old_pathname = pathname
@@ -106,28 +129,36 @@ module Imap::Backup
       end
     end
 
+    # @return [Integer] the UID validity for the folder
     def uid_validity
       ensure_loaded
       @uid_validity
     end
 
+    # Sets the folder's UID validity and saves the metadata file
+    # @param value [Integer] the new UID validity
+    # @return [void]
     def uid_validity=(value)
       ensure_loaded
       @uid_validity = value
       save
     end
 
-    # Make private
+    # @return [Array<Hash>]
     def messages
       ensure_loaded
       @messages
     end
 
-    # Deprecated
+    # @return [Array<Integer>] The uids of all messages
     def uids
       messages.map(&:uid)
     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)
       index = messages.find_index { |m| m.uid == old }
       return if index.nil?
@@ -136,11 +167,16 @@ module Imap::Backup
       save
     end
 
+    # @return [String] The format version for the metadata file
     def version
       ensure_loaded
       @version
     end
 
+    # Saves the file,
+    # except in a transaction when it does nothing
+    # @raise [RuntimeError] if UID validity has not been set
+    # @return [void]
     def save
       return if tsx.in_transaction?
 

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

@@ -3,6 +3,7 @@ module Imap; end
 module Imap::Backup
   class Serializer; end
 
+  # An error indicating the folder is not serialized correctly
   class Serializer::FolderIntegrityError < StandardError; end
 
   # Checks that both the mailbox and its associated metadata file match