Network.AWS

The core module for making requests to the various AWS services.

Requests

Synchronous

send :: (MonadCatch m, MonadResource m, AWSRequest a) => Env -> 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.

Note: Requests will be retried depending upon each service's respective strategy. This can be overriden using envRetry. Requests which contain streaming request bodies (such as S3's PutObject) are never considered for retries.

Paginated

paginate :: (MonadCatch m, MonadResource m, AWSPager a) => Env -> 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.

Eventual consistency

await :: (MonadCatch m, MonadResource m, AWSRequest a) => Env -> Wait a -> a -> m (Response a)

Poll the API until a predefined condition is fulfilled using the supplied Wait specification from the respective service.

The response will be either the first error returned that is not handled by the specification, or the successful response from the await request.

Note: You can find any available Wait specifications under then Network.AWS.ServiceName.Waiters namespace for supported services.

Pre-signing URLs

presign

Arguments

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

=> Env

-> a

Request to presign.

-> UTCTime

Signing time.

-> Integer

Expiry time in seconds.

-> m Request

Presign an HTTP request that expires at the specified amount of time in the future.

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

presignURL

Arguments

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

=> Env

-> a

Request to presign.

-> UTCTime

Signing time.

-> Integer

Expiry time in seconds.

-> m ByteString

Presign a URL that expires at the specified amount of time in the future.

See: presign

Environment

data Env

The environment containing the parameters required to make AWS requests.

Instances

ToBuilder Env

Monad m => MonadReader Env (AWST m)

Lenses

envRegion :: Lens' Env Region

The current region.

envLogger :: Lens' Env Logger

The function used to output log messages.

envRetryCheck :: Lens' Env (Int -> HttpException -> IO Bool)

The function used to determine if an HttpException should be retried.

envRetryPolicy :: Lens' Env (Maybe RetryPolicy)

The RetryPolicy used to determine backoffon and retry delaygrowth.

envManager :: Lens' Env Manager

The Manager used to create and manage open HTTP connections.

envAuth :: Lens' Env Auth

The credentials used to sign requests for authentication with AWS.

Creating the environment

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 in the specified Region with silent log output and a new Manager.

Any errors are thrown using error.

See: newEnv for safe Env instantiation.

Specifying credentials

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 using fromKeys without having to use the impure getAuth.

FromSession AccessKey SecretKey SecurityToken

A session containing the access key, secret key, and a security token. Note: you can achieve the same result purely using fromSession without having to use the impure getAuth.

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

ToBuilder Credentials

fromKeys :: AccessKey -> SecretKey -> Auth

Explicit access and secret keys.

fromSession :: AccessKey -> SecretKey -> SecurityToken -> Auth

A session containing the access key, secret key, and a security token.

getAuth :: (Functor m, MonadIO m) => Manager -> Credentials -> ExceptT String m Auth

Retrieve authentication information using the specified Credentials style.

accessKey

Arguments

:: Text

AWS_ACCESS_KEY

Default access key environment variable.

secretKey

Arguments

:: Text

AWS_SECRET_KEY

Default secret key environment variable.

Logging

newLogger :: MonadIO m => LogLevel -> Handle -> m Logger

This is a primitive logger which can be used to log messages to a Handle. A more sophisticated logging library such as tinylog or FastLogger should be used in production code.

Streaming body helpers

sourceBody :: Digest SHA256 -> Int64 -> Source (ResourceT IO) ByteString -> RqBody

Unsafely construct a RqBody from a source, manually specifying the SHA256 hash and file size.

sourceHandle :: Digest SHA256 -> Int64 -> Handle -> RqBody

Unsafely construct a RqBody from a Handle, manually specifying the SHA256 hash and file size.

sourceFile :: Digest SHA256 -> Int64 -> FilePath -> RqBody

Unsafely construct a RqBody from a FilePath, manually specifying the SHA256 hash and file size.

sourceFileIO :: MonadIO m => FilePath -> m RqBody

Safely construct a RqBody from a FilePath, calculating the SHA256 hash and file size.

Note: While this function will perform in constant space, it will read the entirety of the file contents _twice_. Firstly to calculate the SHA256 and lastly to stream the contents to the socket during sending.

Types

module Network.AWS.Types

module Network.AWS.Error