Control.Monad.Trans.AWS

A monad transformer built on top of functions from Network.AWS which encapsulates various common parameters, errors, and usage patterns.

Transformer

type AWS = AWST IO

A convenient alias for AWST IO.

data AWST m a

The transformer. This satisfies all of the constraints that the functions in this module require, such as providing MonadResource instances, as well as keeping track of the internal Env environment.

The MonadError instance for this transformer internally uses ExceptT to handle actions that result in an Error. For more information see sendCatch and paginateCatch.

Instances

MFunctor AWST

MMonad AWST

MonadTrans AWST

MonadTransControl AWST

MonadBaseControl b m => MonadBaseControl b (AWST m)

Monad m => MonadError Error (AWST m)

Monad m => MonadReader Env (AWST m)

MonadBase b m => MonadBase b (AWST m)

(Monad m, Functor m) => Alternative (AWST m)

Monad m => Monad (AWST m)

Functor m => Functor (AWST m)

Monad m => MonadPlus (AWST m)

(Monad m, Functor m) => Applicative (AWST m)

MonadThrow m => MonadThrow (AWST m)

MonadCatch m => MonadCatch (AWST m)

MonadIO m => MonadIO (AWST m)

(Applicative m, MonadIO m, MonadBase IO m, MonadThrow m) => MonadResource (AWST m)

data StT AWST = StTAWS {

• unStTAWS :: StT (ExceptT Error) (StT (ReaderT (Env, InternalState)) a)

}

data StM (AWST m) = StMAWST {

• unStMAWST :: ComposeSt AWST m a

}

type MonadAWS m = (MonadBaseControl IO m, MonadCatch m, MonadResource m, MonadError Error m, MonadReader Env m)

Provides an alias for shortening type signatures if preferred.

Note: requires the ConstraintKinds extension.

Running

runAWST :: MonadBaseControl IO m => Env -> AWST m a -> m (Either Error a)

Unwrap an AWST transformer, calling all of the registered ResourceT release actions.

Environment

data Env

The environment containing the parameters required to make AWS requests.

Instances

Monad m => MonadReader Env (AWST m)

envAuth :: Lens' Env Auth

envRegion :: Lens' Env Region

envManager :: Lens' Env Manager

envLogger :: Lens' Env Logger

scoped :: MonadReader Env m => (Env -> m a) -> m a

Pass the current environment to a function.

Creating the environment

data Credentials :: *

Determines how authentication information is retrieved.

Constructors

FromKeys AccessKey SecretKey

Explicit access and secret keys. Note: you can achieve the same result purely by using fromKeys.

FromSession AccessKey SecretKey SecurityToken

A session containing the access key, secret key, and a security token. Note: you can achieve the same result purely by using fromSession.

FromProfile Text

An IAM Profile name to lookup from the local EC2 instance-data.

FromEnv Text Text

Environment variables to lookup for the access and secret keys.

Discover

Attempt to read the default access and secret keys from the environment, falling back to the first available IAM profile if they are not set.

Note: This attempts to resolve http://instance-data rather than directly retrieving http://169.254.169.254 for IAM profile information to ensure the dns lookup terminates promptly if not running on EC2.

Instances

Eq Credentials

Show Credentials

ToText Credentials

newEnv :: (Functor m, MonadIO m) => Region -> Credentials -> Manager -> ExceptT String m Env

This creates a new environment without debug logging and uses getAuth to expand/discover the supplied Credentials.

Lenses such as envLogger can be used to modify the Env with a debug logger.

getEnv :: Region -> Credentials -> IO Env

Create a new environment without debug logging, creating a new Manager.

Any errors are thrown using error.

See: newEnv

Debugging

debug :: (MonadIO m, MonadReader Env m) => Text -> m ()

Use the logger from envLogger to log a debug message.

whenDebug :: MonadReader Env m => m () -> m ()

Perform a monadic action if envLogger is set to Debug.

Analogous to when.

Regionalisation

data Region :: *

The sum of available AWS regions.

Constructors

Ireland

Europe / eu-west-1

Frankfurt

Europe / eu-central-1

Tokyo

Asia Pacific / ap-northeast-1

Singapore

Asia Pacific / ap-southeast-1

Sydney

Asia Pacific / ap-southeast-2

Beijing

China / cn-north-1

NorthVirginia

US / us-east-1

NorthCalifornia

US / us-west-1

Oregon

US / us-west-2

GovCloud

AWS GovCloud / us-gov-west-1

GovCloudFIPS

AWS GovCloud (FIPS 140-2) S3 Only / fips-us-gov-west-1

SaoPaulo

South America / sa-east-1

Instances

Eq Region

Ord Region

Read Region

Show Region

Generic Region

Default Region

FromXML Region

ToXML Region

ToByteString Region

FromText Region

ToText Region

type Rep Region = D1 D1Region ((:+:) ((:+:) ((:+:) (C1 C1_0Region U1) ((:+:) (C1 C1_1Region U1) (C1 C1_2Region U1))) ((:+:) (C1 C1_3Region U1) ((:+:) (C1 C1_4Region U1) (C1 C1_5Region U1)))) ((:+:) ((:+:) (C1 C1_6Region U1) ((:+:) (C1 C1_7Region U1) (C1 C1_8Region U1))) ((:+:) (C1 C1_9Region U1) ((:+:) (C1 C1_10Region U1) (C1 C1_11Region U1)))))

within :: MonadReader Env m => Region -> m a -> m a

Scope a monadic action within the specific Region.

Errors

type Error = ServiceError String

The top-level error type.

hoistEither :: (MonadError Error m, AWSError e) => Either e a -> m a

Hoist an Either throwing the Left case, and returning the Right.

throwAWSError :: (MonadError Error m, AWSError e) => e -> m a

verify :: (AWSError e, MonadError Error m) => Prism' e a -> e -> m ()

verifyWith :: (AWSError e, MonadError Error m) => Prism' e a -> (a -> Bool) -> e -> m ()

Requests

Synchronous

send :: (MonadCatch m, MonadResource m, MonadReader Env m, MonadError Error m, AWSRequest a) => a -> m (Rs a)

Send a data type which is an instance of AWSRequest, returning it's associated Rs response type.

This will throw any HTTPException or AWSServiceError returned by the service using the MonadError instance. In the case of AWST this will cause the internal ExceptT to short-circuit and return an Error in the Left case as the result of the computation.

send_ :: (MonadCatch m, MonadResource m, MonadReader Env m, MonadError Error m, AWSRequest a) => a -> m ()

A variant of send which discards any successful response.

sendCatch :: (MonadCatch m, MonadResource m, MonadReader Env m, AWSRequest a) => a -> m (Response a)

Send a data type which is an instance of AWSRequest, returning either the associated Rs response type in the success case, or the related service's Er type in the error case.

This includes HTTPExceptions, serialisation errors, and any service errors returned as part of the Response.

Paginated

paginate :: (MonadCatch m, MonadResource m, MonadReader Env m, MonadError Error m, AWSPager a) => a -> Source m (Rs a)

Send a data type which is an instance of AWSPager and paginate while there are more results as defined by the related service operation.

Errors will be handle identically to send.

Note: The ResumableSource will close when there are no more results or the ResourceT computation is unwrapped. See: runResourceT for more information.

paginateCatch :: (MonadCatch m, MonadResource m, MonadReader Env m, AWSPager a) => a -> Source m (Response a)

Send a data type which is an instance of AWSPager and paginate over the associated Rs response type in the success case, or the related service's Er type in the error case.

Note: The ResumableSource will close when there are no more results or the ResourceT computation is unwrapped. See: runResourceT for more information.

Pre-signing URLs

presign

Arguments

:: (MonadIO m, MonadReader Env m, AWSRequest a, AWSPresigner (Sg (Sv a)))

=> a

Request to presign.

-> UTCTime

Signing time.

-> UTCTime

Expiry time.

-> m (Signed a (Sg (Sv a)))

Presign a URL with expiry to be used at a later time.

Note: Requires the service's signer to be an instance of AWSPresigner. Not all signing process support this.

Types

module Network.AWS.Types