This module provides a simple AWS monad and a set of operations which can be performed against remote Amazon Web Services APIs, for use with the types supplied by the various amazonka-* libraries.

A MonadAWS typeclass is used as a function constraint to provide automatic lifting of functions when embedding AWS as a layer inside your own application stack.

Control.Monad.Trans.AWS contains the underlying AWST transformer.

The key functions dealing with the request/response lifecycle are:

• send
• paginate
• await

These functions have constraints that types from the amazonka-* libraries satisfy. To utilise these, you will need to specify what Region you wish to operate in and your Amazon credentials for AuthN/AuthZ purposes.

Credentials can be supplied in a number of ways. Either via explicit keys, via session profiles, or have Amazonka retrieve the credentials from an underlying IAM Role/Profile.

As a basic example, you might wish to store an object in an S3 bucket using amazonka-s3:

import Control.Lens
import Network.AWS
import Network.AWS.S3
import System.IO

example :: IO PutObjectResponse
example = do
    -- A new Logger to replace the default noop logger is created, with the logger
    -- set to print debug information and errors to stdout:
    lgr  <- newLogger Debug stdout

    -- To specify configuration preferences, newEnv is used to create a new
    -- configuration environment. The Credentials parameter is used to specify
    -- mechanism for supplying or retrieving AuthN/AuthZ information.
    -- In this case Discover will cause the library to try a number of options such
    -- as default environment variables, or an instance's IAM Profile and identity document:
    env  <- newEnv Discover

    -- The payload (and hash) for the S3 object is retrieved from a FilePath,
    -- either hashedFile or chunkedFile can be used, with the latter ensuring
    -- the contents of the file is enumerated exactly once, during send:
    body <- chunkedFile defaultChunkSize "local/path/to/object-payload"

    -- We now run the AWS computation with the overriden logger, performing the
    -- PutObject request. envRegion or within can be used to set the
    -- remote AWS Region:
    runResourceT $ runAWS (env & envLogger .~ lgr) $
        within Frankfurt $
            send (putObject "bucket-name" "object-key" body)

AuthN/AuthZ information is handled similarly to other AWS SDKs. You can read some of the options available here.

When running on an EC2 instance and using FromProfile or Discover, a thread is forked which transparently handles the expiry and subsequent refresh of IAM profile information. See fromProfileName for more information.

To send a request you need to create a value of the desired operation type using the relevant constructor, as well as any further modifications of default/optional parameters using the appropriate lenses. This value can then be sent using send or paginate and the library will take care of serialisation/authentication and so forth.

The default Service configuration for a request contains retry configuration that is used to determine if a request can safely be retried and what kind of back off/on strategy should be used. (Usually exponential.) Typically services define retry strategies that handle throttling, general server errors and transport errors. Streaming requests are never retried.

Some AWS operations return results that are incomplete and require subsequent requests in order to obtain the entire result set. The process of sending subsequent requests to continue where a previous request left off is called pagination. For example, the ListObjects operation of Amazon S3 returns up to 1000 objects at a time, and you must send subsequent requests with the appropriate Marker in order to retrieve the next page of results.

Operations that have an AWSPager instance can transparently perform subsequent requests, correctly setting Markers and other request facets to iterate through the entire result set of a truncated API operation. Operations which support this have an additional note in the documentation.

Many operations have the ability to filter results on the server side. See the individual operation parameters for details.

Waiters poll by repeatedly sending a request until some remote success condition configured by the Wait specification is fulfilled. The Wait specification determines how many attempts should be made, in addition to delay and retry strategies. Error conditions that are not handled by the Wait configuration will be thrown, or the first successful response that fulfills the success condition will be returned.

Wait specifications can be found under the Network.AWS.{ServiceName}.Waiters namespace for services which support await.

When a request is sent, various values such as the endpoint, retry strategy, timeout and error handlers are taken from the associated Service for a request. For example, DynamoDB will use the dynamoDB configuration when sending PutItem, Query and all other operations.

You can modify a specific Service's default configuration by using configure or reconfigure. To modify all configurations simultaneously, see override.

An example of how you might alter default configuration using these mechanisms is demonstrated below. Firstly, the default dynamoDB service is configured to use non-SSL localhost as the endpoint:

let dynamo :: Service
    dynamo = setEndpoint False "localhost" 8000 dynamoDB

The updated configuration is then passed to the Env during setup:

e <- newEnv Frankfurt Discover <&> configure dynamo
runAWS e $ do
    -- This S3 operation will communicate with remote AWS APIs.
    x <- send listBuckets

    -- DynamoDB operations will communicate with localhost:8000.
    y <- send listTables

    -- Any operations for services other than DynamoDB, are not affected.
    ...

You can also scope the Endpoint modifications (or any other Service configuration) to specific actions:

e <- newEnv Ireland Discover
runAWS e $ do
    -- Service operations here will communicate with AWS, even DynamoDB.
    x <- send listTables

    reconfigure dynamo $ do
       -- In here, DynamoDB operations will communicate with localhost:8000,
       -- with operations for services not being affected.
       ...

Functions such as within, once, and timeout likewise modify the underlying configuration for all service requests within their respective scope.

Streaming comes in two flavours. HashedBody represents a request that requires a precomputed SHA256 hash, or a ChunkedBody type for those services that can perform incremental signing and do not require the entire payload to be hashed (such as S3). The type signatures for request smart constructors advertise which respective body type is required, denoting the underlying signing capabilities.

ToHashedBody and ToBody typeclass instances are available to construct the streaming bodies, automatically calculating any hash or size as needed for types such as Text, ByteString, or Aeson's Value type. To read files and other IO primitives, functions such as hashedFile, chunkedFile, or hashedBody should be used.

For responses that contain streaming bodies (such as GetObject), you can use sinkBody to connect the response body to a conduit compatible sink.

Presigning requires the Service signer to be an instance of AWSPresigner. Not all signing algorithms support this.

Metadata can be retrieved from the underlying host assuming that you're running the code on an EC2 instance or have a compatible instance-data endpoint available.

Requests can be sent asynchronously, but due to guarantees about resource closure require the use of lifted-async.

The following example demonstrates retrieving two objects from S3 concurrently:

import Control.Concurrent.Async.Lifted
import Control.Lens
import Control.Monad.Trans.AWS
import Network.AWS.S3

do x   <- async . send $ getObject "bucket" "prefix/object-foo"
   y   <- async . send $ getObject "bucket" "prefix/object-bar"
   foo <- wait x
   bar <- wait y
   ...

See: Control.Concurrent.Async.Lifted

Errors are thrown by the library using MonadThrow (unless Control.Monad.Error.AWS is used). Sub-errors of the canonical Error type can be caught using trying or catching and the appropriate AsError Prism:

trying _Error          (send $ ListObjects "bucket-name") :: Either Error          ListObjectsResponse
trying _TransportError (send $ ListObjects "bucket-name") :: Either HttpException  ListObjectsResponse
trying _SerializeError (send $ ListObjects "bucket-name") :: Either SerializeError ListObjectsResponse
trying _ServiceError   (send $ ListObjects "bucket-name") :: Either ServiceError   ListObjectsResponse

Many of the individual amazonka-* libraries export compatible Getters for matching service specific error codes and messages in the style above. See the Error Matchers heading in each respective library for details.

The exposed logging interface is a primitive Logger function which gets threaded through service calls and serialisation routines. This allows the library to output useful information and diagnostics.

The newLogger function can be used to construct a simple logger which writes output to a Handle, but in most production code you should probably consider using a more robust logging library such as tiny-log or fast-logger.