DESCRIPTION

Furl is yet another HTTP client library. LWP is the de facto standard HTTP client for Perl 5, but it is too slow for some critical jobs, and too complex for weekend hacking. Furl resolves these issues. Enjoy it!

INTERFACE

Class Methods

Furl::HTTP->new(%args | \%args) :Furl

Creates and returns a new Furl client with %args. Dies on errors.

%args might be:

agent :Str = "Furl/$VERSION"

timeout :Int = 10

Seconds until the call to $furl->request returns a timeout error (as an internally generated 500 error). The timeout might not be accurate since some underlying modules / built-ins function may block longer than the specified timeout. See the FAQ for how to support timeout during name resolution.

max_redirects :Int = 7

proxy :Str

no_proxy :Str

headers :ArrayRef

header_format :Int = HEADERS_AS_ARRAYREF

This option choose return value format of $furl->request.

This option allows HEADERS_NONE or HEADERS_AS_ARRAYREF.

HEADERS_AS_ARRAYREF is a default value. This makes $headers as ArrayRef.

HEADERS_NONE makes $headers as undef. Furl does not return parsing result of headers. You should take needed headers from special_headers.

connection_pool :Object

This is the connection pool object for keep-alive requests. By default, it is a instance of Furl::ConnectionCache.

You may not customize this variable otherwise to use Coro. This attribute requires a duck type object. It has two methods, $obj->steal($host, $port and $obj->push($host, $port, $sock).

stop_if :CodeRef

A callback function that is called by Furl after when a blocking function call returns EINTR. Furl will abort the HTTP request and return immediately if the callback returns true. Otherwise the operation is continued (the default behaviour).

You must encode all the queries or this method will die, saying Wide character in ....

$furl->get($url :Str, $headers :ArrayRef[Str] )

This is an easy-to-use alias to request(), sending the GET method.

$furl->head($url :Str, $headers :ArrayRef[Str] )

This is an easy-to-use alias to request(), sending the HEAD method.

$furl->post($url :Str, $headers :ArrayRef[Str], $content :Any)

This is an easy-to-use alias to request(), sending the POST method.

$furl->put($url :Str, $headers :ArrayRef[Str], $content :Any)

This is an easy-to-use alias to request(), sending the PUT method.

$furl->delete($url :Str, $headers :ArrayRef[Str] )

This is an easy-to-use alias to request(), sending the DELETE method.

FAQ

Why IO::Socket::SSL?

Net::SSL is not well documented.

Why is env_proxy optional?

Environment variables are highly dependent on each users' environment, and we think it may confuse users when something doesn't go right.

What operating systems are supported?

Linux 2.6 or higher, OSX Tiger or higher, Windows XP or higher.

And other operating systems will be supported if you send a patch.

Why doesn't Furl support chunked upload?

There are reasons why chunked POST/PUTs should not be used in general.

First, you cannot send chunked requests unless the peer server at the other end of the established TCP connection is known to be a HTTP/1.1 server.

Second, HTTP/1.1 servers disconnect their persistent connection quite quickly (compared to the time they wait for the first request), so it is not a good idea to post non-idempotent requests (e.g. POST, PUT, etc.) as a succeeding request over persistent connections.

These facts together makes using chunked requests virtually impossible (unless you _know_ that the server supports HTTP/1.1), and this is why we decided that supporting the feature is NOT of high priority.

Native multipart/form-data support for Furl is available if you can send a patch for me.

How do you use Keep-Alive and what happens on the HEAD method?

Furl supports HTTP/1.1, hence Keep-Alive. However, if you use the HEAD method, the connection is closed immediately.

RFC 2616 section 9.4 says:

The HEAD method is identical to GET except that the server MUST NOT
return a message-body in the response.

Some web applications, however, returns message bodies on the HEAD method, which might confuse Keep-Alive processes, so Furl closes connection in such cases.

Anyway, the HEAD method is not so useful nowadays. The GET method and If-Modified-Sinse are more suitable to cache HTTP contents.

Why does Furl take longer than specified until it returns a timeout error?

Although Furl itself supports timeout, some underlying modules / functions do not. And the most noticeable one is Socket::inet_aton, the function used for name resolution (a function that converts hostnames to IP addresses). If you need accurate and short timeout for name resolution, the use of Net::DNS::Lite is recommended. The following code snippet describes how to use the module in conjunction with Furl.

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.