mailshears 0.0.1

data/lib/common/domain.rb

@@ -0,0 +1,64 @@
+require 'common/errors'
+
+# A class representing a syntactically valid domain. Essentially, the
+# part after the "@" in an email address. Once constructed, you can be
+# sure that it's valid.
+#
+class Domain
+
+  # @domain contains the String representation of this domain.
+  @domain = nil
+
+
+  # Initialize this Domain object. If the domain is invalid, then an
+  # {InvalidDomainError} will be raised containing the reason
+  # why the domain is invalid.
+  #
+  # @param domain [String] the string representation of this domain.
+  #
+  def initialize(domain)
+    if domain.empty? then
+      msg = "domain cannot be empty"
+      raise InvalidDomainError.new(msg)
+    end
+
+    @domain = domain
+  end
+
+
+  # Convert this domain to a String.
+  #
+  # @return [String] the string representation of this Domain.
+  #
+  def to_s()
+    return @domain
+  end
+
+
+  # Check if this Domain is equal to some other Domain. The comparison
+  # is based on their String representations.
+  #
+  # @param other [Domain] the Domain object to compare me to.
+  #
+  # @return [Boolean] If *self* and *other* have equal String
+  #   representations, then true is returned. Otherwise, false is
+  #   returned.
+  #
+  def ==(other)
+    return self.to_s() == other.to_s()
+  end
+
+
+  # Compare two Domain objects for sorting purposes. The comparison
+  # is based on their String representations.
+  #
+  # @param other [Domain] the Domain object to compare me to.
+  #
+  # @return [0,1,-1] a trinary indicator of how *self* relates to *other*,
+  #   obtained by performing the same comparison on the String
+  #   representations of *self* and *other*.
+  #
+  def <=>(other)
+    return self.to_s() <=> other.to_s()
+  end
+end

data/lib/common/dovecot_plugin.rb

@@ -0,0 +1,130 @@
+require 'common/domain'
+require 'common/filesystem'
+require 'common/plugin'
+require 'common/user'
+
+# Code that all Dovecot plugins ({DovecotPrune}, {DovecotRm}, and
+# {DovecotMv}) will share.
+#
+module DovecotPlugin
+
+  # We implement the Plugin "interface."
+  include Plugin
+
+
+  # Initialize this Dovecot {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
+  def initialize(cfg)
+    @domain_root = cfg.dovecot_mail_root
+  end
+
+  # Describe the given Dovecot domain by its filesystem path. The
+  # domain need not exist to obtain its path.
+  #
+  # @param domain [Domain] the {Domain} object whose description we want.
+  #
+  # @return [String] a String giving the path under which this domain's
+  #   mailboxes would reside on the filesystem.
+  #
+  def describe_domain(domain)
+    return get_domain_path(domain)
+  end
+
+
+  # Describe the given Dovecot user by its filesystem mailbox
+  # path. The user need not exist to obtain its mailbox path.
+  #
+  # @param user [User] the {User} object whose description we want.
+  #
+  # @return [String] a String giving the path where this user's
+  #   mailbox would reside on the filesystem.
+  #
+  def describe_user(user)
+    return get_user_path(user)
+  end
+
+
+  protected;
+
+  # Return the filesystem path for the given {Domain} object.
+  #
+  # @param domain [Domain] the {Domain} whose path we want.
+  #
+  # @return [String] the filesystem path where this domain's mail
+  #   would be located.
+  #
+  def get_domain_path(domain)
+    return File.join(@domain_root, domain.to_s())
+  end
+
+
+  # Return the filesystem path of this {User}'s mailbox.
+  #
+  # @param user [User] the {User} whose mailbox path we want.
+  #
+  # @return [String] the filesystem path where this user's mail
+  #   would be located.
+  #
+  def get_user_path(user)
+    domain_path = get_domain_path(user.domain())
+    return File.join(domain_path, user.localpart())
+  end
+
+
+  # Produce a list of domains that exist in the Dovecot mailstore.
+  #
+  # @return [Array<Domain>] an array of {Domain} objects that have
+  #   corresponding directories within the Dovecot mailstore.
+  #
+  def list_domains()
+    return Filesystem.get_subdirs(@domain_root).map{ |d| Domain.new(d) }
+  end
+
+
+  # Produce a list of users belonging to the given *domains* in the
+  # Dovecot mailstore.
+  #
+  # @param domains [Array<Domain>] an array of {Domain} objects whose
+  #   users we'd like to find.
+  #
+  # @return [Array<User>] an array of {User} objects that have
+  #   corresponding directories within the Dovecot mailstore belonging
+  #   to the specified *domains*.
+  #
+  def list_domains_users(domains)
+    users = []
+
+    domains.each do |domain|
+      begin
+        # Throws a NonexistentDomainError if the domain's path
+        # doesn't exist on the filesystem. In this case, we want
+        # to report zero users.
+        domain_path = get_domain_path(domain)
+        usernames = Filesystem.get_subdirs(domain_path)
+
+        usernames.each do |username|
+          users << User.new("#{username}@#{domain}")
+        end
+      rescue NonexistentDomainError
+        # Party hard.
+      end
+    end
+
+    return users
+  end
+
+
+  # Produce a list of all users in the Dovecot mailstore.
+  #
+  # @return [Array<User>] a list of users who have mailbox directories
+  #   within the Dovecot mailstore.
+  #
+  def list_users()
+    domains = list_domains()
+    users = list_domains_users(domains)
+    return users
+  end
+
+end

data/lib/common/errors.rb

@@ -0,0 +1,15 @@
+# An error indicating that a username is syntactically invalid.
+class InvalidUserError < StandardError; end
+
+# An error indicating that a domain is syntactically invalid.
+class InvalidDomainError < StandardError; end
+
+# An error indicating that a user does not exist.
+class NonexistentUserError < StandardError; end
+
+# An error indicating that a domain does not exist.
+class NonexistentDomainError < StandardError; end
+
+# An error indicating that some user already exists. For example, if
+# one tries to rename a user and the destination user already exists.
+class UserAlreadyExistsError < StandardError; end

data/lib/common/exit_codes.rb

@@ -0,0 +1,9 @@
+# Command-line exit codes. In other words, what you'll see if you
+# <tt>echo $?</tt> after running the executable on the command-line.
+module ExitCodes
+  # Everything went better than expected.
+  SUCCESS = 0
+
+  # The command-line arguments were not what we expected.
+  BAD_COMMAND_LINE = 1
+end

data/lib/common/filesystem.rb

@@ -0,0 +1,43 @@
+# Convenience methods for working with the filesystem. This class
+# only provides static methods, to be used analogously to the File
+# class (for example, <tt>File.directory?</tt>).
+#
+class Filesystem
+
+  # Return whether or not the given path begins with a dot (ASCII
+  # period).
+  #
+  # @param path [String] the path whose first character you want to check.
+  #
+  # @return [Boolean] whether or not *path* begins with an ASCII period.
+  #
+  def self.begins_with_dot?(path)
+    return (path[0..0] == '.')
+  end
+
+
+  # Get a list of all real subdirectories of the given directory.
+  #
+  # @param dir [String] the directory whose subdirectories you want.
+  #
+  # @return [Array<String>] a list of subdirectories of *dir*, not
+  #   including the pseudo-directories "." and ".." (the current/parent
+  #   directories).
+  #
+  def self.get_subdirs(dir)
+    subdirs = []
+    return subdirs if not File.directory?(dir)
+
+    Dir.open(dir) do |d|
+      d.each do |entry|
+        relative_path = File.join(dir, entry)
+        if File.directory?(relative_path) and not self.begins_with_dot?(entry)
+          subdirs << entry
+        end
+      end
+    end
+
+    return subdirs
+  end
+
+end

data/lib/common/plugin.rb

@@ -0,0 +1,238 @@
+require 'common/domain'
+require 'common/user'
+
+# Methods that all plugins must provide. Certain operations -- for
+# example, user listing -- must be supported by all plugins. These
+# operations are defined here, often with naive default
+# implementations, but it is up to each individual plugin to ensure
+# that they are in fact implemented (well).
+#
+module Plugin
+
+  # These are class methods for runnable plugins, meant to be
+  # _extended_. Those runnable plugins get a magic *run* method but
+  # need to define their own *runner* and *dummy_runner* to make it
+  # work.
+  #
+  module Run
+
+    # A callback function, called whenever another class or module
+    # includes this one. This is used to build a list of all things
+    # that inherited this class. Having such a list lets us run a
+    # collection of plugins without knowing in advance what they are.
+    #
+    # @param c [Class,Module] the name of the class or module that
+    #   included us.
+    #
+    def included(c)
+      @includers ||= []
+      @includers << c
+    end
+
+
+    # Obtain the list of classes and modules that have included this one.
+    #
+    # @return [Array<Class,Module>] the list of classes and modules
+    #   that have included this one.
+    #
+    def includers()
+      @includers ||= []
+      return @includers
+    end
+
+
+    # The runner class associated with this plugin. This method must
+    # be supplied by the child class, since they will all have
+    # different runners.
+    #
+    # @return [Class] the runner class associated with this plugin.
+    #
+    def runner()
+      raise NotImplementedError
+    end
+
+
+    # The "dummy" runner class associated with this plugin. This method
+    # must be supplied by the child class, since they will all have
+    # different dummy runners.
+    #
+    # @return [Class] the dummy runner class associated with this
+    #   plugin.
+    #
+    def dummy_runner()
+      raise NotImplementedError
+    end
+
+
+    # Run all of the plugins that have included this module.
+    #
+    # @param cfg [Configuration] the configuration options to pass to
+    #   each of the plugins.
+    #
+    # @param args [Array<Object>] a variable number of additional
+    #   arguments to be passed to the plugins we're running.
+    #
+    def run(cfg, *args)
+      includers().each do |includer|
+        plugin = includer.new(cfg)
+
+        if cfg.i_mean_business then
+          runner = runner().new()
+        else
+          runner = dummy_runner().new()
+        end
+
+        # The splat passes the correct (we hope) number of arguments to the
+        # appropriate runner. The Rm(Dummy)Runner have splats on their
+        # *target arguments as well, to turn ARGV back into an array.
+        runner.run(cfg, plugin, *args)
+      end
+    end
+  end
+
+
+  # A generic version of {#describe_user}/{#describe_domain} that
+  # dispatches base on the class of the target.
+  #
+  # @param target [User,Domain] either a user or a domain to describe.
+  #
+  # @return [String] a string describing the *target*. The contents of
+  #   the string depend on the plugin.
+  #
+  def describe(target)
+    if target.is_a?(User)
+      if user_exists(target) then
+        return describe_user(target)
+      else
+        return 'User not found'
+      end
+    elsif target.is_a?(Domain)
+      if domain_exists(target) then
+        return describe_domain(target)
+      else
+        return 'Domain not found'
+      end
+    else
+      raise NotImplementedError
+    end
+  end
+
+
+  # Provide a description of the given *domain*. This is output along
+  # with the domain name and can be anything of use to the system
+  # administrator. The default doesn't do anything useful and should
+  # be overridden if possible.
+  #
+  # @param domain [Domain] the domain to describe.
+  #
+  # @return [String] a string description of *domain*.
+  #
+  def describe_domain(domain)
+    return domain.to_s()
+  end
+
+
+  # Provide a description of the given *user*. This is output along
+  # with the username and can be anything of use to the system
+  # administrator. The default doesn't do anything useful and should
+  # be overridden if possible.
+  #
+  # @param user [User] the domain to describe.
+  #
+  # @return [String] a string description of *user*.
+  #
+  def describe_user(user)
+    return user.to_s()
+  end
+
+
+  # Return a list of all users managed by this plugin. This must be
+  # supplied by the individual plugins (who know how to find their
+  # users).
+  #
+  # @return [Array<User>] a list of the users that this plugin knows
+  #   about.
+  #
+  def list_users()
+    raise NotImplementedError
+  end
+
+
+  # Return a list of all domains managed by this plugin. This must be
+  # supplied by the individual plugins (who know how to find their
+  # domains). Many plugins will not have a separate concept of
+  # "domain", so the default implementation constructs a list of
+  # domains resulting from {#list_users}.
+  #
+  # For plugins that do know about domains, smarter implementations
+  # are surely possible.
+  #
+  # @return [Array<Domain>] a list of the domains that this plugin knows
+  #   about.
+  #
+  def list_domains()
+    users = list_users()
+    domains = users.map{ |u| u.domain() }
+    return domains.uniq()
+  end
+
+
+  # Does the given *user* exist for this plugin? We use a naive
+  # implementation here based on {#list_users}. Plugins should override
+  # this with something faster.
+  #
+  # @param user [User] the user whose existence is in question.
+  #
+  # @return [Boolean] true if *user* exists for this plugin, and
+  #   false otherwise.
+  #
+  def user_exists(user)
+    users = list_users()
+    return users.include?(user)
+  end
+
+
+  # Does the given *domain* exist for this plugin? We use a naive
+  # implementation here based on {#list_domains}. Plugins that know
+  # about domains should override this with something fast.
+  #
+  # @param domain [Domain] the domain whose existence is in question.
+  #
+  # @return [Boolean] true if *domain* exists for this plugin, and
+  #   false otherwise.
+  #
+  def domain_exists(domain)
+    domains = list_domains()
+    return domains.include?(domain)
+  end
+
+
+  # List all users belonging to the given domains. We say that a user
+  # belongs to a domain "example.com" if the domain part of the user's
+  # email address is "example.com".
+  #
+  # This uses a naive loop, but relies only on the existence of
+  # {#list_users}. Plugins that know about domains should provide a
+  # more efficient implementation.
+  #
+  # @param domains [Array<Domain>] the domains whose users we want.
+  #
+  # @return [Array<User>] a list of {User} objects belonging to
+  #   *domains* for this plugin.
+  #
+  def list_domains_users(domains)
+    domains_users = []
+
+    users = list_users();
+    domains.each do |d|
+      matches = users.select do |user|
+        user.domainpart() == d.to_s()
+      end
+
+      domains_users += matches
+    end
+
+    return domains_users
+  end
+
+end