Sprocket::Plugin - Base class for Sprocket plugins

  use Sprocket qw( Plugin );
  use base qw( Sprocket::Plugin );

  sub new {
      shift->SUPER::new(
          name => 'MyPlugin',
          @_
      );
  }

  sub as_string {
      __PACKAGE__;
  }

  ...

  __PACKAGE__->mk_accessors( qw( foo bar baz ) );

package Sprocket::Plugin;

use Class::Accessor::Fast;
use base qw(Class::Accessor::Fast);
use Scalar::Util qw( weaken blessed );
use POE;
use Sprocket;
use Sprocket::Local;
use Errno qw( EADDRINUSE );

__PACKAGE__->mk_accessors( qw( uuid _uuid name parent_id ID ) );

use overload '""' => sub { shift->ID() };

use strict;
use warnings;

# Sprocket::Spread import will replace this
# when imported on demand
our $sprocket_spread;

our %plugin_event_list = map { $_ => 1 } qw(
    local_accept
    local_connected
    local_receive
    local_disconnected
    local_time_out
    local_error

    remote_accept
    remote_connected
    remote_receive
    remote_disconnected
    remote_connect_error
    remote_time_out

    plugin_start_aio
    add_plugin
);

our %plugin_event_discon = map { $_ => 1 } qw(
    local_disconnected

    remote_disconnected
    remote_connect_error
);

sub new {
    my $class = shift;
    
    my $self = bless( {
        __conlist__ => {},
        &adjust_params,
    }, ref $class || $class );

    # unique uuid, different for each instance
    $self->uuid( new_uuid() );
    
    $self->ID( $class.'/'.$self->uuid );
    
    # uuid based off of the plugin's ref
    $self->_uuid( gen_uuid( $self ) );

    $sprocket->add_plugin( $self );
    
    return $self;
}

sub handle_event {
    my ( $self, $event ) = ( shift, shift );
    
    delete $self->{__conlist__}->{ $_[ 1 ]->ID }
        if ( $self->{__conlist__} && exists( $plugin_event_discon{ $event } ) );
    
    if ( $self->can( $event ) ) {
        $self->$event( @_ );
    } else {
        $self->_log( v => $self->{log_unhandled_events}, msg => "unhandled plugin event: $event" )
            if ( $self->{log_unhandled_events} && !exists( $plugin_event_list{ $event } ) );
    }
    
    return 1;
}

sub _log {
    $poe_kernel->call( shift->parent_id => _log => ( call => ( caller(1) )[ 3 ], @_ ) );
    return;
}

# ==========================================
# Events
# ==========================================

sub local_accept {
    my ( $self, $server, $con, $socket ) = @_;
    if ( $server->shutting_down ) {
        $con->reject();
    } else {
        $con->accept();
    }
    return;
}

sub local_connected {
    my ( $self, $server, $con, $socket ) = @_;
    $server->_log( v => 4, msg => 'Rejecting connection because plugin:'
        .$self.' did not define a local_connected event' );
    $con->reject();
    return;
}

sub local_error {
    my ( $self, $server, $operation, $errnum, $errstr ) = @_;
    # note that this has no $con, it's a server wheel error
    $server->shutdown() if ( $errnum == EADDRINUSE );
    return;
}

sub local_time_out {
    my ( $self, $server, $con, $time ) = @_;
    $server->_log( v => 4, msg => 'Timeout for connection ' );
    $con->close();
    return;
}

sub local_shutdown {
    my ( $self, $server, $con ) = @_;
    $server->_log( v => 4, msg => 'Closing connection, shutting down' );
    $con->close( 1 );
    return;
}

sub remote_connected {
    my ( $self, $client, $con, $socket ) = @_;
    $client->_log( v => 4, msg => 'Rejecting connection because plugin:'
        .$self.' did not define a remote_connected event' );
    $con->reject();
    return;
}

sub remote_accept {
    my ( $self, $client, $con, $socket ) = @_;
    # XXX shutting_down?
    $con->accept();
    return;
}

sub remote_disconnected {
    my ( $self, $client, $con ) = @_;
    $con->close();
    return;
}

sub remote_connect_error {
    my ( $self, $client, $con, $res_err, $res_obj ) = @_;
    $con->close();
    return;
}

sub remote_time_out {
    my ( $self, $client, $con, $time ) = @_;
    $client->_log( v => 4, msg => 'Timeout for connection' );
    $con->close();
    return;
}

sub remote_shutdown {
    my ( $self, $client, $con ) = @_;
    $client->_log( v => 4, msg => 'Closing connection, shutting down' );
    $con->close( 1 );
    return;
}

# ==========================================
# Methods
# ==========================================

sub get_plugin_connection {
    my ( $self, $server, $id ) = @_;

    # Sprocket::Local singleton
    return $sprocket_local->get_connection( $server, $id );
}

sub take_connection {
    my ( $self, $con ) = @_;
    
    $self->{__conlist__}->{ $con->ID } = 1
        if ( $self->{__conlist__} );
    
    $con->plugin( $self->uuid );
    return;
}

sub release_connection {
    my ( $self, $con ) = @_;
    
    delete $self->{__conlist__}->{ $con->ID }
        if ( $self->{__conlist__} );
    
    $con->plugin( undef );
    return;
}

sub spread_subscribe {
    my ( $self, $groups ) = @_;

    if ( !defined( $sprocket_spread ) ) {
        # XXX is there a better way?
        require Sprocket::Spread;
        import Sprocket::Spread;
    }
    
    $groups = [ $groups ] unless ( ref $groups );

    return $sprocket_spread->plugin_subscribe( $self, $groups );
}

sub spread_unsubscribe {
    my ( $self, $groups ) = @_;

    if ( !defined( $sprocket_spread ) ) {
        # XXX is there a better way?
        require Sprocket::Spread;
        import Sprocket::Spread;
    }
    $groups = [ $groups ] unless ( ref $groups );

    return $sprocket_spread->plugin_unsubscribe( $self, $groups );
}

sub spread_publish {
    my $self = shift;
    my $groups = shift;

    if ( !defined( $sprocket_spread ) ) {
        # XXX is there a better way?
        require Sprocket::Spread;
        import Sprocket::Spread;
    }
    
    $groups = [ $groups ] unless ( ref $groups );

    return $sprocket_spread->plugin_publish( $self, $groups, @_ );
}

sub con_list {
    my $self = shift;
    
    if ( $self->{__conlist__} ) {
        my @ids = keys %{ $self->{__conlist__} };
        return wantarray ? @ids : \@ids;
    }

    return wantarray ? () : [];
}

*con_id_list = *con_list;

1;

__END__