imap-backup 8.0.2 → 9.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31b3a3ccf051c6496e8b4fde5eb0b062927fc8a0cb0c605dd597bc1289dd77e1
-  data.tar.gz: f7a7a88cb51f2ebe01e5debd4a25df4df8adf4ee1a5fd2480532c948d51e382b
+  metadata.gz: 3daac577a7328b73a4593e677826b2f168f7565487595a04b37504b863dccd46
+  data.tar.gz: 3290089c8c67f31d7dc7cfc53ca6c6d2dd20328727447b2164273409408d36d5
 SHA512:
-  metadata.gz: 47377d324d8a4f4bf0853ac12f6e972107bbb2d215f4916bd5a6ec301870ef6fad2eb646325dba127dd7bb8ca02f6abe72d2bfeccc139bac87c9df38a55d498a
-  data.tar.gz: 2a07b644b145263f41394f2f96590a0003381911389238f242f973236828ded448c169ed043ec7453d8bd0acc942ecb3d210e298b46d975c08b015794b7f4445
+  metadata.gz: df10381df343a5c4c08d8fa39310a6593b6383608926d360202feb92652bc2ad42bbeffc306789e6f4761bc06405cb2b8d51efe76e65cfc5a9507d397d36e2ae
+  data.tar.gz: 05a4d8b9941622fc56f68e952f71b38383a9593fe6abedb64d6c4b1a5670eee0ca2c40a27cc14a7d05d298638e3c242f056b3a8b68288a61dafae8449f51e36b

data/docs/delimiters-and-prefixes.md

@@ -0,0 +1,16 @@
+# Delimiters and Prefixes
+
+A simple folder name is `Friends`.
+
+Most email servers allow you to put folders inside other folders.
+
+On most email servers, the parts of a folder's name are separated with a `/` character.
+So you might have `People/Friends`.
+
+On the other hand, some email servers use a `.`, giving `People.Friends`.
+
+Some email servers keep most email in a parent folder, often `INBOX`, so the above folder
+would be `INBOX/People/Friends`.
+
+The `migrate` and `mirror` commands provide options to help "translate" between
+the behaviour of the source and destination servers.

data/docs/development.md

@@ -4,6 +4,11 @@
 * Restartable - calculate start point based on already downloaded messages
 * Standalone - do not rely on an email client or MTA
 
+# Development
+
+A setup for developing under any available Ruby version is
+available in the container directory.
+
 # Testing
 
 ## Feature Specs
@@ -56,6 +61,11 @@ uids = imap.uid_search(["ALL"]).sort
 fetch_data_items = imap.uid_fetch(uids, ["BODY[]"])
 ```
 
+# Older Ruby Versions
+
+Dockerfiles are available for all the supported Ruby versions,
+see the `docker` directory.
+
 # Contributing
 
 1. Fork it

data/docs/restore.md

@@ -25,6 +25,4 @@ is already on the server is skipped.
 
 ## How do I restore to a different service?
 
-1. Run setup and add the new server, (but don't run any backups),
-2. Rename of the existing backup directory to match the new email address,
-3. Run the restore.
+It is best to use the `migrate` command in this case.

data/docs/setup.md

@@ -2,4 +2,4 @@
 
 ## Set the server for a Google Apps account
 
-Use imap.gmail.com
+Use `imap.gmail.com` as the 'server' setting.

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

@@ -0,0 +1,96 @@
+module Imap::Backup
+  class CLI::FolderEnumerator
+    attr_reader :destination
+    attr_reader :destination_delimiter
+    attr_reader :source
+    attr_reader :source_delimiter
+
+    def initialize(
+      destination:,
+      source:,
+      destination_delimiter: "/",
+      destination_prefix: "",
+      source_delimiter: "/",
+      source_prefix: ""
+    )
+      @destination = destination
+      @destination_delimiter = destination_delimiter
+      @destination_prefix = destination_prefix
+      @source = source
+      @source_delimiter = source_delimiter
+      @source_prefix = source_prefix
+    end
+
+    def each
+      return enum_for(:each) if !block_given?
+
+      glob = File.join(source_local_path, "**", "*.imap")
+      Pathname.glob(glob) do |path|
+        name = source_folder_name(path)
+        serializer = Serializer.new(source_local_path, name)
+        folder = destination_folder_for(name)
+        yield serializer, folder
+      end
+    end
+
+    private
+
+    def destination_prefix_clipped
+      @destination_prefix_clipped ||=
+        if @destination_prefix.end_with?(destination_delimiter)
+          @destination_prefix[0..-2]
+        else
+          @destination_prefix
+        end
+    end
+
+    def source_prefix_clipped
+      @source_prefix_clipped ||=
+        if @source_prefix.end_with?(source_delimiter)
+          @source_prefix[0..-2]
+        else
+          @source_prefix
+        end
+    end
+
+    def destination_folder_for(name)
+      parts = name.split(source_delimiter)
+      no_source_prefix =
+        if source_prefix_clipped != "" && parts.first == source_prefix_clipped
+          parts[1..]
+        else
+          parts
+        end
+
+      with_destination_prefix =
+        if destination_prefix_clipped && destination_prefix_clipped != ""
+          no_source_prefix.unshift(destination_prefix_clipped)
+        else
+          no_source_prefix
+        end
+
+      destination_name = with_destination_prefix.join(destination_delimiter)
+
+      Account::Folder.new(
+        destination.connection,
+        destination_name
+      )
+    end
+
+    def source_local_path
+      source.local_path
+    end
+
+    def source_folder_name(imap_pathname)
+      base = Pathname.new(source_local_path)
+      imap_name = imap_pathname.relative_path_from(base).to_s
+      dir = File.dirname(imap_name)
+      stripped = File.basename(imap_name, ".imap")
+      if dir == "."
+        stripped
+      else
+        File.join(dir, stripped)
+      end
+    end
+  end
+end

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

@@ -1,3 +1,4 @@
+require "imap/backup/cli/folder_enumerator"
 require "imap/backup/migrator"
 
 module Imap::Backup
@@ -5,10 +6,12 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    attr_reader :destination_delimiter
     attr_reader :destination_email
     attr_reader :destination_prefix
     attr_reader :config_path
     attr_reader :reset
+    attr_reader :source_delimiter
     attr_reader :source_email
     attr_reader :source_prefix
 
@@ -16,15 +19,19 @@ module Imap::Backup
       source_email,
       destination_email,
       config: nil,
+      destination_delimiter: "/",
       destination_prefix: "",
       reset: false,
+      source_delimiter: "/",
       source_prefix: ""
     )
       super([])
+      @destination_delimiter = destination_delimiter
       @destination_email = destination_email
       @destination_prefix = destination_prefix
       @config_path = config
       @reset = reset
+      @source_delimiter = source_delimiter
       @source_email = source_email
       @source_prefix = source_prefix
     end
@@ -51,62 +58,28 @@ module Imap::Backup
         @config ||= load_config(config: config_path)
       end
 
-      def destination_account
-        config.accounts.find { |a| a.username == destination_email }
+      def enumerator_options
+        {
+          destination: destination_account,
+          destination_delimiter: destination_delimiter,
+          destination_prefix: destination_prefix,
+          source: source_account,
+          source_delimiter: source_delimiter,
+          source_prefix: source_prefix
+        }
       end
 
       def folders
-        return enum_for(:folders) if !block_given?
-
-        glob = File.join(source_local_path, "**", "*.imap")
-        Pathname.glob(glob) do |path|
-          name = source_folder_name(path)
-          serializer = Serializer.new(source_local_path, name)
-          folder = folder_for(name)
-          yield serializer, folder
-        end
+        CLI::FolderEnumerator.new(**enumerator_options)
       end
 
-      def folder_for(source_folder)
-        no_source_prefix =
-          if source_prefix != "" && source_folder.start_with?(source_prefix)
-            source_folder.delete_prefix(source_prefix)
-          else
-            source_folder.to_s
-          end
-
-        with_destination_prefix =
-          if destination_prefix && destination_prefix != ""
-            destination_prefix + no_source_prefix
-          else
-            no_source_prefix
-          end
-
-        Account::Folder.new(
-          destination_account.connection,
-          with_destination_prefix
-        )
-      end
-
-      def source_local_path
-        source_account.local_path
+      def destination_account
+        config.accounts.find { |a| a.username == destination_email }
       end
 
       def source_account
         config.accounts.find { |a| a.username == source_email }
       end
-
-      def source_folder_name(imap_pathname)
-        base = Pathname.new(source_local_path)
-        imap_name = imap_pathname.relative_path_from(base).to_s
-        dir = File.dirname(imap_name)
-        stripped = File.basename(imap_name, ".imap")
-        if dir == "."
-          stripped
-        else
-          File.join(dir, stripped)
-        end
-      end
     end
   end
 end

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

@@ -1,3 +1,4 @@
+require "imap/backup/cli/folder_enumerator"
 require "imap/backup/mirror"
 
 module Imap::Backup
@@ -5,9 +6,11 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    attr_reader :destination_delimiter
     attr_reader :destination_email
     attr_reader :destination_prefix
     attr_reader :config_path
+    attr_reader :source_delimiter
     attr_reader :source_email
     attr_reader :source_prefix
 
@@ -15,13 +18,17 @@ module Imap::Backup
       source_email,
       destination_email,
       config: nil,
+      destination_delimiter: "/",
       destination_prefix: "",
+      source_delimiter: "/",
       source_prefix: ""
     )
       super([])
+      @destination_delimiter = destination_delimiter
       @destination_email = destination_email
       @destination_prefix = destination_prefix
       @config_path = config
+      @source_delimiter = source_delimiter
       @source_email = source_email
       @source_prefix = source_prefix
     end
@@ -61,62 +68,28 @@ module Imap::Backup
         @config = load_config(config: config_path)
       end
 
-      def destination_account
-        config.accounts.find { |a| a.username == destination_email }
+      def enumerator_options
+        {
+          destination: destination_account,
+          destination_delimiter: destination_delimiter,
+          destination_prefix: destination_prefix,
+          source: source_account,
+          source_delimiter: source_delimiter,
+          source_prefix: source_prefix
+        }
       end
 
       def folders
-        return enum_for(:folders) if !block_given?
-
-        glob = File.join(source_local_path, "**", "*.imap")
-        Pathname.glob(glob) do |path|
-          name = source_folder_name(path)
-          serializer = Serializer.new(source_local_path, name)
-          folder = folder_for(name)
-          yield serializer, folder
-        end
-      end
-
-      def folder_for(source_folder)
-        no_source_prefix =
-          if source_prefix != "" && source_folder.start_with?(source_prefix)
-            source_folder.delete_prefix(source_prefix)
-          else
-            source_folder.to_s
-          end
-
-        with_destination_prefix =
-          if destination_prefix && destination_prefix != ""
-            destination_prefix + no_source_prefix
-          else
-            no_source_prefix
-          end
-
-        Account::Folder.new(
-          destination_account.connection,
-          with_destination_prefix
-        )
+        CLI::FolderEnumerator.new(**enumerator_options)
       end
 
-      def source_local_path
-        source_account.local_path
+      def destination_account
+        config.accounts.find { |a| a.username == destination_email }
       end
 
       def source_account
         config.accounts.find { |a| a.username == source_email }
       end
-
-      def source_folder_name(imap_pathname)
-        base = Pathname.new(source_local_path)
-        imap_name = imap_pathname.relative_path_from(base).to_s
-        dir = File.dirname(imap_name)
-        stripped = File.basename(imap_name, ".imap")
-        if dir == "."
-          stripped
-        else
-          File.join(dir, stripped)
-        end
-      end
     end
   end
 end

data/lib/imap/backup/cli.rb

@@ -69,9 +69,12 @@ module Imap::Backup
       All emails which have been backed up for the "source account" (SOURCE_EMAIL) are
       uploaded to the "destination account" (DESTINATION_EMAIL).
 
-      When one or other account has namespaces (i.e. prefixes like "INBOX."),
+      When one or other account has namespaces (i.e. prefixes like "INBOX"),
       use the `--source-prefix=` and/or `--destination-prefix=` options.
 
+      When one or other account uses a delimiter other than `/` (i.e. `.`),
+      use the `--source-delimiter=` and/or `--destination-delimiter=` options.
+
       Usually, you should migrate to an account with empty folders.
 
       Before migrating each folder, `imap-backup` checks if the destination
@@ -86,6 +89,11 @@ module Imap::Backup
     config_option
     quiet_option
     verbose_option
+    method_option(
+      "destination-delimiter",
+      type: :string,
+      desc: "the delimiter for destination folder names"
+    )
     method_option(
       "destination-prefix",
       type: :string,
@@ -98,6 +106,11 @@ module Imap::Backup
       desc: "DANGER! This option deletes all messages from destination folders before uploading",
       aliases: ["-r"]
     )
+    method_option(
+      "source-delimiter",
+      type: :string,
+      desc: "the delimiter for source folder names"
+    )
     method_option(
       "source-prefix",
       type: :string,
@@ -132,12 +145,22 @@ module Imap::Backup
     config_option
     quiet_option
     verbose_option
+    method_option(
+      "destination-delimiter",
+      type: :string,
+      desc: "the delimiter for destination folder names"
+    )
     method_option(
       "destination-prefix",
       type: :string,
       desc: "the prefix (namespace) to add to destination folder names",
       aliases: ["-d"]
     )
+    method_option(
+      "source-delimiter",
+      type: :string,
+      desc: "the delimiter for source folder names"
+    )
     method_option(
       "source-prefix",
       type: :string,

data/lib/imap/backup/version.rb

@@ -1,9 +1,9 @@
 module Imap; end
 
 module Imap::Backup
-  MAJOR    = 8
+  MAJOR    = 9
   MINOR    = 0
-  REVISION = 2
+  REVISION = 0
   PRE      = nil
   VERSION  = [MAJOR, MINOR, REVISION, PRE].compact.map(&:to_s).join(".")
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 8.0.2
+  version: 9.0.0
 platform: ruby
 authors:
 - Joe Yates
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-12 00:00:00.000000000 Z
+date: 2022-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -218,6 +218,7 @@ files:
 - README.md
 - bin/imap-backup
 - docs/configuration.md
+- docs/delimiters-and-prefixes.md
 - docs/development.md
 - docs/restore.md
 - docs/setup.md
@@ -240,6 +241,7 @@ files:
 - lib/imap/backup/account/folder.rb
 - lib/imap/backup/cli.rb
 - lib/imap/backup/cli/backup.rb
+- lib/imap/backup/cli/folder_enumerator.rb
 - lib/imap/backup/cli/helpers.rb
 - lib/imap/backup/cli/local.rb
 - lib/imap/backup/cli/migrate.rb