.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Async::FastCGI::Request 3pm"
.TH Net::Async::FastCGI::Request 3pm "2021-01-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"Net::Async::FastCGI::Request" \- a single active FastCGI request
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& 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\er\en" .
\&                           "Content\-type: text/plain\er\en" .
\&                           "\er\en" .
\&                           "You requested $path" );
\&       $req\->finish();
\&    }
\& );
\&
\& my $loop = IO::Async::Loop\->new();
\&
\& $loop\->add( $fcgi );
\&
\& $loop\->run;
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1STDIN\s0 data. The program can then write response data to the
\&\s-1STDOUT\s0 stream, messages to the \s-1STDERR\s0 stream, and eventually finish it.
.PP
This module would not be used directly by a program using
\&\f(CW\*(C`Net::Async::FastCGI\*(C'\fR, but rather, objects in this class are passed into the
\&\f(CW\*(C`on_request\*(C'\fR event of the containing \f(CW\*(C`Net::Async::FastCGI\*(C'\fR object.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$hashref = $req\->params"
.el .SS "\f(CW$hashref\fP = \f(CW$req\fP\->params"
.IX Subsection "$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.
.ie n .SS "$p = $req\->param( $key )"
.el .SS "\f(CW$p\fP = \f(CW$req\fP\->param( \f(CW$key\fP )"
.IX Subsection "$p = $req->param( $key )"
This method returns the value of a single request parameter, or \f(CW\*(C`undef\*(C'\fR if no
such key exists.
.ie n .SS "$method = $req\->method"
.el .SS "\f(CW$method\fP = \f(CW$req\fP\->method"
.IX Subsection "$method = $req->method"
Returns the value of the \f(CW\*(C`REQUEST_METHOD\*(C'\fR parameter, or \f(CW\*(C`GET\*(C'\fR if there is no
value set for it.
.ie n .SS "$script_name = $req\->script_name"
.el .SS "\f(CW$script_name\fP = \f(CW$req\fP\->script_name"
.IX Subsection "$script_name = $req->script_name"
Returns the value of the \f(CW\*(C`SCRIPT_NAME\*(C'\fR parameter.
.ie n .SS "$path_info = $req\->path_info"
.el .SS "\f(CW$path_info\fP = \f(CW$req\fP\->path_info"
.IX Subsection "$path_info = $req->path_info"
Returns the value of the \f(CW\*(C`PATH_INFO\*(C'\fR parameter.
.ie n .SS "$path = $req\->path"
.el .SS "\f(CW$path\fP = \f(CW$req\fP\->path"
.IX Subsection "$path = $req->path"
Returns the full request path by reconstructing it from \f(CW\*(C`script_name\*(C'\fR and
\&\f(CW\*(C`path_info\*(C'\fR.
.ie n .SS "$query_string = $req\->query_string"
.el .SS "\f(CW$query_string\fP = \f(CW$req\fP\->query_string"
.IX Subsection "$query_string = $req->query_string"
Returns the value of the \f(CW\*(C`QUERY_STRING\*(C'\fR parameter.
.ie n .SS "$protocol = $req\->protocol"
.el .SS "\f(CW$protocol\fP = \f(CW$req\fP\->protocol"
.IX Subsection "$protocol = $req->protocol"
Returns the value of the \f(CW\*(C`SERVER_PROTOCOL\*(C'\fR parameter.
.ie n .SS "$req\->set_encoding( $encoding )"
.el .SS "\f(CW$req\fP\->set_encoding( \f(CW$encoding\fP )"
.IX Subsection "$req->set_encoding( $encoding )"
Sets the character encoding used by the request's \s-1STDIN, STDOUT\s0 and \s-1STDERR\s0
streams. This method may be called at any time to change the encoding in
effect, which will be used the next time \f(CW\*(C`read_stdin_line\*(C'\fR, \f(CW\*(C`read_stdin\*(C'\fR,
\&\f(CW\*(C`print_stdout\*(C'\fR or \f(CW\*(C`print_stderr\*(C'\fR are called. This encoding will remain in
effect until changed again. The encoding of a new request is determined by the
\&\f(CW\*(C`default_encoding\*(C'\fR parameter of the containing \f(CW\*(C`Net::Async::FastCGI\*(C'\fR object.
If the value \f(CW\*(C`undef\*(C'\fR is passed, the encoding will be removed, and the above
methods will work directly on bytes instead of encoded strings.
.ie n .SS "$line = $req\->read_stdin_line"
.el .SS "\f(CW$line\fP = \f(CW$req\fP\->read_stdin_line"
.IX Subsection "$line = $req->read_stdin_line"
This method works similarly to the \f(CW\*(C`<HANDLE>\*(C'\fR 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 \f(CW\*(C`undef\*(C'\fR
is returned instead.
.ie n .SS "$data = $req\->read_stdin( $size )"
.el .SS "\f(CW$data\fP = \f(CW$req\fP\->read_stdin( \f(CW$size\fP )"
.IX Subsection "$data = $req->read_stdin( $size )"
This method works similarly to the \f(CW\*(C`read(HANDLE)\*(C'\fR function. It returns the
next block of up to \f(CW$size\fR bytes from the \s-1STDIN\s0 buffer. If no data is available
any more, then \f(CW\*(C`undef\*(C'\fR is returned instead. If \f(CW$size\fR is not defined, then it
will return all the available data.
.ie n .SS "$req\->print_stdout( $data )"
.el .SS "\f(CW$req\fP\->print_stdout( \f(CW$data\fP )"
.IX Subsection "$req->print_stdout( $data )"
This method appends the given data to the \s-1STDOUT\s0 stream of the FastCGI
request, sending it to the webserver to be sent to the client.
.ie n .SS "$req\->print_stderr( $data )"
.el .SS "\f(CW$req\fP\->print_stderr( \f(CW$data\fP )"
.IX Subsection "$req->print_stderr( $data )"
This method appends the given data to the \s-1STDERR\s0 stream of the FastCGI
request, sending it to the webserver.
.ie n .SS "$req\->stream_stdout_then_finish( $readfn, $exitcode )"
.el .SS "\f(CW$req\fP\->stream_stdout_then_finish( \f(CW$readfn\fP, \f(CW$exitcode\fP )"
.IX Subsection "$req->stream_stdout_then_finish( $readfn, $exitcode )"
This method installs a callback for streaming data to the \s-1STDOUT\s0 stream.
Whenever the output stream is otherwise-idle, the function will be called to
generate some more data to output. When this function returns \f(CW\*(C`undef\*(C'\fR it
indicates the end of the stream, and the request will be finished with the
given exit code.
.PP
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
\&\f(CW\*(C`Content\-Length\*(C'\fR, if such was provided. This logic should be performed by the
containing application; \f(CW\*(C`Net::Async::FastCGI\*(C'\fR will not track it.
.ie n .SS "$stdin = $req\->stdin"
.el .SS "\f(CW$stdin\fP = \f(CW$req\fP\->stdin"
.IX Subsection "$stdin = $req->stdin"
Returns an \s-1IO\s0 handle representing the request's \s-1STDIN\s0 buffer. This may be read
from using the \f(CW\*(C`read\*(C'\fR or \f(CW\*(C`readline\*(C'\fR functions or the \f(CW\*(C`<$stdin>\*(C'\fR
operator.
.PP
Note that this will be a tied \s-1IO\s0 handle, it will not be useable directly as an
OS-level filehandle.
.ie n .SS "$stdout = $req\->stdout"
.el .SS "\f(CW$stdout\fP = \f(CW$req\fP\->stdout"
.IX Subsection "$stdout = $req->stdout"
.ie n .SS "$stderr = $req\->stderr"
.el .SS "\f(CW$stderr\fP = \f(CW$req\fP\->stderr"
.IX Subsection "$stderr = $req->stderr"
Returns an \s-1IO\s0 handle representing the request's \s-1STDOUT\s0 or \s-1STDERR\s0 streams
respectively. These may written to using \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR, \f(CW\*(C`say\*(C'\fR, etc..
.PP
Note that these will be tied \s-1IO\s0 handles, they will not be useable directly as
an OS-level filehandle.
.ie n .SS "$req\->finish( $exitcode )"
.el .SS "\f(CW$req\fP\->finish( \f(CW$exitcode\fP )"
.IX Subsection "$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 \s-1STDOUT\s0 stream. At some point after calling this method,
the request object will be removed from the containing \f(CW\*(C`Net::Async::FastCGI\*(C'\fR
object, once all the buffered outbound data has been sent.
.PP
If present, \f(CW$exitcode\fR should indicate the numeric status code to send to
the webserver. If absent, a value of \f(CW0\fR is presumed.
.ie n .SS "$stdout = $req\->stdout_with_close"
.el .SS "\f(CW$stdout\fP = \f(CW$req\fP\->stdout_with_close"
.IX Subsection "$stdout = $req->stdout_with_close"
Similar to the \f(CW\*(C`stdout\*(C'\fR method, except that when the \f(CW\*(C`close\*(C'\fR method is
called on the returned filehandle, the request will be finished by calling
\&\f(CW\*(C`finish\*(C'\fR.
.ie n .SS "$req\->is_aborted"
.el .SS "\f(CW$req\fP\->is_aborted"
.IX Subsection "$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.
.PP
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.
.SH "HTTP::Request/Response Interface"
.IX Header "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.
.ie n .SS "$http_req = $req\->as_http_request"
.el .SS "\f(CW$http_req\fP = \f(CW$req\fP\->as_http_request"
.IX Subsection "$http_req = $req->as_http_request"
Returns a new \f(CW\*(C`HTTP::Request\*(C'\fR object that gives a reasonable approximation to
the request. Because the webserver has translated the original \s-1HTTP\s0 request
into FastCGI parameters, this may not be a perfect recreation of the request
as received by the webserver.
.ie n .SS "$req\->send_http_response( $resp )"
.el .SS "\f(CW$req\fP\->send_http_response( \f(CW$resp\fP )"
.IX Subsection "$req->send_http_response( $resp )"
Sends the given \f(CW\*(C`HTTP::Response\*(C'\fR object as the response to this request. The
status, headers and content are all written out to the request's \s-1STDOUT\s0 stream
and then the request is finished with 0 as the exit code.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Streaming A File"
.IX Subsection "Streaming A File"
To serve contents of files on disk, it may be more efficient to use
\&\f(CW\*(C`stream_stdout_then_finish\*(C'\fR:
.PP
.Vb 2
\& 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\er\en" .
\&                           "Content\-type: application/octet\-stream\er\en" .
\&                           "\er\en" );
\&
\&       $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;
.Ve
.PP
It may be more efficient again to instead use the \f(CW\*(C`X\-Sendfile\*(C'\fR feature of
certain webservers, which allows the webserver itself to serve the file
efficiently. See your webserver's documentation for more detail.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>