/ 
WebService-Litportnet-FreeProxy-0.001
/ WebService::Litportnet::FreeProxy

NAME

WebService::Litportnet::FreeProxy - Client for Litport's free proxy snapshot API

SYNOPSIS

use WebService::Litportnet::FreeProxy;

my $client = WebService::Litportnet::FreeProxy->new;
my $proxies = $client->pick_best(5, {
    protocol        => 'socks5',
    country         => 'us',
    max_latency_ms  => 500,
    min_uptime_7d   => 90,
    min_checks_7d   => 50,
    checked_within_min => 30,
});
print "$_->{url}\n" for @$proxies;

DESCRIPTION

WebService::Litportnet::FreeProxy is a dependency-free (core-modules-only) Perl client for Litport's API snapshot of verified HTTP, SOCKS4, and SOCKS5 proxies. It fetches a JSON snapshot, validates its envelope and rows, normalizes each record into a plain hash reference, applies caller-supplied filters, and returns the results sorted by freshness-aware uptime and latency.

The client only retrieves proxy records; it does not route traffic through any proxy. Free proxies are for testing only. Never send credentials, cookies, payment data, or other private data through them.

The client is built on core modules, but IO::Socket::SSL and Net::SSLeay are required runtime prerequisites: the default snapshot endpoint is https, and HTTP::Tiny cannot negotiate TLS without them. Pass a plain http api_url, or your own transport callback, if you need to avoid them.

CONSTRUCTOR

new

my $client = WebService::Litportnet::FreeProxy->new(
    api_url   => $url,      # default https://litport.net/api/free-proxy/snapshot?checkedWithinMin=1440
    timeout   => 10,        # seconds, must be a positive finite number
    transport => sub { my ($url, $timeout) = @_; return ($status, $headers_hashref, $body_string) },
    now       => sub { time },
);

transport and now are optional and mainly intended for deterministic tests. When transport is omitted, requests are made with HTTP::Tiny. When now is omitted, it defaults to sub { time } (current epoch seconds, UTC).

Throws WebService::Litportnet::FreeProxy::Error::FilterValidationError if timeout is not a positive finite number.

METHODS

get_proxies

my $proxies = $client->get_proxies(\%filters);

Fetches the snapshot, validates it, normalizes and filters the rows, and returns an array reference of normalized proxy hash references (see "FILTERS" for the record and filter shapes). %filters is optional.

pick_best

my $proxies = $client->pick_best($n, \%filters);

Equivalent to calling get_proxies and returning at most the first $n results. $n must be a non-negative integer.

FILTERS

All filter keys are optional and use snake_case:

  • protocol - one of http, socks4, socks5

  • country - a two-letter ASCII country code, case-insensitive (normalized to lowercase)

  • anonymity - one of transparent, anonymous, elite, unknown

  • https - boolean or undef; accepts Perl-style 0/1 and JSON::PP::Boolean values

  • max_latency_ms - non-negative integer

  • min_uptime_7d - non-negative integer

  • min_checks_7d - non-negative integer

  • checked_within_min - integer from 1 to 1440, default 30

  • limit - non-negative integer

Unknown filter keys raise WebService::Litportnet::FreeProxy::Error::FilterValidationError.

Each normalized proxy record is a hash reference with the keys: protocol, ip, port, url, country, region, city, timezone, asn, asn_org, anonymity, https, latency_ms, latency_median_ms, uptime_24h, uptime_7d, checks_7d, exit_ip, sources_count, first_seen, last_checked. uptime_7d is undef whenever a record has fewer than 50 seven-day checks. Results are sorted with defined uptime_7d first (descending), then defined latency_ms first (ascending), then ascending url.

ERRORS

All errors are blessed objects rooted at WebService::Litportnet::FreeProxy::Error, which overloads stringification to its message, so both ref($@) and $@->isa(...) work as expected in eval/$@ or Try::Tiny-style handling:

  • WebService::Litportnet::FreeProxy::Error - base class

  • WebService::Litportnet::FreeProxy::Error::TimeoutError - the request timed out

  • WebService::Litportnet::FreeProxy::Error::HttpError - the HTTP status was outside 200..299; carries a status accessor

  • WebService::Litportnet::FreeProxy::Error::SnapshotValidationError - the snapshot envelope or a row failed validation

  • WebService::Litportnet::FreeProxy::Error::SnapshotTruncatedError - the snapshot reported truncated => true

  • WebService::Litportnet::FreeProxy::Error::FilterValidationError - the supplied filters (or constructor arguments) were invalid

RESOURCES

This client only retrieves proxy records over the snapshot API; it does not route any traffic through a proxy. Free proxies are for testing only - never send credentials, cookies, payment data, or other private data through them.

AUTHOR

Litport <litport@cpan.org>

LICENSE

This software is copyright (c) 2026 by Litport. It is released under the MIT license. See the LICENSE file included with this distribution for the full text.