NAME

Feersum::Connection - HTTP connection encapsulation

SYNOPSIS

For a streaming response:

Feersum->endjinn->request_handler(sub {
    my $req = shift; # this is a Feersum::Connection object
    my $env = $req->env();
    my $w = $req->start_streaming(200, ['Content-Type' => 'text/plain']);
    # then immediately or after some time:
    $w->write("Ergrates ");
    $w->write(\"FTW.");
    $w->close();
});

For a response with a Content-Length header:

Feersum->endjinn->request_handler(sub {
    my $req = shift; # this is a Feersum::Connection object
    my $env = $req->env();
    $req->send_response(200, ['Content-Type' => 'text/plain'], \"Ergrates FTW.");
});

DESCRIPTION

Encapsulates an HTTP connection to Feersum. It's roughly analogous to an Apache::Request or Apache2::Connection object, but differs significantly in functionality.

With HTTP/1.1 Keep-Alive support, multiple requests can be served over the same connection.

See Feersum for more examples on usage.

METHODS

my $env = $req->env()

Obtain an environment hash. This hash contains the same entries as for a PSGI handler environment hash. See Feersum for details on the contents.

This is a method instead of a parameter so that future versions of Feersum can request a slice of the hash for speed.

my $w = $req->start_streaming($code, \@headers)

A full HTTP header section is sent with "Transfer-Encoding: chunked" (or "Connection: close" for HTTP/1.0 clients).

Returns a Feersum::Connection::Writer handle which should be used to complete the response. See Feersum::Connection::Handle for methods.

$req->send_response($code, \@headers, $body)

$req->send_response($code, \@headers, \@body)

Respond with a full HTTP header (including Content-Length) and body.

Returns the number of bytes calculated for the body.

$req->force_http10

$req->force_http11

Force the response to use HTTP/1.0 or HTTP/1.1, respectively.

Normally, if the request was made with 1.1 then Feersum uses HTTP/1.1 for the response, otherwise HTTP/1.0 is used (this includes requests made with the HTTP "0.9" non-declaration).

For streaming under HTTP/1.1 Transfer-Encoding: chunked is used, otherwise a Connection: close stream-style is used (with the usual non-guarantees about delivery). You may know about certain user-agents that support/don't-support T-E:chunked, so this is how you can override that.

Supposedly clients and a lot of proxies support the Connection: close stream-style, see support in Varnish at http://www.varnish-cache.org/trac/ticket/400

$req->is_http11

Returns true if the request was made using HTTP/1.1, false otherwise. Useful for determining protocol capabilities before sending a response.

$req->is_keepalive

Returns true if the connection has keep-alive enabled for this request. This takes into account the HTTP version, Connection header, and server configuration.

$req->fileno

The socket file-descriptor number for this connection.

$req->io

Returns an IO::Handle for the underlying connection socket (typically an IO::Socket::INET). This is the native interface equivalent of psgix.io in the PSGI environment. Any buffered request data will be pushed back into the socket's read buffer.

For HTTP/2 Extended CONNECT streams (RFC 8441), this returns one end of a Unix socketpair instead of the raw TCP socket. Feersum shuttles data between the other end of the pair and H2 DATA frames internally. The handle is bidirectional and suitable for WebSocket or other tunnel protocols.

WARNING: Once you call this method, Feersum relinquishes control of the socket. You are responsible for all I/O and must not use other Feersum response methods on this connection.

$req->return_from_io($io)

Returns control of the socket back to Feersum after io() was called. This allows keepalive to continue working if you decided not to upgrade the connection (e.g., WebSocket handshake failed). Any buffered data in the IO handle will be pulled back into Feersum's read buffer.

Returns the number of bytes pulled back from the IO buffer.

$req->response_guard($guard)

Register a guard to be triggered when the response is completely sent and the socket is closed. A "guard" in this context is some object that will do something interesting in its DESTROY/DEMOLISH method. For example, Guard.

my $method = $req->method

req method (GET/POST..) (psgi REQUEST_METHOD)

my $uri = $req->uri

full request uri (psgi REQUEST_URI)

my $protocol = $req->protocol

protocol (psgi SERVER_PROTOCOL)

my $path = $req->path

percent decoded request path (psgi PATH_INFO)

my $query = $req->query

request query (psgi QUERY_STRING)

my $len = $req->content_length

body content length (psgi CONTENT_LENGTH)

my $input = $req->input

input body handler (psgi.input), it is advised to close it after read is done

my $headers = $req->headers([normalization_style])

Returns a hash reference of headers in form of { name => value, ... }.

normalization_style is one of:

0 - skip normalization (default) HEADER_NORM_LOCASE - "content-type" HEADER_NORM_UPCASE - "CONTENT-TYPE" HEADER_NORM_LOCASE_DASH - "content_type" HEADER_NORM_UPCASE_DASH - "CONTENT_TYPE" (like PSGI, but without "HTTP_" prefix)

One can export these constants via use Feersum 'HEADER_NORM_LOCASE'

my $value = $req->header(name)

simple lookup for header value, name should be in lowercase, eg. 'content-type'

my $addr = $req->remote_address

Remote address of the connection (psgi REMOTE_ADDR). This always returns the actual socket peer address.

my $port = $req->remote_port

Remote port of the connection (psgi REMOTE_PORT).

my $addr = $req->client_address

Client address, respecting reverse proxy mode. When reverse_proxy is enabled and X-Forwarded-For header is present, returns the first (leftmost) IP from that header. Otherwise returns the same as remote_address.

my $scheme = $req->url_scheme

URL scheme (http or https), respecting reverse proxy mode. When reverse_proxy is enabled and X-Forwarded-Proto header is present, returns that value. Otherwise returns "http".

my $tlvs = $req->proxy_tlvs

Returns a hash reference of PROXY protocol v2 TLV (Type-Length-Value) extensions, or undef if no TLVs were received. Keys are TLV type numbers (as integers), values are raw TLV data bytes. Only populated when proxy_protocol is enabled and the client sends a v2 header with TLV extensions (e.g. PP2_TYPE_SSL, PP2_TYPE_AUTHORITY).

AUTHOR

Jeremy Stashewsky, stash@cpan.org

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Jeremy Stashewsky & Socialtext Inc.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.