`Web::Transport::GenericServerConnection`

Common API for HTTP server connection

DESCRIPTION

The Web::Transport::GenericServerConnection class is a superclass of HTTP server connection implementations. There are these subclasses:

Web::Transport::PSGIServerConnection: A PSGI Web application server API
Web::Transport::ProxyServerConnection: An HTTP proxy server API

This module itself cannot be used by applications directly.

METHODS

There are following methods:

$con = $class->new_from_aeargs_and_opts ($aeargs, $opts)

Create and return a server connection object, wrapping server's socket.

The class can be either Web::Transport::PSGIServerConnection or Web::Transport::ProxyServerConnection.

The first argument must be an array reference of the arguments received by the AnyEvent::Socket::tcp_server's callback. That is, the filehandle of the socket, the remote host, and the remote port (if TCP). The socket can be a TCP or Unix domain server accepted socket filehandle object.

The second argument must be a hash reference of one or more key/value pairs specifying the server's behavior:

tls => {$name => $value, ...}

A hash reference with key/value pairs XXX, if TLS should be used over the connection (i.e. it is an HTTPS server). If not specified, TLS is not used (i.e. it is a plain HTTP server).

psgi_app => $code (PSGI server only, required)

A PSGI application, i.e. a code reference. See the PSGI specification for the requirements on the code reference.

handle_request => $code (proxy server only)

A request handler code reference. See "REQUEST HANDLER" in Web::Transport::ProxyServerConnection.

handle_response => $code (proxy server only)

A response handler code reference. See "RESPONSE HANDLER" in Web::Transport::ProxyServerConnection.

max_request_body_length => $integer (PSGI server only)

The maximum length of the request body to be accepted by the server, in bytes. If undef is explicitly specified, no limit is set. If this option is not given, a default finite value is set.

Note that the PSGI server loads the whole request body on memory, even when the PSGI application does not want to read the request body, as the server has to notify the request body's length of the application upon its invocation.

state => $object (PSGI server only)

The "server state" object which is shared among the PSGI application invocations on a same server session. (The definition of the "server session" is server application dependent.) The object is accessible as the manakai.server.state field value of the PSGI environment hash reference given to the PSGI applications. This object can be used to store objects whose lifetimes are longer than a request-response processing, such as connections to the database server. See the manakai PSGI extensions specification for more information.

server_header => $header_value

The name of the server, used as the Server: header value of the response generated by the server. If no value is specified, the default value is used.

client => {$name => $value, ...} (proxy server only)

The client options for the connections to the upstream server.

Client options are same as those for the Web::Transport::BasicClient (see "CLIENT OPTIONS" in Web::Transport::BasicClient), with following exceptions: The debug option's default value is $opts' debug option's value. The last_resort_timeout option's default value is -1. The parent_id option is not available and is set to appropriate value by the proxy.

debug => $mode

The debug mode. If not defined, the WEBSERVER_DEBUG environment variable's value is used. See WEBSERVER_DEBUG section in "ENVIRONMENT VARIABLES" in Web::Transport for available mode values.

parent_id => $string

A short string that identifies the "parent" context in which the connection appears, which will be used in debug outputs.

$con->onexception ($code)

$code = $con->onexception

Get or set the callback code reference that is invoked when an error is detected while interacting with the PSGI application or the proxy handlers such that the server returns an error response to the client (or abnormally close the HTTP connection).

The callback has to be set as soon as the object has been created and it should not be changed later.

The callback can return a promise, to delay the resolution of the complated promise until the promise is resolved or rejected.

$promise = $con->completed

Return a promise (Promise) which will be resolved once the connection between the server and the client has been closed and the PSGI application or the upstream connection has been completed.

An invocation of PSGI application is considered as completed when either a complete response is returned by the PSGI application or the PSGI application invoked the $writer->close method, and the psgix.exit_guard condvar's callback is invoked.

$con->close_after_current_response (timeout => $seconds)

Schedule to close the connection as soon as possible.

If the connection is not used at the moment, it is immediately closed. Otherwise, the connection is closed after the response to the currently processed request is sent.

The timeout option can be specified as a key/value pair. The option specifies the seconds of the timeout, whose default is 10 (seconds). If this option is set to an number greater than zero and the current response is not closed before that seconds have elapsed since the invocation of this method, the connection is aborted. The PSGI application is expected to return the whole response before this timeout.

Please note that even when the connection is aborted because of the timeout, the completed promise is not resolved or rejected until the psgix.exit_guard condvar is fullfilled and any reference to the PSGI writer is destroyed. As the PSGI does not provide any way to abort the PSGI application, invocation of this method does not terminate any running PSGI application.

This method can be used to gracefully terminate the server.

$string = $con->id

A short string assigned to the server connection, which can be used for debugging purposes. It is composed from the parent_id option to the constructor, if any.