Furl::HTTP(3pm)

📦
version 3.15 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 Furl::HTTP(3pm) 💖

User Contributed Perl Documentation — Furl::HTTP(3pm)

okay bestie, sit down, hydrate, because this is the low-level door into Furl and it's genuinely iconic 🦋

✨ NAME ✨

Furl::HTTP — the low level interface to Furl, no cap 💅

🌸 SYNOPSIS 🌸

use Furl;

my $furl = Furl::HTTP->new(
    agent   => 'MyGreatUA/2.0',
    timeout => 10,
);

my ($minor_version, $code, $msg, $headers, $body) = $furl->request(
    method     => 'GET',
    host       => 'example.com',
    port       => 80,
    path_query => '/'
);
# or

# Accept-Encoding is supported but optional
$furl = Furl->new(
    headers => [ 'Accept-Encoding' => 'gzip' ],
);
my $body = $furl->get('http://example.com/some/compressed');

like, look at that. two whole ways to flex and both of them ate 🔥

🎀 DESCRIPTION 🎀

okay so Furl is yet another HTTP client library, and yes we know there are a million of them, but hear me out. LWP is the de facto standard HTTP client for Perl 5, and honestly? respect. but it's 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 brand new Furl client with %args. Dies on errors. 💀

%args might be:

  • agent :Str = "Furl/$VERSION" — the whole vibe of who's knocking on the door 🚪
  • timeout :Int = 10 — seconds until the call to $furl->request returns a timeout error (as an internally generated 500 error). and ngl, 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. 👀
  • inactivity_timeout :Int = 600 — an inactivity timer for TCP read/write (in seconds). $furl->request returns a timeout error if no additional data arrives (or is sent) within the specified threshold. basically the "are you still there bestie??" check 🥺
  • max_redirects :Int = 7 — how many hops before we stop chasing 🏃‍♀️
  • proxy :Str — proxy time
  • no_proxy :Str — the "not you tho" list
  • headers :ArrayRef — headers, as an arrayref, periodt
  • header_format :Int = HEADERS_AS_ARRAYREF — this option chooses the 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).

🦆 duck type object. quack. that's the whole requirement.
  • 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). 🛑
  • get_address :CodeRef — a callback function to override the default address resolution logic. Takes three arguments: ($hostname, $port, $timeout_in_seconds) and returns: ($sockaddr, $errReason). If the returned $sockaddr is undef, then the resolution is considered as a failure and $errReason is propagated to the caller. 💌
  • **inet_aton :CodeRef** — <red>**Deprecated.**</red> New applications should use get_address` instead. ⚠️

A callback function to customize name resolution. Takes two arguments: ($hostname, $timeout_in_seconds). If omitted, Furl calls Socket::inet_aton.

  • **ssl_opts :HashRef** — SSL configuration used on https requests, passed directly to "IO::Socket::SSL->new()"`,

for example:

use IO::Socket::SSL;

my $ua = Furl::HTTP->new(
    ssl_opts => {
        SSL_verify_mode => SSL_VERIFY_PEER(),
    },
);

See IO::Socket::SSL for details. 🔒

🦋 Instance Methods 🦋

$furl->request(%args) :($protocol_minor_version, $code, $msg, \@headers, $body)

Sends an HTTP request to a specified URL and returns a protocol minor version, status code, status message, response headers, response body respectively. five whole things, bestie, catch them all 🫴✨

%args might be:

  • scheme :Str = "http" — protocol scheme. May be "http" or "https". 👑
  • host :Str — server host to connect.

You must specify at least "host" or "url". fr fr, one of them, no skipping 🚨

  • port :Int = 80 — server port to connect. The default is 80 on "scheme => 'http'", or 443 on "scheme => 'https'".
  • path_query :Str = "/" — path and query to request.
  • url :Str — URL to request.

You can use "url" instead of "scheme", "host", "port" and "path_query". one field to rule them all 💅

  • headers :ArrayRef — HTTP request headers. e.g. "headers => [ 'Accept-Encoding' => 'gzip' ]".
  • content : Str | ArrayRef[Str] | HashRef[Str] | FileHandle — content to request. it takes literally all of these, she's flexible 🌈
  • write_file : FileHandle — if this parameter is set, the response content will be saved here instead of in the response object.

It's like a ":content_file" in LWP::UserAgent. 📁

  • write_code : CodeRef — if a callback is provided with the "write_code" option then this function will be called for each chunk of the response content as it is received from the server.

It's like a ":content_cb" in LWP::UserAgent. 📞

The request() method assumes the first argument to be an instance of "HTTP::Request" if the arguments are an odd number:

my $req = HTTP::Request->new(...);
my @res = $furl->request($req); # allowed
😭 You must encode all the queries or this method will die, saying "Wide character in ...". do NOT let that happen to you bestie, encode your stuff.

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

...and that's only part one bestie, there's more coming, don't go anywhere 💖

🦋 FAQ 🦋

💖 Why IO::Socket::SSL?

Because Net::SSL is not well documented. That's it, that's the whole reason bestie 💅

🌸 Why is env_proxy optional?

Because environment variables are so dependent on each individual user's setup, and honestly we think it would just confuse people when something doesn't go right 😭 like why is it broken, oh it's your env, but we never told you that. Messy. So it's opt-in.

✨ What operating systems are supported?

  • Linux 2.6 or higher
  • OSX Tiger or higher
  • Windows XP or higher

And bestie, other operating systems will be supported if you send a patch 👑 that's the deal, that's the energy.

💀 Why doesn't Furl support chunked upload?

Okay so there are actual reasons why chunked POST/PUTs should not be used in general, and they're giving very much "trust me on this":

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 🫶

🧚 How do you build the response content as it arrives?

You can use IO::Callback for this purpose ✨

my $fh = IO::Callback->new(
    '<',
    sub {
        my $x = shift @data;
        $x ? "-$x" : undef;
    }
);
my ( $code, $msg, $headers, $content ) =
  $furl->put( "http://127.0.0.1:$port/", [ 'Content-Length' => $len ], $fh,
  );

🌈 How do you use gzip/deflate compressed communication?

Add an Accept-Encoding header to your request. Furl inflates response bodies transparently according to the Content-Encoding response header 💅 like it just handles it for you, iconic behaviour.

🎀 How do you use multipart/form-data?

You can use multipart/form-data with HTTP::Request::Common 🦋

use HTTP::Request::Common;

my $furl = Furl->new();
$req = POST 'http://www.perl.org/survey.cgi',
  Content_Type => 'form-data',
  Content      => [
    name   => 'Hiromu Tokunaga',
    email  => 'tokuhirom@example.com',
    gender => 'F',
    born   => '1978',
    init   => ["$ENV{HOME}/.profile"],
  ];
$furl->request($req);

Native multipart/form-data support for Furl is available if you can send a patch for me 🫶 (yes that's the vibe, patches welcome, always)

💜 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-Since" 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 host names 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.

use Net::DNS::Lite qw();

my $furl = Furl->new(
    timeout   => $my_timeout_in_seconds,
    inet_aton => sub { Net::DNS::Lite::inet_aton(@_) },
);

🔥 How can I replace Host header instead of hostname?

Furl::HTTP does not provide a way to replace the Host header because such a design leads to security issues 💀 not negotiable bestie.

If you want to send HTTP requests to a dedicated server (or a UNIX socket), you should use the get_address callback to designate the peer to which Furl should connect as sockaddr.

The example below sends all requests to 127.0.0.1:8080:

my $ua = Furl::HTTP->new(
    get_address => sub {
        my ($host, $port, $timeout) = @_;
        pack_sockaddr_in(8080, inet_aton("127.0.0.1"));
    },
);

my ($minor_version, $code, $msg, $headers, $body) = $furl->request(
    url => 'http://example.com/foo',
    method => 'GET'
);

🌟 TODO 🌟

  • AnyEvent::Furl?
  • ipv6 support
  • better docs for NO_PROXY

👑 OPTIONAL FEATURES 👑

🌸 Internationalized Domain Name (IDN)

This feature requires Net::IDN::Encode ✨

💅 SSL

This feature requires IO::Socket::SSL 🔒

🎀 Content-Encoding (deflate, gzip)

This feature requires Compress::Raw::Zlib 🦋

🛠️ DEVELOPMENT 🛠️

To setup your environment:

$ git clone http://github.com/tokuhirom/Furl.git
$ cd Furl

To get picohttpparser:

$ git submodule init
$ git submodule update

$ perl Makefile.PL
$ make
$ sudo make install

💖 HOW TO CONTRIBUTE

Please send the pull request via <http://github.com/tokuhirom/Furl/> 🫶 bestie we love a PR.

🌈 SEE ALSO 🌈

📜 LICENSE 📜

Copyright (C) Tokuhiro Matsuno.

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

And that's the whole page bestie 💖 this was Furl::HTTP(3pm) from the perl v5.40.1 toolchain, dated 2025-10-18 — go forth and make requests responsibly, mwah 💅✨🦋

📦 where this page comes from