OpenSSH.pm

package POE::Component::OpenSSH;

use strict;
use warnings;

our $VERSION = '0.06';

use Moose;
use Net::OpenSSH;
use MooseX::Aliases;
use POE::Component::Generic;

has 'args'    => ( is => 'ro', isa => 'ArrayRef', default => sub { [] } );
has 'options' => ( is => 'ro', isa => 'HashRef',  default => sub { {} } );
has 'error'   => ( is => 'ro', isa => 'HashRef',  default => sub { {} } );
has 'alias'   => ( is => 'ro', isa => 'Str',      default => q{}        );
has 'debug'   => ( is => 'ro', isa => 'Bool',     default => 0          );
has 'verbose' => ( is => 'ro', isa => 'Bool',     default => 0          );

has 'obj' => (
    is         => 'rw',
    isa        => 'POE::Component::Generic',
    alias      => 'object',
    lazy_build => 1,
);

sub _build_obj {
    my $self = shift;

    my @optional = ( qw( alias debug verbose options ) );
    my $obj  = POE::Component::Generic->spawn(
        alias          => $self->alias,
        package        => 'Net::OpenSSH',
        object_options => $self->args,
        debug          => $self->debug,
        verbose        => $self->verbose,
        error          => $self->error,
    );

    return $obj;
}

no Moose;
__PACKAGE__->meta->make_immutable;

1;

__END__

=head1 NAME

POE::Component::OpenSSH - Nonblocking SSH Component for POE using Net::OpenSSH

=head1 VERSION

Version 0.06

=head1 SYNOPSIS

Need nonblocking SSH? You like Net::OpenSSH? Try out this stuff right here.

    use POE::Component::OpenSSH;

    my $ssh = POE::Component::OpenSSH->new( args => [ $host, user => $user ] );
    $ssh->obj->system( { event => 'read_system_output' }, 'w' );

Perhaps you want it with debugging and verbose of POE::Component::Generic

    my $ssh = POE::Component::OpenSSH->new(
        args    => [ 'root@host', passwd => $pass ],
        verbose => 1, # turns on POE::Component::Generic verbose
        debug   => 1, # turns on POE::Component::Generic debug
    );

What about setting timeout for Net::OpenSSH?

    my $ssh = POE::Component::OpenSSH->new(
        args => [ 'root@host', passwd => $pass, timeout => 10 ],
    );

=head1 DESCRIPTION

This module allows you to use SSH (via L<Net::OpenSSH>) in a nonblocking manner.

I kept having to write this small thing each time I needed nonblocking SSH in a project. I got tired of it so I wrote this instead.

You might ask 'why put the args in an "args" attribute instead of straight away attributes?' Because Net::OpenSSH has a lot of options and they may collide with POE::Component::Generic's options and I don't feel like maintaining the mess.

It's on Github so you can patch it up if you want (I accept patches... and foodstamps).

Here is a more elaborate example using L<MooseX::POE>:

(If you know L<POE::Session>, you can use that too)

    package Runner;

    use MooseX::POE;

    has 'host' => ( is => 'ro', isa => 'Str', default => 'localhost' );
    has 'user' => ( is => 'ro', isa => 'Str', default => 'root'      );
    has 'pass' => ( is => 'ro', isa => 'Str', default => 'psss'      );
    has 'cmd'  => ( is => 'ro', isa => 'Str', default => 'w'         );

    sub START {
        my $self = $_[OBJECT];
        my $ssh  = POE::Component::OpenSSH->new(
            args => [
                $self->host,
                user   => $self->user,
                passwd => $self->passwd,
            ],
        );

        # remember, $ssh is just POE::Component::OpenSSH
        # you want the Net::OpenSSH object (or psuedo-object)
        $ssh->obj->capture( { event => 'parse_cmd' }, $cmd );

        # this is the same:
        $ssh->object->capture( { event => 'parse_cmd' }, $cmd );
    }

    event 'parse_cmd' => sub {
        my ( $self, $output ) @_[ OBJECT, ARG1 ];
        my $host = $self->host;
        print "[$host]: $output";
    };

    package main;

    use POE::Kernel;

    my @machines = ( qw( server1 server2 server3 ) );

    foreach my $machine (@machines) {
        Runner->new(
            host => $machine,
            pass => 'my_super_pass',
            cmd  => 'uname -a',
        );
    }

    POE::Kernel->run();

=head1 METHODS

=head2 new

Creates a new POE::Component::OpenSSH object. If you want to access the Net::OpenSSH check I<obj> below.

You should note this object is simply a component, you're still required to put it in a L<POE::Session>. The examples use L<MooseX::POE> which does the same thing.

=over 4

=item args

The arguments that will go to L<Net::OpenSSH>.

=item options

The options that will go to L<POE::Component::Generic>'s I<options> argument, stuff like C< { trace => 1 } >.

=item error

Event when L<POE::Component::Generic> has an error. Either a hashref with I<session> and I<event> or a string with the event in the current session.

=item alias

A session alias to register with the kernel. Default is none.

=item debug

Shows component debugging information.

=item verbose

Some stuff about what is happening to L<Net::OpenSSH>. Very useful for debugging the L<Net::OpenSSH> object.

=back

=head2 obj

This method access the actual Net::OpenSSH object. It is wrapped with L<POE::Component::Generic>, so the first argument is actually a hashref that POE::Component::Generic requires. Specifically, noting which event will handle the return of the Net::OpenSSH method.

For example:

    $ssh->obj->capture( { event => 'handle_capture' }, 'echo yo yo' );

=head2 object

An alias for I<obj>.

=head2 args

These are the arguments that will go to L<Net::OpenSSH> creation. This is an arrayref.

For example:

    # using user@host
    my $ssh = POE::Component::OpenSSH->new( args => [ 'root@remote_host' ] );

    # using separate arguments
    my $ssh = POE::Component::OpenSSH->new( args => [ 'remote_host, user => 'root' ] );

    # same thing, just with pass, and writing it nicer
    my $ssh = POE::Component::OpenSSH->new(
        args => [
            'remote_host',
            user   => 'root',
            passwd => $pass,
        ],
    );

=head1 AUTHOR

Sawyer X, C<< <xsawyerx at cpan.org> >>

=head1 BUGS

There is one known issue I've personally stumbled across which I've yet to figure out and resolve. Using L<MooseX::POE>, running C<capture>s from the C<START> event works, but running from another event doesn't. The connection fails and hangs. In order to fix it, I use a clearance on the attribute before running the second C<capture>.

Please report any bugs or feature requests to C<bug-poe-component-openssh at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-OpenSSH>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

Also available is the Github's issue tracker at L<http://github.com/xsawyerx/poe-component-openssh/issues>.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc POE::Component::OpenSSH

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-OpenSSH>

=item * Github issue tracker

L<http://github.com/xsawyerx/poe-component-openssh/issues>

=item * Github page

L<http://github.com/xsawyerx/poe-component-openssh/tree/master>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/POE-Component-OpenSSH>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/POE-Component-OpenSSH>

=item * Search CPAN

L<http://search.cpan.org/dist/POE-Component-OpenSSH/>

=back

=head1 SEE ALSO

If you have no idea what I'm doing (but you generally know what POE is), check these stuff:

L<POE::Component::Generic>

L<Net::OpenSSH>

If you don't know POE at all, check L<POE>.

=head1 DEPENDENCIES

L<Net::OpenSSH>

L<POE>

L<POE::Component::Generic>

L<Moose>

=head1 ACKNOWLEDGEMENTS

All the people involved in the aforementioned projects and the Perl community.

=head1 COPYRIGHT & LICENSE

Copyright 2009 Sawyer X, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.