imap-backup 14.4.4 → 14.5.0

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

@@ -3,14 +3,21 @@ require "imap/backup/serializer/transaction"
 module Imap; end
 
 module Imap::Backup
+  # Stores messages
   class Serializer::Mbox
+    # @return [String] The path of the mailbox file, without the '.mbox' extension
     attr_reader :folder_path
 
+    # @param folder_path [String] The path of the mailbox file, without the '.mbox' extension
     def initialize(folder_path)
       @folder_path = folder_path
       @tsx = nil
     end
 
+    # Starts a transaction
+    # @param block [block] the block that is wrapped by the transaction
+    # @raise re-raises errors which occur in the block
+    # @return [void]
     def transaction(&block)
       tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")
 
@@ -26,6 +33,8 @@ module Imap::Backup
       end
     end
 
+    # Returns to the pre-transaction state
+    # @return [void]
     def rollback
       tsx.fail_outside_transaction!(:rollback)
 
@@ -36,12 +45,19 @@ module Imap::Backup
       exist?
     end
 
+    # Serializes a message
+    # @param message [String] the message text
+    # @return [void]
     def append(message)
       File.open(pathname, "ab") do |file|
         file.write message
       end
     end
 
+    # Reads a message from disk
+    # @param offset [Integer] the start of the message inside the mailbox file
+    # @param length [Integer] the length of the message (as stored on disk)
+    # @return [String] the message
     def read(offset, length)
       File.open(pathname, "rb") do |f|
         f.seek offset
@@ -49,6 +65,8 @@ module Imap::Backup
       end
     end
 
+    # Deletes the mailbox
+    # @return [void]
     def delete
       return if !exist?
 
@@ -59,16 +77,22 @@ module Imap::Backup
       File.exist?(pathname)
     end
 
+    # @return [Integer] The lsize of the disk file
     def length
       return nil if !exist?
 
       File.stat(pathname).size
     end
 
+    # @return [String] The full path name of the mailbox
     def pathname
       "#{folder_path}.mbox"
     end
 
+    # Renames the mailbox, 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
@@ -79,6 +103,8 @@ module Imap::Backup
       end
     end
 
+    # Sets the mailbox file's updated time to the current time
+    # @return [void]
     def touch
       File.open(pathname, "a") {}
     end

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

@@ -5,10 +5,15 @@ require "imap/backup/email/mboxrd/message"
 module Imap; end
 
 module Imap::Backup
+  # Represents a stored message
   class Serializer::Message
+    # @return [Array[Symbol]] the message's flags
     attr_accessor :flags
+    # @return [Integer] the length of the message (as stored on disk)
     attr_reader :length
+    # @return [Integer] the start of the message inside the mailbox file
     attr_reader :offset
+    # @return [Integer] the message's UID
     attr_accessor :uid
 
     extend Forwardable
@@ -16,6 +21,11 @@ module Imap::Backup
     def_delegator :message, :supplied_body, :body
     def_delegators :message, :imap_body, :date, :subject
 
+    # @param uid [Integer] the message's UID
+    # @param offset [Integer] the start of the message inside the mailbox file
+    # @param length [Integer] the length of the message (as stored on disk)
+    # @param mbox [Serializer::Mbox] the mailbox containing the message
+    # @param flags [Array[Symbol]] the message's flags
     def initialize(uid:, offset:, length:, mbox:, flags: [])
       @uid = uid
       @offset = offset
@@ -24,6 +34,7 @@ module Imap::Backup
       @flags = flags.map(&:to_sym)
     end
 
+    # @return [Hash] the message metadata
     def to_h
       {
         uid: uid,
@@ -33,6 +44,8 @@ module Imap::Backup
       }
     end
 
+    # Reads the message text and returns the original form
+    # @return [String] the message
     def message
       @message =
         begin

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

@@ -1,13 +1,17 @@
 module Imap; end
 
 module Imap::Backup
+  # Enumerates over a list of stores messages
   class Serializer::MessageEnumerator
-    attr_reader :imap
-
+    # @param imap [Serializer::Imap] the metadata serializer for the folder
     def initialize(imap:)
       @imap = imap
     end
 
+    # Enumerates over the messages
+    # @param uids [Array<Integer>] the message UIDs of the messages to iterate over
+    # @yieldparam message [Serializer::Message]
+    # @return [void]
     def run(uids:)
       uids.each do |uid_maybe_string|
         uid = uid_maybe_string.to_i
@@ -18,5 +22,9 @@ module Imap::Backup
         yield message
       end
     end
+
+    private
+
+    attr_reader :imap
   end
 end

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

@@ -3,12 +3,18 @@ require "imap/backup/file_mode"
 module Imap; end
 
 module Imap::Backup
+  # Ensures a file has the desired permissions
   class Serializer::PermissionChecker
+    # @param filename [String] the file name
+    # @param limit [Integer] the maximum permission that should be set
     def initialize(filename:, limit:)
       @filename = filename
       @limit = limit
     end
 
+    # Runs the check
+    # @raise [RuntimeError] if the permissions are incorrect
+    # @return [void]
     def run
       actual = FileMode.new(filename: filename).mode
       return nil if actual.nil?

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

@@ -1,15 +1,23 @@
 module Imap; end
 
 module Imap::Backup
+  # Stores data during a transaction
   class Serializer::Transaction
+    # @return the transaction's stored data
     attr_reader :data
 
+    # @param owner [any] the class using the transaction -
+    #   this is used when raising errors
     def initialize(owner:)
       @data = nil
       @owner = owner
       @in_transaction = false
     end
 
+    # Runs the transaction
+    # @param data [any] the data to maintain during the transaction
+    # @param block [block] the block to wrap with the transaction
+    # @return [void]
     def begin(data, &block)
       @data = data
       @in_transaction = true
@@ -17,6 +25,8 @@ module Imap::Backup
       @in_transaction = false
     end
 
+    # Clears rollback data
+    # @return [void]
     def clear
       @data = nil
     end
@@ -25,10 +35,18 @@ module Imap::Backup
       @in_transaction
     end
 
+    # Throws an exception if there is a current transaction
+    # @param method [Symbol] the method where the check is run
+    # @raise [RuntimeError] if called from inside a transaction
+    # @return [void]
     def fail_in_transaction!(method, message: "not supported inside trasactions")
       raise "#{owner.class}##{method} #{message}" if in_transaction?
     end
 
+    # Throws an exception if there is not a current transaction
+    # @param method [Symbol] the method where the check is run
+    # @raise [RuntimeError] if called from outside a transaction
+    # @return [void]
     def fail_outside_transaction!(method)
       raise "#{owner.class}##{method} can only be called inside a transaction" if !in_transaction?
     end

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

@@ -3,11 +3,15 @@ require "imap/backup/serializer"
 module Imap; end
 
 module Imap::Backup
+  # Finds a name that can be used to rename a serialized folder
   class Serializer::UnusedNameFinder
+    # @param serializer [Serializer] a folder serializer
     def initialize(serializer:)
       @serializer = serializer
     end
 
+    # Finds the name
+    # @return [String] the name
     def run
       digit = 0
       folder = nil

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

@@ -5,7 +5,9 @@ require "imap/backup/serializer/imap"
 module Imap; end
 
 module Imap::Backup
+  # Migrates serialized folder metadata from the version 2 format to the version 3 format
   class Serializer::Version2Migrator
+    # @param folder_path [String] the base pathv(without extension) of the folder backup
     def initialize(folder_path)
       @folder_path = folder_path
     end
@@ -21,6 +23,8 @@ module Imap::Backup
       true
     end
 
+    # Runs the migration
+    # @return [Boolean] whether the migration was run
     def run
       return false if !required?
 

data/lib/imap/backup/serializer.rb

@@ -15,7 +15,11 @@ require "imap/backup/serializer/unused_name_finder"
 module Imap; end
 
 module Imap::Backup
+  # Handles serialization for a folder
   class Serializer
+    # @param path [String] an account's backup path
+    # @param folder [String] a folder name
+    # @return [String] the full path to a serialized folder (without file extensions)
     def self.folder_path_for(path:, folder:)
       relative = File.join(path, folder)
       File.expand_path(relative)
@@ -26,9 +30,13 @@ module Imap::Backup
     def_delegator :mbox, :pathname, :mbox_pathname
     def_delegators :imap, :get, :messages, :uid_validity, :uids, :update_uid
 
+    # @return [String] a folder name
     attr_reader :folder
+    # @return [String] an account's backup path
     attr_reader :path
 
+    # @param path [String] an account's backup path
+    # @param folder [String] a folder name
     def initialize(path, folder)
       @path = path
       @folder = folder
@@ -38,14 +46,17 @@ module Imap::Backup
     # Calls the supplied block.
     # This method is present so that this class implements the same
     # interface as {DelayedMetadataSerializer}
+    # @param block [block] the block that is wrapped by the transaction
     #
     # @return [void]
     def transaction(&block)
       block.call
     end
 
-    # Returns true if there are existing, valid files
-    # false otherwise (in which case any existing files are deleted)
+    # Checks that the metadata files are valid, migrates the metadata file
+    # from older versions, if necessary,
+    # 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
 
@@ -61,16 +72,33 @@ module Imap::Backup
       false
     end
 
+    # Checks that the folder's data is stored correctly
+    # @return [void]
     def check_integrity!
       IntegrityChecker.new(imap: imap, mbox: mbox).run
     end
 
+    # Deletes the serialized data
+    # @return [void]
     def delete
       imap.delete
       mbox.delete
       reload
     end
 
+    # Sets the folder's UID validity.
+    # If the existing value is nil, it sets the new value
+    # and ensures that both the metadata file and the mailbox
+    # are saved.
+    # If the supplied value is the same as the existing value,
+    # it does nothing.
+    # If the supplied valued is *different* to the existing value,
+    # it renames the existing folder to a new name, and creates a
+    # new folder with the supplied value.
+    #
+    # @param value [Integer] The new UID validity value
+    #
+    # @return [String, nil] The name of the new folder
     def apply_uid_validity(value)
       validate!
 
@@ -86,12 +114,22 @@ module Imap::Backup
       end
     end
 
+    # Overwrites the UID validity of the folder
+    # and ensures that both the metadata file and the mailbox
+    # are saved.
+    # @param value [Integer] the new UID validity
+    # @return [void]
     def force_uid_validity(value)
       validate!
 
       internal_force_uid_validity(value)
     end
 
+    # Appends a message to the serialized data
+    # @param uid [Integer] the message's UID
+    # @param message [Integer] the message text
+    # @param flags [Array[Symbol]] the message's flags
+    # @return [void]
     def append(uid, message, flags)
       validate!
 
@@ -99,6 +137,10 @@ module Imap::Backup
       appender.append(uid: uid, message: message, flags: flags)
     end
 
+    # Updates a messages flags
+    # @param uid [Integer] the message's UID
+    # @param flags [Array<Symbol>] the flags to set on the message
+    # @return [void]
     def update(uid, flags: nil)
       message = imap.get(uid)
       return if !message
@@ -107,6 +149,10 @@ module Imap::Backup
       imap.save
     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
 
@@ -118,6 +164,10 @@ module Imap::Backup
       enumerator.run(uids: required_uids, &block)
     end
 
+    # Calls the supplied block on each message in the folder
+    # and discards those for which the block returns a false result
+    # @param block [block] the block to call
+    # @return [void]
     def filter(&block)
       temp_name = Serializer::UnusedNameFinder.new(serializer: self).run
       temp_folder_path = self.class.folder_path_for(path: path, folder: temp_name)
@@ -137,14 +187,18 @@ module Imap::Backup
       reload
     end
 
+    # @return [String] the path to the serialized folder (without file extensions)
     def folder_path
       self.class.folder_path_for(path: path, folder: sanitized)
     end
 
+    # @return [String] The folder's name adapted for using as a file name
     def sanitized
       @sanitized ||= Naming.to_local_path(folder)
     end
 
+    # Forces a reload of the serialized files
+    # @return [void]
     def reload
       @imap = nil
       @mbox = nil

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

@@ -8,12 +8,18 @@ module Imap::Backup
   class Setup; end
   class Setup::Account; end
 
+  # Displays the header to the account modification menu
   class Setup::Account::Header
+    # @param menu [Highline::Menu] the menu
+    # @param account [Account] an Account
     def initialize(menu:, account:)
       @menu = menu
       @account = account
     end
 
+    # Displays the header
+    #
+    # @return [void]
     def run
       rows = [
         email,

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

@@ -10,13 +10,19 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Handles interactive account setup
   class Setup::Account
+    # @param config [Configuration] the application configuration
+    # @param account [Account] an Account
+    # @param highline [Higline] the configured Highline instance
     def initialize(config, account, highline)
       @account = account
       @config = config
       @highline = highline
     end
 
+    # Shows the menu
+    # @return [void]
     def run
       if !account.local_path
         account.local_path = File.join(config.path, account.username.tr("@", "_"))

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

@@ -3,11 +3,17 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Implements interactively requesting information from the user
   class Setup::Asker
+    # @param highline [Higline] the configured Highline instance
     def initialize(highline)
       @highline = highline
     end
 
+    # Asks for a email address
+    #
+    # @param default [String] the existing email address
+    # @return [String] the email address
     def email(default = "")
       highline.ask("email address: ") do |q|
         q.default               = default
@@ -16,6 +22,9 @@ module Imap::Backup
       end
     end
 
+    # Asks for a password
+    #
+    # @return [String] the password
     def password
       password     = highline.ask("password: ")        { |q| q.echo = false }
       confirmation = highline.ask("repeat password: ") { |q| q.echo = false }
@@ -29,10 +38,17 @@ module Imap::Backup
       password
     end
 
+    # Asks for a email address using the configured menu handler
+    #
+    # @param default [String] the existing email address
+    # @return [String] the email address
     def self.email(default = "")
       new(Setup.highline).email(default)
     end
 
+    # Asks for a password using the configured menu handler
+    #
+    # @return [String] the password
     def self.password
       new(Setup.highline).password
     end

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

@@ -3,12 +3,18 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Requests an updated backup path from the user
   class Setup::BackupPath
+    # @param account [Account] an Account
+    # @param config [Configuration] the application configuration
     def initialize(account:, config:)
       @account = account
       @config = config
     end
 
+    # Asks the user for a backup path
+    #
+    # @return [void]
     def run
       account.local_path = highline.ask("backup directory: ") do |q|
         q.default  = account.local_path

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

@@ -5,11 +5,16 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Attempts to login to an account and reports the result
   class Setup::ConnectionTester
+    # @param account [Account] an Account
     def initialize(account)
       @account = account
     end
 
+    # Carries out the attempted login and indicates
+    # whether it was successful
+    # @return [void]
     def test
       account.client.login
       "Connection successful"

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

@@ -6,12 +6,18 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Asks the user for a new email address
   class Setup::EmailChanger
+    # @param account [Account] an Account
+    # @param config [Configuration] the application configuration
     def initialize(account:, config:)
       @account = account
       @config = config
     end
 
+    # Asks the user for an email address,
+    # ensuring that the supplied address is not an existing account
+    # @return [void]
     def run
       username = Setup::Asker.email(account.username)
       other_accounts = config.accounts.reject { |a| a == account }

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

@@ -5,11 +5,15 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Allows the user to select and deselect folders to be backed up
   class Setup::FolderChooser
+    # @param account [Account] an Account
     def initialize(account)
       @account = account
     end
 
+    # Lists account folders and allows the user to toggle whther they are selected
+    # @return [void]
     def run
       if client.nil?
         highline.ask "Press a key "

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

@@ -5,11 +5,15 @@ module Imap::Backup; end
 class Imap::Backup::Setup; end
 
 class Imap::Backup::Setup::GlobalOptions
+  # Allows changing the globally configured download strategy
   class DownloadStrategyChooser
+    # @param config [Configuration] the application configuration
     def initialize(config:)
       @config = config
     end
 
+    # Shows the menu
+    # @return [void]
     def run
       catch :done do
         loop do

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

@@ -6,11 +6,15 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Shows the menu of global options
   class Setup::GlobalOptions
+    # @param config [Configuration] the application configuration
     def initialize(config:)
       @config = config
     end
 
+    # Shows the menu
+    # @return [void]
     def run
       catch :done do
         loop do

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

@@ -5,11 +5,14 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Helpers for the setup system
   class Setup::Helpers
+    # @return [String] the prefix for setup menus
     def title_prefix
       "imap-backup -"
     end
 
+    # @return [String] the current application version
     def version
       VERSION
     end

data/lib/imap/backup/setup.rb

@@ -10,16 +10,21 @@ require "imap/backup/setup/helpers"
 module Imap; end
 
 module Imap::Backup
+  # Interactively updates the application's configuration file
   class Setup
     class << self
+      # @return [Highline]
       attr_accessor :highline
     end
     self.highline = HighLine.new
 
+    # @param config [Configuration] the application configuration
     def initialize(config:)
       @config = config
     end
 
+    # Shows the menu
+    # @return [void]
     def run
       catch :done do
         loop do

data/lib/imap/backup/text/sanitizer.rb

@@ -5,17 +5,24 @@ module Imap; end
 module Imap::Backup
   module Text; end
 
+  # Wraps standard output and hides passwords from debug output
+  # Any text matching Net::IMAP debug output of passwords is sanitized
   class Text::Sanitizer
     extend Forwardable
 
     delegate puts: :output
     delegate write: :output
 
+    # @param output [IO] the stream to write output to
     def initialize(output)
       @output = output
       @current = ""
     end
 
+    # Outputs everything up to the last newline character,
+    # storing whatever follows the newline.
+    # @param args [Array<String>] lines of text
+    # @return [void]
     def print(*args)
       @current << args.join
       loop do
@@ -28,6 +35,8 @@ module Imap::Backup
       end
     end
 
+    # Outputs any text still not printed
+    # @return [void]
     def flush
       return if @current == ""