view release on metacpan or  search on metacpan

lib/Feersum/Connection.pm  view on Meta::CPAN

does something interesting in its DESTROY/DEMOLISH method. For example,
L<Guard>.

B<On an HTTP/1 keepalive connection this is not when the response finishes.>
The guard is released at whichever comes first: the next C<response_guard()>
call on the same connection, which replaces it, or the connection closing.  So
an app that registers one on every request sees request N's guard fire during
request N+1's handler, and the last one only at close.  Do not use a guard to
release a per-request resource unless keepalive is off.

Guards are also released on client disconnect or HTTP/2 stream reset, and a
guard may capture the request environment without keeping a completed
connection alive.  See L<Feersum::Connection::Handle/"$h-E<gt>response_guard($guard)">.

=item C<< my $method = $req->method >>

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

=item C<< my $uri = $req->uri >>

full request uri (psgi REQUEST_URI)

=item C<< my $protocol = $req->protocol >>

The HTTP version from the request line: C<HTTP/1.1> or C<HTTP/1.0>.

B<Note:> unlike C<< $env->{SERVER_PROTOCOL} >>, this returns C<HTTP/1.1> for
an HTTP/2 stream - it reports the request-line version, which HTTP/2 does not
have.  Check the env hash if you need to distinguish HTTP/2.

=item C<< my $path = $req->path >>

percent decoded request path (psgi PATH_INFO)

=item C<< my $query = $req->query >>

request query (psgi QUERY_STRING)

=item C<< my $len = $req->content_length >>

body content length (psgi CONTENT_LENGTH)

=item C<< my $input = $req->input >>

Input body handler (psgi.input).  Returns C<undef> when there is no body to
read -- i.e. the (decoded) body length is zero, as for GET/HEAD or a
zero-length POST.  Note a chunked request with a non-empty body has no
Content-Length yet still yields a handle.  Check with C<defined> before
use.  It is advised to close it after read is done.

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

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

normalization_style is one of (always use named constants, not numeric values):

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

One can export these constants via C<< use Feersum 'HEADER_NORM_LOCASE' >>

=item C<< my $value = $req->header(name) >>

Lookup a single header value by name (case-insensitive).  When multiple
headers share the same name, values are joined with C<", "> (or C<"; "> for
cookies per RFC 9113 section 8.2.3).  Returns C<undef> if the header is absent.

=item C<< my $addr = $req->remote_address >>

Remote address of the connection (psgi REMOTE_ADDR).  When PROXY protocol is
active, returns the client address from the PROXY header; otherwise returns
the socket peer address.

=item C<< my $port = $req->remote_port >>

Remote port of the connection (psgi REMOTE_PORT).  When PROXY protocol is
active, returns the client port from the PROXY header.

=item C<< my $addr = $req->client_address >>

Client address, respecting reverse proxy mode. When C<reverse_proxy> is
enabled and the leftmost entry of X-Forwarded-For is a valid IPv4 or IPv6
address, returns that address. If the header is absent or its first value is
not a valid IP (e.g. a hostname or spoofed string), returns the same as
C<remote_address>.

=item C<< my $scheme = $req->url_scheme >>

URL scheme (http or https). Resolution order: (1) "https" if the connection
uses TLS or HTTP/2, (2) "https" if PROXY protocol indicates SSL (PP2_TYPE_SSL
TLV) or original destination port 443, (3) X-Forwarded-Proto header value when
C<reverse_proxy> is enabled, (4) "http" otherwise.

=item C<< my $tlvs = $req->proxy_tlvs >>

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

=item C<< my $trailers = $req->trailers >>

Returns an array reference of request trailers in form of [ name => value, ... ],
or C<undef> if no trailers were received. Only supported for HTTP/2
requests currently.

=back

=begin comment

=head2 Private Methods

=over 4

=item C<< new() >>

Croaks; connections cannot be constructed directly. Feersum creates these