imap-backup 14.6.1 → 15.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf35a029c76b09db247f5d45e6624fe6d0d1f1453ee29edd1e02e6621eb42710
-  data.tar.gz: 2238c658e5306848de14ff2edffbf1275576ff1b27c0aa04c642a7c2de9d7fba
+  metadata.gz: de4f5bfc1260430435d380fd3fa6c315efad4ef503b0429bce041615d3ae2e10
+  data.tar.gz: 3c1541e30cb01d1ecd6da9372e79b8e8c71f119eee5a11770bef76b90e89e037
 SHA512:
-  metadata.gz: d066629d29da0114e76d95b137caa7ba4ac26d91bda560a8a2fced551ad88f22477a67a0cfc9130365dafe7a4a60928b2ebedbc301ab6371d4aeade2de6131ab
-  data.tar.gz: 75ac7182884ca791e30a7058940b40c4940f4ad515677f081de8f29e7c9da72061d3ee6eee9fce02efc734803f31ab2f2a66ae25356d284ce38f66d3af2ee8eb
+  metadata.gz: 25aa565a7860560958b59c5f88f67b470128405acc15fc67fe3683152d0ea9c63d8787287f006249a22b26a88d92425bed653254126ef92259ea85022b33efcb
+  data.tar.gz: 54d8df69cef34dcafd3ba97f63f202b0f00e2306f8e12c4ea7329dfae5028e42e9a4050630fae2d03131048aa3c70e90ee7bb8a49a1388084bd136ad3e0ce973

data/imap-backup.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |gem|
 
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.require_paths = ["lib"]
-  gem.required_ruby_version = ">= 2.7"
+  gem.required_ruby_version = ">= 3.0"
 
   gem.add_runtime_dependency "highline"
   gem.add_runtime_dependency "mail", "2.7.1"

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

@@ -29,11 +29,13 @@ module Imap::Backup
 
       serializer.apply_uid_validity(folder.uid_validity)
 
-      download_serializer.transaction do
+      serializer.transaction do
         downloader.run
+        FlagRefresher.new(folder, serializer).run if account.mirror_mode || refresh
       end
-
-      clean_up
+      # After the transaction the serializer will have any appended messages
+      # so we can check differences between the server and the local backup
+      LocalOnlyMessageDeleter.new(folder, raw_serializer).run if account.mirror_mode
     end
 
     private
@@ -55,34 +57,29 @@ module Imap::Backup
       true
     end
 
-    def clean_up
-      LocalOnlyMessageDeleter.new(folder, serializer).run if account.mirror_mode
-      FlagRefresher.new(folder, serializer).run if account.mirror_mode || refresh
-    end
-
     def downloader
       @downloader ||= Downloader.new(
         folder,
-        download_serializer,
+        serializer,
         multi_fetch_size: account.multi_fetch_size,
         reset_seen_flags_after_fetch: account.reset_seen_flags_after_fetch
       )
     end
 
-    def download_serializer
-      @download_serializer ||=
+    def serializer
+      @serializer ||=
         case account.download_strategy
         when "direct"
-          serializer
+          raw_serializer
         when "delay_metadata"
-          Serializer::DelayedMetadataSerializer.new(serializer: serializer)
+          Serializer::DelayedMetadataSerializer.new(serializer: raw_serializer)
         else
           raise "Unknown download strategy '#{account.download_strategy}'"
         end
     end
 
-    def serializer
-      @serializer ||= Serializer.new(account.local_path, folder.name)
+    def raw_serializer
+      @raw_serializer ||= Serializer.new(account.local_path, folder.name)
     end
   end
 end

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

@@ -32,7 +32,7 @@ module Imap::Backup
     # @yieldparam serializer [Serializer] the folder's serializer
     # @yieldparam folder [Account::Folder] the online folder
     # @return [Enumerator, void]
-    def each
+    def each(&block)
       return enum_for(:each) if !block_given?
 
       glob = File.join(source_local_path, "**", "*.imap")
@@ -40,7 +40,7 @@ module Imap::Backup
         name = source_folder_name(path)
         serializer = Serializer.new(source_local_path, name)
         folder = destination_folder_for_path(name)
-        yield serializer, folder
+        block.call(serializer, folder)
       end
     end
 

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

@@ -1,5 +1,6 @@
 require "thor"
 
+require "imap/backup/cli/options"
 require "imap/backup/configuration"
 require "imap/backup/configuration_not_found"
 
@@ -11,67 +12,8 @@ module Imap::Backup
   # Provides helper methods for CLI classes
   module CLI::Helpers
     def self.included(base)
-      base.class_eval do
-        def self.accounts_option
-          method_option(
-            "accounts",
-            type: :string,
-            desc: "a comma-separated list of accounts (defaults to all configured accounts)",
-            aliases: ["-a"]
-          )
-        end
-
-        def self.config_option
-          method_option(
-            "config",
-            type: :string,
-            desc: "supply the configuration file path (default: ~/.imap-backup/config.json)",
-            aliases: ["-c"]
-          )
-        end
-
-        def self.format_option
-          method_option(
-            "format",
-            type: :string,
-            desc: "the output type, 'text' for plain text or 'json'",
-            aliases: ["-f"]
-          )
-        end
-
-        def self.quiet_option
-          method_option(
-            "quiet",
-            type: :boolean,
-            desc: "silence all output",
-            aliases: ["-q"]
-          )
-        end
-
-        def self.refresh_option
-          method_option(
-            "refresh",
-            type: :boolean,
-            desc: "in the default 'keep all emails' mode, " \
-                  "updates flags for messages that are already downloaded",
-            aliases: ["-r"]
-          )
-        end
-
-        def self.verbose_option
-          method_option(
-            "verbose",
-            type: :boolean,
-            desc:
-              "increase the amount of logging. " \
-              "Without this option, the program gives minimal output. " \
-              "Using this option once gives more detailed output. " \
-              "Whereas, using this option twice also shows all IMAP network calls",
-            aliases: ["-v"],
-            repeatable: true
-          )
-        end
-      end
+      options = CLI::Options.new(base: base)
+      options.define_options
     end
 
     # Processes command-line parameters
@@ -81,7 +23,7 @@ module Imap::Backup
     def options
       @symbolized_options ||= # rubocop:disable Naming/MemoizedInstanceVariableName
         begin
-          options = super()
+          options = super
           options.each.with_object({}) do |(k, v), acc|
             key =
               if k.is_a?(String)

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

@@ -0,0 +1,74 @@
+require "thor"
+
+module Imap; end
+
+module Imap::Backup
+  class CLI < Thor; end
+
+  # Defines option methods for CLI classes
+  class CLI::Options
+    attr_reader :base
+
+    # Options common to many commands
+    OPTIONS = [
+      {
+        name: "accounts",
+        parameters: {
+          type: :string, aliases: ["-a"],
+          desc: "a comma-separated list of accounts (defaults to all configured accounts)"
+        }
+      },
+      {
+        name: "config",
+        parameters: {
+          type: :string, aliases: ["-c"],
+          desc: "supply the configuration file path (default: ~/.imap-backup/config.json)"
+        }
+      },
+      {
+        name: "format",
+        parameters: {
+          type: :string, desc: "the output type, 'text' for plain text or 'json'", aliases: ["-f"]
+        }
+      },
+      {
+        name: "quiet",
+        parameters: {
+          type: :boolean, desc: "silence all output", aliases: ["-q"]
+        }
+      },
+      {
+        name: "refresh",
+        parameters: {
+          type: :boolean, aliases: ["-r"],
+          desc: "in the default 'keep all emails' mode, " \
+                "updates flags for messages that are already downloaded"
+        }
+      },
+      {
+        name: "verbose",
+        parameters: {
+          type: :boolean, aliases: ["-v"], repeatable: true,
+          desc: "increase the amount of logging. " \
+                "Without this option, the program gives minimal output. " \
+                "Using this option once gives more detailed output. " \
+                "Whereas, using this option twice also shows all IMAP network calls"
+        }
+      }
+    ].freeze
+
+    def initialize(base:)
+      @base = base
+    end
+
+    def define_options
+      OPTIONS.each do |option|
+        base.singleton_class.class_eval do
+          define_method("#{option[:name]}_option") do
+            method_option(option[:name], **option[:parameters])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -23,12 +23,12 @@ module Imap::Backup
     # Proxies calls to the client.
     # Before the first call does login
     # @return the return value of the client method called
-    def method_missing(method_name, *arguments, &block)
+    def method_missing(method_name, ...)
       if login_called
-        client.send(method_name, *arguments, &block)
+        client.send(method_name, ...)
       else
         do_first_login
-        client.send(method_name, *arguments, &block) if method_name != :login
+        client.send(method_name, ...) if method_name != :login
       end
     end
 

data/lib/imap/backup/flag_refresher.rb

@@ -28,6 +28,13 @@ module Imap::Backup
 
     def refresh_block(uids)
       uids_and_flags = folder.fetch_multi(uids, ["FLAGS"])
+      if !uids_and_flags
+        Logger.logger.debug(
+          "[#{folder.name}] failed to fetch flags for #{uids} - " \
+          "cannot refresh flags"
+        )
+        return
+      end
       uids_and_flags.each do |uid_and_flags|
         uid = uid_and_flags[:uid]
         flags = uid_and_flags[:flags]

data/lib/imap/backup/logger.rb

@@ -51,11 +51,11 @@ module Imap::Backup
     # Wraps a block, filtering output to standard error,
     # hidng passwords and outputs the results to standard out
     # @return [void]
-    def self.sanitize_stderr
+    def self.sanitize_stderr(&block)
       sanitizer = Text::Sanitizer.new($stdout)
       previous_stderr = $stderr
       $stderr = sanitizer
-      yield
+      block.call
     ensure
       sanitizer.flush
       $stderr = previous_stderr

data/lib/imap/backup/naming.rb

@@ -7,7 +7,7 @@ module Imap::Backup
     # 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
+    INVALID_FILENAME_CHARACTER_MATCH = /([#{INVALID_FILENAME_CHARACTERS}])/
 
     # @param name [String] a folder name
     # @return [String] the supplied string iwth disallowed characters replaced

data/lib/imap/backup/retry_on_error.rb

@@ -13,9 +13,9 @@ module Imap::Backup
     # @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)
+    def retry_on_error(errors:, limit: 10, on_error: nil, &block)
       tries ||= 1
-      yield
+      block.call
     rescue *errors => e
       if tries < limit
         message = "#{e}, attempt #{tries} of #{limit}"

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

@@ -10,7 +10,7 @@ module Imap; end
 module Imap::Backup
   class Serializer; end
 
-  # Wraps the Serializer, delaying metadata appends
+  # Wraps the Serializer, delaying metadata changes
   class Serializer::DelayedMetadataSerializer
     extend Forwardable
 
@@ -31,7 +31,7 @@ module Imap::Backup
     def transaction(&block)
       tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")
 
-      tsx.begin({metadata: []}) do
+      tsx.begin({appends: [], updates: []}) do
         mbox.transaction do
           block.call
 
@@ -42,7 +42,21 @@ module Imap::Backup
       end
     end
 
-    # Appends a message to the mbox file and adds the metadata
+    # Sets the folder's UID validity via the serializer
+    #
+    # @param uid_validity [Integer] the UID validity to apply
+    # @raise [RuntimeError] if called inside a transaction
+    # @return [void]
+    def apply_uid_validity(uid_validity)
+      tsx.fail_in_transaction!(
+        :transaction,
+        message: "UID validity cannot be changed in a transaction"
+      )
+
+      serializer.apply_uid_validity(uid_validity)
+    end
+
+    # Appends a message to the mbox file and adds the appended message's metadata
     # to the transaction
     #
     # @param uid [Integer] the UID of the message
@@ -53,10 +67,21 @@ module Imap::Backup
       tsx.fail_outside_transaction!(:append)
       mboxrd_message = Email::Mboxrd::Message.new(message)
       serialized = mboxrd_message.to_serialized
-      tsx.data[:metadata] << {uid: uid, length: serialized.bytesize, flags: flags}
+      tsx.data[:appends] << {uid: uid, length: serialized.bytesize, flags: flags}
       mbox.append(serialized)
     end
 
+    # Stores changes to a message's metadata for later update
+    #
+    # @param uid [Integer] the UID of the message
+    # @param length [Integer] the length of the message
+    # @param flags [Array<Symbol>] the flags for the message
+    # @return [void]
+    def update(uid, length: nil, flags: nil)
+      tsx.fail_outside_transaction!(:update)
+      tsx.data[:updates] << {uid: uid, length: length, flags: flags}
+    end
+
     private
 
     attr_reader :serializer
@@ -64,9 +89,12 @@ module Imap::Backup
     def commit
       # rubocop:disable Lint/RescueException
       imap.transaction do
-        tsx.data[:metadata].each do |m|
+        tsx.data[:appends].each do |m|
           imap.append m[:uid], m[:length], flags: m[:flags]
         end
+        tsx.data[:updates].each do |m|
+          imap.update m[:uid], length: m[:length], flags: m[:flags]
+        end
       rescue Exception => e
         Logger.logger.error "#{self.class} handling #{e.class}"
         imap.rollback

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

@@ -97,11 +97,27 @@ module Imap::Backup
       save
     end
 
-    # Get message metadata
+    # Updates a message's length and/or flags
+    # @param uid [Integer] the existing message's UID
+    # @param length [Integer] the length of the message (as stored on disk)
+    # @param flags [Array[Symbol]] the message's flags
+    # @raise [RuntimeError] if the UID does not exist
+    # @return [void]
+    def update(uid, length: nil, flags: nil)
+      index = messages.find_index { |m| m.uid == uid }
+      raise "UID #{uid} not found" if !index
+
+      messages[index].length = length if length
+      messages[index].flags = flags if flags
+      save
+    end
+
+    # Get a copy of message metadata
     # @param uid [Integer] a message UID
     # @return [Serializer::Message]
     def get(uid)
-      messages.find { |m| m.uid == uid }
+      message = messages.find { |m| m.uid == uid }
+      message&.dup
     end
 
     # Deletes the metadata file
@@ -158,11 +174,15 @@ module Imap::Backup
       messages.map(&:uid)
     end
 
-    # Update a message's metadata, replacing its UID
+    # Update a message's UID
     # @param old [Integer] the existing message UID
     # @param new [Integer] the new UID to apply to the message
+    # @raise [RuntimeError] if the new UID already exists
     # @return [void]
     def update_uid(old, new)
+      existing = messages.find_index { |m| m.uid == new }
+      raise "UID #{new} already exists" if existing
+
       index = messages.find_index { |m| m.uid == old }
       return if index.nil?
 

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

@@ -14,14 +14,14 @@ module Imap::Backup
     # @param uids [Array<Integer>] the message UIDs of the messages to iterate over
     # @yieldparam message [Serializer::Message]
     # @return [void]
-    def run(uids:)
+    def run(uids:, &block)
       uids.each do |uid_maybe_string|
         uid = uid_maybe_string.to_i
         message = imap.get(uid)
 
         next if !message
 
-        yield message
+        block.call(message)
       end
     end
 

data/lib/imap/backup/serializer.rb

@@ -28,6 +28,7 @@ module Imap::Backup
     extend Forwardable
 
     def_delegator :mbox, :pathname, :mbox_pathname
+    def_delegator :imap, :update
 
     # Get message metadata
     # @param uid [Integer] a message UID
@@ -77,7 +78,7 @@ module Imap::Backup
       @validated = nil
     end
 
-    # Calls the supplied block.
+    # Calls the supplied block without implementing transactional behaviour.
     # 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
@@ -177,18 +178,6 @@ 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
-
-      message.flags = flags if flags
-      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

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

@@ -55,7 +55,7 @@ module Imap::Backup
 
     private
 
-    EMAIL_MATCHER = /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]+$/i.freeze
+    EMAIL_MATCHER = /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]+$/i
 
     attr_reader :highline
   end

data/lib/imap/backup/version.rb

@@ -2,11 +2,11 @@ module Imap; end
 
 module Imap::Backup
   # @private
-  MAJOR    = 14
+  MAJOR    = 15
   # @private
-  MINOR    = 6
+  MINOR    = 0
   # @private
-  REVISION = 1
+  REVISION = 2
   # @private
   PRE      = nil
   # The application version

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 14.6.1
+  version: 15.0.2
 platform: ruby
 authors:
 - Joe Yates
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-30 00:00:00.000000000 Z
+date: 2024-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -153,6 +153,7 @@ files:
 - lib/imap/backup/cli/helpers.rb
 - lib/imap/backup/cli/local.rb
 - lib/imap/backup/cli/local/check.rb
+- lib/imap/backup/cli/options.rb
 - lib/imap/backup/cli/remote.rb
 - lib/imap/backup/cli/restore.rb
 - lib/imap/backup/cli/setup.rb
@@ -226,7 +227,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="