README.md
1Introduction
2============
3
4The `aws` package attempts to provide support for using Amazon Web
5Services like S3 (storage), SQS (queuing) and others to Haskell
6programmers. The ultimate goal is to support all Amazon Web Services.
7
8Installation
9============
10
11Make sure you have a recent GHC installed, as well as cabal-install, and
12installation should be as easy as:
13
14``` {.bash}
15$ cabal install aws
16```
17
18If you prefer to install from source yourself, you should first get a
19clone of the `aws` repository, and install it from inside the source
20directory:
21
22``` {.bash}
23$ git clone https://github.com/aristidb/aws.git
24$ cd aws
25$ cabal install
26```
27
28Using aws
29=========
30
31Concepts and organisation
32-------------------------
33
34The aws package is organised into the general `Aws` module namespace,
35and subnamespaces like `Aws.S3` for each Amazon Web Service. Under each
36service namespace in turn, there are general support modules and and
37`Aws.<Service>.Commands.<Command>` module for each command. For easier
38usage, there are the "bundling" modules `Aws` (general support), and
39`Aws.<Service>`.
40
41The primary concept in aws is the *Transaction*, which corresponds to a
42single HTTP request to the Amazon Web Services. A transaction consists
43of a request and a response, which are associated together via the
44`Transaction` typeclass. Requests and responses are simple Haskell
45records, but for some requests there are convenience functions to fill
46in default values for many parameters.
47
48Example usage
49-------------
50
51To be able to access AWS resources, you should put your into a
52configuration file. (You don't have to store it in a file, but that's
53how we do it in this example.) Save the following in `$HOME/.aws-keys`.
54
55``` {.example}
56default AccessKeyID SecretKey
57```
58
59You do have to replace AccessKeyID and SecretKey with the Access Key ID
60and the Secret Key respectively, of course.
61
62Then, copy this example into a Haskell file, and run it with `runghc`
63(after installing aws):
64
65``` {.haskell}
66{-# LANGUAGE OverloadedStrings #-}
67
68import qualified Aws
69import qualified Aws.S3 as S3
70import Control.Monad.Trans.Resource
71import Data.Conduit ((.|), runConduit)
72import Data.Conduit.Binary (sinkFile)
73import Network.HTTP.Conduit (newManager, tlsManagerSettings, responseBody)
74
75main :: IO ()
76main = do
77 {- Set up AWS credentials and the default configuration. -}
78 cfg <- Aws.baseConfiguration
79 let s3cfg = Aws.defServiceConfig :: S3.S3Configuration Aws.NormalQuery
80
81 {- Set up a ResourceT region with an available HTTP manager. -}
82 mgr <- newManager tlsManagerSettings
83 runResourceT $ do
84 {- Create a request object with S3.getObject and run the request with pureAws. -}
85 S3.GetObjectResponse { S3.gorResponse = rsp } <-
86 Aws.pureAws cfg s3cfg mgr $
87 S3.getObject "haskell-aws" "cloud-remote.pdf"
88
89 {- Save the response to a file. -}
90 runConduit $ responseBody rsp .| sinkFile "cloud-remote.pdf"
91```
92
93You can also find this example in the source distribution in the
94`Examples/` folder.
95
96Frequently Asked Questions
97==========================
98
99S3 questions
100------------
101
102- I get an error when I try to access my bucket with upper-case
103 characters / a very long name.
104
105 Those names are not compliant with DNS. You need to use path-style
106 requests, by setting `s3RequestStyle` in the configuration to
107 `PathStyle`. Note that such bucket names are only allowed in the US
108 standard region, so your endpoint needs to be US standard.
109
110Release Notes
111=============
112
113See CHANGELOG
114
115Resources
116=========
117
118- [aws on Github](https://github.com/aristidb/aws)
119- [aws on Hackage](http://hackage.haskell.org/package/aws) (includes
120 reference documentation)
121- [Official Amazon Web Services website](http://aws.amazon.com/)
122
123Contributors
124============
125
126 Name |Github |E-Mail |Company |Components
127 --------------------|-------------------------------------------------|--------------------------------|-----------------------------------------------------|--------------------
128 Abhinav Gupta |[abhinav](https://github.com/abhinav) |mail@abhinavg.net |- |IAM, SES
129 Aristid Breitkreuz |[aristidb](https://github.com/aristidb) |aristidb@gmail.com |- |Co-Maintainer
130 Bas van Dijk |[basvandijk](https://github.com/basvandijk) |v.dijk.bas@gmail.com |[Erudify AG](http://erudify.ch) |S3
131 David Vollbracht |[qxjit](https://github.com/qxjit) | | |
132 Felipe Lessa |[meteficha](https://github.com/meteficha) |felipe.lessa@gmail.com |currently secret |Core, S3, SES
133 Nathan Howell |[NathanHowell](https://github.com/NathanHowell) |nhowell@alphaheavy.com |[Alpha Heavy Industries](http://www.alphaheavy.com) |S3
134 Ozgun Ataman |[ozataman](https://github.com/ozataman) |ozgun.ataman@soostone.com |[Soostone Inc](http://soostone.com) |Core, S3, DynamoDb
135 Steve Severance |[sseveran](https://github.com/sseveran) |sseverance@alphaheavy.com |[Alpha Heavy Industries](http://www.alphaheavy.com) |S3, SQS
136 John Wiegley |[jwiegley](https://github.com/jwiegley) |johnw@fpcomplete.com |[FP Complete](http://fpcomplete.com) |Co-Maintainer, S3
137 Chris Dornan |[cdornan](https://github.com/cdornan) |chris.dornan@irisconnect.co.uk |[Iris Connect](http://irisconnect.co.uk) |Core
138 John Lenz |[wuzzeb](https://github/com/wuzzeb) | | |DynamoDB, Core
139
140
141