# NAME

Retry::Policy - Simple retry wrapper with exponential backoff and jitter

# SYNOPSIS

    use Retry::Policy;

    my $p = Retry::Policy->new(
        max_attempts  => 5,
        base_delay_ms => 100,
        max_delay_ms  => 10_000,
        jitter        => 'full',
    );

    my $value = $p->run(sub {
        my ($attempt) = @_;
        die "transient\n" if $attempt < 3;
        return "ok";
    });

# DESCRIPTION

Small, dependency-light retry helper for backend and system code where
transient failures are expected.

# DESIGN NOTES

- Exponential backoff with a maximum cap is a common production default for transient failures.
- Full jitter helps avoid synchronized retries (thundering herd) across multiple workers or hosts.
- Defaults are intentionally conservative; callers should tune retry behavior per dependency (database, HTTP service, filesystem, etc.).
- Validation is strict: invalid configurations fail fast rather than producing undefined retry behavior.

# PRACTICAL USE CASES

## Retry a flaky HTTP call (transient network or service errors)

    use Retry::Policy;

    my $p = Retry::Policy->new(
        max_attempts  => 6,
        base_delay_ms => 200,
        max_delay_ms  => 5000,
        retry_on      => sub {
            my ($err) = @_;
            return ($err =~ /timeout|temporarily unavailable|connection reset/i) ? 1 : 0;
        },
    );

    my $body = $p->run(sub {
        # Replace this block with your HTTP client of choice
        die "timeout\n" if rand() < 0.2;
        return "ok";
    });

## Retry a database connection (DBI)

    use DBI;
    use Retry::Policy;

    my $p = Retry::Policy->new(
        max_attempts  => 5,
        base_delay_ms => 250,
        max_delay_ms  => 8000,
        retry_on      => sub {
            my ($err) = @_;
            return ($err =~ /server has gone away|lost connection|timeout/i) ? 1 : 0;
        },
    );

    my $dbh = $p->run(sub {
        my $dbh = DBI->connect($dsn, $user, $pass, { RaiseError => 1, PrintError => 0 });
        return $dbh;
    });

## Retry acquiring a lock or contended resource

    use Fcntl qw(:flock);
    use Retry::Policy;

    my $p = Retry::Policy->new(
        max_attempts  => 20,
        base_delay_ms => 50,
        max_delay_ms  => 1000,
        retry_on      => sub { 1 }, # lock contention is typically transient
    );

    $p->run(sub {
        open my $fh, ">>", "/tmp/my.lock" or die "open lock: $!\n";
        flock($fh, LOCK_EX | LOCK_NB) or die "lock busy\n";
        # work while lock held
        return 1;
    });

# LICENSE

Same terms as Perl itself.