Document everything with YARD and fix some bugs along the way.

[mailshears.git] / lib / rm / rm_plugin.rb

diff --git a/lib/rm/rm_plugin.rb b/lib/rm/rm_plugin.rb
index cad493d9f85c95ae8a3c79bee121e59c508a8efb..ff165b4e8081c653c047276a5fb7045ba9a0d938 100644 (file)
--- a/lib/rm/rm_plugin.rb
+++ b/lib/rm/rm_plugin.rb
@@ -1,34 +1,76 @@
+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.
   #
-  # Plugins for the removal of accounts.
+  # @return [Class] the {RmRunner} class.
   #
-
-  def RmPlugin.included(c)
-    # Callback, called whenever another class or module includes this
-    # one. The parameter given is the name of the class or module
-    # that included us.
-    @includers ||= []
-    @includers << c
+  def self.runner()
+    return RmRunner
   end
 
-  def RmPlugin.includers
-    return @includers
+
+  # The "dummy" runner class associated with removal plugins.
+  #
+  # @return [Class] the {RmDummyRunner} class.
+  #
+  def self.dummy_runner()
+    return RmDummyRunner
   end
 
-  def delete_domain(domain)
-    # Delete the given domain.
-    raise NotImplementedError
+
+  # 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
 
-  def delete_account(account)
-    # Delete the given account.
-    raise NotImplementedError
+
+  # 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
 
-  def get_domain_usernames(domain)
-    # Get a list of usernames for a given domain,
-    # needed to delete accounts before removing
-    # a domain.
+
+  # 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