/ 
Net-Blossom-Server-0.001000
/ Net::Blossom::Server::MirrorFetcher::HTTP

NAME

Net::Blossom::Server::MirrorFetcher::HTTP - Allowlist HTTP fetcher for Blossom mirrors

SYNOPSIS

use Net::Blossom::Server::MirrorFetcher::HTTP;

my $fetcher = Net::Blossom::Server::MirrorFetcher::HTTP->new(
    allowed_hosts => ['cdn.example.com'],
    max_bytes     => 50_000_000,
    timeout       => 5,
);

my $server = Net::Blossom::Server->new(
    storage        => $storage,
    mirror_fetcher => $fetcher,
);

DESCRIPTION

Net::Blossom::Server::MirrorFetcher::HTTP is a small allowlist-only fetcher for PUT /mirror. It is intentionally conservative: it does not provide public internet mirroring by default.

The fetcher validates the URL before making a request, requires the URL host to match one of the configured allowed_hosts, disables redirects in the default HTTP client, clears common proxy environment variables while fetching, and enforces a maximum response size while streaming into the supplied sink.

CONSTRUCTOR

new

my $fetcher = Net::Blossom::Server::MirrorFetcher::HTTP->new(%args);

Required arguments:

  • allowed_hosts

    Array reference of host names that may be mirrored. Matching is exact and case-insensitive. Wildcards are not supported. Only default ports for the URL scheme are allowed.

  • max_bytes

    Positive integer maximum response size in bytes.

Optional arguments:

  • timeout

    Positive integer request timeout in seconds. Defaults to 5.

  • user_agent

    Object with a request method compatible with HTTP::Tiny. This is mainly for tests or applications that need to supply their own HTTP transport.

    Custom user agents are trusted transport policy. They must not follow redirects unless each redirected URL is checked against the same allowlist, and they must not route requests through proxies or other transports that bypass the configured allowed_hosts policy.

Unknown arguments or invalid values croak.

ACCESSORS

allowed_hosts

Returns a copy array reference of allowed host names.

timeout

Returns the request timeout.

max_bytes

Returns the maximum response size.

user_agent

Returns the HTTP transport object.

METHODS

fetch_blob

my $metadata = $fetcher->fetch_blob($url, sink => $sink);

Fetches an allowed http or https URL, calls $sink->start(%metadata), streams scalar byte chunks through $sink->write($chunk), and returns a metadata hash reference with type and optional content_length. Missing Content-Type defaults to application/octet-stream. A body value is never returned.

The method throws Net::Blossom::Server::Error for expected HTTP-facing failures: 400 for malformed URLs, 403 for non-allowlisted hosts, 413 for blobs larger than max_bytes, and 502 for origin failures or unusable origin responses.