NAME

       "Net::Async::FastCGI::Request" - a single active FastCGI request

SYNOPSIS

        use Net::Async::FastCGI;
        use IO::Async::Loop;

        my $fcgi = Net::Async::FastCGI->new(
           on_request => sub {
              my ( $fcgi, $req ) = @_;

              my $path = $req->param( "PATH_INFO" );
              $req->print_stdout( "Status: 200 OK\r\n" .
                                  "Content-type: text/plain\r\n" .
                                  "\r\n" .
                                  "You requested $path" );
              $req->finish();
           }
        );

        my $loop = IO::Async::Loop->new();

        $loop->add( $fcgi );

        $loop->run;

DESCRIPTION

       Instances of this object class represent individual requests received from the webserver
       that are currently in-progress, and have not yet been completed.  When given to the
       controlling program, each request will already have its parameters and STDIN data. The
       program can then write response data to the STDOUT stream, messages to the STDERR stream,
       and eventually finish it.

       This module would not be used directly by a program using "Net::Async::FastCGI", but
       rather, objects in this class are passed into the "on_request" event of the containing
       "Net::Async::FastCGI" object.

METHODS

   $hashref = $req->params
       This method returns a reference to a hash containing a copy of the request parameters that
       had been sent by the webserver as part of the request.

   $p = $req->param( $key )
       This method returns the value of a single request parameter, or "undef" if no such key
       exists.

   $method = $req->method
       Returns the value of the "REQUEST_METHOD" parameter, or "GET" if there is no value set for
       it.

   $script_name = $req->script_name
       Returns the value of the "SCRIPT_NAME" parameter.

   $path_info = $req->path_info
       Returns the value of the "PATH_INFO" parameter.

   $path = $req->path
       Returns the full request path by reconstructing it from "script_name" and "path_info".

   $query_string = $req->query_string
       Returns the value of the "QUERY_STRING" parameter.

   $protocol = $req->protocol
       Returns the value of the "SERVER_PROTOCOL" parameter.

   $req->set_encoding( $encoding )
       Sets the character encoding used by the request's STDIN, STDOUT and STDERR streams. This
       method may be called at any time to change the encoding in effect, which will be used the
       next time "read_stdin_line", "read_stdin", "print_stdout" or "print_stderr" are called.
       This encoding will remain in effect until changed again. The encoding of a new request is
       determined by the "default_encoding" parameter of the containing "Net::Async::FastCGI"
       object.  If the value "undef" is passed, the encoding will be removed, and the above
       methods will work directly on bytes instead of encoded strings.

   $line = $req->read_stdin_line
       This method works similarly to the "<HANDLE>" operator. If at least one line of data is
       available then it is returned, including the linefeed, and removed from the buffer. If
       not, then any remaining partial line is returned and removed from the buffer. If no data
       is available any more, then "undef" is returned instead.

   $data = $req->read_stdin( $size )
       This method works similarly to the "read(HANDLE)" function. It returns the next block of
       up to $size bytes from the STDIN buffer. If no data is available any more, then "undef" is
       returned instead. If $size is not defined, then it will return all the available data.

   $req->print_stdout( $data )
       This method appends the given data to the STDOUT stream of the FastCGI request, sending it
       to the webserver to be sent to the client.

   $req->print_stderr( $data )
       This method appends the given data to the STDERR stream of the FastCGI request, sending it
       to the webserver.

   $req->stream_stdout_then_finish( $readfn, $exitcode )
       This method installs a callback for streaming data to the STDOUT stream.  Whenever the
       output stream is otherwise-idle, the function will be called to generate some more data to
       output. When this function returns "undef" it indicates the end of the stream, and the
       request will be finished with the given exit code.

       If this method is used, then care should be taken to ensure that the number of bytes
       written to the server matches the number that was claimed in the "Content-Length", if such
       was provided. This logic should be performed by the containing application;
       "Net::Async::FastCGI" will not track it.

   $stdin = $req->stdin
       Returns an IO handle representing the request's STDIN buffer. This may be read from using
       the "read" or "readline" functions or the "<$stdin>" operator.

       Note that this will be a tied IO handle, it will not be useable directly as an OS-level
       filehandle.

   $stdout = $req->stdout
   $stderr = $req->stderr
       Returns an IO handle representing the request's STDOUT or STDERR streams respectively.
       These may written to using "print", "printf", "say", etc..

       Note that these will be tied IO handles, they will not be useable directly as an OS-level
       filehandle.

   $req->finish( $exitcode )
       When the request has been dealt with, this method should be called to indicate to the
       webserver that it is finished. After calling this method, no more data may be appended to
       the STDOUT stream. At some point after calling this method, the request object will be
       removed from the containing "Net::Async::FastCGI" object, once all the buffered outbound
       data has been sent.

       If present, $exitcode should indicate the numeric status code to send to the webserver. If
       absent, a value of 0 is presumed.

   $stdout = $req->stdout_with_close
       Similar to the "stdout" method, except that when the "close" method is called on the
       returned filehandle, the request will be finished by calling "finish".

   $req->is_aborted
       Returns true if the webserver has already closed the control connection. No further work
       on this request is necessary, as it will be discarded.

       It is not required to call this method; if the request is aborted then any output will be
       discarded. It may however be useful to call just before expensive operations, in case
       effort can be avoided if it would otherwise be wasted.

HTTP::Request/Response Interface

       The following pair of methods form an interface that allows the request to be used as a
       source of HTTP::Request objects, responding to them by sending HTTP::Response objects.
       This may be useful to fit it in to existing code that already uses these.

   $http_req = $req->as_http_request
       Returns a new "HTTP::Request" object that gives a reasonable approximation to the request.
       Because the webserver has translated the original HTTP request into FastCGI parameters,
       this may not be a perfect recreation of the request as received by the webserver.

   $req->send_http_response( $resp )
       Sends the given "HTTP::Response" object as the response to this request. The status,
       headers and content are all written out to the request's STDOUT stream and then the
       request is finished with 0 as the exit code.

EXAMPLES

   Streaming A File
       To serve contents of files on disk, it may be more efficient to use
       "stream_stdout_then_finish":

        use Net::Async::FastCGI;
        use IO::Async::Loop;

        my $fcgi = Net::Async::FastCGI->new(
           on_request => sub {
              my ( $fcgi, $req ) = @_;

              open( my $file, "<", "/path/to/file" );
              $req->print_stdout( "Status: 200 OK\r\n" .
                                  "Content-type: application/octet-stream\r\n" .
                                  "\r\n" );

              $req->stream_stdout_then_finish(
                 sub { read( $file, my $buffer, 8192 ) or return undef; return $buffer },
                 0
              );
           }

        my $loop = IO::Async::Loop->new();

        $loop->add( $fcgi );

        $loop->run;

       It may be more efficient again to instead use the "X-Sendfile" feature of certain
       webservers, which allows the webserver itself to serve the file efficiently. See your
       webserver's documentation for more detail.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>