CPANPL...:Fetch(3pm)

💖 CPANPLUS::Internals::Fetch — the internals for fetching files 💖

okay bestie, so this is CPANPLUS::Internals::Fetch, a page from the User Contributed Perl Documentation collection (the 3pm girlies know), and it's literally all about the behind-the-scenes machinery that goes and grabs your files. not the glamorous part, but it's the part that makes everything else work, so. main character energy fr fr. 🎀

---

✨ SYNOPSIS ✨

here's the vibe check, verbatim:

my $output = $cb->_fetch(
                    module      => $modobj,
                    fetchdir    => '/path/to/save/to',
                    verbose     => BOOL,
                    force       => BOOL,
                );

$cb->_add_fail_host( host => 'foo.com' );
$cb->_host_ok(       host => 'foo.com' );

that's it. that's the whole teaser. now let's get into it 🦋

---

🌸 DESCRIPTION 🌸

CPANPLUS::Internals::Fetch fetches files from either ftp, http, file or rsync mirrors. yes, all four. she contains multitudes 💅

and the rough flow — the whole plot, condensed — is this:

$cb->_fetch
    Delegate to File::Fetch;

so she does the thinking, and File::Fetch does the actual grabbing. delegation queen. 👑

---

💜 METHODS 💜

$path = _fetch( module => $modobj, [fetchdir => '/path/to/save/to', fetch_from => 'scheme://path/to/fetch/from', verbose => BOOL, force => BOOL, prefer_bin => BOOL, ttl => $seconds] )

so _fetch goes and fetches files based on whatever info is living inside a module object. you always need a module object — that part is non-negotiable, no cap. and if you want a fake module object for a one-off fetch, go look at CPANPLUS::Module::Fake. she's right there, ready to be your stand-in 🫶

now the args, one by one:

• fetchdir — the place to save the file to. usually this info comes from your configuration, but you can override it expressly if you need to. your config, your rules, but also your call 💖
• fetch_from — lets you specify an URI to get this file from. if you don't specify one, your list of configured hosts will be probed to download the file from. so either you tell her exactly where to go, or she goes knocking on doors. either way, she's getting that file.
• force — forces a new download, even if the file already exists. yes bestie, even then. it's giving "I said what I said" 😤
• verbose — simply indicates whether or not to print extra messages. she can be chatty or she can be mysterious, your choice ✨
• prefer_bin — indicates whether you prefer the use of commandline programs over perl modules. defaults to your corresponding config setting.
• ttl (in seconds) — indicates how long a cached copy is valid for. if the fetch time of the local copy is within the ttl, the cached copy is returned. otherwise, the file is refetched. so like, if your snack is still fresh, you eat the snack. if it's expired, new snack. periodt 🍓

and then, _fetch figures out — based on the host list — what scheme to use, and from there she delegates to File::Fetch to do the actual fetching. the way she just knows which scheme. iykyk 🌈

Returns the path of the output file on success, false on failure. that's the receipt, bestie.

🚨 important side note: you can set a "blacklist" on certain methods in the config. simply add the identifying name of the method (ie, "lwp") to:

$conf->_set_fetch( blacklist => ['lwp'] );

and the "LWP" function will be skipped by File::Fetch. blocking someone without blocking them, iconic behavior 💀

---

_add_fail_host( host => $host_hashref )

mark a particular host as bad. 🚫 this makes CPANPLUS::Internals::Fetch skip it in fetches until this cache is flushed. she's holding a grudge, but like, a productive one. it's on the list and it's staying on the list 🙈

---

_host_ok( host => $host_hashref )

query the cache to see if this host is ok, or if it has been flagged as bad. basically a background check, but make it fetch-adjacent 🕵️♀️

Returns true if the host is ok, false otherwise. simple as that, no notes.

---

and that's the whole page, bestie!! 💅✨ this was perl v5.40.1, dated 2025-03-01, and honestly? she ate. go fetch something. 🎀💖🦋