The manakai project

Web::Transport::PSGIServerConnection

PSGI interface for HTTP server connection

SYNOPSIS

  $psgi_app = sub { ... };
  tcp_server $host, $port, sub {
    my $con = Web::Transport::PSGIServerConnection
        ->new_from_app_and_ae_tcp_server_args ($psgi_app, [@_]);
    $con->completed->then (sub {
      warn "Client disconnected and PSGI application done";
    });
  };

DESCRIPTION

The Web::Transport::PSGIServerConnection module is an implementation of HTTP server and PSGI. It wraps an HTTP server's TCP connection socket and processes any incoming request by a PSGI application.

METHODS

There are following methods:

$con = Web::Transport::PSGIServerConnection->new_from_app_and_ae_tcp_server_args ($app, [...], NAME => VALUE, ...)

Create an object.

The first argument must be a PSGI application, i.e. a code reference. See the PSGI specification for the requirements on the code reference.

The second 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 of a TCP or UNIX socket domain.

Additionally, options can be specified as key/value pairs.

The parent_id option, if any, specifies the short string that identifies the "parent" context in which the connection appears, which will be used in debug outputs.

The state option, if any, specifies 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.

$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 such that the server returns an error response to the client.

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.

$con->max_request_body_length ($integer)
$integer = $con->max_request_body_length

Get or set the maximum length of the request body to be accepted by the server, in bytes. If undef, no limit is set.

Note that the server loads the whole request body on memory, as the server has to notify the request body's length of the PSGI application at the time of invocation.

$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 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.

SEE ALSO

AnyEvent::Socket.

SPECIFICATIONS

Web Transport Processing <https://wiki.suikawiki.org/n/Web%20Transport%20Processing>.

RFC 3875, The Common Gateway Interface (CGI) Version 1.1 <https://tools.ietf.org/html/rfc3875>.

PSGI <https://github.com/plack/psgi-specs/blob/master/PSGI.pod>.

PSGI::Extensions <https://github.com/plack/psgi-specs/blob/master/PSGI/Extensions.pod>.

psgix.exit_guard <https://github.com/kazeburo/Twiggy-Prefork#psgi-extensions>.

manakai PSGI extensions <https://wiki.suikawiki.org/n/manakai%20PSGI%20extensions>.

AUTHOR

Wakaba <wakaba@suikawiki.org>.

LICENSE

Copyright 2016-2017 Wakaba <wakaba@suikawiki.org>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.