=begin pod

=head1 NAME

AWS::RefreshableCredentials - Temporary credentials that refresh themselves

=head1 SYNOPSIS

    use AWS::Credentials;

    my $credentials = load-credentials();

    my $access-key  = $credentials.access-key;
    my $secret-key  = $credentials.secret-key;
    my $token       = $credentials.session-token;

=head1 DESCRIPTION

In AWS, many access keys are generated for temporary use. These credentials need
to be periodically renewed. This class provides tools for transparently managing
such credentials.

The API is identical to the one used in L<AWS::Credentials> (and this class
inherits the interface from that one). However, you should be aware that the
getter methods silently refresh the credentials on request when they are
nearly expired or have expired already.

B<NOTE:> Credential refresh is not quite implemented, so the presence of this
class is more of a wish than a feature.

=head1 ATTRIBUTES

=head2 access-key

=head2 secret-key

=head2 token

These attributes are all inherited from L<AWS::Credentials>.

=head2 expiry-time

This is a L<DateTime> that indicates the time stamp after which the associated
credentials will be valid no longer.

=head1 METHODS

=head2 refresh-needed

    method refresh-needed(Duration :$refresh-in?) returns Bool

Returns C<True> if the C<expiry-date> is within C<$refresh-in> seconds.

=head2 refresh

    method refresh()

Performs a refresh on the credentials attached if a refresh is needed. Calling
this method directly is completely superfluous. It will be called automatically
whenever one of the other methods describing the credentials are called.

=end pod
