add docs (#8)

motivation: help users better undersatnd how to use the library

changes:
* add API docs to public APIs
* add narattive docs in README

Author: tomerd

Sources/SwiftAwsLambda/HttpClient.swift

@@ -16,6 +16,7 @@ import Foundation
 import NIO
 import NIOHTTP1
 
+/// A barebone HTTP client to interact with AWS Runtime Engine which is an HTTP server.
 internal class HTTPClient {
     let eventLoop: EventLoop
 

Sources/SwiftAwsLambda/Lambda+Codable.swift

@@ -14,11 +14,19 @@
 
 import Foundation
 
+/// Extension to the `Lambda` companion to enable execution of Lambdas that take and return `Codable` payloads.
+/// This is the most common way to use this library in AWS Lambda, since its JSON based.
 extension Lambda {
+    /// Run a Lambda defined by implementing the `LambdaCodableClosure` closure, having `In` and `Out` extending `Decodable` and `Encodable` respectively.
+    ///
+    /// - note: This is a blocking operation that will run forever, as it's lifecycle is managed by the AWS Lambda Runtime Engine.
     public static func run<In: Decodable, Out: Encodable>(_ closure: @escaping LambdaCodableClosure<In, Out>) {
         self.run(LambdaClosureWrapper(closure))
     }
 
+    /// Run a Lambda defined by implementing the `LambdaCodableHandler` protocol, having `In` and `Out` are `Decodable` and `Encodable` respectively.
+    ///
+    /// - note: This is a blocking operation that will run forever, as it's lifecycle is managed by the AWS Lambda Runtime Engine.
     public static func run<T>(_ handler: T) where T: LambdaCodableHandler {
         self.run(handler as LambdaHandler)
     }
@@ -34,12 +42,18 @@ extension Lambda {
     }
 }
 
+/// A result type for a Lambda that returns a generic `Out`, having `Out` extend `Encodable`.
 public typealias LambdaCodableResult<Out> = Result<Out, String>
 
+/// A callback for a Lambda that returns a `LambdaCodableResult<Out>` result type, having `Out` extend `Encodable`.
 public typealias LambdaCodableCallback<Out> = (LambdaCodableResult<Out>) -> Void
 
+/// A processing closure for a Lambda that takes an `In` and returns an `Out` via `LambdaCodableCallback<Out>` asynchronously,
+/// having `In` and `Out` extending `Decodable` and `Encodable` respectively.
 public typealias LambdaCodableClosure<In, Out> = (LambdaContext, In, LambdaCodableCallback<Out>) -> Void
 
+/// A processing protocol for a Lambda that takes an `In` and returns an `Out` via `LambdaCodableCallback<Out>` asynchronously,
+/// having `In` and `Out` extending `Decodable` and `Encodable` respectively.
 public protocol LambdaCodableHandler: LambdaHandler {
     associatedtype In: Decodable
     associatedtype Out: Encodable
@@ -48,19 +62,22 @@ public protocol LambdaCodableHandler: LambdaHandler {
     var codec: LambdaCodableCodec<In, Out> { get }
 }
 
-// default uses json codec. advanced users that want to inject their own codec can do it here
+/// Default implementation for `LambdaCodableHandler` codec which uses JSON via `LambdaCodableJsonCodec`.
+/// Advanced users that want to inject their own codec can do it by overriding this.
 public extension LambdaCodableHandler {
     var codec: LambdaCodableCodec<In, Out> {
         return LambdaCodableJsonCodec<In, Out>()
     }
 }
 
+/// LambdaCodableCodec is an abstract/empty implementation for codec which does `Encodable` -> `[UInt8]` encoding and `[UInt8]` -> `Decodable' decoding.
 // TODO: would be nicer to use a protocol instead of this "abstract class", but generics get in the way
 public class LambdaCodableCodec<In: Decodable, Out: Encodable> {
     func encode(_: Out) -> [UInt8]? { return nil }
     func decode(_: [UInt8]) -> In? { return nil }
 }
 
+/// Default implementation of `Encodable` -> `[UInt8]` encoding and `[UInt8]` -> `Decodable' decoding
 public extension LambdaCodableHandler {
     func handle(context: LambdaContext, payload: [UInt8], callback: @escaping (LambdaResult) -> Void) {
         guard let payloadAsCodable = codec.decode(payload) else {
@@ -80,6 +97,8 @@ public extension LambdaCodableHandler {
     }
 }
 
+/// LambdaCodableJsonCodec is an implementation of `LambdaCodableCodec` which does `Encodable` -> `[UInt8]` encoding and `[UInt8]` -> `Decodable' decoding
+/// using JSONEncoder and JSONDecoder respectively.
 // This is a class as encoder amd decoder are a class, which means its cheaper to hold a reference to both in a class then a struct.
 private class LambdaCodableJsonCodec<In: Decodable, Out: Encodable>: LambdaCodableCodec<In, Out> {
     private let encoder = JSONEncoder()

Sources/SwiftAwsLambda/Lambda+String.swift

@@ -12,11 +12,18 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// Extension to the `Lambda` companion to enable execution of Lambdas that take and return `String` payloads.
 extension Lambda {
+    /// Run a Lambda defined by implementing the `LambdaStringClosure` protocol.
+    ///
+    /// - note: This is a blocking operation that will run forever, as it's lifecycle is managed by the AWS Lambda Runtime Engine.
     public static func run(_ closure: @escaping LambdaStringClosure) {
         self.run(LambdaClosureWrapper(closure))
     }
 
+    /// Run a Lambda defined by implementing the `LambdaStringHandler` protocol.
+    ///
+    /// - note: This is a blocking operation that will run forever, as it's lifecycle is managed by the AWS Lambda Runtime Engine.
     public static func run(_ handler: LambdaStringHandler) {
         self.run(handler as LambdaHandler)
     }
@@ -32,16 +39,21 @@ extension Lambda {
     }
 }
 
+/// A result type for a Lambda that returns a `String`.
 public typealias LambdaStringResult = Result<String, String>
 
+/// A callback for a Lambda that returns a `LambdaStringResult` result type.
 public typealias LambdaStringCallback = (LambdaStringResult) -> Void
 
+/// A processing closure for a Lambda that takes a `String` and returns a `LambdaStringResult` via `LambdaStringCallback` asynchronously.
 public typealias LambdaStringClosure = (LambdaContext, String, LambdaStringCallback) -> Void
 
+/// A processing protocol for a Lambda that takes a `String` and returns a `LambdaStringResult` via `LambdaStringCallback` asynchronously.
 public protocol LambdaStringHandler: LambdaHandler {
     func handle(context: LambdaContext, payload: String, callback: @escaping LambdaStringCallback)
 }
 
+/// Default implementation of `String` -> `[UInt8]` encoding and `[UInt8]` -> `String' decoding 
 public extension LambdaStringHandler {
     func handle(context: LambdaContext, payload: [UInt8], callback: @escaping LambdaCallback) {
         guard let payloadAsString = String(bytes: payload, encoding: .utf8) else {

Sources/SwiftAwsLambda/Lambda.swift

@@ -16,10 +16,16 @@ import Foundation
 import NIO
 
 public enum Lambda {
+    /// Run a Lambda defined by implementing the `LambdaClosure` closure.
+    ///
+    /// - note: This is a blocking operation that will run forever, as it's lifecycle is managed by the AWS Lambda Runtime Engine.
     public static func run(_ closure: @escaping LambdaClosure) {
         let _: LambdaLifecycleResult = run(closure)
     }
 
+    /// Run a Lambda defined by implementing the `LambdaHandler` protocol.
+    ///
+    /// - note: This is a blocking operation that will run forever, as it's lifecycle is managed by the AWS Lambda Runtime Engine.
     public static func run(_ handler: LambdaHandler) {
         let _: LambdaLifecycleResult = run(handler: handler)
     }
@@ -132,12 +138,15 @@ public enum Lambda {
     }
 }
 
+/// A result type for a Lambda that returns a `[UInt8]`.
 public typealias LambdaResult = Result<[UInt8], String>
 
 public typealias LambdaCallback = (LambdaResult) -> Void
 
+/// A processing closure for a Lambda that takes a `[UInt8]` and returns a `LambdaResult` result type asynchronously.
 public typealias LambdaClosure = (LambdaContext, [UInt8], LambdaCallback) -> Void
 
+/// A processing protocol for a Lambda that takes a `[UInt8]` and returns a `LambdaResult` result type asynchronously.
 public protocol LambdaHandler {
     func handle(context: LambdaContext, payload: [UInt8], callback: @escaping LambdaCallback)
 }

Sources/SwiftAwsLambda/LambdaRunner.swift

@@ -15,6 +15,7 @@
 import Foundation
 import NIO
 
+/// LambdaRunner manages the Lambda runtime workflow, or business logic.
 internal final class LambdaRunner {
     private let lambdaHandler: LambdaHandler
     private let runtimeClient: LambdaRuntimeClient

Sources/SwiftAwsLambda/LambdaRuntimeClient.swift

@@ -16,6 +16,10 @@ import Foundation
 import NIO
 import NIOHTTP1
 
+/// An HTTP based client for AWS Runtime Engine. This encapsulates the RESTful methods exposed by the Runtime Engine:
+/// * /runtime/invocation/next
+/// * /runtime/invocation/response
+/// * /runtime/invocation/error
 internal class LambdaRuntimeClient {
     private let baseUrl: String
     private let httpClient: HTTPClient

Sources/SwiftAwsLambda/Utils.swift

@@ -15,11 +15,17 @@
 import Dispatch
 import NIO
 
+/// Genric result type, that is used throught the library.
 public enum Result<Value, Error> {
     case success(Value)
     case failure(Error)
 }
 
+internal enum Defaults {
+    static let host = "127.0.0.1"
+    static let port = 8080
+}
+
 internal enum Consts {
     static let hostPortEnvVariableName = "AWS_LAMBDA_RUNTIME_API"
 
@@ -30,6 +36,7 @@ internal enum Consts {
     static let postErrorURLSuffix = "/error"
 }
 
+/// AWS Lambda HTTP Headers, used to populate the `LambdaContext` object.
 internal enum AmazonHeaders {
     static let requestID = "Lambda-Runtime-Aws-Request-Id"
     static let traceID = "Lambda-Runtime-Trace-Id"
@@ -39,11 +46,7 @@ internal enum AmazonHeaders {
     static let invokedFunctionARN = "Lambda-Runtime-Invoked-Function-Arn"
 }
 
-internal enum Defaults {
-    static let host = "127.0.0.1"
-    static let port = 8080
-}
-
+/// Utility to read environment variables
 internal enum Environment {
     static func string(name: String, defaultValue: String) -> String {
         return self.string(name) ?? defaultValue
@@ -68,16 +71,7 @@ internal enum Environment {
     }
 }
 
-internal enum Signal: Int32 {
-    case HUP = 1
-    case INT = 2
-    case QUIT = 3
-    case ABRT = 6
-    case KILL = 9
-    case ALRM = 14
-    case TERM = 15
-}
-
+/// Helper function to trap signals
 internal func trap(signal sig: Signal, handler: @escaping (Signal) -> Void) -> DispatchSourceSignal {
     let signalSource = DispatchSource.makeSignalSource(signal: sig.rawValue, queue: DispatchQueue.global())
     signal(sig.rawValue, SIG_IGN)
@@ -88,3 +82,13 @@ internal func trap(signal sig: Signal, handler: @escaping (Signal) -> Void) -> D
     signalSource.resume()
     return signalSource
 }
+
+internal enum Signal: Int32 {
+    case HUP = 1
+    case INT = 2
+    case QUIT = 3
+    case ABRT = 6
+    case KILL = 9
+    case ALRM = 14
+    case TERM = 15
+}

Tests/SwiftAwsLambdaTests/LambdaContextTest.swif

@@ -1,6 +1,6 @@
 # Swift AWS Lambda
 
-This library is designed to allow writing AWS Lambdas using the Swift programming language.
+This library is designed to simplify implementing an AWS Lambda using the Swift programming language.
 
 ## Getting started
 
@@ -25,26 +25,45 @@ This library is designed to allow writing AWS Lambdas using the Swift programmin
   )
   ```
 
-  2. Create a main.swift and implement you lambda. typically a lambda is implemented as a closure. For example, a simple lambda for a closure that receives a string payload and replies with the reverse version:
+  2. Create a main.swift and implement your Lambda. Typically a Lambda is implemented as a closure. For example, a simple closure that receives a string payload and replies with the reverse version:
 
   ```
   import SwiftAwsLambda
 
-  _ = Lambda.run { (context: LambdaContext, payload: String, callback: LambdaStringCallback) in
+  Lambda.run { (context: LambdaContext, payload: String, callback: LambdaStringCallback) in
       callback(.success(String(payload.reversed())))
   }
   ```
 
-note you can implement 3 types of lambdas:
+  SwiftAwsLambda supports three types of Lambdas:
+    1. `[UInt8]` (byte array) based (default): see `SwiftAwsLambdaExample`
+    2. `String` based: see `SwiftAwsLambdaStringExample`
+    3. `Codable` based: see `SwiftAwsLambdaCodableExample`. This is the most pragmatic mode of operation, since AWS Lambda is JSON based.
 
-1. `[UInt8]` (byte array) based (default): see `SwiftAwsLambdaExample`
-2. `String` based: see `SwiftAwsLambdaStringExample`
-3. `Codable` based: see `SwiftAwsLambdaCodableExample`
+    See more on [SwiftAwsLambda Sample](https://github.com/swift-server/swift-aws-lambda-sample).
+
+  3. Deploy to AWS Lambda. To do so, you need to compile your Application for EC2 Linux, package it as a Zip file, and upload to AWS. You can find sample build and deployment scripts in [SwiftAwsLambda Sample](https://github.com/swift-server/swift-aws-lambda-sample).
 
 ## Architecture
 
-TODO
+The library is designed to integrate with AWS Lambda Runtime Engine, via the BYOL Native Runtime API.
+The latter is an HTTP server that exposes three main RESTful endpoint:
+* /runtime/invocation/next
+* /runtime/invocation/response
+* /runtime/invocation/error
+
+The library encapsulates these endpoints and the expected lifecycle via `LambdaRuntimeClient` and `LambdaRunner` respectively.
+
+**Single Lambda Execution Workflow**
+
+1. The library calls AWS Lambda Runtime Engine `/next` endpoint to retrieve the next invocation request.
+2. The library parses the response HTTP headers and populate the `LambdaContext` object.
+3. The library reads the response body and attempt to decode it, if required. Typically it decodes to user provided type which extends  `Decodable`, but users may choose to write Lambdas that receive the input as `String` or `[UInt8]` byte array which require less, or no decoding.
+4. The library hands off the `Context` and `Request` to the user provided handler on a dedicated `Dispatch` queue, providing isolation between user's and the library's code.
+5. User's code processes the request asynchronously, invoking a callback upon completion, which returns a result type with the `Response` or `Error` populated.
+6. In case of error, the library posts to AWS Lambda Runtime Engine `/error` endpoint to provide the error details, which will show up on AWS Lambda logs.
+7. In case of success, the library will attempt to encode the response, if required. Typically it encodes from user provided type which extends `Encodable`, but users may choose to write Lambdas that return a `String` or `[UInt8]` byte array, which require less, or no encoding. The library then posts to AWS Lambda Runtime Engine `/response` endpoint to provide the response.
 
-## Deploying
+**Lifecycle Management**
 
-TODO
+AWS Runtime Engine controls the Application lifecycle and in the happy case never terminates the application, only suspends it's execution when no work is avaialble. As such, the library main entry point is designed to run forever in a blocking fashion, performing the workflow described above in an endless loop. That loop is broken if/when an internal error occurs, such as a failure to communicate with AWS Runtime Engine API, or under other unexpected conditions.