imap-backup 3.3.0 → 4.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78b548972cde69ce86be3d23e21dd973730f414b90e5fd0526fd94c2852dc031
-  data.tar.gz: d83b2679e25bea24837b3474ce53c5dede5e90e3611b4c2e7374930dc531aa20
+  metadata.gz: ba3f202308a586f7ec54b28d66ea2f9422cf30f706c118ab02f362346351f268
+  data.tar.gz: 585bd29f2d2f836aad27c6ac58855649b7621eff770d5e2b40bfdd3f6aa774f0
 SHA512:
-  metadata.gz: 419aa2779f25fdb7d34d50b8931a7c77118042082bad3e8d4dcc94a0b5b0a9084d20a684bfe8b8e8b6820f134e3e4f6a3ec0e1d185ad53eb6ccb6ec718f97371
-  data.tar.gz: 90a2a552949b4977acd5bbe920de73ac2f39a20bd3c7656dbac1000176d7457c7969305334d9be7e8d3ec8075f292dbbff2901246022dd5e51d65104e507c8df
+  metadata.gz: 6270660f55ab52e3a3d8242bdfbb2d044ce7428ccc75daabf25b6753a7c91f9c3f4d8b2be4db517f44fb887663a40e946f128c2bf06f4d1006cd02182d9f477e
+  data.tar.gz: f94af41fee60be97e15e0d2aa3da5a0696b9d8bab5cb03cb42c805881b13e8a38fc5be42ee30efd26576d5cadb10d2f53b0c46c00fc94ca72cf23f94e05d602b

data/.circleci/config.yml

@@ -27,7 +27,7 @@ jobs:
         type: string
     environment:
       BUNDLE_PATH: ./vendor/bundle
-      DOCKER_IMAP_PORT: 993
+      DOCKER_IMAP_SERVER: 993
     docker:
       - image: "cimg/ruby:<< parameters.ruby_version >>"
       - image: antespi/docker-imap-devel:latest
@@ -48,4 +48,4 @@ workflows:
       - test:
           matrix:
             parameters:
-              ruby_version: ["2.4", "2.5", "2.6", "2.7"]
+              ruby_version: ["2.5", "2.6", "2.7"]

data/.rubocop_todo.yml

@@ -1,42 +1,129 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2021-01-09 09:21:34 UTC using RuboCop version 0.89.1.
+# on 2021-09-21 15:30:34 UTC using RuboCop version 1.21.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 11
-# Configuration parameters: IgnoredMethods.
-Metrics/AbcSize:
-  Max: 33
+# Offense count: 1
+# Cop supports --auto-correct.
+Layout/ElseAlignment:
+  Exclude:
+    - 'lib/imap/backup/configuration/gmail_oauth2.rb'
 
 # Offense count: 2
-# Configuration parameters: CountComments, CountAsOne, ExcludedMethods.
-# ExcludedMethods: refine
-Metrics/BlockLength:
-  Max: 138
+# Cop supports --auto-correct.
+# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
+Layout/EmptyLineBetweenDefs:
+  Exclude:
+    - 'lib/google/auth/stores/in_memory_token_store.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyleAlignWith, Severity.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/imap/backup/configuration/gmail_oauth2.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: Width, IgnoredPatterns.
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/imap/backup/configuration/gmail_oauth2.rb'
+
+# Offense count: 34
+# Configuration parameters: AllowedMethods.
+# AllowedMethods: enums
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - 'lib/imap/backup/configuration/asker.rb'
+    - 'spec/unit/gmail/authenticator_spec.rb'
+    - 'spec/unit/google/auth/stores/in_memory_token_store_spec.rb'
+    - 'spec/unit/imap/backup/account/connection_spec.rb'
+    - 'spec/unit/imap/backup/account/folder_spec.rb'
+    - 'spec/unit/imap/backup/configuration/account_spec.rb'
+    - 'spec/unit/imap/backup/configuration/gmail_oauth2_spec.rb'
 
 # Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: AllowComments.
+Lint/UselessMethodDefinition:
+  Exclude:
+    - 'lib/imap/backup/configuration/account.rb'
+    - 'lib/imap/backup/configuration/asker.rb'
+
+# Offense count: 11
+# Configuration parameters: IgnoredMethods, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 33
+
+# Offense count: 3
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 167
+  Max: 172
 
-# Offense count: 17
-# Configuration parameters: CountComments, CountAsOne, ExcludedMethods.
+# Offense count: 19
+# Configuration parameters: CountComments, CountAsOne, ExcludedMethods, IgnoredMethods.
 Metrics/MethodLength:
-  Max: 25
+  Max: 26
 
 # Offense count: 2
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 141
+  Max: 145
+
+# Offense count: 2
+# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers.
+# SupportedStyles: snake_case, normalcase, non_integer
+# AllowedIdentifiers: capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339
+Naming/VariableNumber:
+  Exclude:
+    - 'lib/email/provider.rb'
+    - 'spec/unit/email/provider_spec.rb'
 
-# Offense count: 200
+# Offense count: 209
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 16
 
-# Offense count: 1
+# Offense count: 49
 RSpec/NestedGroups:
   Max: 6
+
+# Offense count: 8
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: nested, compact
+Style/ClassAndModuleChildren:
+  Exclude:
+    - 'lib/email/mboxrd/message.rb'
+    - 'lib/imap/backup/downloader.rb'
+    - 'lib/imap/backup/serializer.rb'
+    - 'lib/imap/backup/serializer/mbox.rb'
+    - 'lib/imap/backup/serializer/mbox_enumerator.rb'
+    - 'lib/imap/backup/serializer/mbox_store.rb'
+    - 'lib/imap/backup/uploader.rb'
+    - 'lib/imap/backup/utils.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/RedundantBegin:
+  Exclude:
+    - 'lib/imap/backup/account/connection.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: MinSize, WordRegex.
+# SupportedStyles: percent, brackets
+Style/WordArray:
+  EnforcedStyle: percent
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 133

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [4.0.0.rc1] - 2021-11-17
+
+### Added
+* `local` commands to list accounts, folders and emails and to view single
+  emails.

data/README.md

@@ -16,11 +16,19 @@
 [Rubygem]: http://rubygems.org/gems/imap-backup "Ruby gem at rubygems.org"
 [Continuous Integration]: https://circleci.com/gh/joeyates/imap-backup "Build status by CirceCI"
 
-## GMail
+# GMail
 
-GMail OAuth2 authentication is supported.
+To use imap-backup with GMail, you will need to enable 'App passwords' on your account.
 
-To set it up, [follow the HOWTO](docs/setting-up-gmail.md).
+## GMail OAuth2
+
+GMail OAuth2 authentication is supported, but as GMail's policy requires
+users to set up an application specific to their account, the feature
+is disabled by default.
+
+You will need to set the environment variable IMAP_BACKUP_ENABLE_GMAIL_OAUTH2.
+
+To set it up, [follow the HOWTO](docs/setting-up-gmail-with-oauth2.md).
 
 # Installation
 

data/bin/imap-backup

@@ -1,98 +1,8 @@
 #!/usr/bin/env ruby
-require "optparse"
 
 $LOAD_PATH.unshift(File.expand_path("../lib/", __dir__))
-require "imap/backup"
+require "imap/backup/cli"
 
-KNOWN_COMMANDS = [
-  {name: "setup",   help: "Create/edit the configuration file"},
-  {name: "backup",  help: "Do the backup (default)"},
-  {name: "folders", help: "List folders for all (or selected) accounts"},
-  {name: "restore", help: "Restore emails to server"},
-  {name: "status",  help: "List count of non backed-up emails per folder"},
-  {name: "help",    help: "Show usage"}
-].freeze
+Imap::Backup::Configuration::List.new.setup_logging
 
-options = {command: "backup"}
-parser = OptionParser.new do |opts|
-  opts.banner = "Usage: #{$PROGRAM_NAME} [options] COMMAND"
-
-  opts.separator ""
-  opts.separator "Commands:"
-  KNOWN_COMMANDS.each do |command|
-    opts.separator format("\t%- 20<name>s %<help>s", command)
-  end
-  opts.separator ""
-  opts.separator "Common options:"
-
-  opts.on(
-    "-a",
-    "--accounts ACCOUNT1[,ACCOUNT2,...]",
-    Array,
-    "only these accounts"
-  ) do |account|
-    options[:accounts] = account
-  end
-
-  opts.on_tail("-h", "--help", "Show usage") do
-    puts opts
-    exit
-  end
-
-  opts.on_tail("--version", "Show version") do
-    puts Imap::Backup::VERSION
-    exit
-  end
-end
-parser.parse!
-
-options[:command] = ARGV.shift if !ARGV.empty?
-
-# rubocop:disable Style/IfUnlessModifier
-if KNOWN_COMMANDS.find { |c| c[:name] == options[:command] }.nil?
-  raise "Unknown command '#{options[:command]}'"
-end
-
-# rubocop:enable Style/IfUnlessModifier
-
-if options[:command] == "help"
-  puts parser
-  exit
-end
-
-begin
-  configuration = Imap::Backup::Configuration::List.new(options[:accounts])
-rescue Imap::Backup::ConfigurationNotFound
-  Imap::Backup::Configuration::Setup.new.run
-  exit
-end
-
-configuration.setup_logging
-
-case options[:command]
-when "setup"
-  Imap::Backup::Configuration::Setup.new.run
-when "backup"
-  configuration.each_connection(&:run_backup)
-when "folders"
-  configuration.each_connection do |connection|
-    puts connection.username
-    folders = connection.folders
-    if folders.nil?
-      warn "Unable to list account folders"
-      exit 1
-    end
-    folders.each { |f| puts "\t#{f}" }
-  end
-when "restore"
-  configuration.each_connection(&:restore)
-when "status"
-  configuration.each_connection do |connection|
-    puts connection.username
-    folders = connection.status
-    folders.each do |f|
-      missing_locally = f[:remote] - f[:local]
-      puts "#{f[:name]}: #{missing_locally.size}"
-    end
-  end
-end
+Imap::Backup::CLI.start(ARGV)

data/imap-backup

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path("../lib/", __dir__))
+require "imap/backup/cli"
+
+Imap::Backup::CLI.start(ARGV)
+
+__END__
+

data/imap-backup.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |gem|
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^spec/})
   gem.require_paths = ["lib"]
-  gem.required_ruby_version = [">= 2.4.0"]
+  gem.required_ruby_version = ">= 2.5"
   gem.version = Imap::Backup::VERSION
 
   gem.add_runtime_dependency "gmail_xoauth"
@@ -21,6 +21,7 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency "highline"
   gem.add_runtime_dependency "mail"
   gem.add_runtime_dependency "rake"
+  gem.add_runtime_dependency "thor", "~> 1.1"
 
   gem.add_development_dependency "codeclimate-test-reporter", "~> 0.4.8"
   if RUBY_ENGINE == "jruby"

data/lib/email/mboxrd/message.rb

@@ -36,12 +36,12 @@ module Email::Mboxrd
       supplied_body.gsub(/(?<!\r)\n/, "\r\n")
     end
 
-    private
-
     def parsed
       @parsed ||= Mail.new(supplied_body)
     end
 
+    private
+
     def from
       @from ||=
         begin

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

@@ -64,7 +64,25 @@ module Imap::Backup
 
         Imap::Backup.logger.debug "[#{folder.name}] running backup"
         serializer.apply_uid_validity(folder.uid_validity)
-        Downloader.new(folder, serializer).run
+        begin
+          Downloader.new(folder, serializer).run
+        rescue Net::IMAP::ByeResponseError
+          reconnect
+          retry
+        end
+      end
+    end
+
+    def local_folders
+      return enum_for(:local_folders) if !block_given?
+
+      glob = File.join(local_path, "**", "*.imap")
+      base = Pathname.new(local_path)
+      Pathname.glob(glob) do |path|
+        name = path.relative_path_from(base).to_s[0..-6]
+        serializer = Serializer::Mbox.new(local_path, name)
+        folder = Account::Folder.new(self, name)
+        yield serializer, folder
       end
     end
 
@@ -75,7 +93,7 @@ module Imap::Backup
     end
 
     def disconnect
-      imap.disconnect
+      imap.disconnect if @imap
     end
 
     def reconnect
@@ -91,7 +109,7 @@ module Imap::Backup
             "Creating IMAP instance: #{server}, options: #{options.inspect}"
           )
           imap = Net::IMAP.new(server, options)
-          if gmail? && Gmail::Authenticator.refresh_token?(password)
+          if use_gmail_oauth2? && Gmail::Authenticator.refresh_token?(password)
             authenticator = Gmail::Authenticator.new(email: username, token: password)
             credentials = authenticator.credentials
             raise InvalidGmailOauth2RefreshToken if !credentials
@@ -163,19 +181,10 @@ module Imap::Backup
       password.gsub(/./, "x")
     end
 
-    def gmail?
-      server == Email::Provider::GMAIL_IMAP_SERVER
-    end
-
-    def local_folders
-      glob = File.join(local_path, "**", "*.imap")
-      base = Pathname.new(local_path)
-      Pathname.glob(glob) do |path|
-        name = path.relative_path_from(base).to_s[0..-6]
-        serializer = Serializer::Mbox.new(local_path, name)
-        folder = Account::Folder.new(self, name)
-        yield serializer, folder
-      end
+    def use_gmail_oauth2?
+      # TODO: test use of ENV
+      server == Email::Provider::GMAIL_IMAP_SERVER &&
+        ENV["IMAP_BACKUP_ENABLE_GMAIL_OAUTH2"]
     end
 
     def backup_folders

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

@@ -0,0 +1,21 @@
+module Imap::Backup
+  class CLI::Backup < Thor
+    include Thor::Actions
+    include CLI::Helpers
+
+    attr_reader :account_names
+
+    def initialize(options)
+      super([])
+      @account_names = (options[:accounts] || "").split(",")
+    end
+
+    no_commands do
+      def run
+        each_connection(account_names) do |connection|
+          connection.run_backup
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Imap::Backup
+  class CLI::Folders < Thor
+    include Thor::Actions
+    include CLI::Helpers
+
+    attr_reader :account_names
+
+    def initialize(options)
+      super([])
+      @account_names = (options[:accounts] || "").split(",")
+    end
+
+    no_commands do
+      def run
+        each_connection(account_names) do |connection|
+          puts connection.username
+          folders = connection.folders
+          if folders.nil?
+            warn "Unable to list account folders"
+            return false
+          end
+          folders.each { |f| puts "\t#{f}" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+require "imap/backup"
+
+module Imap::Backup::CLI::Helpers
+  def symbolized(options)
+    options.each.with_object({}) { |(k, v), acc| acc[k.intern] = v }
+  end
+
+  def each_connection(names)
+    begin
+      connections = Imap::Backup::Configuration::List.new(names)
+    rescue Imap::Backup::ConfigurationNotFound
+      raise "imap-backup is not configured. Run `imap-backup setup`"
+      return
+    end
+
+    connections.each_connection do |connection|
+      yield connection
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+module Imap::Backup
+  class CLI::Local < Thor
+    include Thor::Actions
+    include CLI::Helpers
+
+    desc "accounts", "list locally backed-up accounts"
+    def accounts
+      connections = Imap::Backup::Configuration::List.new
+      connections.accounts.each { |a| puts a[:username] }
+    end
+
+    desc "folders EMAIL", "list account folders"
+    def folders(email)
+      connections = Imap::Backup::Configuration::List.new
+      account = connections.accounts.find { |a| a[:username] == email }
+      raise "#{email} is not a configured account" if !account
+
+      account_connection = Imap::Backup::Account::Connection.new(account)
+      account_connection.local_folders.each do |_s, f|
+        puts %("#{f.name}")
+      end
+    end
+
+    desc "emails EMAIL FOLDER", "list emails in a folder"
+    def emails(email, folder_name)
+      connections = Imap::Backup::Configuration::List.new
+      account = connections.accounts.find { |a| a[:username] == email }
+      raise "#{email} is not a configured account" if !account
+
+      account_connection = Imap::Backup::Account::Connection.new(account)
+      folder_serializer, folder = account_connection.local_folders.find do |(_s, f)|
+        f.name == folder_name
+      end
+      raise "Folder '#{folder_name}' not found" if !folder_serializer
+
+      max_subject = 60
+      puts format("%-10<uid>s  %-#{max_subject}<subject>s - %<date>s", {uid: "UID", subject: "Subject", date: "Date"})
+      puts "-" * (12 + max_subject + 28)
+
+      uids = folder_serializer.uids
+
+      folder_serializer.each_message(uids).map do |uid, message|
+        m = {uid: uid, date: message.parsed.date.to_s, subject: message.parsed.subject}
+        if m[:subject].length > max_subject
+          puts format("% 10<uid>u: %.#{max_subject - 3}<subject>s... - %<date>s", m)
+        else
+          puts format("% 10<uid>u: %-#{max_subject}<subject>s - %<date>s", m)
+        end
+      end
+    end
+
+    desc "email EMAIL FOLDER UID", "show an email"
+    def email(email, folder_name, uid)
+      connections = Imap::Backup::Configuration::List.new
+      account = connections.accounts.find { |a| a[:username] == email }
+      raise "#{email} is not a configured account" if !account
+
+      account_connection = Imap::Backup::Account::Connection.new(account)
+      folder_serializer, _folder = account_connection.local_folders.find do |(_s, f)|
+        f.name == folder_name
+      end
+      raise "Folder '#{folder_name}' not found" if !folder_serializer
+
+      loaded_message = folder_serializer.load(uid)
+      raise "Message #{uid} not found in folder '#{folder_name}'" if !loaded_message
+
+      puts loaded_message.supplied_body
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Imap::Backup
+  class CLI::Restore < Thor
+    include Thor::Actions
+    include CLI::Helpers
+
+    attr_reader :account_names
+
+    def initialize(options)
+      super([])
+      @account_names = (options[:accounts] || "").split(",")
+    end
+
+    no_commands do
+      def run
+        each_connection(account_names) { |connection| connection.restore }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+class Imap::Backup::CLI::Setup < Thor
+  include Thor::Actions
+
+  def initialize()
+    super([])
+  end
+
+  no_commands do
+    def run
+      Imap::Backup::Configuration::Setup.new.run
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Imap::Backup
+  class CLI::Status < Thor
+    include Thor::Actions
+    include CLI::Helpers
+
+    attr_reader :account_names
+
+    def initialize(options)
+      super([])
+      @account_names = (options[:accounts] || "").split(",")
+    end
+
+    no_commands do
+      def run
+        each_connection(account_names) do |connection|
+          puts connection.username
+          folders = connection.status
+          folders.each do |f|
+            missing_locally = f[:remote] - f[:local]
+            puts "#{f[:name]}: #{missing_locally.size}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/imap/backup/cli.rb

@@ -0,0 +1,87 @@
+require "thor"
+
+class Imap::Backup::CLI < Thor
+  require "imap/backup/cli/helpers"
+
+  autoload :Backup, "imap/backup/cli/backup"
+  autoload :Folders, "imap/backup/cli/folders"
+  autoload :Local, "imap/backup/cli/local"
+  autoload :Remote, "imap/backup/cli/remote"
+  autoload :Restore, "imap/backup/cli/restore"
+  autoload :Setup, "imap/backup/cli/setup"
+  autoload :Status, "imap/backup/cli/status"
+
+  include Helpers
+
+  default_task :backup
+
+  def self.exit_on_failure?
+    true
+  end
+
+  def self.accounts_option
+    method_option(
+      "accounts",
+      type: :string,
+      banner: "a comma-separated list of accounts (defaults to all configured accounts)",
+      aliases: ["-a"]
+    )
+  end
+
+  desc "backup [OPTIONS]", "Run the backup"
+  long_desc <<~DESC
+    Downloads any emails not yet present locally.
+    Runs the backup for each configured account,
+    or for those requested via the --accounts option.
+    By default all folders, are backed up.
+    The setup tool can be used to choose a specific list of folders to back up.
+  DESC
+  accounts_option
+  def backup
+    Backup.new(symbolized(options)).run
+  end
+
+  desc "folders [OPTIONS]", "This command is deprecated, use `imap-backup remote folders ACCOUNT`"
+  long_desc <<~DESC
+    Lists all folders of all configured accounts.
+    This command is deprecated.
+    Instead, use a combination of `imap-backup local accounts` to get the list of accounts,
+    and `imap-backup remote folders ACCOUNT` to get the folder list.
+  DESC
+  accounts_option
+  def folders
+    Folders.new(symbolized(options)).run
+  end
+
+  desc "restore [OPTIONS]", "This command is deprecated, use `imap-backup restore ACCOUNT`"
+  long_desc <<~DESC
+    By default, restores all local emails to their respective servers.
+    This command is deprecated.
+    Instead, use `imap-backup restore ACCOUNT` to restore a single account.
+  DESC
+  accounts_option
+  def restore
+    Restore.new(symbolized(options)).run
+  end
+
+  desc "setup", "Configure imap-backup"
+  long_desc <<~DESC
+    A menu-driven command-line application used to configure imap-backup.
+    Configure email accounts to back up.
+  DESC
+  def setup
+    Setup.new().run
+  end
+
+  desc "status", "Show backup status"
+  long_desc <<~DESC
+    For each configured account and folder, lists the number of emails yet to be downloaded.
+  DESC
+  accounts_option
+  def status
+    Status.new(symbolized(options)).run
+  end
+
+  desc "local subcommand ...ARGS", "View local info"
+  subcommand "local", Local
+end

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

@@ -69,7 +69,7 @@ module Imap::Backup
     def modify_password(menu)
       menu.choice("modify password") do
         password =
-          if account[:server] == Email::Provider::GMAIL_IMAP_SERVER
+          if use_gmail_oauth2?(account)
             Configuration::GmailOauth2.new(account).run
           else
             Configuration::Asker.password
@@ -82,6 +82,11 @@ module Imap::Backup
       end
     end
 
+    def use_gmail_oauth2?(account)
+      account[:server] == Email::Provider::GMAIL_IMAP_SERVER &&
+        ENV["IMAP_BACKUP_ENABLE_GMAIL_OAUTH2"]
+    end
+
     def modify_server(menu)
       menu.choice("modify server") do
         server = highline.ask("server: ")

data/lib/imap/backup/configuration/gmail_oauth2.rb

@@ -8,7 +8,7 @@ module Imap::Backup
       You need to authorize imap_backup to get access to your email.
       To do so, please follow the instructions here:
 
-      https://github.com/joeyates/imap-backup/blob/main/docs/setting-up-gmail.md
+      https://github.com/joeyates/imap-backup/blob/main/docs/setting-up-gmail-with-oauth2.md
 
     BANNER
 

data/lib/imap/backup/configuration/list.rb

@@ -4,7 +4,7 @@ module Imap::Backup
   class Configuration::List
     attr_reader :required_accounts
 
-    def initialize(required_accounts = nil)
+    def initialize(required_accounts = [])
       @required_accounts = required_accounts
     end
 
@@ -12,6 +12,7 @@ module Imap::Backup
       return if !config_exists?
 
       Imap::Backup.setup_logging config
+      Net::IMAP.debug = config.debug?
     end
 
     def each_connection
@@ -22,6 +23,17 @@ module Imap::Backup
       end
     end
 
+    def accounts
+      @accounts ||=
+        if required_accounts.empty?
+          config.accounts
+        else
+          config.accounts.select do |account|
+            required_accounts.include?(account[:username])
+          end
+        end
+    end
+
     private
 
     def config
@@ -37,16 +49,5 @@ module Imap::Backup
     def config_exists?
       Configuration::Store.exist?
     end
-
-    def accounts
-      @accounts ||=
-        if required_accounts.nil?
-          config.accounts
-        else
-          config.accounts.select do |account|
-            required_accounts.include?(account[:username])
-          end
-        end
-    end
   end
 end

data/lib/imap/backup/version.rb

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

data/spec/fixtures/connection.yml

@@ -2,6 +2,6 @@
 :username: 'address@example.org'
 :password: 'pass'
 :connection_options:
-  :port: <%= ENV.fetch("DOCKER_IMAP_SERVER", 993) %>
+  :port: <%= ENV.fetch("DOCKER_IMAP_SERVER", 8993) %>
   :ssl:
     :verify_mode: 0

data/spec/unit/imap/backup/account/connection_spec.rb

@@ -111,7 +111,15 @@ describe Imap::Backup::Account::Connection do
             with(email: USERNAME, token: PASSWORD) { authenticator }
       end
 
-      context "when the password is our copy of a GMail refresh token" do
+      context "when the password is our copy of a GMail refresh token and  the environment IMAP_BACKUP_ENABLE_GMAIL_OAUTH2 is set" do
+        before do
+          ENV["IMAP_BACKUP_ENABLE_GMAIL_OAUTH2"] = "1"
+        end
+
+        after do
+          ENV.delete("IMAP_BACKUP_ENABLE_GMAIL_OAUTH2")
+        end
+
         it "uses the OAuth2 access_token to authenticate" do
           subject.imap
 
@@ -288,6 +296,24 @@ describe Imap::Backup::Account::Connection do
       end
     end
 
+    context "when the IMAP session expires" do
+      before do
+        data = OpenStruct.new(data: "Session expired")
+        response = OpenStruct.new(data: data)
+        outcomes = [
+          -> { raise Net::IMAP::ByeResponseError, response },
+          -> { nil }
+        ]
+        allow(downloader).to receive(:run) { outcomes.shift.call }
+      end
+
+      it "reconnects" do
+        expect(downloader).to receive(:run).exactly(:twice)
+
+        subject.run_backup
+      end
+    end
+
     context "when run" do
       before { subject.run_backup }
 
@@ -407,24 +433,49 @@ describe Imap::Backup::Account::Connection do
   end
 
   describe "#reconnect" do
-    it "disconnects from the server" do
-      expect(imap).to receive(:disconnect)
+    context "when the IMAP connection has been used" do
+      before { subject.imap }
 
-      subject.reconnect
+      it "disconnects from the server" do
+        expect(imap).to receive(:disconnect)
+
+        subject.reconnect
+      end
+    end
+
+    context "when the IMAP connection has not been used" do
+      it "does not disconnect from the server" do
+        expect(imap).to_not receive(:disconnect)
+
+        subject.reconnect
+      end
     end
 
     it "causes reconnection on future access" do
       expect(Net::IMAP).to receive(:new)
 
       subject.reconnect
+      subject.imap
     end
   end
 
   describe "#disconnect" do
-    it "disconnects from the server" do
-      expect(imap).to receive(:disconnect)
+    context "when the IMAP connection has been used" do
+      it "disconnects from the server" do
+        subject.imap
 
-      subject.disconnect
+        expect(imap).to receive(:disconnect)
+
+        subject.disconnect
+      end
+    end
+
+    context "when the IMAP connection has not been used" do
+      it "does not disconnect from the server" do
+        expect(imap).to_not receive(:disconnect)
+
+        subject.disconnect
+      end
     end
   end
 end

data/spec/unit/imap/backup/configuration/account_spec.rb

@@ -214,16 +214,10 @@ describe Imap::Backup::Configuration::Account do
 
     describe "choosing 'modify password'" do
       let(:new_password) { "new_password" }
-      let(:gmail_oauth2) do
-        instance_double(Imap::Backup::Configuration::GmailOauth2, run: nil)
-      end
 
       before do
         allow(Imap::Backup::Configuration::Asker).
           to receive(:password) { new_password }
-        allow(Imap::Backup::Configuration::GmailOauth2).
-          to receive(:new).
-            with(account) { gmail_oauth2 }
         subject.run
         menu.choices["modify password"].call
       end
@@ -245,14 +239,49 @@ describe Imap::Backup::Configuration::Account do
 
         include_examples "it doesn't flag the account as modified"
       end
+    end
 
-      context "when the server is for GMail" do
-        let(:current_server) { GMAIL_IMAP_SERVER }
+    describe "choosing 'modify password' when the server is for GMail" do
+      let(:new_password) { "new_password" }
+      let(:current_server) { GMAIL_IMAP_SERVER }
+      let(:gmail_oauth2) do
+        instance_double(Imap::Backup::Configuration::GmailOauth2, run: nil)
+      end
+
+      before do
+        allow(Imap::Backup::Configuration::Asker).
+          to receive(:password) { new_password }
+        allow(Imap::Backup::Configuration::GmailOauth2).
+          to receive(:new).
+            with(account) { gmail_oauth2 }
+      end
+
+      context "when the environment IMAP_BACKUP_ENABLE_GMAIL_OAUTH2 is set" do
+        before do
+          ENV["IMAP_BACKUP_ENABLE_GMAIL_OAUTH2"] = "1"
+          subject.run
+          menu.choices["modify password"].call
+        end
+
+        after do
+          ENV.delete("IMAP_BACKUP_ENABLE_GMAIL_OAUTH2")
+        end
 
         it "sets up GMail OAuth2" do
           expect(gmail_oauth2).to have_received(:run)
         end
       end
+
+      context "when the environment IMAP_BACKUP_ENABLE_GMAIL_OAUTH2 is not set" do
+        before do
+          subject.run
+          menu.choices["modify password"].call
+        end
+
+        it "sets up GMail OAuth2" do
+          expect(gmail_oauth2).to_not have_received(:run)
+        end
+      end
     end
 
     describe "choosing 'modify server'" do

data/spec/unit/imap/backup/configuration/list_spec.rb

@@ -35,6 +35,7 @@ describe Imap::Backup::Configuration::List do
       allow(Imap::Backup::Configuration::Store).
         to receive(:exist?) { config_exists }
       allow(Imap::Backup).to receive(:setup_logging)
+      allow(store).to receive(:debug?)
     end
 
     it "sets global logging level" do

data/spec/unit/imap/backup/configuration/setup_spec.rb

@@ -43,7 +43,7 @@ describe Imap::Backup::Configuration::Setup do
     describe "main menu" do
       before { subject.run }
 
-      %w(add\ account save\ and\ exit exit\ without\ saving).each do |choice|
+      ["add account", "save and exit", "exit without saving"].each do |choice|
         it "includes #{choice}" do
           expect(output.string).to include(choice)
         end

data/spec/unit/imap/backup/utils_spec.rb

@@ -12,7 +12,6 @@ describe Imap::Backup::Utils do
   describe ".check_permissions" do
     let(:requested) { 0o345 }
 
-    # rubocop:disable RSpec/EmptyExampleGroup
     context "with existing files" do
       [
         [0o100, "less than the limit", true],
@@ -37,7 +36,6 @@ describe Imap::Backup::Utils do
         end
       end
     end
-    # rubocop:enable RSpec/EmptyExampleGroup
 
     context "with non-existent files" do
       let(:exists) { false }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 4.0.0.rc1
 platform: ruby
 authors:
 - Joe Yates
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-21 00:00:00.000000000 Z
+date: 2021-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gmail_xoauth
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: codeclimate-test-reporter
   requirement: !ruby/object:Gem::Requirement
@@ -178,6 +192,7 @@ files:
 - ".rspec-all"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
@@ -210,7 +225,8 @@ files:
 - docs/26-type-code-into-imap-backup.png
 - docs/27-success.png
 - docs/docker-imap.md
-- docs/setting-up-gmail.md
+- docs/setting-up-gmail-with-oauth2.md
+- imap-backup
 - imap-backup.gemspec
 - lib/email/mboxrd/message.rb
 - lib/email/provider.rb
@@ -219,6 +235,14 @@ files:
 - lib/imap/backup.rb
 - lib/imap/backup/account/connection.rb
 - lib/imap/backup/account/folder.rb
+- lib/imap/backup/cli.rb
+- lib/imap/backup/cli/backup.rb
+- lib/imap/backup/cli/folders.rb
+- lib/imap/backup/cli/helpers.rb
+- lib/imap/backup/cli/local.rb
+- lib/imap/backup/cli/restore.rb
+- lib/imap/backup/cli/setup.rb
+- lib/imap/backup/cli/status.rb
 - lib/imap/backup/configuration/account.rb
 - lib/imap/backup/configuration/asker.rb
 - lib/imap/backup/configuration/connection_tester.rb
@@ -283,14 +307,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Backup GMail (or other IMAP) accounts to disk