Infernal

The Infernal Machine - An AWS Lambda Custom Runtime for Haskell

See runLambda or runSimpleLambda for entrypoints to build your Lambda function.

Documentation

data CallbackConfig n

User callbacks to be invoked by the main loop (see runLambda).

Constructors

CallbackConfig

Fields

• _cbcRunCallback :: !(RunCallback n)

  See RunCallback

• _cbcInvokeErrorCallback :: !(InvokeErrorCallback n)

  See InvokeErrorCallback

• _cbcUncaughtErrorCallback :: !(UncaughtErrorCallback n)

  See UncaughtErrorCallback

type InitErrorCallback n = SomeException -> n LambdaError

Error mapper for init errors. The result will be POSTed to the init error endpoint (docs). Exceptions of type LambdaError will not trigger this callback, and ExitCode will be rethrown after it executes.

type InvokeErrorCallback n = LambdaRequest -> SomeException -> n LambdaError

Error mapper for invocation errors. The result will be POSTed to the invocation error endpoint (docs). Exceptions of type LambdaError will not trigger this callback, and ExitCode will be rethrown after it executes.

data LambdaError

An error formatted to propagate to AWS (docs). Note that this is an Exception so you can throw it to short-circuit processing and report useful information. By default, if you throw anything else a defaultLambdaError will be reported with no useful information.

Constructors

LambdaError

Fields

• _lerrErrorType :: !Text

  The type of error that occurred. In this library is is often StartCase-formated.

• _lerrErrorMessage :: !Text

  A useful error message

Instances

Eq LambdaError

Defined in Infernal

Methods

(==) :: LambdaError -> LambdaError -> Bool

(/=) :: LambdaError -> LambdaError -> Bool

Show LambdaError

Defined in Infernal

Methods

showsPrec :: Int -> LambdaError -> ShowS

show :: LambdaError -> String

showList :: [LambdaError] -> ShowS

Generic LambdaError

Defined in Infernal

Associated Types

type Rep LambdaError :: Type -> Type

Methods

from :: LambdaError -> Rep LambdaError x

to :: Rep LambdaError x -> LambdaError

ToJSON LambdaError

Defined in Infernal

Methods

toJSON :: LambdaError -> Value

toEncoding :: LambdaError -> Encoding

toJSONList :: [LambdaError] -> Value

toEncodingList :: [LambdaError] -> Encoding

Exception LambdaError

Defined in Infernal

Methods

toException :: LambdaError -> SomeException

fromException :: SomeException -> Maybe LambdaError

displayException :: LambdaError -> String

type Rep LambdaError

Defined in Infernal

type Rep LambdaError = D1 (MetaData "LambdaError" "Infernal" "infernal-0.3.0-6x9jhkeaDTq78l8lsFd4SM" False) (C1 (MetaCons "LambdaError" PrefixI True) (S1 (MetaSel (Just "_lerrErrorType") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Text) :*: S1 (MetaSel (Just "_lerrErrorMessage") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Text)))

newtype LambdaRequestId

The UUID associated with a Lambda request.

Constructors

LambdaRequestId

Fields

• _unLambdaRequestId :: Text

Instances

Eq LambdaRequestId

Defined in Infernal

Methods

(==) :: LambdaRequestId -> LambdaRequestId -> Bool

(/=) :: LambdaRequestId -> LambdaRequestId -> Bool

Ord LambdaRequestId

Defined in Infernal

Methods

compare :: LambdaRequestId -> LambdaRequestId -> Ordering

(<) :: LambdaRequestId -> LambdaRequestId -> Bool

(<=) :: LambdaRequestId -> LambdaRequestId -> Bool

(>) :: LambdaRequestId -> LambdaRequestId -> Bool

(>=) :: LambdaRequestId -> LambdaRequestId -> Bool

max :: LambdaRequestId -> LambdaRequestId -> LambdaRequestId

min :: LambdaRequestId -> LambdaRequestId -> LambdaRequestId

Show LambdaRequestId

Defined in Infernal

Methods

showsPrec :: Int -> LambdaRequestId -> ShowS

show :: LambdaRequestId -> String

showList :: [LambdaRequestId] -> ShowS

IsString LambdaRequestId

Defined in Infernal

Methods

fromString :: String -> LambdaRequestId

Hashable LambdaRequestId

Defined in Infernal

Methods

hashWithSalt :: Int -> LambdaRequestId -> Int

hash :: LambdaRequestId -> Int

data LambdaRequest

The request parsed from the "next invocation" API (docs)

Constructors

LambdaRequest

Fields

• _lreqId :: !LambdaRequestId

  From the Lambda-Runtime-Aws-Request-Id header

• _lreqTraceId :: !Text

  From the Lambda-Runtime-Trace-Id header

• _lreqFunctionArn :: !Text

  From the Lambda-Runtime-Invoked-Function-Arn header

• _lreqDeadlineMs :: !Int

  From the Lambda-Runtime-Deadline-Ms header, an epoch deadline in ms

• _lreqBody :: !ByteString

  The unparsed request body. Typically you will decode this.

Instances

Eq LambdaRequest

Defined in Infernal

Methods

(==) :: LambdaRequest -> LambdaRequest -> Bool

(/=) :: LambdaRequest -> LambdaRequest -> Bool

Show LambdaRequest

Defined in Infernal

Methods

showsPrec :: Int -> LambdaRequest -> ShowS

show :: LambdaRequest -> String

showList :: [LambdaRequest] -> ShowS

newtype LambdaResponse

A response to the LambdaRequest, typically as encoded JSON.

Constructors

LambdaResponse

Fields

• _unLambdaResponse :: ByteString

Instances

Eq LambdaResponse

Defined in Infernal

Methods

(==) :: LambdaResponse -> LambdaResponse -> Bool

(/=) :: LambdaResponse -> LambdaResponse -> Bool

Ord LambdaResponse

Defined in Infernal

Methods

compare :: LambdaResponse -> LambdaResponse -> Ordering

(<) :: LambdaResponse -> LambdaResponse -> Bool

(<=) :: LambdaResponse -> LambdaResponse -> Bool

(>) :: LambdaResponse -> LambdaResponse -> Bool

(>=) :: LambdaResponse -> LambdaResponse -> Bool

max :: LambdaResponse -> LambdaResponse -> LambdaResponse

min :: LambdaResponse -> LambdaResponse -> LambdaResponse

Show LambdaResponse

Defined in Infernal

Methods

showsPrec :: Int -> LambdaResponse -> ShowS

show :: LambdaResponse -> String

showList :: [LambdaResponse] -> ShowS

IsString LambdaResponse

Defined in Infernal

Methods

fromString :: String -> LambdaResponse

Hashable LambdaResponse

Defined in Infernal

Methods

hashWithSalt :: Int -> LambdaResponse -> Int

hash :: LambdaResponse -> Int

data LambdaVars

Environment variables set by AWS (docs). You may not need to read any of these, but the implementation needs the API endpoint var to handle requests.

Constructors

LambdaVars

Fields

• _lvLogGroupName :: !Text

  From the AWS_LAMBDA_LOG_GROUP_NAME env var

• _lvLogStreamName :: !Text

  From the AWS_LAMBDA_LOG_STREAM_NAME env var

• _lvFunctionVersion :: !Text

  From the AWS_LAMBDA_FUNCTION_VERSION env var

• _lvFunctionName :: !Text

  From the AWS_LAMBDA_FUNCTION_NAME env var

• _lvTaskRoot :: !Text

  From the LAMBDA_TASK_ROOT env var

• _lvApiEndpoint :: !Text

  From the AWS_LAMBDA_RUNTIME_API env var

• _lvFunctionMemory :: !Text

  From the AWS_LAMBDA_FUNCTION_MEMORY_SIZE env var

• _lvHandlerName :: !Text

  From the _HANDLER env var

type RunCallback n = LambdaRequest -> n LambdaResponse

The "function" part of your Lambda: takes a request with a JSON-encoded body and returns a JSON-encoded response body. You can throw any Exception and the appropriate error callbacks will process it. Most importantly, LambdaError will propagate a formatted error to AWS, and ExitCode will halt the program. Except for ExitCode, throwing exceptions here will not terminate the main loop (see runLambda). Note that the AWS custom runtime loop implemented in this library is single-threaded (as required - we must finish an invocation before fetching the next) but you are free to spawn threads in your callback.

type UncaughtErrorCallback n = SomeException -> n ()

A handler for otherwise uncaught errors (like failures to fetch next invocation). These happen outside context in which we can report them to AWS, so there is no need to return a LambdaError. Exceptions of type ExitCode will be rethrown after this callback executes.

decodeRequest :: (MonadThrow m, FromJSON a) => LambdaRequest -> m a

Decodes a request with FromJSON or throws a LambdaError (BadRequestError).

defaultCallbackConfig :: Applicative n => RunCallback n -> CallbackConfig n

A CallbackConfig that returns defaultLambdaError from all error callbacks.

defaultLambdaError :: LambdaError

A LambdaError that indicates a vague InternalError to AWS.

defaultInitErrorCallback :: Applicative n => InitErrorCallback n

A InitErrorCallback that always returns defaultLambdaError.

encodeResponse :: ToJSON a => a -> LambdaResponse

Encodes a response with ToJSON. (Mostly here to save you an Aeson import.)

runLambda

Arguments

:: (MonadCatch m, WithSimpleLog env m)

=> UnliftIO n

Runs your monad n in IO (see MonadUnliftIO from unliftio-core)

-> InitErrorCallback n

Error mapper for the callback builder

-> (LambdaVars -> n (CallbackConfig n))

Callback builder. When possible, do init work here so the framework can propagate init errors to AWS.

-> m ()

The full-powered entrypoint underlying runSimpleLambda that allows you to use any UnliftIO-capable monad for your callbacks. This runs the main loop of our AWS Lambda Custom Runtime to fetch invocations, process them, and report errors or results. Control will not return from this function, and AWS Lambda will terminate the process at its will.

runSimpleLambda :: RunCallback (RIO App) -> IO ()

A simple entrypoint that delegates to runLambda. Use this as the body of your main function if you want to get a Lambda function up and running quickly. All you need to do is provide a RunCallback that handles JSON-encoded requests and returns JSON-encoded responses (or throws LambdaError exceptions). Your callback has access to a simple logger (try logDebug, for example) whose output will be collected by Lambda and published to CloudWatch.