livery_s3_credentials (livery_s3 v0.1.0)

View Source

AWS credential providers for the S3 client.

A provider says where credentials come from; prepare/1 turns it into a handle() stored on the client. One-shot sources (static, environment, shared config file) are resolved immediately into a {fixed, _} handle. Refreshing sources (EC2/ECS instance metadata, web-identity/STS, custom funs) become a {dynamic, _, _} handle whose credentials are fetched lazily and cached by livery_s3_credentials_store, which refreshes them before expires_at.

The credentials themselves (key, secret, optional session token) feed SigV4 and work against any S3-compatible store; the providers are environment-specific (env/file/static everywhere, IMDS on AWS, web-identity on AWS or MinIO STS).

Summary

Types

creds()
handle()
provider()

Functions

current/1

Return the current credentials for a handle, refreshing if needed.

fetch/1

Fetch fresh credentials for a refreshing provider (used by the cache). One-shot providers (static/env/file) resolve at prepare/1 and never reach here.

prepare/1

Turn a provider into a handle. One-shot providers resolve now (and may fail); refreshing providers return a lazy handle that fetches on first use.

Types

creds()

-type creds() ::
          #{access_key_id := binary(),
            secret_access_key := binary(),
            session_token => binary(),
            expires_at => integer()}.

handle()

-opaque handle()

provider()

-type provider() ::
          {static, binary(), binary(), binary() | undefined} |
          env |
          {file, binary()} |
          imds |
          {imds, map()} |
          {web_identity, map()} |
          default |
          fun(() -> {ok, creds()} | {error, term()}) |
          {module(), atom(), [term()]}.

Functions

current/1

-spec current(handle()) -> {ok, creds()} | {error, term()}.

Return the current credentials for a handle, refreshing if needed.

fetch/1

-spec fetch(provider()) -> {ok, creds()} | {error, term()}.

Fetch fresh credentials for a refreshing provider (used by the cache). One-shot providers (static/env/file) resolve at prepare/1 and never reach here.

prepare/1

-spec prepare(provider()) -> {ok, handle()} | {error, term()}.

Turn a provider into a handle. One-shot providers resolve now (and may fail); refreshing providers return a lazy handle that fetches on first use.