aws

Amazon Web Services (AWS) for Haskell

http://github.com/aristidb/aws

Version on this page:0.13.0@rev:1
LTS Haskell 22.14:0.24.1
Stackage Nightly 2024-03-28:0.24.2
Latest on Hackage:0.24.2

See all snapshots aws appears in

BSD-3-Clause licensed by Aristid Breitkreuz, contributors see README
Maintained by [email protected]
This version can be pinned in stack with:aws-0.13.0@sha256:57beb101b4203e6784df90817aadfbda98972052e31f85fa620f2d7dcdf6a446,12547

Module documentation for 0.13.0

#+TITLE: Amazon Web Services for Haskell

* Introduction

The ~aws~ package attempts to provide support for using Amazon Web Services like S3 (storage), SQS (queuing) and others
to Haskell programmers. The ultimate goal is to support all Amazon Web Services.

* Installation

Make sure you have a recent GHC installed, as well as cabal-install, and installation should be as easy as:

#+BEGIN_SRC bash
$ cabal install aws
#+END_SRC

If you prefer to install from source yourself, you should first get a clone of the ~aws~ repository, and install it from
inside the source directory:

#+BEGIN_SRC bash
$ git clone https://github.com/aristidb/aws.git
$ cd aws
$ cabal install
#+END_SRC

* Using aws

** Concepts and organisation

The aws package is organised into the general =Aws= module namespace, and subnamespaces like =Aws.S3= for each Amazon Web
Service. Under each service namespace in turn, there are general support modules and and =Aws.<Service>.Commands.<Command>=
module for each command. For easier usage, there are the "bundling" modules =Aws= (general support), and =Aws.<Service>=.

The primary concept in aws is the /Transaction/, which corresponds to a single HTTP request to the Amazon Web Services.
A transaction consists of a request and a response, which are associated together via the =Transaction= typeclass. Requests
and responses are simple Haskell records, but for some requests there are convenience functions to fill in default values
for many parameters.

** Example usage

To be able to access AWS resources, you should put your into a configuration file. (You don't have to store it in a file,
but that's how we do it in this example.) Save the following in ~$HOME/.aws-keys~.

#+BEGIN_EXAMPLE
default AccessKeyID SecretKey
#+END_EXAMPLE

You do have to replace AccessKeyID and SecretKey with the Access Key ID and the Secret Key respectively, of course.

Then, copy this example into a Haskell file, and run it with ~runghc~ (after installing aws):

#+BEGIN_SRC haskell
{-# LANGUAGE OverloadedStrings #-}

import qualified Aws
import qualified Aws.S3 as S3
import Data.Conduit (($$+-))
import Data.Conduit.Binary (sinkFile)
import Network.HTTP.Conduit (withManager, responseBody)

main :: IO ()
main = do
{- Set up AWS credentials and the default configuration. -}
cfg <- Aws.baseConfiguration
let s3cfg = Aws.defServiceConfig :: S3.S3Configuration Aws.NormalQuery

{- Set up a ResourceT region with an available HTTP manager. -}
withManager $ \mgr -> do
{- Create a request object with S3.getObject and run the request with pureAws. -}
S3.GetObjectResponse { S3.gorResponse = rsp } <-
Aws.pureAws cfg s3cfg mgr $
S3.getObject "haskell-aws" "cloud-remote.pdf"

{- Save the response to a file. -}
responseBody rsp $$+- sinkFile "cloud-remote.pdf"
#+END_SRC

You can also find this example in the source distribution in the ~Examples/~ folder.


* Frequently Asked Questions

** S3 questions

- I get an error when I try to access my bucket with upper-case characters / a very long name.

Those names are not compliant with DNS. You need to use path-style requests, by setting ~s3RequestStyle~ in the configuration to
~PathStyle~. Note that such bucket names are only allowed in the US standard region, so your endpoint needs to be US standard.

* Release Notes

See CHANGELOG

* Resources

- [[https://github.com/aristidb/aws][aws on Github]]
- [[http://hackage.haskell.org/package/aws][aws on Hackage]] (includes reference documentation)
- [[http://aws.amazon.com/][Official Amazon Web Services website]]

* Contributors

| Name | Github | E-Mail | Company | Components |
|--------------------+--------------+---------------------------+------------------------+---------------|
| Abhinav Gupta | [[https://github.com/abhinav][abhinav]] | [email protected] | - | IAM, SES |
| Aristid Breitkreuz | [[https://github.com/aristidb][aristidb]] | [email protected] | - | Co-Maintainer |
| Bas van Dijk | [[https://github.com/basvandijk][basvandijk]] | [email protected] | [[http://erudify.ch][Erudify AG]] | S3 |
| David Vollbracht | [[https://github.com/qxjit][qxjit]] | | | |
| Felipe Lessa | [[https://github.com/meteficha][meteficha]] | [email protected] | currently secret | Core, S3, SES |
| Nathan Howell | [[https://github.com/NathanHowell][NathanHowell]] | [email protected] | [[http://www.alphaheavy.com][Alpha Heavy Industries]] | S3 |
| Ozgun Ataman | [[https://github.com/ozataman][ozataman]] | [email protected] | [[http://soostone.com][Soostone Inc]] | Core, S3, DynamoDb |
| Steve Severance | [[https://github.com/sseveran][sseveran]] | [email protected] | [[http://www.alphaheavy.com][Alpha Heavy Industries]] | S3, SQS |
| John Wiegley | [[https://github.com/jwiegley][jwiegley]] | [email protected] | [[http://fpcomplete.com][FP Complete]] | Co-Maintainer, S3 |
| Chris Dornan | [[https://github.com/cdornan][cdornan]] | [email protected] | [[http://irisconnect.co.uk][Iris Connect]] | Core |
| John Lenz | [[https://github/com/wuzzeb][wuzzeb]] | | | DynamoDB, Core |