mailshears 0.0.1

data/lib/common/postfixadmin_plugin.rb

@@ -0,0 +1,180 @@
+require 'common/domain'
+require 'common/plugin'
+require 'common/user'
+require 'pg'
+
+# Code that all Postfixadmin plugins ({PostfixadminPrune},
+# {PostfixadminRm}, {PostfixadminMv}) share.
+#
+module PostfixadminPlugin
+
+  # We implement the Plugin "interface."
+  include Plugin
+
+  # Initialize this Postfixadmin {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
+  def initialize(cfg)
+    @db_hash = {
+      :host     => cfg.postfixadmin_dbhost,
+      :port     => cfg.postfixadmin_dbport,
+      :options  => cfg.postfixadmin_dbopts,
+      :tty      => cfg.postfixadmin_dbtty,
+      :dbname   => cfg.postfixadmin_dbname,
+      :user     => cfg.postfixadmin_dbuser,
+      :password => cfg.postfixadmin_dbpass }
+  end
+
+
+  # Obtain a list of domains from Postfixadmin. This is more efficient
+  # than the {Plugin} default implementation because domains have
+  # their own table in the database and we can easily select them
+  # rather than filtering the list of users.
+  #
+  # @return [Array<Domain>] a list of the domains in Postfixadmin.
+  #
+  def list_domains()
+    domains = []
+
+    connection = PG::Connection.new(@db_hash)
+
+    # 'ALL' is a magic domain, and we don't want it.
+    sql_query = "SELECT domain FROM domain WHERE domain <> 'ALL';"
+
+    begin
+      connection.query(sql_query) do |result|
+        domains = result.field_values('domain')
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return domains.map{ |d| Domain.new(d) }
+  end
+
+
+  # Return a list of Postfixadmin users.
+  #
+  # @return [Array<User>] a list of users contained in the
+  #   Postfixadmin database.
+  #
+  def list_users()
+    users = []
+
+    connection = PG::Connection.new(@db_hash)
+
+    sql_query = 'SELECT username FROM mailbox;'
+
+    begin
+      connection.query(sql_query) do |result|
+        users = result.field_values('username')
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return users.map{ |u| User.new(u) }
+  end
+
+
+
+  # Efficiently list all Postfixadmin users belonging to the given
+  # Postfixadmin *domains*.
+  #
+  # @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)
+    usernames = []
+    return usernames if domains.length() == 0
+
+    connection = PG::Connection.new(@db_hash)
+
+    # The number of parameters that we'll pass into our prepared query
+    # is the number of domains that we're given. It's important that
+    # we have at least one domain here.
+    params = 1.upto(domains.length()).map{ |i| '$' + i.to_s() }.join(',')
+    sql_query  = "SELECT username FROM mailbox WHERE domain IN (#{params});"
+
+    begin
+      # Now replace each Domain with its string representation and pass
+      # those in as our individual parameters.
+      connection.query(sql_query, domains.map{ |d| d.to_s() }) do |result|
+        usernames = result.field_values('username')
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return usernames.map{ |u| User.new(u) }
+  end
+
+
+  # Get a list of all Postfixadmin aliases as a <tt>from => to</tt>
+  # hash. This is useful for testing, since aliases should be removed
+  # when either the "from user" or "to user" are removed.
+  #
+  # @return [Hash] all aliases known to Postfixadmin in the form of a
+  #   <tt>from => to</tt> hash.
+  #
+  def list_aliases()
+    aliases = []
+
+    connection = PG::Connection.new(@db_hash)
+
+    sql_query = 'SELECT address,goto FROM alias;'
+
+    begin
+      results = connection.query(sql_query)
+      results.each do |row|
+        # row should be a hash
+        aliases << row
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return aliases
+  end
+
+
+  # A fast implementation of the "does this domain exist?"
+  # operation. It only queries the database for the existence of
+  # *domain* rather than a list of all domains (which is the default
+  # implementation).
+  #
+  # @param domain [Domain] the domain whose existence is in question.
+  #
+  # @return [Boolean] true if *domain* exists in the Postfixadmin
+  #   database and false otherwise.
+  #
+  def domain_exists(domain)
+    count = 0
+
+    connection = PG::Connection.new(@db_hash)
+
+    sql_query = 'SELECT COUNT(domain) as count FROM domain WHERE domain = $1;'
+
+    begin
+      connection.query(sql_query, [domain.to_s()]) do |result|
+        return false if result.ntuples() < 1
+        count = result.getvalue(0,0).to_i()
+
+        return false if count.nil?
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return (count > 0)
+  end
+
+end

data/lib/common/roundcube_plugin.rb

@@ -0,0 +1,96 @@
+require 'common/plugin'
+require 'common/user'
+
+# Code that all Roundcube plugins ({RoundcubePrune}, {RoundcubeRm},
+# {RoundcubeMv}) share.
+#
+module RoundcubePlugin
+
+  # We implement the Plugin "interface."
+  include Plugin
+
+
+  # Initialize this Roundcube {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
+  def initialize(cfg)
+    @db_hash = {
+      :host     => cfg.roundcube_dbhost,
+      :port     => cfg.roundcube_dbport,
+      :options  => cfg.roundcube_dbopts,
+      :tty      => cfg.roundcube_dbtty,
+      :dbname   => cfg.roundcube_dbname,
+      :user     => cfg.roundcube_dbuser,
+      :password => cfg.roundcube_dbpass }
+  end
+
+
+  # Describe the given Roundcube *user*.
+  #
+  # @param user [User] the user whose description we want.
+  #
+  # @return [String] a string containing the Roundcube "User ID"
+  #   associated with *user*.
+  #
+  def describe_user(user)
+    user_id = self.get_user_id(user)
+    return "User ID: #{user_id}"
+  end
+
+
+  # Return a list of Roundcube users.
+  #
+  # @return [Array<User>] a list of users contained in the
+  #   Roundcube database.
+  #
+  def list_users()
+    usernames = []
+
+    connection = PG::Connection.connect(@db_hash)
+
+    sql_query = 'SELECT username FROM users;'
+
+    begin
+      connection.query(sql_query) do |result|
+        usernames = result.field_values('username')
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return usernames.map{ |u| User.new(u) }
+  end
+
+  protected;
+
+
+  # Find the Roundcube "User ID" associated with the given *user*.
+  #
+  # @param user [User] the user whose Roundcube "User ID" we want.
+  #
+  # @return [Fixnum] the Roundcube "User ID" for *user*.
+  #
+  def get_user_id(user)
+    user_id = nil
+
+    connection = PG::Connection.new(@db_hash)
+    sql_query = 'SELECT user_id FROM users WHERE username = $1;'
+
+    begin
+      connection.query(sql_query, [user.to_s()]) do |result|
+        if result.num_tuples > 0
+          user_id = result[0]['user_id']
+        end
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return user_id
+  end
+
+
+end

data/lib/common/runner.rb

@@ -0,0 +1,73 @@
+# Methods inherited by the various runner classes ({PruneRunner},
+# {MvRunner}, {RmRunner}).
+#
+module Runner
+
+
+  # The main thing a runner does is <tt>run()</tt>. Each runner will
+  # actually take a different number of arguments, so their
+  # <tt>run()</tt> signatures will differ. This stub is only here to
+  # let you know that it needs to be implemented.
+  #
+  # @param args [Array<Object>] whatever arguments the real implementation
+  #   would take.
+  #
+  def run(*args)
+    raise NotImplementedError
+  end
+
+
+  # When we're describing a user or domain, we often want to output
+  # some additional description of it. But then, sometimes that
+  # additional description is pointless, like when it's exactly the
+  # same as the username that we're already outputting. This function
+  # determines whether or not *desc* is pointless for *target*.
+  #
+  # @param target [User,Domain] the user or domain described by *desc*.
+  #
+  # @param desc [String] a string description of *target*.
+  #
+  # @return [Boolean] true if *desc* is a pointless description of
+  #   *target* and false otherwise.
+  #
+  def pointless?(target, desc)
+    return (desc.nil? or desc.empty? or desc == target.to_s())
+  end
+
+
+  # If *desc* is not a pointless description of *target*, return the
+  # string representation of *target* followed by *desc* in
+  # parentheses. If *desc* is pointless, we return only the string
+  # representation of *target*
+  #
+  # @param target [User,Domain] the user or domain we want to describe
+  #   as a string.
+  #
+  # @param desc [String] a string description of *target*.
+  #
+  # @return [String] the string representation of *target*, possibly
+  #   followed by the non-pointless description *desc*.
+  #
+  def add_description(target, desc)
+    if pointless?(target, desc)
+      return target.to_s()
+    else
+      return target.to_s() + " (#{desc})"
+    end
+  end
+
+
+  # Report a message from the given *plugin*. All this does is prefix
+  # the message with the plugin name and then print it to stdout.
+  #
+  # @param plugin [Object] t plugin object that generated the message
+  #   we're reporting.
+  #
+  # @param msg [String] the message to report.
+  #
+  def report(plugin, msg)
+    print "#{plugin.class.to_s()} - "
+    puts msg
+  end
+
+end

data/lib/common/user.rb

@@ -0,0 +1,120 @@
+require 'common/domain'
+require 'common/errors'
+
+# A class representing a syntactically valid user; that is, an email
+# address. Once constructed, you can be sure that it's valid.
+#
+class User
+
+  # @localpart is a String containing the "user" part of "user@domain".
+  @localpart = nil
+
+  # @domain contains a {Domain} object representing the domain part of
+  # "user@domain".
+  @domain = nil
+
+
+  # Obtain the {Domain} object corresponding to this User.
+  #
+  # @return [Domain] the domain corresponding to this User.
+  #
+  def domain()
+    return @domain
+  end
+
+
+  # Obtain the domain part of this User object as a string.
+  #
+  # @return [String] a String representation of this User's domain.
+  #
+  def domainpart()
+    return @domain.to_s()
+  end
+
+
+  # Initialize this User object. If either of the local/domain parts
+  # is invalid, then either an {InvalidUserError} or an {InvalidDomainError}
+  # will be raised containing the reason why that part is invalid.
+  #
+  # @param username [String] an email address from which to construct
+  #   this User.
+  #
+  def initialize(username)
+
+    if not username.is_a?(String)
+      msg =  'username must be a String '
+      msg += "but a #{username.class.to_s()} was given"
+      raise InvalidUserError.new(msg)
+    end
+
+    parts = username.split('@')
+
+    if parts.length() < 2 then
+      msg = "the username #{username} does not contain an '@' symbol"
+      raise InvalidUserError.new(msg)
+    end
+
+    localpart = parts[0]
+
+    if localpart.length() > 64 then
+      msg = "the local part of #{username} cannot have more than 64 characters"
+      raise InvalidUserError(msg)
+    end
+
+    if localpart.empty? then
+      msg = "the local part of #{username} cannot be empty"
+      raise InvalidUserError.new(msg)
+    end
+
+    @localpart = localpart
+    @domain = Domain.new(parts[1])
+  end
+
+
+  # Obtain the "user" part of this User object as a String.
+  #
+  # @return [String] the "user" part of this User's "user@domain"
+  #   address.
+  #
+  def localpart()
+    return @localpart
+  end
+
+
+  # Convert this User to an email address string.
+  #
+  # @return [String] an email address String constructed from this
+  #   user's local and domain parts.
+  #
+  def to_s()
+    return @localpart + '@' + @domain.to_s()
+  end
+
+
+  # Check if this User is equal to some other User. The comparison
+  # is based on their String representations.
+  #
+  # @param other [User] the User 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 User objects for sorting purposes. The comparison is
+  # is based on their String representations.
+  #
+  # @param other [User] the User 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