Copyright | (c) 2013-2021 Brendan Hay |
---|---|
License | Mozilla Public License, v. 2.0. |
Maintainer | Brendan Hay <brendan.g.hay+amazonka@gmail.com> |
Stability | provisional |
Portability | non-portable (GHC extensions) |
Safe Haskell | None |
Synopsis
- data Env' withAuth = Env {
- _envRegion :: Region
- _envLogger :: Logger
- _envRetryCheck :: Int -> HttpException -> Bool
- _envOverride :: Dual (Endo Service)
- _envManager :: Manager
- _envAuth :: withAuth Auth
- type Env = Env' Identity
- type EnvNoAuth = Env' Proxy
- newEnv :: MonadIO m => Credentials -> m Env
- newEnvNoAuth :: MonadIO m => m EnvNoAuth
- newEnvWith :: Manager -> EnvNoAuth
- envAuthMaybe :: Foldable withAuth => Env' withAuth -> Maybe Auth
- authenticate :: (MonadIO m, Foldable withAuth) => Credentials -> Env' withAuth -> m Env
- override :: (Service -> Service) -> Env -> Env
- configure :: Service -> Env -> Env
- within :: Region -> Env -> Env
- once :: Env -> Env
- timeout :: Seconds -> Env -> Env
- envRegion :: Lens' (Env' withAuth) Region
- envLogger :: Lens' (Env' withAuth) Logger
- envRetryCheck :: Lens' (Env' withAuth) (Int -> HttpException -> Bool)
- envOverride :: Lens' (Env' withAuth) (Dual (Endo Service))
- envManager :: Lens' (Env' withAuth) Manager
- envAuth :: Lens (Env' withAuth) (Env' withAuth') (withAuth Auth) (withAuth' Auth)
- runResourceT :: MonadUnliftIO m => ResourceT m a -> m a
- newtype AccessKey = AccessKey ByteString
- newtype SecretKey = SecretKey ByteString
- newtype SessionToken = SessionToken ByteString
- data Credentials
- newtype Region where
- Region' {
- fromRegion :: Text
- pattern Mumbai :: Region
- pattern Sydney :: Region
- pattern Singapore :: Region
- pattern Osaka :: Region
- pattern Seoul :: Region
- pattern Tokyo :: Region
- pattern HongKong :: Region
- pattern Ningxia :: Region
- pattern Beijing :: Region
- pattern CapeTown :: Region
- pattern Bahrain :: Region
- pattern Stockholm :: Region
- pattern Paris :: Region
- pattern Milan :: Region
- pattern London :: Region
- pattern Ireland :: Region
- pattern Frankfurt :: Region
- pattern SaoPaulo :: Region
- pattern Montreal :: Region
- pattern GovCloudEast :: Region
- pattern GovCloudWest :: Region
- pattern Oregon :: Region
- pattern NorthCalifornia :: Region
- pattern Ohio :: Region
- pattern NorthVirginia :: Region
- Region' {
- data Endpoint = Endpoint {}
- setEndpoint :: Bool -> ByteString -> Int -> Service -> Service
- send :: (MonadResource m, AWSRequest a) => Env -> a -> m (AWSResponse a)
- sendEither :: (MonadResource m, AWSRequest a) => Env -> a -> m (Either Error (AWSResponse a))
- paginate :: (MonadResource m, AWSPager a) => Env -> a -> ConduitM () (AWSResponse a) m ()
- paginateEither :: (MonadResource m, AWSPager a) => Env -> a -> ConduitM () (AWSResponse a) m (Either Error ())
- await :: (MonadResource m, AWSRequest a) => Env -> Wait a -> a -> m Accept
- awaitEither :: (MonadResource m, AWSRequest a) => Env -> Wait a -> a -> m (Either Error Accept)
- class ToBody a where
- toBody :: a -> RequestBody
- data RequestBody
- newtype ResponseBody = ResponseBody {
- _streamBody :: ConduitM () ByteString (ResourceT IO) ()
- class ToHashedBody a where
- toHashed :: a -> HashedBody
- data HashedBody
- = HashedStream (Digest SHA256) !Integer (ConduitM () ByteString (ResourceT IO) ())
- | HashedBytes (Digest SHA256) ByteString
- hashedFile :: MonadIO m => FilePath -> m HashedBody
- hashedFileRange :: MonadIO m => FilePath -> Integer -> Integer -> m HashedBody
- hashedBody :: Digest SHA256 -> Integer -> ConduitM () ByteString (ResourceT IO) () -> HashedBody
- data ChunkedBody = ChunkedBody {
- _chunkedSize :: ChunkSize
- _chunkedLength :: Integer
- _chunkedBody :: ConduitM () ByteString (ResourceT IO) ()
- newtype ChunkSize = ChunkSize Int
- defaultChunkSize :: ChunkSize
- chunkedFile :: MonadIO m => ChunkSize -> FilePath -> m RequestBody
- chunkedFileRange :: MonadIO m => ChunkSize -> FilePath -> Integer -> Integer -> m RequestBody
- unsafeChunkedBody :: ChunkSize -> Integer -> ConduitM () ByteString (ResourceT IO) () -> RequestBody
- sinkBody :: MonadIO m => ResponseBody -> ConduitM ByteString Void (ResourceT IO) a -> m a
- getFileSize :: MonadIO m => FilePath -> m Integer
- sinkMD5 :: forall (m :: Type -> Type) o. Monad m => ConduitM ByteString o m (Digest MD5)
- sinkSHA256 :: forall (m :: Type -> Type) o. Monad m => ConduitM ByteString o m (Digest SHA256)
- presignURL :: (MonadIO m, AWSRequest a) => Env -> UTCTime -> Seconds -> a -> m ByteString
- presign :: (MonadIO m, AWSRequest a) => Env -> UTCTime -> Seconds -> a -> m ClientRequest
- data Dynamic
- dynamic :: MonadIO m => Env -> Dynamic -> m ByteString
- data Metadata
- = AMIId
- | AMILaunchIndex
- | AMIManifestPath
- | AncestorAMIIds
- | BlockDevice !Mapping
- | Hostname
- | IAM !Info
- | InstanceAction
- | InstanceId
- | InstanceType
- | KernelId
- | LocalHostname
- | LocalIPV4
- | MAC
- | Network !Text !Interface
- | AvailabilityZone
- | ProductCodes
- | PublicHostname
- | PublicIPV4
- | OpenSSHKey
- | RAMDiskId
- | ReservationId
- | SecurityGroups
- metadata :: MonadIO m => Env -> Metadata -> m ByteString
- userdata :: MonadIO m => Env -> m (Maybe ByteString)
- class AsError a where
- class AsAuthError a where
- _AuthError :: Prism' a AuthError
- _RetrievalError :: Prism' a HttpException
- _MissingEnvError :: Prism' a Text
- _InvalidEnvError :: Prism' a Text
- _MissingFileError :: Prism' a FilePath
- _InvalidFileError :: Prism' a Text
- _InvalidIAMError :: Prism' a Text
- trying :: MonadCatch m => Getting (First a) SomeException a -> m r -> m (Either a r)
- catching :: MonadCatch m => Getting (First a) SomeException a -> m r -> (a -> m r) -> m r
- _MatchServiceError :: AsError a => Service -> ErrorCode -> Getting (First ServiceError) a ServiceError
- hasService :: (Applicative f, Choice p) => Service -> Optic' p f ServiceError ServiceError
- hasStatus :: (Applicative f, Choice p) => Int -> Optic' p f ServiceError ServiceError
- hasCode :: (Applicative f, Choice p) => ErrorCode -> Optic' p f ServiceError ServiceError
- data LogLevel
- type Logger = LogLevel -> ByteStringBuilder -> IO ()
- newLogger :: MonadIO m => LogLevel -> Handle -> m Logger
- module Amazonka.Core
Usage
The key functions dealing with the request/response lifecycle are:
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:
{-# LANGUAGE OverloadedStrings #-} import qualified Amazonka as AWS import qualified Amazonka.S3 as S3 import qualified System.IO as IO example :: IO S3.PutObjectResponse example = do -- A newLogger
to replace the default noop logger is created, with the logger -- set to print debug information and errors to stdout: logger <- AWS.newLogger AWS.Debug IO.stdout -- To specify configuration preferences,newEnv
is used to create a new -- configuration environment. TheCredentials
parameter is used to specify -- mechanism for supplying or retrieving AuthN/AuthZ information. -- In this caseDiscover
will cause the library to try a number of options such -- as default environment variables, or an instance's IAM Profile and identity document: discover <- AWS.newEnv AWS.Discover let env = discover { AWS._envLogger = logger , AWS._envRegion = AWS.Frankfurt } -- The payload (and hash) for the S3 object is retrieved from aFilePath
, -- eitherhashedFile
orchunkedFile
can be used, with the latter ensuring -- the contents of the file is enumerated exactly once, during send: body <- AWS.chunkedFile AWS.defaultChunkSize "local/path/to/object-payload" -- We now run theAWS
computation with the overriden logger, performing the --PutObject
request.$sel:_envRegion:Env
orwithin
can be used to set the -- remote AWSRegion
: AWS.runResourceT $ AWS.send env (S3.newPutObject "bucket-name" "object-key" body)
Authentication and Environment
The environment containing the parameters required to make AWS requests.
This type tracks whether or not we have credentials at the type level, to avoid "presigning" requests when we lack auth information.
Env | |
|
Instances
Generic (Env' withAuth) Source # | |
type Rep (Env' withAuth) Source # | |
Defined in Amazonka.Auth type Rep (Env' withAuth) = D1 ('MetaData "Env'" "Amazonka.Auth" "libZSamazonkaZSamazonka" 'False) (C1 ('MetaCons "Env" 'PrefixI 'True) ((S1 ('MetaSel ('Just "_envRegion") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Region) :*: (S1 ('MetaSel ('Just "_envLogger") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Logger) :*: S1 ('MetaSel ('Just "_envRetryCheck") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Int -> HttpException -> Bool)))) :*: (S1 ('MetaSel ('Just "_envOverride") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Dual (Endo Service))) :*: (S1 ('MetaSel ('Just "_envManager") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Manager) :*: S1 ('MetaSel ('Just "_envAuth") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (withAuth Auth)))))) |
:: MonadIO m | |
=> Credentials | Credential discovery mechanism. |
-> m Env |
Creates a new environment with a new Manager
without debug logging
and uses getAuth
to expand/discover the supplied Credentials
.
Lenses can be used to further configure the resulting Env
.
Since: 1.5.0
- The region is now retrieved from the AWS_REGION
environment
variable (identical to official SDKs), or defaults to us-east-1
.
You can override the Env
region by using envRegion
, or the current operation's
region by using within
.
Since: 1.3.6
- The default logic for retrying HttpException
s now uses
retryConnectionFailure
to retry specific connection failure conditions up to 3 times.
Previously only service specific errors were automatically retried.
This can be reverted to the old behaviour by resetting the Env
using
envRetryCheck
lens to (\_ _ -> False)
.
Throws AuthError
when environment variables or IAM profiles cannot be read.
See: newEnvWith
.
newEnvNoAuth :: MonadIO m => m EnvNoAuth Source #
Generate an environment without credentials, which may only make unsigned requests.
This is useful for the STS AssumeRoleWithWebIdentity operation, which needs to make an unsigned request to pass the token from an identity provider.
Service Configuration
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 defaultService
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:
import qualified Amazonka as AWS import qualified Amazonka.DynamoDB as Dynamo let dynamo :: AWS.Service dynamo = AWS.setEndpoint False "localhost" 8000 DynamoDB.defaultService
The updated configuration is then passed to the Env
during setup:
env <- AWS.configure dynamo <$> AWS.newEnv AWS.Discover AWS.runResourceT $ do -- This S3 operation will communicate with remote AWS APIs. x <- AWS.send env newListBuckets -- DynamoDB operations will communicate with localhost:8000. y <- AWS.send env Dynamo.newListTables -- Any operations for services other than DynamoDB, are not affected. ...
You can also scope the service configuration modifications to specific actions:
env <- AWS.newEnv AWS.Discover AWS.runResourceT $ do -- Service operations here will communicate with AWS, even remote DynamoDB. x <- AWS.send env Dynamo.newListTables -- Here DynamoDB operations will communicate with localhost:8000. y <- AWS.send (AWS.configure dynamo env) Dynamo.newListTables
Functions such as within
, once
, and timeout
can also be used to modify
service configuration for all (or specific) requests.
:: (MonadIO m, Foldable withAuth) | |
=> Credentials | Credential discovery mechanism. |
-> Env' withAuth | Previous environment. |
-> m Env |
override :: (Service -> Service) -> Env -> Env Source #
Provide a function which will be added to the existing stack of overrides applied to all service configurations.
configure :: Service -> Env -> Env Source #
Configure a specific service. All requests belonging to the supplied service will use this configuration instead of the default.
It's suggested you modify the default service configuration,
such as Amazonka.DynamoDB.dynamoDB
.
Scope an action such that any retry logic for the Service
is
ignored and any requests will at most be sent once.
timeout :: Seconds -> Env -> Env Source #
Scope an action such that any HTTP response will use this timeout value.
Default timeouts are chosen by considering:
- This
timeout
, if set. - The related
Service
timeout for the sent request if set. (Usually 70s) - The
envManager
timeout if set. - The default
ClientRequest
timeout. (Approximately 30s)
Lenses
envRetryCheck :: Lens' (Env' withAuth) (Int -> HttpException -> Bool) Source #
Running AWS Actions
runResourceT :: MonadUnliftIO m => ResourceT m a -> m a #
Unwrap a ResourceT
transformer, and call all registered release actions.
Note that there is some reference counting involved due to resourceForkIO
.
If multiple threads are sharing the same collection of resources, only the
last call to runResourceT
will deallocate the resources.
NOTE Since version 1.2.0, this function will throw a
ResourceCleanupException
if any of the cleanup functions throw an
exception.
Since: resourcet-0.3.0
Credential Discovery
An access key ID.
For example: AKIAIOSFODNN7EXAMPLE
Instances
Eq AccessKey | |
Read AccessKey | |
Show AccessKey | |
IsString AccessKey | |
Defined in Amazonka.Types fromString :: String -> AccessKey # | |
Generic AccessKey | |
NFData AccessKey | |
Defined in Amazonka.Types | |
Hashable AccessKey | |
Defined in Amazonka.Types | |
ToJSON AccessKey | |
Defined in Amazonka.Types | |
FromJSON AccessKey | |
ToLog AccessKey | |
Defined in Amazonka.Types build :: AccessKey -> ByteStringBuilder # | |
ToQuery AccessKey | |
Defined in Amazonka.Types toQuery :: AccessKey -> QueryString # | |
FromXML AccessKey | |
ToXML AccessKey | |
Defined in Amazonka.Types | |
ToByteString AccessKey | |
Defined in Amazonka.Types toBS :: AccessKey -> ByteString # | |
FromText AccessKey | |
ToText AccessKey | |
Defined in Amazonka.Types | |
type Rep AccessKey | |
Defined in Amazonka.Types type Rep AccessKey = D1 ('MetaData "AccessKey" "Amazonka.Types" "libZSamazonka-coreZSamazonka-core" 'True) (C1 ('MetaCons "AccessKey" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString))) |
Secret access key credential.
For example: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKE
Instances
Eq SecretKey | |
IsString SecretKey | |
Defined in Amazonka.Types fromString :: String -> SecretKey # | |
Generic SecretKey | |
NFData SecretKey | |
Defined in Amazonka.Types | |
Hashable SecretKey | |
Defined in Amazonka.Types | |
ToJSON SecretKey | |
Defined in Amazonka.Types | |
FromJSON SecretKey | |
FromXML SecretKey | |
ToXML SecretKey | |
Defined in Amazonka.Types | |
ToByteString SecretKey | |
Defined in Amazonka.Types toBS :: SecretKey -> ByteString # | |
FromText SecretKey | |
ToText SecretKey | |
Defined in Amazonka.Types | |
type Rep SecretKey | |
Defined in Amazonka.Types type Rep SecretKey = D1 ('MetaData "SecretKey" "Amazonka.Types" "libZSamazonka-coreZSamazonka-core" 'True) (C1 ('MetaCons "SecretKey" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString))) |
newtype SessionToken #
A session token used by STS to temporarily authorise access to an AWS resource.
Instances
data Credentials Source #
Determines how AuthN/AuthZ information is retrieved.
FromKeys AccessKey SecretKey | Explicit access and secret keys. See |
FromSession AccessKey SecretKey SessionToken | Explicit access key, secret key and a session token. See |
FromEnv Text Text (Maybe Text) (Maybe Text) | Lookup specific environment variables for access key, secret key, an optional session token, and an optional region, respectively. |
FromProfile Text | An IAM Profile name to lookup from the local EC2 instance-data. Environment variables to lookup for the access key, secret key and optional session token. |
FromFile Text FilePath FilePath | A credentials profile name (the INI section), the path to the AWS
credentials file,
and the path to the |
FromWebIdentity | Obtain credentials using STS:AssumeRoleWithWebIdentity See About web identity federation in the AWS documentation for more information. |
FromContainer | Obtain credentials by attempting to contact the ECS container agent
at http://169.254.170.2 using the path in |
Discover | Attempt credentials discovery via the following steps:
An attempt is made to resolve http://instance-data rather than directly retrieving http://169.254.169.254 for IAM profile information. This assists in ensuring the DNS lookup terminates promptly if not running on EC2. |
Instances
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.
Supported Regions
The available AWS regions.
pattern Mumbai :: Region | |
pattern Sydney :: Region | |
pattern Singapore :: Region | |
pattern Osaka :: Region | |
pattern Seoul :: Region | |
pattern Tokyo :: Region | |
pattern HongKong :: Region | |
pattern Ningxia :: Region | |
pattern Beijing :: Region | |
pattern CapeTown :: Region | |
pattern Bahrain :: Region | |
pattern Stockholm :: Region | |
pattern Paris :: Region | |
pattern Milan :: Region | |
pattern London :: Region | |
pattern Ireland :: Region | |
pattern Frankfurt :: Region | |
pattern SaoPaulo :: Region | |
pattern Montreal :: Region | |
pattern GovCloudEast :: Region | |
pattern GovCloudWest :: Region | |
pattern Oregon :: Region | |
pattern NorthCalifornia :: Region | |
pattern Ohio :: Region | |
pattern NorthVirginia :: Region |
Instances
Eq Region | |
Ord Region | |
Read Region | |
Show Region | |
IsString Region | |
Defined in Amazonka.Types fromString :: String -> Region # | |
Generic Region | |
NFData Region | |
Defined in Amazonka.Types | |
Hashable Region | |
Defined in Amazonka.Types | |
ToJSON Region | |
Defined in Amazonka.Types | |
FromJSON Region | |
ToLog Region | |
Defined in Amazonka.Types build :: Region -> ByteStringBuilder # | |
ToQuery Region | |
Defined in Amazonka.Types toQuery :: Region -> QueryString # | |
FromXML Region | |
ToXML Region | |
Defined in Amazonka.Types | |
ToByteString Region | |
Defined in Amazonka.Types toBS :: Region -> ByteString # | |
FromText Region | |
ToText Region | |
Defined in Amazonka.Types | |
type Rep Region | |
Defined in Amazonka.Types |
Service Endpoints
:: Bool | Whether to use HTTPS (ie. SSL). |
-> ByteString | The hostname to connect to. |
-> Int | The port number to connect to. |
-> Service | The service configuration to override. |
-> Service |
A convenience function for overriding the Service
Endpoint
.
See: serviceEndpoint
.
Sending Requests
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.
send :: (MonadResource m, AWSRequest a) => Env -> a -> m (AWSResponse a) Source #
Send a request, returning the associated response if successful.
Errors are thrown in IO
.
See sendEither
.
sendEither :: (MonadResource m, AWSRequest a) => Env -> a -> m (Either Error (AWSResponse a)) Source #
Send a request, returning the associated response if successful.
See send
.
Pagination
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.
paginate :: (MonadResource m, AWSPager a) => Env -> a -> ConduitM () (AWSResponse a) m () Source #
Repeatedly send a request, automatically setting markers and performing pagination. Exits on the first encountered error.
Errors are thrown in IO
.
See paginateEither
.
paginateEither :: (MonadResource m, AWSPager a) => Env -> a -> ConduitM () (AWSResponse a) m (Either Error ()) Source #
Repeatedly send a request, automatically setting markers and performing pagination.
Exits on the first encountered error.
See paginate
.
Waiters
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 Amazonka.{ServiceName}.Waiters
namespace for services which support await
.
await :: (MonadResource m, AWSRequest a) => Env -> Wait a -> a -> m Accept Source #
Poll the API with the supplied request until a specific Wait
condition
is fulfilled.
Errors are thrown in IO
.
See awaitEither
.
awaitEither :: (MonadResource m, AWSRequest a) => Env -> Wait a -> a -> m (Either Error Accept) Source #
Streaming
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.
Anything that can be converted to a streaming request Body
.
Nothing
toBody :: a -> RequestBody #
Convert a value to a request body.
Instances
data RequestBody #
Invariant: only services that support _both_ standard and
chunked signing expose RequestBody
as a parameter.
Instances
Show RequestBody | |
Defined in Amazonka.Data.Body showsPrec :: Int -> RequestBody -> ShowS # show :: RequestBody -> String # showList :: [RequestBody] -> ShowS # | |
IsString RequestBody | |
Defined in Amazonka.Data.Body fromString :: String -> RequestBody # | |
ToBody RequestBody | |
Defined in Amazonka.Data.Body toBody :: RequestBody -> RequestBody # |
newtype ResponseBody #
A streaming, exception safe response body.
ResponseBody | |
|
Instances
Show ResponseBody | |
Defined in Amazonka.Data.Body showsPrec :: Int -> ResponseBody -> ShowS # show :: ResponseBody -> String # showList :: [ResponseBody] -> ShowS # |
Hashed Request Bodies
class ToHashedBody a where #
Anything that can be safely converted to a HashedBody
.
toHashed :: a -> HashedBody #
Convert a value to a hashed request body.
Instances
ToHashedBody String | |
Defined in Amazonka.Data.Body toHashed :: String -> HashedBody # | |
ToHashedBody ByteString | |
Defined in Amazonka.Data.Body toHashed :: ByteString -> HashedBody # | |
ToHashedBody Text | |
Defined in Amazonka.Data.Body toHashed :: Text -> HashedBody # | |
ToHashedBody Value | |
Defined in Amazonka.Data.Body toHashed :: Value -> HashedBody # | |
ToHashedBody Element | |
Defined in Amazonka.Data.Body toHashed :: Element -> HashedBody # | |
ToHashedBody Base64 | |
Defined in Amazonka.Data.Base64 toHashed :: Base64 -> HashedBody # | |
ToHashedBody HashedBody | |
Defined in Amazonka.Data.Body toHashed :: HashedBody -> HashedBody # | |
ToHashedBody QueryString | |
Defined in Amazonka.Data.Body toHashed :: QueryString -> HashedBody # | |
ToHashedBody TextLazy | |
Defined in Amazonka.Data.Body toHashed :: TextLazy -> HashedBody # | |
ToHashedBody ByteStringLazy | |
Defined in Amazonka.Data.Body toHashed :: ByteStringLazy -> HashedBody # | |
ToHashedBody (HashMap Text Value) | |
Defined in Amazonka.Data.Body |
data HashedBody #
An opaque request body containing a SHA256
hash.
HashedStream (Digest SHA256) !Integer (ConduitM () ByteString (ResourceT IO) ()) | |
HashedBytes (Digest SHA256) ByteString |
Instances
Show HashedBody | |
Defined in Amazonka.Data.Body showsPrec :: Int -> HashedBody -> ShowS # show :: HashedBody -> String # showList :: [HashedBody] -> ShowS # | |
IsString HashedBody | |
Defined in Amazonka.Data.Body fromString :: String -> HashedBody # | |
ToHashedBody HashedBody | |
Defined in Amazonka.Data.Body toHashed :: HashedBody -> HashedBody # | |
ToBody HashedBody | |
Defined in Amazonka.Data.Body toBody :: HashedBody -> RequestBody # |
:: MonadIO m | |
=> FilePath | The file path to read. |
-> m HashedBody |
Construct a HashedBody
from a FilePath
, calculating the SHA256
hash
and file size.
Note: While this function will perform in constant space, it will enumerate the entirety of the file contents _twice_. Firstly to calculate the SHA256 and lastly to stream the contents to the socket during sending.
See: ToHashedBody
.
:: MonadIO m | |
=> FilePath | The file path to read. |
-> Integer | The byte offset at which to start reading. |
-> Integer | The maximum number of bytes to read. |
-> m HashedBody |
Construct a HashedBody
from a FilePath
, specifying the range of bytes
to read. This can be useful for constructing multiple requests from a single
file, say for S3 multipart uploads.
See: hashedFile
, sourceFileRange
.
:: Digest SHA256 | A SHA256 hash of the file contents. |
-> Integer | The size of the stream in bytes. |
-> ConduitM () ByteString (ResourceT IO) () | |
-> HashedBody |
Construct a HashedBody
from a Source
, manually specifying the SHA256
hash and file size. It's left up to the caller to calculate these correctly,
otherwise AWS will return signing errors.
See: ToHashedBody
.
Chunked Request Bodies
data ChunkedBody #
An opaque request body which will be transmitted via
Transfer-Encoding: chunked
.
Invariant: Only services that support chunked encoding can
accept a ChunkedBody
. (Currently S3.) This is enforced by the type
signatures emitted by the generator.
ChunkedBody | |
|
Instances
Show ChunkedBody | |
Defined in Amazonka.Data.Body showsPrec :: Int -> ChunkedBody -> ShowS # show :: ChunkedBody -> String # showList :: [ChunkedBody] -> ShowS # | |
ToBody ChunkedBody | |
Defined in Amazonka.Data.Body toBody :: ChunkedBody -> RequestBody # |
Specifies the transmitted size of the 'Transfer-Encoding' chunks.
See: defaultChunk
.
Instances
Enum ChunkSize | |
Defined in Amazonka.Data.Body succ :: ChunkSize -> ChunkSize # pred :: ChunkSize -> ChunkSize # fromEnum :: ChunkSize -> Int # enumFrom :: ChunkSize -> [ChunkSize] # enumFromThen :: ChunkSize -> ChunkSize -> [ChunkSize] # enumFromTo :: ChunkSize -> ChunkSize -> [ChunkSize] # enumFromThenTo :: ChunkSize -> ChunkSize -> ChunkSize -> [ChunkSize] # | |
Eq ChunkSize | |
Integral ChunkSize | |
Defined in Amazonka.Data.Body | |
Num ChunkSize | |
Ord ChunkSize | |
Defined in Amazonka.Data.Body | |
Real ChunkSize | |
Defined in Amazonka.Data.Body toRational :: ChunkSize -> Rational # | |
Show ChunkSize | |
ToLog ChunkSize | |
Defined in Amazonka.Data.Body build :: ChunkSize -> ByteStringBuilder # |
defaultChunkSize :: ChunkSize #
The default chunk size of 128 KB. The minimum chunk size accepted by AWS is 8 KB, unless the entirety of the request is below this threshold.
A chunk size of 64 KB or higher is recommended for performance reasons.
chunkedFile :: MonadIO m => ChunkSize -> FilePath -> m RequestBody #
Construct a ChunkedBody
from a FilePath
, where the contents will be
read and signed incrementally in chunks if the target service supports it.
Will intelligently revert to HashedBody
if the file is smaller than the
specified ChunkSize
.
See: ToBody
.
:: MonadIO m | |
=> ChunkSize | The idealized size of chunks that will be yielded downstream. |
-> FilePath | The file path to read. |
-> Integer | The byte offset at which to start reading. |
-> Integer | The maximum number of bytes to read. |
-> m RequestBody |
Construct a ChunkedBody
from a FilePath
, specifying the range of bytes
to read. This can be useful for constructing multiple requests from a single
file, say for S3 multipart uploads.
See: chunkedFile
.
:: ChunkSize | The idealized size of chunks that will be yielded downstream. |
-> Integer | The size of the stream in bytes. |
-> ConduitM () ByteString (ResourceT IO) () | |
-> RequestBody |
Unsafely construct a ChunkedBody
.
This function is marked unsafe because it does nothing to enforce the chunk size.
Typically for conduit IO
functions, it's whatever ByteString's
defaultBufferSize
is, around 32 KB. If the chunk size is less than 8 KB,
the request will error. 64 KB or higher chunk size is recommended for
performance reasons.
Note that it will always create a chunked body even if the request is too small.
See: ToBody
.
Response Bodies
sinkBody :: MonadIO m => ResponseBody -> ConduitM ByteString Void (ResourceT IO) a -> m a #
Connect a Sink
to a response stream.
File Size and MD5/SHA256
getFileSize :: MonadIO m => FilePath -> m Integer #
Convenience function for obtaining the size of a file.
sinkMD5 :: forall (m :: Type -> Type) o. Monad m => ConduitM ByteString o m (Digest MD5) #
Incrementally calculate a MD5
Digest
.
sinkSHA256 :: forall (m :: Type -> Type) o. Monad m => ConduitM ByteString o m (Digest SHA256) #
Incrementally calculate a SHA256
Digest
.
Presigning Requests
Presigning requires the Service
signer to be an instance of AWSPresigner
.
Not all signing algorithms support this.
:: (MonadIO m, AWSRequest a) | |
=> Env | |
-> UTCTime | Signing time. |
-> Seconds | Expiry time. |
-> a | Request to presign. |
-> m ByteString |
Presign an URL that is valid from the specified time until the number of seconds expiry has elapsed.
:: (MonadIO m, AWSRequest a) | |
=> Env | |
-> UTCTime | Signing time. |
-> Seconds | Expiry time. |
-> a | Request to presign. |
-> m ClientRequest |
Presign an HTTP request that is valid from the specified time until the number of seconds expiry has elapsed.
EC2 Instance Metadata
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.
FWS | Value showing whether the customer has enabled detailed one-minute monitoring in CloudWatch. Valid values: enabled | disabled. |
Document | JSON containing instance attributes, such as instance-id,
private IP address, etc.
See: |
PKCS7 | Used to verify the document's authenticity and content against the signature. |
Signature |
Instances
Eq Dynamic Source # | |
Ord Dynamic Source # | |
Show Dynamic Source # | |
Generic Dynamic Source # | |
ToText Dynamic Source # | |
Defined in Amazonka.EC2.Metadata | |
type Rep Dynamic Source # | |
Defined in Amazonka.EC2.Metadata type Rep Dynamic = D1 ('MetaData "Dynamic" "Amazonka.EC2.Metadata" "libZSamazonkaZSamazonka" 'False) ((C1 ('MetaCons "FWS" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Document" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "PKCS7" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Signature" 'PrefixI 'False) (U1 :: Type -> Type))) |
AMIId | The AMI ID used to launch the instance. |
AMILaunchIndex | If you started more than one instance at the same time, this value indicates the order in which the instance was launched. The value of the first instance launched is 0. |
AMIManifestPath | The path to the AMI's manifest file in Amazon S3. If you used an Amazon EBS-backed AMI to launch the instance, the returned result is unknown. |
AncestorAMIIds | The AMI IDs of any instances that were rebundled to create this AMI. This value will only exist if the AMI manifest file contained an ancestor-amis key. |
BlockDevice !Mapping | See: |
Hostname | The private hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). |
IAM !Info | See: |
InstanceAction | Notifies the instance that it should reboot in preparation for bundling. Valid values: none | shutdown | bundle-pending. |
InstanceId | The ID of this instance. |
InstanceType | The type of instance. See: |
KernelId | The ID of the kernel launched with this instance, if applicable. |
LocalHostname | The private DNS hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). |
LocalIPV4 | The private IP address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). |
MAC | The instance's media access control (MAC) address. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). |
Network !Text !Interface | See: |
AvailabilityZone | The Availability Zone in which the instance launched. |
ProductCodes | Product codes associated with the instance, if any. |
PublicHostname | The instance's public DNS. If the instance is in a VPC, this category is only returned if the enableDnsHostnames attribute is set to true. For more information, see Using DNS with Your VPC. |
PublicIPV4 | The public IP address. If an Elastic IP address is associated with the instance, the value returned is the Elastic IP address. |
OpenSSHKey | Public key. Only available if supplied at instance launch time. |
RAMDiskId | The ID of the RAM disk specified at launch time, if applicable. |
ReservationId | ID of the reservation. |
SecurityGroups | The names of the security groups applied to the instance. |
Instances
userdata :: MonadIO m => Env -> m (Maybe ByteString) Source #
Retrieve the user data. Returns Nothing
if no user data is assigned
to the instance.
Running Asynchronous Actions
Requests can be sent asynchronously, but due to guarantees about resource closure require the use of UnliftIO.Async.
The following example demonstrates retrieving two objects from S3 concurrently:
{-# LANGUAGE OverloadedStrings #-} import qualified Amazonka as AWS import qualified Amazonka.S3 as S3 import qualified UnliftIO.Async as Async let requestA = S3.newGetObject "bucket" "prefix/object-a" let requestB = S3.newGetObject "bucket" "prefix/object-b" runResourceT $ Async.withAsync
(send env requestA) $ \asyncA -> Async.withAsync
(send env requestB) $ \asyncB -> do Async.waitBoth
asyncA asyncB
If you are running many async requests in parallel, using
ContT
can hide the giant callback pyramid:
runResourceT .evalContT
$ do asyncA <- ContT $ Async.withAsync
(send env requestA) asyncB <- ContT $ Async.withAsync
(send env requestB) Async.waitBoth
asyncA asyncB
Handling Errors
Errors are either returned or thrown by the library using IO
. Sub-errors of
the canonical Error
type can be caught using trying
or catching
and the
appropriate AsError
Prism
when using the non-Either
send variants:
trying_Error
(send $ newListObjects "bucket-name") :: EitherError
ListObjectsResponse trying_TransportError
(send $ newListObjects "bucket-name") :: EitherHttpException
ListObjectsResponse trying_SerializeError
(send $ newListObjects "bucket-name") :: EitherSerializeError
ListObjectsResponse trying_ServiceError
(send $ newListObjects "bucket-name") :: EitherServiceError
ListObjectsResponse
Many of the individual amazonka-*
libraries export compatible Getter
s for
matching service specific error codes and messages in the style above.
See the Error Matchers
heading in each respective library for details.
A general Amazonka error.
_TransportError :: Prism' a HttpException #
An error occured while communicating over HTTP with a remote service.
_SerializeError :: Prism' a SerializeError #
A serialisation error occured when attempting to deserialise a response.
_ServiceError :: Prism' a ServiceError #
A service specific error returned by the remote service.
Instances
AsError SomeException | |
AsError Error | |
Defined in Amazonka.Types |
class AsAuthError a where Source #
_AuthError :: Prism' a AuthError Source #
A general authentication error.
_RetrievalError :: Prism' a HttpException Source #
An error occured while communicating over HTTP with the local metadata endpoint.
_MissingEnvError :: Prism' a Text Source #
The named environment variable was not found.
_InvalidEnvError :: Prism' a Text Source #
An error occured parsing named environment variable's value.
_MissingFileError :: Prism' a FilePath Source #
The specified credentials file could not be found.
_InvalidFileError :: Prism' a Text Source #
An error occured parsing the credentials file.
_InvalidIAMError :: Prism' a Text Source #
The specified IAM profile could not be found or deserialised.
Instances
trying :: MonadCatch m => Getting (First a) SomeException a -> m r -> m (Either a r) #
A variant of try
that takes a Prism
(or any Fold
) to select which
exceptions are caught (c.f. tryJust
, catchJust
). If the
Exception
does not match the predicate, it is re-thrown.
trying
::MonadCatch
m =>Prism'
SomeException
a -> m r -> m (Either
a r)trying
::MonadCatch
m =>Lens'
SomeException
a -> m r -> m (Either
a r)trying
::MonadCatch
m =>Traversal'
SomeException
a -> m r -> m (Either
a r)trying
::MonadCatch
m =>Iso'
SomeException
a -> m r -> m (Either
a r)trying
::MonadCatch
m =>Getter
SomeException
a -> m r -> m (Either
a r)trying
::MonadCatch
m =>Fold
SomeException
a -> m r -> m (Either
a r)
catching :: MonadCatch m => Getting (First a) SomeException a -> m r -> (a -> m r) -> m r #
Catch exceptions that match a given Prism
(or any Fold
, really).
>>>
catching _AssertionFailed (assert False (return "uncaught")) $ \ _ -> return "caught"
"caught"
catching
::MonadCatch
m =>Prism'
SomeException
a -> m r -> (a -> m r) -> m rcatching
::MonadCatch
m =>Lens'
SomeException
a -> m r -> (a -> m r) -> m rcatching
::MonadCatch
m =>Traversal'
SomeException
a -> m r -> (a -> m r) -> m rcatching
::MonadCatch
m =>Iso'
SomeException
a -> m r -> (a -> m r) -> m rcatching
::MonadCatch
m =>Getter
SomeException
a -> m r -> (a -> m r) -> m rcatching
::MonadCatch
m =>Fold
SomeException
a -> m r -> (a -> m r) -> m r
Building Error Prisms
_MatchServiceError :: AsError a => Service -> ErrorCode -> Getting (First ServiceError) a ServiceError #
Provides a generalised prism for catching a specific service error identified by the opaque service abbreviation and error code.
This can be used if the generated error prisms provided by
Amazonka.ServiceName.Types
do not cover all the thrown error codes.
For example to define a new error prism:
{-# LANGUAGE OverloadedStrings #-} import Amazonka.S3 (ServiceError, s3) _NoSuchBucketPolicy :: AsError a => Getting (First ServiceError) a ServiceError _NoSuchBucketPolicy = _MatchServiceError s3 "NoSuchBucketPolicy"
With example usage being:
>>>
import Control.Exception.Lens (trying)
>>>
:t trying _NoSuchBucketPolicy
MonadCatch m => m a -> m (Either ServiceError a)
hasService :: (Applicative f, Choice p) => Service -> Optic' p f ServiceError ServiceError #
hasStatus :: (Applicative f, Choice p) => Int -> Optic' p f ServiceError ServiceError #
hasCode :: (Applicative f, Choice p) => ErrorCode -> Optic' p f ServiceError ServiceError #
Logging
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
tinylog or
fast-logger.
Info | Info messages supplied by the user - this level is not emitted by the library. |
Error | Error messages only. |
Debug | Useful debug information + info + error levels. |
Trace | Includes potentially sensitive signing metadata, and non-streaming response bodies. |
Instances
Enum LogLevel | |
Eq LogLevel | |
Ord LogLevel | |
Defined in Amazonka.Types | |
Show LogLevel | |
Generic LogLevel | |
ToByteString LogLevel | |
Defined in Amazonka.Types toBS :: LogLevel -> ByteString # | |
FromText LogLevel | |
ToText LogLevel | |
Defined in Amazonka.Types | |
type Rep LogLevel | |
Defined in Amazonka.Types type Rep LogLevel = D1 ('MetaData "LogLevel" "Amazonka.Types" "libZSamazonka-coreZSamazonka-core" 'False) ((C1 ('MetaCons "Info" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Error" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "Debug" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Trace" 'PrefixI 'False) (U1 :: Type -> Type))) |
type Logger = LogLevel -> ByteStringBuilder -> IO () #
A function threaded through various request and serialisation routines to log informational and debug messages.
Constructing a Logger
newLogger :: MonadIO m => LogLevel -> Handle -> m Logger Source #
This is a primitive logger which can be used to log builds to a Handle
.
Note: A more sophisticated logging library such as tinylog or fast-logger should be used in production code.
Re-exported Types
module Amazonka.Core