Documentation updates.

Author: dnikolovv

doc/01-getting-started.md

@@ -49,7 +49,7 @@ packages:
 - .
 
 extra-deps:
-- aws-lambda-haskell-runtime-2.0.1
+- aws-lambda-haskell-runtime-3.0.0
 ```
 
 ## Adding the dependency to an existing project
@@ -60,15 +60,15 @@ to the `stack.yaml` file:
 
 ```yaml
 extra-deps:
-- aws-lambda-haskell-runtime-2.0.1
+- aws-lambda-haskell-runtime-3.0.0
 ```
 
 and, to the `package.yaml` file:
 
 ```yaml
 dependencies:
 - ... # other dependencies of your project
-- aws-lambda-haskell-runtime >= 2.0
+- aws-lambda-haskell-runtime >= 3.0.0
 ```
 
 ## Keep reading!

doc/02-adding-a-handler.md

@@ -21,6 +21,7 @@ modules:
 ```haskell
 {-# LANGUAGE DeriveGeneric  #-}
 {-# LANGUAGE DeriveAnyClass #-}
+
 module Lib where
 ```
 
@@ -46,7 +47,7 @@ Now, let's write the handler. It **must** be a function that is called `handler`
 The arguments to this function will always go like this:
 
 * The first argument to this handler will always be the input type we expect (note that it has to implement `FromJSON`).
-* The second argument is the `Aws.Lambda` `Context` type, which has some information regarding our Lambda execution.
+* The second argument is the `Aws.Lambda` `Context` type, which has some information regarding our Lambda execution. The `Context` type also takes a `context` parameter, which we can use if we want to have some state that is shared between Lambda calls. For this example, we don't want to have such state, so we'll just use `()`.
 
 The output will always be an `IO (Either errorType resultType)` where
 
@@ -59,7 +60,7 @@ For example, here we will check if the age of a `Person` is positive, and will r
 will return a `String` error:
 
 ```haskell top
-handler :: Person -> Context -> IO (Either String Person)
+handler :: Person -> Context () -> IO (Either String Person)
 handler person context =
   if age person > 0 then
     pure (Right person)

doc/03-configuring-the-dispatcher.md

@@ -8,21 +8,28 @@ The dispatcher is a special main function that checks which handler it has to ru
 and runs it
 
 To make the package generate a dispatcher for you, you have to configure it in
-your `app/Main.hs` file.
+your `app/Main.hs` file to use the `generateLambdaDispatcher` function from `Aws.Lambda`.
 
-First, activate `TemplateHaskell` for enabling the metaprogramming features of Haskell.
+The `generateLambdaDispatcher` function has two options: `StandaloneLambda` and `UseWithAPIGateway`.
+
+Use `UseWithAPIGateway` when you'll be exposing your lambda through API Gateway. For more information check the [Use with API Gateway](./04-usage-with-api-gateway.md) page.
+
+Use `StandaloneLambda` when you want to use your lambda as usual. This is what we're going to use for our person age validator function.
+
+To continue the person age validator lambda, activate `TemplateHaskell` for enabling the metaprogramming features of Haskell.
 Then, import the `Aws.Lambda` module:
 
 ```haskell
 {-# LANGUAGE TemplateHaskell #-}
+
 module Main where
 import Aws.Lambda
 ```
 
 After this, add a line with the following statement:
 
 ```haskell
-generateLambdaDispatcher
+generateLambdaDispatcher StandaloneLambda defaultDispatcherOptions
 ```
 
 This statement will generate something that looks a little bit like this:

doc/04-usage-with-api-gateway.md

@@ -4,158 +4,42 @@ title: Usage with API Gateway
 
 # Usage with API Gateway
 
-In order to write a handler for the API Gateway, we will receive a special JSON with
-a lot of fields with information from the API Gateway, and we will have to return
-a special JSON as the response.
+A common use-case is to expose your lambdas through API Gateway. Luckily, `aws-lambda-haskell-runtime` has native support for that.
 
-## The request
-
-The full request type looks more or less like this:
-
-```haskell
-data APIGatewayRequest = APIGatewayRequest
-  { resource :: String
-  , path :: ByteString
-  , httpMethod :: Method
-  , headers :: RequestHeaders
-  , queryStringParameters :: [(ByteString, Maybe ByteString)]
-  , pathParameters :: HashMap String String
-  , stageVariables :: HashMap String String
-  , body :: String
-  } deriving (Generic, FromJSON)
-```
-
-Feel free to copy-paste this data type into your project. Note that you don't have to use all of
-it's fields, if you only need, say, the `body` and the `httpMethod` fields, you can use this one
-(`resource` is mandatory):
+If you're using API Gateway, simply pass the `UseWithAPIGateway` option to `generateLambdaDispatcher` in your `app/Main.hs` file.
 
 ```haskell
-data APIGatewayRequest	= APIGatewayRequest
-  { resource :: String
-  , httpMethod :: Method
-  , body :: String
-  } deriving (Generic, FromJSON)
+generateLambdaDispatcher UseWithAPIGateway defaultDispatcherOptions 
 ```
 
-## The response
-
-The response type looks more or less like this:
+Passing `UseWithAPIGateway` will make the compiler error if you do not have your handlers in the following form:
 
 ```haskell
-data APIGatewayResponse = APIGatewayResponse
-  { statusCode :: Int
-  , headers :: [(HeaderName, ByteString)]
-  , body :: String
-  } deriving (Generic, ToJSON)
+handler :: ApiGatewayRequest request -> Context context -> IO (Either (ApiGatewayResponse error) (ApiGatewayResponse success))
+handler = ...
 ```
 
-Again, you can use this type in your project, and use only the fields you need.
-Note that `HeaderName` comes from [`Network.HTTP.Simple`](https://hackage.haskell.org/package/http-conduit-2.3.7.1/docs/Network-HTTP-Simple.html#t:Header).
-
-Notice some fields need implementation of ToJSON. See the example with headers below.
-
-## An example
-
-```haskell top
-{-# LANGUAGE RecordWildCards #-}
-{-# LANGUAGE DuplicateRecordFields #-}
-{-# LANGUAGE DeriveAnyClass #-}
-{-# LANGUAGE DeriveGeneric #-}
-
-module Lib where
-
-import GHC.Generics
-import Aws.Lambda
-import Data.Aeson
-import qualified Data.ByteString.Lazy.Char8 as ByteString
+You can use the `ApiGatewayRequest` wrapper to access additional request information that API Gateway provides, such as path, query string parameters, authentication info and much more. You can find more information about that under the `Input format of a Lambda function for proxy integration` section [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html).
 
--- Input
-data Event = Event
-  { resource :: String
-  , body :: String
-  } deriving (Generic, FromJSON)
+You can use the `ApiGatewayResponse` wrapper in order to return a custom status code or attach custom headers to the response.
 
--- Output
-data Response = Response
-  { statusCode:: Int
-  , body :: String
-  } deriving (Generic, ToJSON)
+Also note the `defaultDispatcherOptions`. They look like this:
 
--- Type that we decode from the 'body' of 'Event'
-data Person = Person
-  { name :: String
-  , age :: Int
-  } deriving (Generic, FromJSON, ToJSON)
-
-greet :: Person -> String
-greet person =
-  "Hello, " ++ name person ++ "!"
-
-handler :: Event -> Context -> IO (Either String Response)
-handler Event{..} context = do
-  case decode (ByteString.pack body) of
-    Just person ->
-      pure $ Right Response
-        { statusCode = 200
-        , body = greet person
-        }
-    Nothing ->
-      pure $ Right Response
-        { statusCode = 200
-        , body = "bad person"
-        }
-```
-## An example with headers
-```src/Hello.hs```
 ```haskell
-{-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE FlexibleInstances #-}
-{-# LANGUAGE RecordWildCards #-}
-{-# LANGUAGE DuplicateRecordFields #-}
-{-# LANGUAGE DeriveAnyClass #-}
-{-# LANGUAGE DeriveGeneric #-}
-
-module Hello where
-
-import           GHC.Generics
-import           Aws.Lambda
-import           Data.Aeson
-import           Network.HTTP.Types.Header
-import           Data.Text.Encoding
-import qualified Data.CaseInsensitive          as CI
-import qualified Data.Aeson.Types              as T
-
--- Input
-data Event = Event
-  { resource :: String
-  , body :: String
-  } deriving (Generic, FromJSON)
-
--- Output
-data ApiGateWayResponse = ApiGateWayResponse
-  { statusCode:: Int
-  , headers :: ResponseHeaders
-  , body :: String
-  } deriving (Generic)
-
--- function to encode Header
-headerToPair :: Header -> T.Pair
-headerToPair (cibyte, bstr) = k .= v
- where
-  k = (decodeUtf8 . CI.original) cibyte
-  v = decodeUtf8 bstr
-
-instance ToJSON ApiGateWayResponse  where
-  toJSON ApiGateWayResponse {..} = object
-    [ "statusCode" .= statusCode
-    , "body" .= body
-    , "headers" .= object (map headerToPair headers)
-    ]
+-- | Options that the dispatcher generator expects
+newtype DispatcherOptions = DispatcherOptions
+  { apiGatewayDispatcherOptions :: ApiGatewayDispatcherOptions
+  } deriving (Lift)
+
+-- | API Gateway specific dispatcher options
+newtype ApiGatewayDispatcherOptions = ApiGatewayDispatcherOptions
+  { propagateImpureExceptions :: Bool
+  -- ^ Should impure exceptions be propagated through the API Gateway interface
+  } deriving (Lift)
+
+defaultDispatcherOptions :: DispatcherOptions
+defaultDispatcherOptions =
+  DispatcherOptions (ApiGatewayDispatcherOptions True)
+```
 
-handler :: Event -> Context -> IO (Either String  ApiGateWayResponse)
-handler Event {..} _ = pure $ Right ApiGateWayResponse
-  { statusCode = 200
-  , headers    = [("Access-Control-Allow-Origin", "*")]
-  , body       = "hello, cors"
-  }
-```
+For production environments, you'd likely want to set `propagateImpureExceptions` to `False` in order to prevent your exception messages from being seen.

doc/index.md

@@ -20,7 +20,7 @@ module WordCount where
 
 import Aws.Lambda
 
-handler :: String -> Context -> IO (Either String Int)
+handler :: String -> Context () -> IO (Either String Int)
 handler someText _ = do
   let wordsCount = length (words someText)
   if wordsCount > 0 then
@@ -34,7 +34,11 @@ Then, in the `Main` module:
 ```haskell
 import Aws.Lambda
 import qualified WordCount
-generateLambdaDispatcher
+
+initializeContext :: IO ()
+initializeContext = return ()
+
+generateLambdaDispatcher StandaloneLambda defaultDispatcherOptions
 ```
 
 # Performance