package bearer

Import Path
	github.com/aws/smithy-go/auth/bearer (on go.dev)

Dependency Relation
	imports 8 packages, and imported by one package

Involved Source Files

	   #d docs.go
		Package bearer provides middleware and utilities for authenticating API
		operation calls with a Bearer Token.

	      middleware.go
	      token.go
	      token_cache.go
Package-Level Type Names (total 10, all are exported)

	/* sort exporteds by: alphabet | popularity */
	 type AuthenticationMiddleware (struct)
		AuthenticationMiddleware provides the Finalize middleware step for signing
		an request message with a bearer token.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			signer Signer
			tokenProvider TokenProvider
		Methods (total 2, both are exported)
			(*AuthenticationMiddleware) HandleFinalize(ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler) (out middleware.FinalizeOutput, metadata middleware.Metadata, err error)
				HandleFinalize implements the FinalizeMiddleware interface in order to
				update the request with bearer token authentication.

			(*AuthenticationMiddleware) ID() string
				ID returns the resolver identifier

		Implements (at least 2, in which 1 are exported)
			*AuthenticationMiddleware : github.com/aws/smithy-go/middleware.FinalizeMiddleware
			/* at least one unexported ... *//* at least one unexported: */
			*AuthenticationMiddleware : github.com/aws/smithy-go/middleware.ider
		As Outputs Of (at least one exported)
			func NewAuthenticationMiddleware(signer Signer, tokenProvider TokenProvider) *AuthenticationMiddleware

	 type Message (interface)
		Message is the middleware stack's request transport message value.

		As Outputs Of (at least 2, both are exported)
			func Signer.SignWithBearerToken(context.Context, Token, Message) (Message, error)
			func SignHTTPSMessage.SignWithBearerToken(ctx context.Context, token Token, message Message) (Message, error)
		As Inputs Of (at least 2, both are exported)
			func Signer.SignWithBearerToken(context.Context, Token, Message) (Message, error)
			func SignHTTPSMessage.SignWithBearerToken(ctx context.Context, token Token, message Message) (Message, error)

	 type Signer (interface)
		Signer provides an interface for implementations to decorate a request
		message with a bearer token. The signer is responsible for validating the
		message type is compatible with the signer.

		Methods (only one, which is exported)
			( Signer) SignWithBearerToken(context.Context, Token, Message) (Message, error)
		Implemented By (at least one exported)
			 SignHTTPSMessage
		As Inputs Of (at least 2, both are exported)
			func AddAuthenticationMiddleware(s *middleware.Stack, signer Signer, tokenProvider TokenProvider) error
			func NewAuthenticationMiddleware(signer Signer, tokenProvider TokenProvider) *AuthenticationMiddleware

	 type SignHTTPSMessage (struct)
		SignHTTPSMessage provides a bearer token authentication implementation that
		will sign the message with the provided bearer token.

		Will fail if the message is not a smithy-go HTTP request or the request is
		not HTTPS.

		Methods (only one, which is exported)
			( SignHTTPSMessage) SignWithBearerToken(ctx context.Context, token Token, message Message) (Message, error)
				SignWithBearerToken returns a copy of the HTTP request with the bearer token
				added via the "Authorization" header, per RFC 6750, https://datatracker.ietf.org/doc/html/rfc6750.

				Returns an error if the request's URL scheme is not HTTPS, or the request
				message is not an smithy-go HTTP Request pointer type.

		Implements (at least one exported)
			 SignHTTPSMessage : Signer
		As Outputs Of (at least one exported)
			func NewSignHTTPSMessage() *SignHTTPSMessage

	 type StaticTokenProvider (struct)
		StaticTokenProvider provides a utility for wrapping a static bearer token
		value within an implementation of a token provider.

		Fields (only one, which is exported)
			Token Token
		Methods (only one, which is exported)
			( StaticTokenProvider) RetrieveBearerToken(context.Context) (Token, error)
				RetrieveBearerToken returns the static token specified.

		Implements (at least one exported)
			 StaticTokenProvider : TokenProvider

	 type Token (struct)
		Token provides a type wrapping a bearer token and expiration metadata.

		Fields (total 3, all are exported)
			CanExpire bool
			Expires time.Time
			Value string
		Methods (only one, which is exported)
			( Token) Expired(now time.Time) bool
				Expired returns if the token's Expires time is before or equal to the time
				provided. If CanExpires is false, Expired will always return false.

		As Outputs Of (at least 6, in which 4 are exported)
			func StaticTokenProvider.RetrieveBearerToken(context.Context) (Token, error)
			func (*TokenCache).RetrieveBearerToken(ctx context.Context) (Token, error)
			func TokenProvider.RetrieveBearerToken(context.Context) (Token, error)
			func TokenProviderFunc.RetrieveBearerToken(ctx context.Context) (Token, error)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func (*TokenCache).getCachedToken() (Token, bool)
			func (*TokenCache).refreshBearerToken(ctx context.Context) (Token, error)
		As Inputs Of (at least 2, both are exported)
			func Signer.SignWithBearerToken(context.Context, Token, Message) (Message, error)
			func SignHTTPSMessage.SignWithBearerToken(ctx context.Context, token Token, message Message) (Message, error)

	 type TokenCache (struct)
		TokenCache provides an utility to cache Bearer Authentication tokens from a
		wrapped TokenProvider. The TokenCache can be has options to configure the
		cache's early and asynchronous refresh of the token.

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			cachedToken atomic.Value
			lastRefreshAttemptTime atomic.Value
			options TokenCacheOptions
			provider TokenProvider
			sfGroup singleflight.Group
		Methods (total 5, in which 1 are exported)
			(*TokenCache) RetrieveBearerToken(ctx context.Context) (Token, error)
				RetrieveBearerToken returns the token if it could be obtained, or error if a
				valid token could not be retrieved.

				The passed in Context's cancel/deadline/timeout will impacting only this
				individual retrieve call and not any other already queued up calls. This
				means underlying provider's RetrieveBearerToken calls could block for ever,
				and not be canceled with the Context. Set RetrieveBearerTokenTimeout to
				provide a timeout, preventing the underlying TokenProvider blocking forever.

				By default, if the passed in Context is canceled, all of its values will be
				considered expired. The wrapped TokenProvider will not be able to lookup the
				values from the Context once it is expired. This is done to protect against
				expired values no longer being valid. To disable this behavior, use
				smithy-go's context.WithPreserveExpiredValues to add a value to the Context
				before calling RetrieveBearerToken to enable support for expired values.

				Without RetrieveBearerTokenTimeout there is the potential for a underlying
				Provider's RetrieveBearerToken call to sit forever. Blocking in subsequent
				attempts at refreshing the token.

			/* 4 unexporteds ... *//* 4 unexporteds: */
			(*TokenCache) getCachedToken() (Token, bool)
				getCachedToken returns the currently cached token and true if found. Returns
				false if no token is cached.

			(*TokenCache) refreshBearerToken(ctx context.Context) (Token, error)
			(*TokenCache) singleRetrieve(ctx context.Context) (interface{}, error)
			(*TokenCache) tryAsyncRefresh(ctx context.Context)
				tryAsyncRefresh attempts to asynchronously refresh the token returning the
				already cached token. If it AsyncRefreshMinimumDelay option is not zero, and
				the duration since the last refresh is less than that value, nothing will be
				done.

		Implements (at least one exported)
			*TokenCache : TokenProvider
		As Outputs Of (at least one exported)
			func NewTokenCache(provider TokenProvider, optFns ...func(*TokenCacheOptions)) *TokenCache

	 type TokenCacheOptions (struct)
		TokenCacheOptions provides a set of optional configuration options for the
		TokenCache TokenProvider.

		Fields (total 4, all are exported)
			AsyncRefreshMinimumDelay time.Duration
				The minimum duration between asynchronous refresh attempts. If the next
				asynchronous recent refresh attempt was within the minimum delay
				duration, the call to retrieve will return the current cached token, if
				not expired.

				The asynchronous retrieve is deduplicated across multiple calls when
				RetrieveBearerToken is called. The asynchronous retrieve is not a
				periodic task. It is only performed when the token has not yet expired,
				and the current item is within the RefreshBeforeExpires window, and the
				TokenCache's RetrieveBearerToken method is called.

				If 0, (default) there will be no minimum delay between asynchronous
				refresh attempts.

				If DisableAsyncRefresh is true, this option is ignored.

			DisableAsyncRefresh bool
				Sets if the TokenCache will attempt to refresh the token in the
				background asynchronously instead of blocking for credentials to be
				refreshed. If disabled token refresh will be blocking.

				The first call to RetrieveBearerToken will always be blocking, because
				there is no cached token.

			RefreshBeforeExpires time.Duration
				The duration before the token will expire when the credentials will be
				refreshed. If DisableAsyncRefresh is true, the RetrieveBearerToken calls
				will be blocking.

				Asynchronous refreshes are deduplicated, and only one will be in-flight
				at a time. If the token expires while an asynchronous refresh is in
				flight, the next call to RetrieveBearerToken will block on that refresh
				to return.

			RetrieveBearerTokenTimeout time.Duration
				The timeout the underlying TokenProvider's RetrieveBearerToken call must
				return within, or will be canceled. Defaults to 0, no timeout.

				If 0 timeout, its possible for the underlying tokenProvider's
				RetrieveBearerToken call to block forever. Preventing subsequent
				TokenCache attempts to refresh the token.

				If this timeout is reached all pending deduplicated calls to
				TokenCache RetrieveBearerToken will fail with an error.


	 type TokenProvider (interface)
		TokenProvider provides interface for retrieving bearer tokens.

		Methods (only one, which is exported)
			( TokenProvider) RetrieveBearerToken(context.Context) (Token, error)
		Implemented By (at least 3, all are exported)
			 StaticTokenProvider
			*TokenCache
			 TokenProviderFunc
		As Inputs Of (at least 3, all are exported)
			func AddAuthenticationMiddleware(s *middleware.Stack, signer Signer, tokenProvider TokenProvider) error
			func NewAuthenticationMiddleware(signer Signer, tokenProvider TokenProvider) *AuthenticationMiddleware
			func NewTokenCache(provider TokenProvider, optFns ...func(*TokenCacheOptions)) *TokenCache

	 type TokenProviderFunc (func)
		TokenProviderFunc provides a helper utility to wrap a function as a type
		that implements the TokenProvider interface.

		Methods (only one, which is exported)
			( TokenProviderFunc) RetrieveBearerToken(ctx context.Context) (Token, error)
				RetrieveBearerToken calls the wrapped function, returning the Token or
				error.

		Implements (at least one exported)
			 TokenProviderFunc : TokenProvider


Package-Level Functions (total 4, all are exported)

	 func AddAuthenticationMiddleware(s *middleware.Stack, signer Signer, tokenProvider TokenProvider) error
		AddAuthenticationMiddleware helper adds the AuthenticationMiddleware to the
		middleware Stack in the Finalize step with the options provided.

	 func NewAuthenticationMiddleware(signer Signer, tokenProvider TokenProvider) *AuthenticationMiddleware
		NewAuthenticationMiddleware returns an initialized AuthenticationMiddleware.

	 func NewSignHTTPSMessage() *SignHTTPSMessage
		NewSignHTTPSMessage returns an initialized signer for HTTP messages.

	 func NewTokenCache(provider TokenProvider, optFns ...func(*TokenCacheOptions)) *TokenCache
		NewTokenCache returns a initialized TokenCache that implements the
		TokenProvider interface. Wrapping the provider passed in. Also taking a set
		of optional functional option parameters to configure the token cache.


Package-Level Variables (only one, which is unexported)

	/* one unexported ... *//* one unexported: */
	  var timeNow func() time.Time
		package variable that can be override in unit tests.


Package-Level Constants (only one, which is unexported)

	/* one unexported ... *//* one unexported: */
	const authenticationMiddlewareID = "BearerTokenAuthentication"

The pages are generated with Golds v0.4.9. (GOOS=linux GOARCH=amd64)