---
name: "Feersum::Connection"
section: "3pm"
platform: "linux"
package: "feersum"
version: "1.505-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Feersum::Connection"
---

# Feersum::Connection(3pm)

HTTP connection encapsulation

## 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->start_whole_response(200, ['Content-Type' => 'text/plain']);
        $req->write_whole_body(\"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.

Until Keep-Alive functionality is supported (if ever) this means that a connection is **also** a request.

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-\>fileno"

  The socket file-descriptor number for this connection.

- "$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 $env = $req-\>method"

  req method (GET/POST..) (psgi REQUEST\_METHOD)

- "my $env = $req-\>uri"

  full request uri (psgi REQUEST\_URI)

- "my $env = $req-\>protocol"

  protocol (psgi SERVER\_PROTOCOL)

- "my $env = $req-\>path"

  percent decoded request path (psgi PATH\_INFO)

- "my $env = $req-\>query"

  request query (psgi QUERY\_STRING)

- "my $env = $req-\>content\_length"

  body content lenght (psgi CONTENT\_LENGTH)

- "my $env = $req-\>input"

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

- "my $env = $req-\>headers(\[normalization\_style\])"

  an array of headers if form of \[name, value, 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 c\<\<use Feersum 'HEADER\_NORM\_LOCASE'\>\>

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

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

- "my $env = $req-\>remote\_address"

  remote address (psgi REMOTE\_ADDR)

- "my $env = $req-\>remote\_port"

  remote port (psgi REMOTE\_PORT)

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