package MCollective::Action;
use strict;
use warnings;
use JSON;

=head1 NAME

MCollective::Action - helper class for writing mcollective actions in perl

=head1 SYNOPSIS


In your mcollective agent

    action "echo" do
        validate :message, String

        implemented by "/tmp/echo.perl"
    end

And C</tmp/echo.perl>

    #!/usr/bin/env perl
    use strict;
    use MCollective::Action;

    my $mc = MCollective::Action->new;
    $mc->reply->{message}   = $mc->request->{message};
    $mc->reply->{timestamp} = time;
    $mc->info("some text to log on the server");


=head1 DESCRIPTION

mcollective version 1.X introduced a mechanism for writing agent actions as
external commands. This module provides a convenient api for writing them in
perl which performs some of the boilerplate for you.

=head2 METHODS

=over

=item new

create a new MCollection::Action helper object

=cut

sub new {
    my $class = shift;
    my $self = bless {
        request  => {},
        reply    => {},
    }, $class;
    $self->_load;
    return $self;
}

=item request

returns a hash reference containing the request

=cut


sub request { $_[0]->{request} }


=item reply

returns a hash reference you should populate with your reply

=cut

sub reply { $_[0]->{reply} }


sub _load {
    my $self = shift;
    my $file = $ENV{MCOLLECTIVE_REQUEST_FILE};
    open my $fh, "<$file"
      or die "Can't open '$file': $!";
    my $json = do { local $/; <$fh> };
    $self->{request} = JSON->new->decode( $json );
    delete $self->request->{data}{process_results};
}

sub DESTROY {
    my $self = shift;
    $self->_save;
}

sub _save {
    my $self = shift;
    my $file = $ENV{MCOLLECTIVE_REPLY_FILE};
    open my $fh, ">$file"
      or die "Can't open '$file': $!";
    print $fh JSON->new->encode( $self->reply );
}

=item info($message)

report a message into the server log

=cut

sub info {
    my ($self, $message) = @_;
    print STDOUT $message, "\n";
}

=item error($message)

report an error into the server log

=cut


sub error {
    my ($self, $message) = @_;
    print STDERR $message, "\n";
}

=item fail

reports an error and exits immediately

=cut

sub fail {
    my ($self, $message) = @_;
    $self->error( $message );
    exit 1;
}

1;

__END__

=back

=head1 AUTHOR

Richard Clamp <richardc@unixbeard.net>

=head1 COPYRIGHT

Copyright 2011, Richard Clamp.  All Rights Reserved.

This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

=head1 SEE ALSO

http://docs.puppetlabs.com/mcollective/

=cut