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, on servers without stdin streaming enabled, its 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
params
$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.
param
$p = $req->param( $key );This method returns the value of a single request parameter, or undef if no such key exists.
method
$method = $req->method;Returns the value of the REQUEST_METHOD parameter, or GET if there is no value set for it.
script_name
$script_name = $req->script_name;Returns the value of the SCRIPT_NAME parameter.
path_info
$path_info = $req->path_info;Returns the value of the PATH_INFO parameter.
path
$path = $req->path;Returns the full request path by reconstructing it from script_name and path_info.
query_string
$query_string = $req->query_string;Returns the value of the QUERY_STRING parameter.
protocol
$protocol = $req->protocol;Returns the value of the SERVER_PROTOCOL parameter.
set_encoding
$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.
read_stdin_line
$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.
read_stdin
$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.
set_on_stdin_read
$req->set_on_stdin_read( $on_stdin_read );
$again = $on_stdin_read->( $req, $buffref, $eof );Since version 0.26.
Only valid on requests on servers with stdin streaming enabled.
This method should be called as part of the on_request event on the server, to set the callback function to invoke when new data is provided to the stdin stream for this request.
The callback function is invoked in a similar style to the on_read event handler of an IO::Async::Stream. It is passed the request itself, along with a SCALAR reference to the buffer containing the stdin data, and a boolean indicating if the end of stdin data has been reached.
It should inspect this buffer and remove some prefix of it that it wishes to consume. Any remaining content will be present on the next call. If it returns a true value, the callback will be invoked again immediately, to consume more data. This continues until there is no more data left, or it returns false.
print_stdout
$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.
print_stderr
$req->print_stderr( $data );This method appends the given data to the STDERR stream of the FastCGI request, sending it to the webserver.
stream_stdout_then_finish
$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
$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
stderr
$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.
finish
$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_with_close
$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.
is_aborted
$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.
as_http_request
$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.
send_http_response
$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>