Furl(3pm)

✨ NAME ✨

okay bestie, welcome to Furl — Lightning-fast URL fetcher 💅⚡

(this is the Furl(3pm) page, bestie, buckle up)

---

🌸 SYNOPSIS 🌸

use Furl;

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

my $res = $furl->get('http://example.com/');
die $res->status_line unless $res->is_success;
print $res->content;

my $res = $furl->post(
    'http://example.com/', # URL
    [...],                 # headers
    [ foo => 'bar' ],      # form data (HashRef/FileHandle are also okay)
);

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

---

🦋 DESCRIPTION 🦋

so. Furl is yet another HTTP client library. no fr, there's already LWP, which is the de facto standard HTTP client for Perl 5 — but it's too slow for some critical jobs, and too complex for weekend hacking. 😭

Furl literally just resolves these issues. periodt. Enjoy it! 💖

---

👑 INTERFACE 👑

💜 Class Methods 💜

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

Creates and returns a brand new Furl client with %args. Dies on errors (no cap, it will simply pass away 💀).

%args might be:

• agent :Str = "Furl/$VERSION" — the user agent string, defaults to that.
• timeout :Int = 10 — timeout in seconds, default 10.
• max_redirects :Int = 7 — how many redirects it'll chase, default 7.
• capture_request :Bool = false — if this parameter is true, Furl::HTTP captures raw request string. You can get it by $res->captured_req_headers and $res->captured_req_content ✨
• proxy :Str — the proxy.
• no_proxy :Str — the no-proxy.
• headers :ArrayRef — headers.
• cookie_jar :Object — (EXPERIMENTAL 🧪) An instance of HTTP::CookieJar or equivalent class that supports the add and cookie_header methods.

🌈 Instance Methods 🌈

$furl->request([$request,] %args) :Furl::Response

Sends an HTTP request to a specified URL and returns a instance of Furl::Response. slay.

%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" (pick one bestie, you can't have neither).
• 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 (iconic shortcut energy).
• headers :ArrayRef — HTTP request headers. e.g. headers => [ 'Accept-Encoding' => 'gzip' ].
• content : Str | ArrayRef[Str] | HashRef[Str] | FileHandle — Content to request.

If the number of arguments is an odd number, this method assumes that the first argument is an instance of HTTP::Request. Remaining arguments can be any of the previously describe values (but currently there's no way to really utilize them, so don't use it 🙈).

my $req = HTTP::Request->new(...);
my $res = $furl->request($req);

You can also specify an object other than HTTP::Request (e.g. Furl::Request), but the object must implement the following methods:

• uri
• method
• content
• headers

These must return the same type of values as their counterparts in HTTP::Request.

⚠️ You must encode all the queries or this method will die, saying "Wide character in ...". like, it will genuinely perish. encode ur stuff bestie.

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

$furl->env_proxy()

Loads proxy settings from $ENV{HTTP_PROXY} and $ENV{NO_PROXY}. 🍓

---

🎀 TIPS 🎀

🧚 IO::Socket::SSL preloading 🧚

Furl interprets the "timeout" argument as the maximum time the module is permitted to spend before returning an error.

The module also lazy-loads IO::Socket::SSL when an HTTPS request is being issued for the first time. Loading the module usually takes ~0.1 seconds.

The time spent for loading the SSL module may become an issue in case you want to impose a very small timeout value for connection establishment. In such case, users are advised to preload the SSL module explicitly. 👑

---

💖 FAQ 💖

Does Furl depends on XS modules?

No. Although some optional features require XS modules, basic features are available without XS modules.

Note that Furl requires HTTP::Parser::XS, which seems an XS module but includes a pure Perl backend, HTTP::Parser::XS::PP. plot twist ✨

I need more speed.

See Furl::HTTP, which provides the low level interface of Furl. It is faster than "Furl.pm" since Furl::HTTP does not create response objects. 🏎️

How do you use cookie_jar?

Furl does not directly support the cookie_jar option available in LWP. You can use HTTP::Cookies, HTTP::Request, HTTP::Response like following.

my $f = Furl->new();
my $cookies = HTTP::Cookies->new();
my $req = HTTP::Request->new(...);
$cookies->add_cookie_header($req);
my $res = $f->request($req)->as_http_response;
$res->request($req);
$cookies->extract_cookies($res);
# and use $res.

How do you limit the response content length?

You can limit the content length by callback function.

my $f = Furl->new();
my $content = '';
my $limit = 1_000_000;
my %special_headers = ('content-length' => undef);
my $res = $f->request(
    method          => 'GET',
    url             => $url,
    special_headers => \%special_headers,
    write_code      => sub {
        my ( $status, $msg, $headers, $buf ) = @_;
        if (($special_headers{'content-length'}||0) > $limit || length($content) > $limit) {
            die "over limit: $limit";
        }
        $content .= $buf;
    }
);

How do you display the progress bar?

my $bar = Term::ProgressBar->new({count => 1024, ETA => 'linear'});
$bar->minor(0);
$bar->max_update_rate(1);

my $f = Furl->new();
my $content = '';
my %special_headers = ('content-length' => undef);;
my $did_set_target = 0;
my $received_size = 0;
my $next_update  = 0;
$f->request(
    method          => 'GET',
    url             => $url,
    special_headers => \%special_headers,
    write_code      => sub {
        my ( $status, $msg, $headers, $buf ) = @_;
        unless ($did_set_target) {
            if ( my $cl = $special_headers{'content-length'} ) {
                $bar->target($cl);
                $did_set_target++;
            }
            else {
                $bar->target( $received_size + 2 * length($buf) );
            }
        }
        $received_size += length($buf);
        $content .= $buf;
        $next_update = $bar->update($received_size)
        if $received_size >= $next_update;
    }
);

HTTPS requests claims warnings!

When you make https requests, IO::Socket::SSL may complain about it like:

*******************************************************************
 Using the default of SSL_verify_mode of SSL_VERIFY_NONE for client
 is depreciated! Please set SSL_verify_mode to SSL_VERIFY_PEER
 together with SSL_ca_file|SSL_ca_path for verification.
 If you really don't want to verify the certificate and keep the
 connection open to Man-In-The-Middle attacks please set
 SSL_verify_mode explicitly to SSL_VERIFY_NONE in your application.
*******************************************************************

You should set "SSL_verify_mode" explicitly with Furl's "ssl_opts".

use IO::Socket::SSL;

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

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

---

🌟 AUTHOR 🌟

Tokuhiro Matsuno <tokuhirom@gmail.com>

Fuji, Goro (gfx)

---

🫶 THANKS TO 🫶

Kazuho Oku

mala

mattn

lestrrat

walf443

lestrrat

audreyt

(yes, lestrrat really is in there twice and honestly? icon behavior 💅)

---

🔥 SEE ALSO 🔥

LWP

IO::Socket::SSL

Furl::HTTP

Furl::Response

---

💀 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, no cap 💖 this was perl v5.40.1 energy, dated 2025-10-18, and it's literally the Furl(3pm) manual — go forth and fetch urls at lightning speed, mwah 💅✨🌈