Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::Async::FastCGI::RUsersContributed Perl DocNet::Async::FastCGI::Request(3)

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>

perl v5.32.0			  2013-02-16   Net::Async::FastCGI::Request(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | HTTP::Request/Response Interface | EXAMPLES | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Async::FastCGI::Request&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help