ext/action_helpers/perl/lib/MCollective/Action.pm

   1 package MCollective::Action;
   2 use strict;
   3 use warnings;
   4 use JSON;
   5
   6 =head1 NAME
   7
   8 MCollective::Action - helper class for writing mcollective actions in perl
   9
  10 =head1 SYNOPSIS
  11
  12
  13 In your mcollective agent
  14
  15     action "echo" do
  16         validate :message, String
  17
  18         implemented by "/tmp/echo.perl"
  19     end
  20
  21 And C</tmp/echo.perl>
  22
  23     #!/usr/bin/env perl
  24     use strict;
  25     use MCollective::Action;
  26
  27     my $mc = MCollective::Action->new;
  28     $mc->reply->{message}   = $mc->request->{message};
  29     $mc->reply->{timestamp} = time;
  30     $mc->info("some text to log on the server");
  31
  32
  33 =head1 DESCRIPTION
  34
  35 mcollective version 1.X introduced a mechanism for writing agent actions as
  36 external commands. This module provides a convenient api for writing them in
  37 perl which performs some of the boilerplate for you.
  38
  39 =head2 METHODS
  40
  41 =over
  42
  43 =item new
  44
  45 create a new MCollection::Action helper object
  46
  47 =cut
  48
  49 sub new {
  50     my $class = shift;
  51     my $self = bless {
  52         request  => {},
  53         reply    => {},
  54     }, $class;
  55     $self->_load;
  56     return $self;
  57 }
  58
  59 =item request
  60
  61 returns a hash reference containing the request
  62
  63 =cut
  64
  65
  66 sub request { $_[0]->{request} }
  67
  68
  69 =item reply
  70
  71 returns a hash reference you should populate with your reply
  72
  73 =cut
  74
  75 sub reply { $_[0]->{reply} }
  76
  77
  78 sub _load {
  79     my $self = shift;
  80     my $file = $ENV{MCOLLECTIVE_REQUEST_FILE};
  81     open my $fh, "<$file"
  82       or die "Can't open '$file': $!";
  83     my $json = do { local $/; <$fh> };
  84     $self->{request} = JSON->new->decode( $json );
  85     delete $self->request->{data}{process_results};
  86 }
  87
  88 sub DESTROY {
  89     my $self = shift;
  90     $self->_save;
  91 }
  92
  93 sub _save {
  94     my $self = shift;
  95     my $file = $ENV{MCOLLECTIVE_REPLY_FILE};
  96     open my $fh, ">$file"
  97       or die "Can't open '$file': $!";
  98     print $fh JSON->new->encode( $self->reply );
  99 }
 100
 101 =item info($message)
 102
 103 report a message into the server log
 104
 105 =cut
 106
 107 sub info {
 108     my ($self, $message) = @_;
 109     print STDOUT $message, "\n";
 110 }
 111
 112 =item error($message)
 113
 114 report an error into the server log
 115
 116 =cut
 117
 118
 119 sub error {
 120     my ($self, $message) = @_;
 121     print STDERR $message, "\n";
 122 }
 123
 124 =item fail
 125
 126 reports an error and exits immediately
 127
 128 =cut
 129
 130 sub fail {
 131     my ($self, $message) = @_;
 132     $self->error( $message );
 133     exit 1;
 134 }
 135
 136 1;
 137
 138 __END__
 139
 140 =back
 141
 142 =head1 AUTHOR
 143
 144 Richard Clamp <richardc@unixbeard.net>
 145
 146 =head1 COPYRIGHT
 147
 148 Copyright 2011, Richard Clamp.  All Rights Reserved.
 149
 150 This program is free software; you can redistribute it
 151 and/or modify it under the same terms as Perl itself.
 152
 153 =head1 SEE ALSO
 154
 155 http://docs.puppetlabs.com/mcollective/
 156
 157 =cut
 158