OpenPlugin - Plugin manager for web applications

  use OpenPlugin();
  my $r = shift;

  my $OP = OpenPlugin->new( config  => { src    => '/etc/myconf.conf' },
                            request => { apache => $r } );

  my $is_authenticated = $OP->authenticate->authenticate({ username => 'badguy',
                                                           password => 'scylla' });
  unless ( $is_authenticated ) {
      $OP->exception->throw( "Login incorrect!" );
  }

  my $session_id = $OP->param->get_incoming('session_id');
  $session = $OP->session->fetch( $session_id );

  $session->{'hair'} = $OP->param->get_incoming('hair');
  $session->{'eyes'} = $OP->param->get_incoming('eyes');
  $OP->session->save( $session );

  $OP->httpheader->send_outgoing();
  print "You have $session->{'hair'} hair and $session->{'eyes'} eyes<br>";

 my $OP = OpenPlugin->new( config => { src => /path/to/OpenPlugin.conf } );

 $OP->plugin->method();

 $OP->plugin()->method();

 my $session = $OP->session->fetch( $session_id );

 $OP->httpheader->send_outgoing();

 my $login = $OP->authenticate->authenticate( 'username', 'password' );

 <plugin session>
     load        = Startup
     expires     = +3h

     <driver ApacheSession>
         Store           = File
         Directory       = /tmp/openplugin
         LockDirectory   = /tmp/openplugin
     </driver>
 </plugin>

 my $session = $OP->session->fetch( $session_id );

 <plugin authenticate>
     load       = Startup
     default    = Passwd

     <driver Passwd>
     </driver>

     <driver SMB>
        pdc     = My_NT_Server
        bdc     = My_Backup_Server
        domain  = NT_DOMAIN
     </driver>

 </plugin>

 my $login = $OP->authenticate->authenticate( 'username', 'password' );

 my $login = $OP->authenticate('SMB')->authenticate( 'username', 'password' );

 # Cache to the default location
 $OP->cache->save( $data_to_cache );

 # Cache to a DBI compatible database
 $OP->cache('DBI')->save( $data_to_cache );

package OpenPlugin;

use strict;
use vars                qw( $AUTOLOAD );
use OpenPlugin::Plugin  qw();
use OpenPlugin::Utility qw();
use Log::Log4perl       qw( get_logger );

use constant STATE      => '_state';
use constant TOGGLE     => '_toggle';
use constant PLUGIN     => '_plugin';
use constant PLUGINCONF => '_pluginconf';
use constant INSTANCE   => '_instance';

$OpenPlugin::VERSION = '0.11';

# We'll need the logger var throughout this entire file
my $logger;

sub new {
    my $pkg    = shift;
    my $params = { @_ };
    my $class  = ref $pkg || $pkg;
    my $self   = bless( {}, $class );

    $self->init( $params->{'init'} );

    # Save all the parameters which were passed in
    $self->state("command_line", $params );

    # TODO: We should try and get all this config stuff into the Config plugin
    # if at all possible, I don't think it belongs here

    # Read configuration from file if given.  Otherwise, see if the package var
    # has our config in it
    $params->{'config'}{'src'} ||= $OpenPlugin::Config::Src;

    if ( $params->{'config'}{'src'} or $params->{'config'}{'data'} ) {

        $self->load_config( $params );

    }
    # Quit if we haven't been given some sort of config to use
    else {
        die "No configuration given!  You need to pass in the location ",
            "to your configuration file, or pass in a hashref containing ",
            "your configuration data.";
    }

    $self->register_plugins;

    return $self;
}

# Set up some stuff before we begin loading any plugins
sub init {
    my ( $self, $params ) = @_;

    my $log_conf = $params->{'log'} || q(
                log4perl.rootLogger              = WARN, stderr
                log4perl.appender.stderr         = Log::Dispatch::Screen
                log4perl.appender.stderr.layout  = org.apache.log4j.PatternLayout
                log4perl.appender.stderr.layout.ConversionPattern  = %C (%L) %m%n
        );

    Log::Log4perl::init( \$log_conf );
    $logger = get_logger("OpenPlugin");

}

########################################
# Public methods
########################################

# This gets and sets state information for user requests.  For instance, we can
# maintain the current user and group, whether the user is an administrator,
# etc.
sub state {
    my ( $self, $key, $value ) = @_;


    # Just a key passed in, return a single value
    if( defined $key and not defined $value ) {
        $logger->info("Calling state() with key [$key].");

        return $self->{ STATE() }{ $key };
    }

    # We have a key and value, so assign the value to the key
    elsif( defined $key and defined $value ) {
        $logger->info("Calling state() with key [$key] and value [$value].");

        return $self->{ STATE() }{ $key } = $value;
    }

    # No key or value, return the entire state hash
    else {
        $logger->info("Calling state() with no parameters.");

        return $self->{ STATE() };
    }
}


# Cleans up the current state in this object and sends a message to
# all plugins to cleanup their state as well.
sub cleanup {
    my ( $self ) = @_;

    $logger->info( "Running cleanup()" );

    # Allow plugins to clean up their own state
    foreach my $plugin ( $self->loaded_plugins ) {
        $self->$plugin()->cleanup;
    }

    # Completely erase all state related information
    $self->{ STATE() } = {};

    # FIXME: This might not be necessary anymore
    # Recreate a hash key for each plugin
    foreach my $plugin ( $self->loaded_plugins ) {
        $self->state( $plugin, {} );
    }

}

# This should be called before the object is taken out of scope and
# should probably incorporated into a DESTROY() method.

sub shutdown {
    my ( $self ) = @_;
    $logger->info( "Calling shutdown() from OP" );
    $self->cleanup();

    # ... do any additional cleanup so we don't have dangling/circular
    # references, etc....

}


########################################
# Accessor methods
########################################

# Get a list of all plugins which the config plugin knows about
sub get_plugins {
    my ( $self, $plugin ) = @_;

    if( $plugin ) {
        return sort keys %{ $self->config->{'plugin'}{ $plugin }{'plugin'} };
    }
    else {
        return sort keys %{ $self->config->{'plugin'} };
    }
}

# Get a list of all drivers for a given plugin
sub get_drivers {
    my ( $self, $plugin ) = @_;

    return sort keys %{ $self->{ PLUGINCONF() }{ $plugin }{'driver'} }
}

# Save any info that we have relating to a plugins configuration
sub set_plugin_info {
    my ( $self, $plugin, $nested_plugin ) = @_;

    # $plugin_info contains all the information about a given plugin that was
    # found in the configuration file
    my $plugin_info;
    if( $nested_plugin ) {
        $plugin_info =
            $self->config->{'plugin'}{ $plugin }{'plugin'}{ $nested_plugin };
        $plugin = $nested_plugin;
    }
    else {
        $plugin_info = $self->config->{'plugin'}{ $plugin };
    }

    # We definitely cannot load a plugin without a driver.  Warn and skip if
    # that is the case.
    unless ( ref $plugin_info eq 'HASH' and $plugin_info->{'driver'} ) {
        $logger->warn("Invalid driver listed for [$plugin]: ",
                      "[$plugin_info->{driver}]. Skipping." );

        return undef;
    }

    $logger->info( "Driver type found for [$plugin]: ",
                   "[$plugin_info->{driver}]" );

    # Store this configuration for whenever we need it
    return $self->{ PLUGINCONF() }{ $plugin } = $plugin_info;

}

# Retrieve config information listed about a given plugin
sub get_plugin_info {
    my ( $self, $plugin ) = @_;

    return $self->{ PLUGINCONF() }{ $plugin };
}

# Get the name of the class name to use for a given driver
sub get_plugin_class {
    my ( $self, $plugin, $driver ) = @_;

    return undef unless $driver;

    # Get the class name for the driver, as defined in the drivermap file
    my $plugin_class = $self->config->{'drivermap'}{ $plugin }{ $driver };

    $logger->info( "Plugin class found for [$plugin]: [$plugin_class]" );

    return $plugin_class;
}


# Retrieve a list of plugins which are currently loaded, return the value we
# received when we called it's load() function earlier
sub loaded_plugins {
    my $self = shift;

    # Return an empty list if no plugins are loaded
    unless ( ref $self->{ PLUGIN() } eq 'HASH' ) {
        return ();
    }

    return sort keys %{ $self->{ PLUGIN() } };
}

# Save the plugin instance (object) that we received by calling its new()
# function
sub set_plugin_instance {
    my ( $self, $plugin, $driver, $instance ) = @_;

    return $self->{ INSTANCE() }{ $plugin }{ $driver } = $instance;
}

# Set which driver will be used when one isn't explicitely given
sub set_default_driver {
    my ( $self, $plugin, $driver ) = @_;

    return $self->{ PLUGINCONF() }{ $plugin }{'default'} = $driver;
}

# Get the name of the default driver for a given plugin
sub get_default_driver {
    my ( $self, $plugin ) = @_;

    return $self->{ PLUGINCONF() }{ $plugin }{'default'};
}


########################################
# Plugin Instanciation
########################################

# TODO: I'd like all these functions to be able to handle plugins defined in
# the config file to be nested at an arbitrary depth.  They currently can only
# be two levels deep.

# Get a list of plugins, and register them
sub register_plugins {
    my $self = shift;

    foreach my $plugin ( $self->get_plugins ) {
        $self->set_plugin_info( $plugin );

        $self->register_plugin( $plugin );
    }

}

# Decide how and when to load a plugin
sub register_plugin {
    my ( $self, $plugin ) = @_;

    my @drivers        = $self->get_drivers( $plugin );
    my $driver_count   = scalar @drivers;
    my $default_driver = $self->get_default_driver( $plugin );

    foreach my $driver ( @drivers ) {

        if( $driver_count == 1 and not defined $default_driver ) {
            $self->set_default_driver( $plugin, $driver );
        }

        my $class_identifier = $plugin . "-" . $driver;
        my $class = $self->get_plugin_class( $plugin, $driver );

        # These plugins have a "load" time of "Startup", meaning they are
        # loaded when the main OpenPlugin module is
        if( $self->get_plugin_info( $plugin )->{'load'} eq "Startup" ) {

            unless( grep m/^$class$/,
                        OpenPlugin::Plugin->get_loaded_classes ) {

                # Tell OpenPlugin::Plugin that we have a new class that we
                # wish to load now
                OpenPlugin::Plugin->add_factory_type(
                    $class_identifier => $class );
            }

            $self->init_plugin( $plugin, $driver );
        }

        # These plugins have a "load" time of "Auto", meaning they are
        # loaded on demand.  If they aren't ever used, they'll never be
        # loaded
        elsif ( $self->get_plugin_info( $plugin )->{'load'} eq "Auto" ) {

            unless( grep m/^$class$/,
                        OpenPlugin::Plugin->get_registered_classes ) {

                # Tell OpenPlugin::Plugin about a class, so it can load it
                # if and when we finally decide to use it
                OpenPlugin::Plugin->register_factory_type(
                   $class_identifier => $self->get_plugin_class( $plugin,
                                                                 $driver ));

            }
        }

        # We need to know how to load a plugin, it doesn't seem appropriate
        # to guess.  If the configuration isn't correct, give a warning
        # message, but skip loading it.
        else {
            $logger->warn("Invalid load time listed for [$plugin]: [",
                          $self->{ PLUGINCONF() }{ $plugin }{'load'},
                          "]. Skipping." );
        }
    }

    # Handle plugins defined within other plugins
    foreach my $nested_plugin ( $self->get_plugins( $plugin )) {
        $self->set_plugin_info( $plugin, $nested_plugin );

        $self->register_plugin( $nested_plugin );
    }

}

# Make a plugin available to programs using us
sub init_plugin {
    my ( $self, $plugin, $driver ) = @_;

    unless( $plugin ) {
        $self->exception->throw( "You must call init_plugin() with a ",
                                 "plugin name!" );
    }

    unless( $self->get_plugin_info( $plugin )) {
        $self->exception->throw( "You attemped to call [$plugin], which is ",
                                 "not a valid plugin!" );
    }

    # No driver name is okay, we'll just use the default
    $driver ||= $self->get_default_driver( $plugin );

    # Create and save an instance for this driver
    my $instance = $self->create_plugin_instance( $plugin, $driver );
    $self->set_plugin_instance( $plugin, $driver, $instance );

    $self->generate_plugin_method_call( $plugin );

    $self->{ PLUGIN() }{ $plugin } = $self->$plugin( $driver )->load();
}

# Create a new instance of a plugin
sub create_plugin_instance {
    my ( $self, $plugin, $driver ) = @_;

    my $class_identifier = $plugin . "-" . $driver;

    return OpenPlugin::Plugin->new( $class_identifier, $self,
                                    $self->state->{'command_line'}{ $plugin });
}

# Build a method call for a given plugin
sub generate_plugin_method_call {
    my ( $self, $plugin ) = @_;

    # Create the new method in the current package's namespace
    my $method = __PACKAGE__ . '::' . $plugin;
    no strict 'refs';

    # Don't redefine existing method names.  This will both save us time, and
    # is more secure.
    unless ( defined &{ $method } ) {

        $logger->info("Generating method [$method]");

        *{ $method } =
            sub {
                my ( $self, $driver ) = @_;
                $driver ||= $self->get_default_driver( $plugin );

                unless( $driver ) {
                    $self->exception->throw( "No driver found for [$plugin].",
                                             "If you have multiple drivers ",
                                             "defined, you must assign one ",
                                             "as the default." );
                }

                # If there is already an instance for this particular driver,
                # return it
                if( $self->{ INSTANCE() }{ $plugin }{ $driver } ) {
                    return $self->{ INSTANCE() }{ $plugin }{ $driver };
                }

                # If there isn't yet an instance (typical when the plugin isn't
                # loaded at startup), create one and return it
                else {
                    my $instance = $self->create_plugin_instance( $plugin,
                                                                  $driver );

                    return $self->set_plugin_instance( $plugin, $driver,
                                                       $instance );
                }
            }
    }
}


########################################
# AUTOLOAD
#   (so great it gets its own section!)
########################################

sub AUTOLOAD {
    my ( $self, $driver ) = @_;
    my $request = $AUTOLOAD;

    $request =~ s/.*://;

    $logger->info( "Autoload request: [$request]\n" );
    $self->init_plugin( $request, $driver );
    $self->$request( $driver );
}


# Lets not go looking for DESTROY via AUTOLOAD
sub DESTROY { }


########################################
# CONFIGURATION
########################################

# Configuration is different from other plugins because of the bootstrapping
# issue.
sub load_config {
    my ( $self, $params ) = @_;

    unless( grep m/^OpenPlugin::Config$/,
                OpenPlugin::Plugin->get_loaded_classes ) {

            OpenPlugin::Plugin->add_factory_type(
                            "config" => 'OpenPlugin::Config' );
    }

    my $config = OpenPlugin::Plugin->new( 'config', $self,
                                          $params->{'config'} );

    if( $params->{'config'}{'src'} ) {
        $self->set_plugin_instance( "config", 'built-in', $config->read );
    }
    elsif( $params->{'config'}{'data'} ) {
        $self->set_plugin_instance( "config", 'built-in',
                                 $config->read( $params->{'config'}{'data'} ));
    }

    $self->generate_plugin_method_call( "config" );
    $self->set_default_driver( "config", "built-in" );

    if( $params->{'config'}{'data'} and $params->{'config'}{'src'} ) {
        $self->config->read( $params->{'config'}{'data'} );
    }

}



1;

__END__