=encoding utf8

=head1 NAME

App::EvalServer - Evaluate arbitrary code in a safe environment

=head1 SYNOPSIS

 use App::EvalServer;

 my $server = App::EvalServer->new(
     port    => 1234,
     timeout => 30,
 );

 $server->run();
 
 # ...
 
 $server->shutdown();

=head1 DESCRIPTION

This application evaluates arbitrary source code in a safe enviroment. It
listens on a TCP port and accepts JSON data desribing a language and some
code to evaluate. The result of the evaluation and some accompanying
information is then returned as back as JSON data. See L</INPUT> and
L</OUTPUT> for details.

=head1 METHODS

=head2 C<new>

Constructs a new C<App::EvalServer> object. Takes the following optional
argunments:

B<'host'>, the host to listen on (default: 'localhost')

B<'port'>, the port to listen on (default: 14400)

B<'user'>, evaluate code as this user (default: 'nobody')

B<'timeout'>, kill the evaluating process after this many seconds (default: 10)

B<'limit'>, resource limit in megabytes (default: 50)

B<'daemonize'>, daemonize the process

B<'unsafe'>, don't chroot or set resource limits (no root needed). Default is
false.

=head2 C<run>

Runs the server. Takes no arguments.

=head2 C<shutdown>

Shuts down the server. Takes no arguments.

=head1 INPUT

To request an evaluation, you need to send a JSON hash containing the
following keys:

B<'lang'>, a string containing the language module suffix, e.g. 'Perl' for
L<App::EvalServer::Language::Perl|App::EvalServer::Language::Perl>.

B<'code'>, a string containing the code you want evaluated.

=head1 OUTPUT

When your request has been processed, you will receive a JSON hash back. If
no errors occurred B<before> the code was evaluated, the hash will contain the
following keys:

=over 4

=item * B<'result'>, containing the result of the evaluation.

=item * B<'stdout'>, a string containing everything that was printed to the
evaluating process' stdout handle.

=item * B<'stderr'>, a string containing everything that was printed to the
evaluating process' stderr handle.

=item * B<'output'> a string containing the merged output (stdout & stderr)
from the evaluating process.

=item * B<'memory'>, the memory use of the evaluating process (as reported by
L<C<(getrusage())[2]>|BSD::Resource/getrusage>).

=item * B<'real_time'>, the real time taken by the evaluating process.

=item * B<'user_time'>, the user time taken by the evaluating process.

=item * B<'sys_time'>, the sys time taken by the evaluating process.

=back

If an error occurred before the code could be evaluated, the only key you
will get is B<'error'>, which tells you what
went wrong.

=head1 AUTHOR

Hinrik E<Ouml>rn SigurE<eth>sson (hinrik.sig@gmail.com), C<buu>, and probably
others

=head1 LICENSE AND COPYRIGHT

Copyright 2010 Hinrik E<Ouml>rn SigurE<eth>sson

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

=cut
