mailshears 0.0.1

data/lib/rm/plugins/roundcube.rb

@@ -0,0 +1,42 @@
+require 'pg'
+
+require 'common/roundcube_plugin'
+require 'rm/rm_plugin'
+
+# Handle removal of Roundcube users from its database. Roundcube has
+# no concept of domains.
+#
+class RoundcubeRm
+
+  include RoundcubePlugin
+  include RmPlugin
+
+  # Remove *user* from the Roundcube database. This should remove him
+  # from _every_ table in which he is referenced. Fortunately the
+  # Roundcube developers were nice enough to include DBMS-specific
+  # install and upgrade scripts, so Postgres can take advantage of ON
+  # DELETE triggers.
+  #
+  # @param user [User] the user to remove.
+  #
+  def remove_user(user)
+    raise NonexistentUserError.new(user.to_s()) if not user_exists(user)
+
+    # Get the primary key for this user in the "users" table.
+    user_id = self.get_user_id(user)
+
+    # Thanks to the ON DELETE triggers, this will remove all child
+    # records associated with user_id too.
+    sql_query = 'DELETE FROM users WHERE user_id = $1::int;'
+
+    connection = PG::Connection.connect(@db_hash)
+
+    begin
+      connection.query(sql_query, [user_id])
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+  end
+
+end

data/lib/rm/rm_dummy_runner.rb

@@ -0,0 +1,39 @@
+require 'common/runner'
+
+# Dummy implementation of a {RmRunner}. Its <tt>run()</tt> method will
+# tell you what would have been removed, but will not actually perform
+# the operation.
+#
+class RmDummyRunner
+  include Runner
+
+
+  # Pretend to remove *targets*. Some "what if"
+  # information will be output to stdout.
+  #
+  # This dummy runner is not particularly useful on its own. About the
+  # only thing it does is let you know that the users/domains in
+  # *targets* do in fact exist (through their descriptions). It's used
+  # to good effect by {PruneDummyRunner}, though.
+  #
+  # @param cfg [Configuration] the configuration options to pass to
+  #   the *plugin* we're runnning.
+  #
+  # @param plugin [RmPlugin] plugin that will perform the move.
+  #
+  # @param targets [Array<User,Domain>] the users and domains to be
+  #   removed.
+  #
+  def run(cfg, plugin, *targets)
+    targets.each do |target|
+      target_description = plugin.describe(target)
+      msg =  "Would remove #{target.class.to_s().downcase()} "
+      msg += add_description(target, target_description)
+      msg += '.'
+
+      report(plugin, msg)
+    end
+
+  end
+
+end

data/lib/rm/rm_plugin.rb

@@ -0,0 +1,77 @@
+require 'common/plugin.rb'
+
+#
+# Plugins for the removal of users and domains.
+#
+module RmPlugin
+
+  # Absorb the subclass run() magic from the Plugin::Run module.
+  extend Plugin::Run
+
+  # The runner class associated with removal plugins.
+  #
+  # @return [Class] the {RmRunner} class.
+  #
+  def self.runner()
+    return RmRunner
+  end
+
+
+  # The "dummy" runner class associated with removal plugins.
+  #
+  # @return [Class] the {RmDummyRunner} class.
+  #
+  def self.dummy_runner()
+    return RmDummyRunner
+  end
+
+
+  # Remove the *target* domain or user. This is a generic version of
+  # the {#remove_user} and {#remove_domain} operations that will
+  # dispatch based on the type of *target*.
+  #
+  # @param target [User,Domain] the user or domain to remove.
+  #
+  def remove(target)
+    # A generic version of remove_user/remove_domain that
+    # dispatches base on the class of the target.
+    if target.is_a?(User)
+      return remove_user(target)
+    elsif target.is_a?(Domain)
+      return remove_domain(target)
+    else
+      raise NotImplementedError
+    end
+  end
+
+
+  # Remove the given *domain*. Some plugins don't have a concept of
+  # domains, so the default implementation here removes all users that
+  # look like they belong to *domain*. Subclasses can be smarter.
+  #
+  # @param domain [Domain] the domain to remove.
+  #
+  def remove_domain(domain)
+    users = list_domains_users([domain])
+
+    # It's possible for a domain to exist with no users, but this
+    # default implementation is based on the assumption that it should
+    # work for plugins having no "domain" concept.
+    raise NonexistentDomainError.new(domain.to_s()) if users.empty?
+
+    users.each do |u|
+      remove_user(u)
+    end
+  end
+
+
+  # The interface for the "remove a user" operation. Subclasses
+  # need to implement this method so that it removes *user*.
+  #
+  # @param user [User] the user to remove.
+  #
+  def remove_user(user)
+    raise NotImplementedError
+  end
+
+end

data/lib/rm/rm_runner.rb

@@ -0,0 +1,51 @@
+require 'common/errors'
+require 'common/runner'
+
+# Perform the removal of users/domains using {RmPlugin}s.
+#
+class RmRunner
+  include Runner
+
+  # Run *plugin* to remove the users/domains in *targets*. The method
+  # signature includes the unused *cfg* for consistency with the
+  # runners that do need a {Configuration}.
+  #
+  # @param cfg [Configuration] unused.
+  #
+  # @param plugin [Class] plugin class that will perform the removal.
+  #
+  # @param targets [Array<User,Domain>] the users and domains to be
+  #   removed.
+  #
+  def run(cfg, plugin, *targets)
+    targets.each do |target|
+      remove_target(plugin, target)
+    end
+  end
+
+
+  protected;
+
+  # Remove *target* using *plugin*. This operation is separate from
+  # the <tt>run()</tt> method so that it can be accessed by the prune
+  # runner.
+  #
+  # @param plugin [RmPlugin] the plugin that will remove the *target*.
+  #
+  # @param target [User,Domain] the user or domain to remove.
+  #
+  def remove_target(plugin, target)
+    target_description = plugin.describe(target)
+
+    begin
+      plugin.remove(target)
+      msg =  "Removed #{target.class.to_s().downcase()} "
+      msg += add_description(target, target_description)
+      msg += '.'
+
+      report(plugin, msg)
+    rescue NonexistentDomainError, NonexistentUserError => e
+      report(plugin, "#{target.class.to_s()} #{e.to_s} not found.")
+    end
+  end
+end

data/mailshears.gemspec

@@ -0,0 +1,39 @@
+Gem::Specification.new do |s|
+
+  s.name              = 'mailshears'
+  s.version           = '0.0.1'
+  s.platform          = Gem::Platform::RUBY
+  s.authors           = ['Michael Orlitzky']
+  s.email             = ['michael@orlitzky.com']
+  s.homepage          = 'http://michael.orlitzky.com/code/mailshears.php'
+  s.summary           = 'Prune unused mail directories.'
+  s.description       = <<-EOF
+    Managing a mail system with virtual users is annoying. The
+    authoritative database of users is stored in one table, but every
+    other piece of software keeps its own database of users.
+
+    If you're using PostfixAdmin to manage your users, what happens when
+    you delete a user? Chances are, nothing happens: mail directories are
+    left behind, webmail preferences are saved, address books become
+    orphaned. That's what mailshears was designed to fix. It cleans up
+    after you remove a user or domain.
+
+    Another stupidly difficult task is renaming a single email
+    account. It's easy to move the user in one database, but then all of
+    the remaining filesystem directories and databases need to be updated
+    as well. Since these two tasks are related, mailshears does them both.
+  EOF
+
+  s.license           = 'AGPL-3'
+  s.required_rubygems_version = '>= 1.3.6'
+
+  # If you have runtime dependencies, add them here
+  s.add_runtime_dependency 'pg', '~> 0.11'
+
+  # The list of files to be contained in the gem
+  s.files         = `git ls-files`.split("\n")
+  s.executables   = ['mailshears']
+
+  s.require_path = 'lib'
+
+end

data/test/mailshears.test.conf.yml

@@ -0,0 +1,36 @@
+i_mean_business: true
+plugins: [agendav, davical, dovecot, postfixadmin, roundcube]
+
+agendav_dbhost: localhost
+agendav_dbport: 5432
+agendav_dbopts:
+agendav_dbtty:
+agendav_dbuser: postgres
+agendav_dbpass:
+agendav_dbname: agendav_test
+
+davical_dbhost: localhost
+davical_dbport: 5432
+davical_dbopts:
+davical_dbtty:
+davical_dbuser: postgres
+davical_dbpass:
+davical_dbname: davical_test
+
+dovecot_mail_root: /tmp/mailshears-test
+
+postfixadmin_dbhost: localhost
+postfixadmin_dbport: 5432
+postfixadmin_dbopts:
+postfixadmin_dbtty:
+postfixadmin_dbuser: postgres
+postfixadmin_dbpass:
+postfixadmin_dbname: postfixadmin_test
+
+roundcube_dbhost: localhost
+roundcube_dbport: 5432
+roundcube_dbopts:
+roundcube_dbtty:
+roundcube_dbuser: postgres
+roundcube_dbpass:
+roundcube_dbname: roundcube_test

data/test/mailshears_test.rb

@@ -0,0 +1,250 @@
+require 'common/configuration'
+require 'fileutils'
+require 'minitest/autorun'
+require 'pg'
+
+class MailshearsTest < MiniTest::Test
+  # This is that class that most (if not all) of our test cases will
+  # inherit. It provides the automatic setup and teardown of the
+  # filesystem and database that the test cases will exercise.
+
+  def configuration()
+    # Return the test config object.
+    return Configuration.new('test/mailshears.test.conf.yml')
+  end
+
+  def maildir_exists(dir)
+    # Check if the given mail directory of the form "example.com/user"
+    # exists.
+    cfg = configuration()
+    return File.directory?("#{cfg.dovecot_mail_root()}/#{dir}")
+  end
+
+  def connect_superuser()
+    # Connect to the database (specified in the test configuration) as
+    # the superuser. Your local configuration is expected to be such
+    # that this "just works."
+    db_host = 'localhost'
+    db_port = 5432
+    db_opts = nil
+    db_tty = nil
+    db_name = 'postgres'
+    db_user = 'postgres'
+    db_pass = nil
+
+    connection = PG::Connection.new(db_host, db_port, db_opts, db_tty,
+                                    db_name, db_user, db_pass)
+
+    return connection
+  end
+
+  def setup
+    # Connect to the database specified in the test configutation as
+    # the super user. Then, run all of the SQL scripts contained in
+    # test/sql. These scripts create the tables for the plugins listed
+    # in the test configuration, and then create some sample data.
+    #
+    # Here is the full list of what gets created. Every test case
+    # inheriting from this class can expect this schema and data to
+    # exist. The filesystem entries are located beneath mail_root from
+    # the configuration file.
+    #
+    # == Filesystem ==
+    #
+    #   * example.com/alice
+    #   * example.com/booger
+    #   * example.com/jeremy
+    #   * example.net/adam
+    #
+    # == Databases ==
+    #
+    # 1. agendav_test
+    #
+    #   +------------------------------+
+    #   |              prefs           |
+    #   +--------------------+---------+
+    #   |      username      | options |
+    #   +--------------------+---------+
+    #   |  adam@example.net  | herp    |
+    #   +--------------------+---------+
+    #   | booger@example.com | herp    |
+    #   +------------------  +---------+
+    #
+    #
+    #   +---------------------------------------------------------+
+    #   |                         shared                          |
+    #   +-----+--------------------+----------+-------------------+
+    #   | sid |     user_from      | calendar |    user_which     |
+    #   +-----+--------------------+----------+-------------------+
+    #   |   1 |  adam@example.net  | derp     | beth@example.net  |
+    #   +-----+--------------------+----------+-------------------+
+    #   |   2 | booger@example.com | derp     | carol@example.net |
+    #   +-----+--------------------+----------+-------------------+
+    #
+    #
+    # 2. davical_test
+    #
+    #   +--------------------------------------------------------+
+    #   |                         usr                            |
+    #   +---------+--------+----------------+--------------------+
+    #   | user_no | active |    joined      |      username      |
+    #   +---------+--------+----------------+--------------------+
+    #   |      17 | t      | 2014-01-04 ... | alice@example.com  |
+    #   +---------+--------+----------------+--------------------+
+    #   |      18 | t      | 2014-01-04 ... | booger@example.com |
+    #   +---------+--------+----------------+--------------------+
+    #
+    #
+    #   +-----------------------------------------+
+    #   |                usr_setting              |
+    #   +---------+--------------+----------------+
+    #   | user_no | setting_name | setting_value  |
+    #   +---------+--------------+----------------+
+    #   |      17 | dumb setting | its dumb value |
+    #   +---------+--------------+----------------+
+    #   |      18 | dumb setting | its dumb value |
+    #   +---------+--------------+----------------+
+    #
+    #
+    # 3. postfixadmin_test
+    #
+    #   +-------------+
+    #   |   domain    |
+    #   +-------------+
+    #   |   domain    |
+    #   +-------------+
+    #   | ALL         |
+    #   +-------------+
+    #   | example.com |
+    #   +-------------+
+    #   | example.net |
+    #   +-------------+
+    #
+    #
+    #   +----------------------------------------------+
+    #   |                    mailbox                   |
+    #   +-------------------+-------------+------------+
+    #   |     username      |   domain    | local_part |
+    #   +-------------------+-------------+------------+
+    #   | alice@example.com | example.com | alice      |
+    #   +-------------------+-------------+------------+
+    #   | bob@example.com   | example.com | bob        |
+    #   +-------------------+-------------+------------+
+    #   | adam@example.net  | example.net | adam       |
+    #   +-------------------+-------------+------------+
+    #   | beth@example.net  | example.net | beth       |
+    #   +-------------------+-------------+------------+
+    #   | carol@example.net | example.net | carol      |
+    #   +-------------------+-------------+------------+
+    #
+    #
+    #   +-------------------------------------------------------+
+    #   |                          alias                        |
+    #   +-------------------+--------------------+--------------+
+    #   |     address       |       goto         |   domain     |
+    #   +-------------------+--------------------+--------------+
+    #   | alice@example.com | alice@example.com, | example.com  |
+    #   |                   | adam@example.net,  |              |
+    #   |                   | bob@example.com,   |              |
+    #   |                   | carol@example.net  |              |
+    #   +-------------------+--------------------+--------------+
+    #   | bob@example.com   | bob@example.com    | example.com  |
+    #   +-------------------+--------------------+--------------+
+    #   | adam@example.net  | adam@example.net   | example.net  |
+    #   +-------------------+--------------------+--------------+
+    #   | beth@example.net  | beth@example.net   | example.net  |
+    #   +-------------------+--------------------+--------------+
+    #   | carol@example.net | carol@example.net  | example.net  |
+    #   +-------------------+--------------------+--------------+
+    #
+    #
+    #   +---------------------------------+
+    #   |          domain_admins          |
+    #   +-------------------+-------------+
+    #   |     username      |   domain    |
+    #   +-------------------+-------------+
+    #   | admin@example.com | example.com |
+    #   +-------------------+-------------+
+    #   | admin@example.com | example.net |
+    #   +-------------------+-------------+
+    #
+    # 4. roundcube_test
+    #
+    #
+    #   +---------+--------------------+
+    #   | user_id |     username       |
+    #   +---------+--------------------+
+    #   |       1 | alice@example.com  |
+    #   +---------+--------------------+
+    #   |       2 | booger@example.com |
+    #   +---------+--------------------+
+    #   |       3 | adam@example.net   |
+    #   +---------+--------------------+
+
+    # First make sure we get rid of everything so we don't get random
+    # failures from databases and directories that already exist.
+    teardown()
+
+    cfg = configuration()
+
+    # First create the "mail directories".
+    FileUtils.mkdir_p("#{cfg.dovecot_mail_root()}/example.com/alice")
+    FileUtils.mkdir_p("#{cfg.dovecot_mail_root()}/example.com/booger")
+    FileUtils.mkdir_p("#{cfg.dovecot_mail_root()}/example.com/jeremy")
+    FileUtils.mkdir_p("#{cfg.dovecot_mail_root()}/example.net/adam")
+
+    # Now the databases and their content.
+    connection = connect_superuser()
+
+    cfg.plugins.each do |plugin|
+      plugin_dbname = cfg.send("#{plugin}_dbname")
+      next if plugin_dbname.nil? # Skip the dovecot plugin
+      query = "CREATE DATABASE #{plugin_dbname};"
+      connection.query(query)
+
+      plugin_dbhost = cfg.send("#{plugin}_dbhost")
+      plugin_dbport = cfg.send("#{plugin}_dbport")
+      plugin_dbopts = cfg.send("#{plugin}_dbopts")
+      plugin_dbtty  = cfg.send("#{plugin}_dbtty")
+      plugin_dbuser = cfg.send("#{plugin}_dbuser")
+      plugin_dbpass = cfg.send("#{plugin}_dbpass")
+
+      plugin_conn = PG::Connection.new(plugin_dbhost, plugin_dbport,
+                                       plugin_dbopts, plugin_dbtty,
+                                       plugin_dbname, plugin_dbuser,
+                                       plugin_dbpass)
+
+      sql = File.open("test/sql/#{plugin}.sql").read()
+      plugin_conn.query(sql)
+      sql = File.open("test/sql/#{plugin}-fixtures.sql").read()
+      plugin_conn.query(sql)
+      plugin_conn.close()
+    end
+
+    connection.close()
+  end
+
+
+  def teardown
+    # Drop all of the databases that were created in setup().
+    cfg = configuration()
+    connection = connect_superuser()
+
+    # Don't emit notices about missing tables. Why this happens when I
+    # explicitly say IF EXISTS is beyond me.
+    connection.set_notice_processor{}
+
+    cfg.plugins.each do |plugin|
+      plugin_dbname = cfg.send("#{plugin}_dbname")
+      next if plugin_dbname.nil? # Skip the dovecot plugin
+      query = "DROP DATABASE IF EXISTS #{plugin_dbname};"
+      connection.query(query)
+    end
+
+    connection.close()
+
+    # Get rid of the maildirs.
+    FileUtils.rm_rf(cfg.dovecot_mail_root())
+  end
+
+end