Initial Implementation (#4)

* Define package targets

* Protocols and extensions

* Helper types

* Additional documentation, tweaks

* Improve error descriptions

* Improve documentation

* Generalize default implementations

* Remove unused annotation

* Add documentation catalog

* Error improvements

* Additional RuntimeContext members

* FunctionContext -> EnvironmentValueProvider

* Add InitializationContext protocol

* Add Coding protocol, APIGateway implementation

* Remove EventHandler, HandlerProvider

* Refactor targets

* Remove main and mocks for now

* Additional helpers

* Implement main library

* Implement mocks

* Fix JSON

Author: mgacy

.gitignore

@@ -88,3 +88,6 @@ fastlane/test_output
 # https://github.com/johnno1962/injectionforxcode
 
 iOSInjectionProject/
+
+# IDEs and Editors
+.vscode

.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>FILEHEADER</key>
+	<string>
+//  ___FILENAME___
+//  LambdaExtras
+//
+//  Created by ___FULLUSERNAME___ on ___DATE___.
+//</string>
+</dict>
+</plist>

.swiftpm/xcode/package.xcworkspace/xcshareddata/IDETemplateMacros.plist

@@ -0,0 +1,51 @@
+// swift-tools-version: 5.7
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-lambda-extras",
+    platforms: [.macOS(.v12)],
+    products: [
+        .library(name: "LambdaExtras", targets: ["LambdaExtras"]),
+        // Core library; does not link AWS products.
+        .library(name: "LambdaExtrasCore", targets: ["LambdaExtrasCore"]),
+        // Testing helpers
+        .library(name: "LambdaMocks", targets: ["LambdaMocks"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-log.git", .upToNextMajor(from: "1.4.2")),
+        .package(url: "https://github.com/apple/swift-nio.git", .upToNextMajor(from: "2.43.1")),
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-events", branch: "main"),
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime", branch: "main")
+    ],
+    targets: [
+        .target(
+            name: "LambdaExtrasCore",
+            dependencies: [
+                .product(name: "Logging", package: "swift-log"),
+                .product(name: "NIOCore", package: "swift-nio")
+            ]
+        ),
+        .target(
+            name: "LambdaExtras",
+            dependencies: [
+                "LambdaExtrasCore",
+                .product(name: "AWSLambdaRuntime",package: "swift-aws-lambda-runtime"),
+                .product(name: "AWSLambdaEvents", package: "swift-aws-lambda-events")
+            ]
+        ),
+        .target(
+            name: "LambdaMocks",
+            dependencies: [
+                "LambdaExtrasCore"
+            ]
+        ),
+        .testTarget(
+            name: "LambdaExtrasTests",
+            dependencies: [
+                "LambdaExtras"
+            ]
+        )
+    ]
+)

Package.resolved

@@ -0,0 +1,83 @@
+//
+//  APIGatewayCoder.swift
+//  LambdaExtras
+//
+//  Created by Mathew Gacy on 12/14/23.
+//
+
+import AWSLambdaEvents
+import AWSLambdaRuntime
+import Foundation
+import LambdaExtrasCore
+
+/// A coder for APIGateway events.
+public struct APIGatewayCoder<E, O>: LambdaCoding where E: Codable, E: Sendable, O: Sendable {
+    /// A JSON decoder.
+    let decoder: JSONDecoder
+
+    /// A closure returning a response body from the given underlying output.
+    let responseBodyProvider: @Sendable (O) -> String?
+
+    /// Creates an instance.
+    ///
+    /// - Parameters:
+    ///   - decoder: A JSON decoder.
+    ///   - responseBody: A closure returning a response body from the given output.
+    public init(
+        decoder: JSONDecoder = .init(),
+        responseBody: @escaping @Sendable (O) -> String? = { _ in nil }
+    ) {
+        self.decoder = decoder
+        self.responseBodyProvider = responseBody
+    }
+
+    public func decode(event: APIGatewayV2Request) async throws -> E {
+        guard let body = event.body else {
+            throw HandlerError.emptyBody
+        }
+
+        return try decoder.decode(E.self, from: body)
+    }
+
+    public func encode(output: O) throws -> APIGatewayV2Response {
+        APIGatewayV2Response(
+            statusCode: .ok,
+            body: responseBodyProvider(output))
+    }
+
+    public func encode(error: Error) throws -> APIGatewayV2Response {
+        switch error {
+        case HandlerError.emptyBody:
+            return APIGatewayV2Response(
+                statusCode: .badRequest,
+                body: errorResponseBody(error.localizedDescription))
+
+        case HandlerError.envError:
+            return APIGatewayV2Response(
+                statusCode: .internalServerError,
+                body: errorResponseBody(error.localizedDescription))
+
+        case HandlerError.custom(let message):
+            return APIGatewayV2Response(
+                statusCode: .internalServerError,
+                body: message.flatMap(errorResponseBody))
+
+        default:
+            return APIGatewayV2Response(
+                statusCode: .internalServerError,
+                body: errorResponseBody(error.localizedDescription))
+        }
+    }
+}
+
+private extension APIGatewayCoder {
+    /// Returns a response body for the given error.
+    ///
+    /// - Parameter message: The error message
+    /// - Returns: The response body.
+    private func errorResponseBody(_ message: String) -> String {
+        """
+        {"reason": "\(message)"}
+        """
+    }
+}

Package.swift

@@ -0,0 +1,14 @@
+//
+//  DefaultEnvironment.swift
+//  LambdaExtras
+//
+//  Created by Mathew Gacy on 12/14/23.
+//
+
+import Foundation
+
+/// The default lambda environment.
+public enum DefaultEnvironment: String {
+    /// The log level of the lambda's logger.
+    case logLevel = "LOG_LEVEL"
+}

Sources/LambdaExtras/APIGatewayCoder.swift

@@ -0,0 +1,11 @@
+# ``LambdaExtras``
+
+Swifty helpers for working with AWS Lambda.
+
+## Overview
+
+`LambdaExtras` provides helper types that make it easier to create AWS Lambdas.
+
+## Topics
+
+### Essentials

Sources/LambdaExtras/DefaultEnvironment.swift

@@ -0,0 +1 @@
+@_exported import LambdaExtrasCore

Sources/LambdaExtras/Documentation.docc/LambdaExtras.md

@@ -0,0 +1,46 @@
+//
+//  Extensions.swift
+//  LambdaExtras
+//
+//  Created by Mathew Gacy on 12/15/23.
+//
+
+import AWSLambdaRuntime
+import AWSLambdaRuntimeCore
+import Foundation
+import LambdaExtrasCore
+import NIOCore
+
+public extension EnvironmentValueProvider where EnvironmentVariable == String {
+    /// Returns the value of the given environment variable.
+    ///
+    /// - Parameter environmentVariable: The environment variable whose value should be returned.
+    func value(for environmentVariable: EnvironmentVariable) throws -> String {
+        guard let value = Lambda.env(environmentVariable) else {
+            throw HandlerError.envError(environmentVariable)
+        }
+
+        return value
+    }
+}
+
+public extension EnvironmentValueProvider where EnvironmentVariable: RawRepresentable<String> {
+    /// Returns the value of the given environment variable.
+    ///
+    /// - Parameter environmentVariable: The environment variable whose value should be returned.
+    func value(for environmentVariable: EnvironmentVariable) throws -> String {
+        guard let value = Lambda.env(environmentVariable.rawValue) else {
+            throw HandlerError.envError(environmentVariable.rawValue)
+        }
+
+        return value
+    }
+}
+
+extension LambdaContext: RuntimeContext {}
+
+extension LambdaInitializationContext: InitializationContext {
+    public func handleShutdown(_ handler: @escaping (EventLoop) -> EventLoopFuture<Void>) {
+        terminator.register(name: "shutdown", handler: handler)
+    }
+}