Breaking change: Merge pull request #72 from dnikolovv/persistent-execution-context

Persistent execution context

Author: Nick Tchayka

aws-lambda-haskell-runtime.cabal

@@ -4,10 +4,10 @@ cabal-version: 1.12
 --
 -- see: https://github.com/sol/hpack
 --
--- hash: eab5b338b49db7854613ecd43b17245f105c8c936c40230ecf9d08c5dfad9d6d
+-- hash: c21b3c988844f7c4bfb806aff4e307c5d5dc63a7973eff4a83eb329e7bccb1c9
 
 name:           aws-lambda-haskell-runtime
-version:        2.0.6
+version:        3.0.0
 synopsis:       Haskell runtime for AWS Lambda
 description:    Please see the README on GitHub at <https://github.com/theam/aws-lambda-haskell-runtime#readme>
 category:       AWS
@@ -46,6 +46,7 @@ library
       Aws.Lambda.Runtime.Environment
       Aws.Lambda.Runtime.Error
       Aws.Lambda.Runtime.Publish
+      Aws.Lambda.Utilities
       Paths_aws_lambda_haskell_runtime
   hs-source-dirs:
       src

doc/01-getting-started.md

@@ -22,7 +22,7 @@ If you are testing the package, or you are starting a new project, we have provi
 To use it, enter the following command:
 
 ```bash
-stack new my-haskell-lambda https://github.com/theam/aws-lambda-haskell-runtime/raw/master/stack-template.hsfiles --resolver=lts-13.25 --omit-packages
+stack new my-haskell-lambda https://github.com/theam/aws-lambda-haskell-runtime/raw/master/stack-template.hsfiles --resolver=lts-15.16 --omit-packages
 ```
 
 This will create a `my-haskell-lambda` directory with the following structure:
@@ -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,34 @@ 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 #-}
+{-# LANGUAGE TemplateHaskell     #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+
 module Main where
 import Aws.Lambda
 ```
 
-After this, add a line with the following statement:
+After this, add the following lines:
 
 ```haskell
-generateLambdaDispatcher
+-- Use this action if you want to have context that is shared between lambda calls.
+-- It is called once per every cold start. We do not wish to have a shared context for our lambda, so we simply use Unit.
+initializeContext :: IO ()
+initializeContext = return ()
+
+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

examples/wai-app/.gitignore

@@ -0,0 +1,4 @@
+.stack-work/
+*~
+build
+*.iml

examples/wai-app/ChangeLog.md

@@ -0,0 +1,3 @@
+# Changelog for lambda-testing
+
+## Unreleased changes

examples/wai-app/LICENSE

@@ -0,0 +1,30 @@
+Copyright Dobromir Nikolov (c) 2020
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+    * Neither the name of Dobromir Nikolov nor the names of other
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.