imapcli 0.0.1

data/lib/imapcli/client.rb

@@ -0,0 +1,226 @@
+module Imapcli
+  # Wrapper for Net::IMAP
+  class Client
+    require 'net/imap'
+    require 'filesize'
+    require 'descriptive_statistics'
+
+    attr_accessor :port, :user, :pass
+    attr_reader :responses
+
+    ## Initializs the Client class.
+    ##
+    ## +server_with_optional_port+ is the server's domain name; the port may be
+    ## added following a colon. Default port is 993.
+    ## +user+ is the user (account) name to log into the server.
+    ## +pass+ is the password to log into the server.
+    def initialize(server_with_optional_port, user, pass)
+      @port = 993 # default
+      self.server, @user, @pass = server_with_optional_port, user, pass
+      clear_log
+    end
+
+    # Attribute reader for the server domain name
+    def server
+      @server
+    end
+
+    # Attribute writer for the server domain name; a port may be appended with
+    # a colon.
+    #
+    # If no port is appended, the default port (993) will be used.
+    def server=(server_with_optional_port)
+      match = server_with_optional_port.match('^([^:]+):(\d+)$')
+      if match
+        @server = match[1]
+        @port = match[2].to_i
+      else
+        @server = server_with_optional_port
+      end
+    end
+
+    # Perform basic sanity check on server name
+    #
+    # Note that a propery regex for an FQDN is hard to achieve.
+    # See https://stackoverflow.com/a/106223/270712 and elsewhere.
+    def server_valid?
+      @server.match? '^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])$'
+    end
+
+    # Perform *very* basic sanity check on user name
+    #
+    def user_valid?
+      @user&.length > 0
+    end
+
+    # Returns true if both server and user name are valid.
+    def valid?
+      server_valid? && user_valid?
+    end
+
+    # Clears the server response log
+    def clear_log
+      @log = []
+    end
+
+    # Returns the last response from the server
+    def last_response
+      @log.last
+    end
+
+    # Returns a connection to the server.
+    #
+    # The value is cached.
+    def connection
+      @connection ||= Net::IMAP.new(@server, @port, true)
+    end
+
+    # Logs in to the server.
+    #
+    # Returns true if login was successful, false if not (e..g, invalid
+    # credentials).
+    def login
+      raise('no connection to a server') unless connection
+      begin
+        response_ok? connection.login(@user, @pass)
+      rescue Net::IMAP::NoResponseError => error
+        log_error error
+      end
+    end
+
+    # Logs out of the server.
+    def logout
+      # access instance variable to avoid creating a new connection
+      @connection.logout if @connection
+    end
+
+    # Returns the server's greeting (which may reveal the server software name
+    # such as 'Dovecot').
+    def greeting
+      query_server { connection.greeting.data.text.strip }
+    end
+
+    # Returns the server's capabilities.
+    def capability
+      @capability ||= query_server { connection.capability }
+    end
+
+    # Returns the character that is used to separate nested mailbox names.
+    def separator
+      @separator ||= query_server { connection.list('', '')[0].delim }
+    end
+
+    # Returns true if the server supports the IMAP QUOTA extension.
+    def supports_quota
+      capability.include? 'QUOTA'
+    end
+
+    # If the server +supports_quota+, returns an array containing the current
+    # usage (in kiB), the total quota (in kiB), and the percent usage.
+    def quota
+      if supports_quota
+        @quota ||= begin
+          info = query_server { @connection.getquotaroot('INBOX')[1] }
+          percent = info.quota.to_i > 0 ? info.usage.to_i.fdiv(info.quota.to_i) * 100 : nil
+          [ info.usage, info.quota, percent ]
+        end
+      end
+    end
+
+    # Returns an array of message indexes for a mailbox.
+    #
+    # The value is currently NOT cached.
+    def messages(mailbox)
+      query_server { connection.examine(mailbox) }
+      query_server { connection.search('ALL') }
+    end
+
+    # Examines a mailbox and returns statistics about the messages in it.
+    #
+    # Returns an array with the following keys:
+    # * :count: Total count of messages.
+    # * :size: Total size of all messages in bytes.
+    # * :min: Size of the smallest message.
+    # * :q1: First quartile of message sizes.
+    # * :median: Median of message sizes.
+    # * :q3: Third quartile of messages sizes.
+    # * :max: Size of largest message.
+    def examine(mailbox)
+      # Could use the EXAMINE command to get the number of messages in a mailbox,
+      # but we need to retrieve an array of message indexes anyway (to compute
+      # the total mailbox size), so we can save one roundtrip to the server.
+      # query_server { connection.examine(mailbox) }
+      # total = connection.responses['EXISTS'][0]
+      # unseen = query_server { connection.search('UNSEEN') }.length
+      messages = messages(mailbox)
+      count = messages.length
+      sizes = query_server { connection.fetch(messages, 'RFC822.SIZE').map { |f| f.attr['RFC822.SIZE'] }.sort }
+      {
+        count: count,
+        size: convert_bytes(sizes.sum),
+        min: convert_bytes(sizes.first),
+        q1: convert_bytes(sizes.percentile(25)),
+        median: convert_bytes(sizes.median),
+        q3: convert_bytes(sizes.percentile(75)),
+        max: convert_bytes(sizes.last)
+      }
+    end
+
+    # Collects stats for all mailboxes recursively.
+    def collect_stats
+      mailbox_tree.collect_stats(self)
+    end
+
+    # Gets a list of Net::IMAP::MailboxList items, one for each mailbox.
+    #
+    # The value is cached.
+    def mailboxes
+      @mailboxes ||= query_server { @connection.list('', '*') }
+    end
+
+    # Returns a tree of +Imapcli::Mailbox+ objects.
+    #
+    # The value is cached.
+    def mailbox_tree
+      @mailbox_tree ||= Mailbox.new(mailboxes)
+    end
+
+    # Attempts to locate a given +mailbox+ in the +mailbox_tree+.
+    #
+    # Returns nil if the mailbox is not found.
+    def find_mailbox(mailbox)
+      mailbox_tree.find_sub_mailbox(mailbox, separator)
+    end
+
+    private
+
+    def response_ok?(response)
+      @log << response
+      response.name == 'OK'
+    end
+
+    def log_error(error)
+      @log << error
+      false
+    end
+
+    # Wrapper function that can be used to execute code that queries the server.
+    #
+    # This function ensures that there is a valid +connection+ and raises an
+    # error if not. The code that queries the server must be contained in the
+    # +block+, and the +block+'s return value is returned by this function.
+    # The +connection+'s responses are logged.
+    def query_server(&block)
+      raise('no connection to a server') unless connection
+      result = yield
+      @log << connection.responses
+      result
+    end
+
+    # Converts a number of bytes to kiB.
+    def convert_bytes(bytes)
+      bytes.fdiv(1024).round
+    end
+
+  end # class Client
+end # module Imapcli

data/lib/imapcli/command.rb

@@ -0,0 +1,100 @@
+module Imapcli
+  # Provides entry points for Imapcli.
+  #
+  # Most of the methods in this class return
+  class Command
+    def initialize(client)
+      raise 'Imapcli::Client is required' unless client
+      @client = client
+    end
+
+    # Checks if the server accepts the login with the given credentials.
+    #
+    # Returns true if successful, false if not.
+    def check
+      @client.login
+    end
+
+    # Collects basic information about the server.
+    #
+    # The block is called repeatedly with informative messages.
+    # If login is not successful, an error will be raised.
+    def info
+      perform do |output|
+        output << "greeting: #{@client.greeting}"
+        output << "capability: #{@client.capability.join(' ')}"
+        output << "hierarchy separator: #{@client.separator}"
+        if @client.supports_quota
+          usage = Filesize.from(@client.quota[0] + ' kB').pretty
+          available = Filesize.from(@client.quota[1] + ' kB').pretty
+          output << "quota: #{usage} used, #{available} available (#{@client.quota[2].round(1)}%)"
+        else
+          output << "quota: IMAP QUOTA extension not supported by this server"
+        end
+      end
+    end
+
+    def list
+      perform do |output|
+        @client.collect_stats
+        output << "mailboxes (folders) tree:"
+        output += traverse_mailbox_tree @client.mailbox_tree, 0
+      end
+    end
+
+    def stats(mailboxes)
+      perform do |output|
+        mailboxes.each do |name|
+          if mailbox = @client.find_mailbox(name)
+            mailbox.collect_stats(@client)
+            output << [
+              mailbox.full_name,
+              mailbox.stats[:count],
+              format_kib(mailbox.stats[:size]),
+              format_kib(mailbox.stats[:min]),
+              format_kib(mailbox.stats[:q1]),
+              format_kib(mailbox.stats[:median]),
+              format_kib(mailbox.stats[:q3]),
+              format_kib(mailbox.stats[:max])
+            ]
+          else
+            output << [ self.class.unknown_mailbox_prefix + name ] + Array.new(7, '---')
+          end
+        end
+      end
+    end
+
+    def self.unknown_mailbox_prefix
+      '!!! '
+    end
+
+    private
+
+    def perform
+      output = []
+      if @client.login
+        yield output
+      else
+        raise 'unable to log into server'
+      end
+      output
+    end
+
+    def traverse_mailbox_tree(mailbox, depth = 0)
+      output = []
+      if mailbox.has_children?
+        indent = ('  ' * depth) || ''
+        mailbox.children.each do |child|
+          output << indent + '- ' + child.name
+          output += traverse_mailbox_tree child, depth + 1
+        end
+      end
+      output
+    end
+
+    def format_kib(kib)
+      kib.to_s.reverse.gsub(/...(?=.)/,'\&,').reverse + ' kiB'.freeze
+    end
+
+  end
+end

data/lib/imapcli/mailbox.rb

@@ -0,0 +1,108 @@
+module Imapcli
+  # In IMAP speak, a mailbox is what one would commonly call a 'folder'
+  class Mailbox
+    attr_reader :level, :children, :imap_mailbox_list, :name, :stats
+
+    # Creates a new root Mailbox object and optionally adds sub mailboxes from
+    # an array of Net::IMAP::MailboxList items.
+    def initialize(mailbox_list_items = nil)
+      @level = 0
+      @children = {}
+      add_mailbox_list(mailbox_list_items) if mailbox_list_items
+    end
+
+    def [](mailbox)
+      @children[mailbox]
+    end
+
+    def full_name
+      imap_mailbox_list&.name
+    end
+
+    def has_children?
+      @children.length > 0
+    end
+
+    def children
+      @children.values
+    end
+
+    # Add a list of mailboxes as returned by Net::IMAP#list.
+    def add_mailbox_list(array_of_mailbox_list_items)
+      array_of_mailbox_list_items.sort_by { |m| m.name.downcase }.each { |i| add_mailbox i }
+    end
+
+    # Adds a sub mailbox designated by the +name+ of a Net::IMAP::MailboxList.
+    def add_mailbox(imap_mailbox_list, options = {})
+      return unless imap_mailbox_list&.name&.length > 0
+      recursive_add(0, imap_mailbox_list, imap_mailbox_list.name, options)
+    end
+
+    # Attempts to locate and retrieve a sub mailbox.
+    #
+    # Returns nil of none exists with the given name.
+    # Name must be relative to the current mailbox.
+    def find_sub_mailbox(relative_name, delimiter)
+      if relative_name
+        sub_mailbox_name, subs_subs = relative_name.split(delimiter, 2)
+        if sub_mailbox = @children[sub_mailbox_name]
+          sub_mailbox.find_sub_mailbox(subs_subs, delimiter)
+        else
+          nil # no matching sub mailbox found, stop searching the tree
+        end
+      else
+        self
+      end
+    end
+
+    # Collects statistics for this mailbox.
+    #
+    # +connection+ must be a Net::IMAP object
+    def collect_stats(client)
+      if full_name # proceed only if this is a mailbox of its own
+        @stats = client.examine(full_name)
+      end
+    end
+
+    # Collects statistics for this mailbox and all of its children.
+    #
+    # +connection+ must be a Net::IMAP object
+    def collect_stats_recursively(connection)
+      collect_stats(connection)
+      @children.values.each { |child| child.collect_stats_recursively(connection) }
+    end
+
+    protected
+
+    def level=(level)
+      @level = level
+    end
+
+    def name=(name)
+      @name = name
+    end
+
+    def recursive_add(level, imap_mailbox_list, relative_name = nil, options = {})
+      delimiter = options[:delimiter] || imap_mailbox_list.delim
+      if relative_name
+        sub_mailbox_name, subs_subs = relative_name.split(delimiter, 2)
+        if options[:case_insensitive] || (level == 0 && relative_name.upcase == 'INBOX')
+          key = sub_mailbox_name.upcase
+        else
+          key = sub_mailbox_name
+        end
+        # Create a new mailbox if there does not exist one by the name
+        unless sub_mailbox = @children[key]
+          sub_mailbox = Mailbox.new
+          sub_mailbox.level = level
+          sub_mailbox.name = sub_mailbox_name
+          @children[key] = sub_mailbox
+        end
+        sub_mailbox.recursive_add(level + 1, imap_mailbox_list, subs_subs, options)
+      else # no more sub mailboxes: we've reached the last of the children
+        @imap_mailbox_list = imap_mailbox_list
+        self
+      end
+    end
+  end
+end

data/lib/imapcli/version.rb

@@ -0,0 +1,3 @@
+module Imapcli
+  VERSION = '0.0.1'
+end

data/lib/imapcli.rb

@@ -0,0 +1,4 @@
+require 'imapcli/version.rb'
+require 'imapcli/command.rb'
+require 'imapcli/client.rb'
+require 'imapcli/mailbox.rb'

data/spec/lib/imapcli/client_spec.rb

@@ -0,0 +1,70 @@
+require 'imapcli'
+require 'dotenv'
+
+RSpec.describe Imapcli::Client do
+
+  context 'with mock credentials for a nonexistent server' do
+    let(:client) { Imapcli::Client.new('imap.example.com', 'username', 'password') }
+    it 'knows when a server name is invalid' do
+      client.server = 'i n v a l i d'
+      expect(client.server_valid?).to eq false
+    end
+    it 'knows when a server name is valid' do
+      client.server = 'imap.gmail.com'
+      expect(client.server_valid?).to eq true
+    end
+    it 'knows when a user name is invalid' do
+      client.user = ''
+      expect(client.user_valid?).to eq false
+    end
+    it 'knows when a user name is valid' do
+      client.user = 'bovender@example.com'
+      expect(client.user_valid?).to eq true
+    end
+    it 'uses port 993 by default' do
+      expect(client.port).to eq 993
+    end
+    it 'extracts a port from the server info' do
+      client.server = 'imap.example.com:143'
+      expect(client.port).to eq 143
+    end
+    it 'extracts a server from the server string when a port is appended' do
+      client.server = 'imap.example.com:143'
+      expect(client.server).to eq 'imap.example.com'
+    end
+  end
+
+  context 'with valid credentials for an actual server' do
+    before :all do
+      Dotenv.load
+    end
+
+    let(:client) { Imapcli::Client.new(ENV['IMAP_SERVER'], ENV['IMAP_USER'], ENV['IMAP_PASS']) }
+
+    it 'the IMAP_SERVER variable must be set' do
+      expect(ENV['IMAP_SERVER']).to_not eq(nil)
+    end
+    it 'the IMAP_USER variable must be set' do
+      expect(ENV['IMAP_USER']).to_not eq(nil)
+    end
+    it 'the IMAP_PASS variable must be set' do
+      expect(ENV['IMAP_PASS']).to_not eq(nil)
+    end
+    it 'successfully logs in to the server' do
+      expect(client.login).to eq true
+    end
+  end
+
+  context 'with invalid credentials for an actual server' do
+    before :all do
+      Dotenv.load
+    end
+
+    let(:client) { Imapcli::Client.new(ENV['IMAP_SERVER'], ENV['IMAP_USER'], ENV['IMAP_PASS'] + 'invalid') }
+
+    it 'cannot log in to the server' do
+      expect(client.login).to eq false
+    end
+  end
+
+end

data/spec/lib/imapcli/mailbox_spec.rb

@@ -0,0 +1,21 @@
+require 'imapcli'
+require 'net/imap'
+
+RSpec.describe Imapcli::Mailbox do
+  # it 'parses a mailbox list' do
+  #   mailbox_list = Net::IMAP::MailboxList.new(attr: nil, delim: '/', name: 'Root/Subfolder')
+  #   mailbox_tree = Imapcli::MailboxTree.new(mailbox_list)
+  #   expect(mailbox_tree.tree.length).to eq 1
+  # end
+  it 'returns nil if a given sub mailbox does not exist' do
+    mailbox = Imapcli::Mailbox.new
+    expect(mailbox.find_sub_mailbox('INBOX.does.not.exist', '.')).to eq nil
+  end
+  it 'adds and retrieves an existing sub mailbox' do
+    name = 'Root/Subfolder/Subsubfolder'
+    imap_mailbox_list = Net::IMAP::MailboxList.new(nil, '/', name)
+    mailbox = Imapcli::Mailbox.new
+    mailbox.add_mailbox(imap_mailbox_list)
+    expect(mailbox.find_sub_mailbox(name, '/').imap_mailbox_list).to eq imap_mailbox_list
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,102 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+require 'pry'
+
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # This allows you to limit a spec run to individual examples or groups
+  # you care about by tagging them with `:focus` metadata. When nothing
+  # is tagged with `:focus`, all examples get run. RSpec also provides
+  # aliases for `it`, `describe`, and `context` that include `:focus`
+  # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
+  config.filter_run_when_matching :focus
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = "doc"
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+end