[plugin] add a deployer plugin + SAM example

.gitignore

@@ -8,3 +8,4 @@
 xcuserdata
 Package.resolved
 .serverless
+.vscode

Examples/SAM/Deploy.swift

@@ -0,0 +1,71 @@
+import AWSLambdaDeploymentDescriptor
+
+// example of a shared resource
+let sharedQueue : Resource = Resource.queue(logicalName: "SharedQueue",
+                                            physicalName: "swift-lambda-shared-queue")
+
+// example of common environment variables
+let sharedEnvironementVariables = ["LOG_LEVEL":"debug"]
+
+let _ = DeploymentDefinition(
+
+    description: "Working SAM template for Swift Lambda function",
+
+    functions: [
+
+        .function(
+            // the name of the function
+            name: "HttpApiLambda",
+
+            // the AWS Lambda architecture (defaults to current build platform)
+            //architecture: .x64,
+
+            // the event sources
+            eventSources: [
+                // example of a catch all API
+//                .httpApi(),
+
+                // example of an API for a specific path and specific http verb
+                .httpApi(method: .GET, path: "/test"),
+            ],
+
+            // optional environment variables - one variable
+            //environment: .variable("NAME","VALUE")
+
+            // optional environment variables - multiple environment variables at once
+            environment: .variable([sharedEnvironementVariables, ["NAME2":"VALUE2"]])
+        ),
+
+        .function(
+            name: "SQSLambda",
+            eventSources: [
+                // this will reference an existing queue
+//                .sqs(queue: "arn:aws:sqs:eu-central-1:012345678901:swift-lambda-shared-queue"),
+
+                // this will create a new queue resource
+                .sqs(queue: "swift-lambda-queue-name"),
+
+                // this will create a new queue resource
+//                .sqs(queue: .queue(logicalName: "LambdaQueueResource", physicalName: "swift-lambda-queue-resource"))
+
+                // this will reference a queue resource created in this deployment descriptor
+//                .sqs(queue: sharedQueue)
+            ],
+            environment: .variable(sharedEnvironementVariables)
+        )
+    ],
+
+    // additional resources
+    resources: [
+
+        // create a SQS queue
+        .queue(logicalName: "TopLevelQueueResource",
+               physicalName: "swift-lambda-top-level-queue"),
+
+        // create a DynamoDB table
+        .table(logicalName: "SwiftLambdaTable",
+               physicalName: "swift-lambda-table",
+               primaryKeyName: "id",
+               primaryKeyType: "String")
+    ]
+)

Examples/SAM/HttpApiLambda/Lambda.swift

@@ -0,0 +1,52 @@
+// ===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftAWSLambdaRuntime project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// ===----------------------------------------------------------------------===//
+
+import AWSLambdaEvents
+import AWSLambdaRuntime
+import Foundation
+
+@main
+struct HttpApiLambda: SimpleLambdaHandler {    
+    init() {}
+    init(context: LambdaInitializationContext) async throws {
+        context.logger.info(
+            "Log Level env var : \(ProcessInfo.processInfo.environment["LOG_LEVEL"] ?? "info" )")
+    }
+
+    // the return value must be either APIGatewayV2Response or any Encodable struct
+    func handle(_ event: APIGatewayV2Request, context: AWSLambdaRuntimeCore.LambdaContext) async throws -> APIGatewayV2Response {
+
+        var header = HTTPHeaders()
+        do {
+            context.logger.debug("HTTP API Message received")
+
+            header["content-type"] = "application/json"
+
+            // echo the request in the response
+            let data = try JSONEncoder().encode(event)
+            let response = String(data: data, encoding: .utf8)
+
+            // if you want contronl on the status code and headers, return an APIGatewayV2Response
+            // otherwise, just return any Encodable struct, the runtime will wrap it for you
+            return APIGatewayV2Response(statusCode: .ok, headers: header, body: response)
+
+        } catch {
+            // should never happen as the decoding was made by the runtime
+            // when the input event is malformed, this function is not even called
+            header["content-type"] = "text/plain"
+            return APIGatewayV2Response(statusCode: .badRequest, headers: header, body: "\(error.localizedDescription)")
+
+        }
+    }
+}

Examples/SAM/Makefile

@@ -0,0 +1,40 @@
+build:
+	swift build
+
+update: 
+	swift package update
+
+test:
+	swift test
+
+release:
+	swift build -c release
+
+archive: build
+	swift package --disable-sandbox archive
+
+deploy: build
+	swift package --disable-sandbox deploy --configuration debug 
+
+nodeploy: build
+	swift package --disable-sandbox deploy --verbose --nodeploy --configuration debug 
+
+localtest:
+	sam local invoke -t sam.json -e Tests/LambdaTests/data/apiv2.json HttpApiLambda 
+
+list: 
+	sam list endpoints -t sam.json --stack-name swift-aws-lambda-runtime-example --output json
+
+clean:
+	# find . -name .build -exec rm -rf {} \;
+	# find . -name .swiftpm -exec rm -rf {} \;
+	# find . -name dist -exec rm -rf {} \;
+	rm -rf ../../.build 
+	rm -rf .build
+
+test-generate:
+	/usr/bin/swift \
+		-L .build/debug  \
+		-I .build/debug \
+		-lAWSLambdaDeploymentDescriptor \
+		./Deploy.swift

Examples/SAM/Package.swift

@@ -0,0 +1,73 @@
+// swift-tools-version:5.7
+
+// ===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftAWSLambdaRuntime project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// ===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+  name: "swift-aws-lambda-runtime-example",
+  platforms: [
+    .macOS(.v12)
+  ],
+  products: [
+    .executable(name: "HttpApiLambda", targets: ["HttpApiLambda"]),
+    .executable(name: "SQSLambda", targets: ["SQSLambda"]),
+  ],
+  dependencies: [
+    // this is the dependency on the swift-aws-lambda-runtime library
+    // in real-world projects this would say
+    // .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", branch: "main"),
+    .package(name: "swift-aws-lambda-runtime", path: "../.."),
+    .package(url: "https://github.com/swift-server/swift-aws-lambda-events.git", branch: "main")
+  ],
+  targets: [
+    .executableTarget(
+      name: "HttpApiLambda",
+      dependencies: [
+        .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"),
+        .product(name: "AWSLambdaEvents", package: "swift-aws-lambda-events"),
+      ],
+      path: "./HttpApiLambda"
+    ),
+    .executableTarget(
+      name: "SQSLambda",
+      dependencies: [
+        .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"),
+        .product(name: "AWSLambdaEvents", package: "swift-aws-lambda-events"),
+      ] ,
+      path: "./SQSLambda"
+    ),
+    .testTarget(
+      name: "LambdaTests",
+      dependencies: [
+        "HttpApiLambda", "SQSLambda",
+        .product(name: "AWSLambdaTesting", package: "swift-aws-lambda-runtime"),
+
+        // at least one target must have this dependency. It ensures the dylib is built
+        // The dylib is loaded dynamically by the deploy plugin when compiling Deploy.swift.
+        // The Lambda functions or the tests do not actually depend on it.
+        // I choose to add the dependency on a test target, because the archive plugin
+        // links the executable targets with --static-swift-stdlib which cannot include this dynamic library,
+        // and causes the build to fail
+        .product(name: "AWSLambdaDeploymentDescriptor", package: "swift-aws-lambda-runtime")
+      ],
+      // testing data 
+      resources: [
+        .process("data/apiv2.json"),
+        .process("data/sqs.json")
+      ]
+    )
+  ]
+)

Examples/SAM/SQSLambda/Lambda.swift

@@ -0,0 +1,40 @@
+// ===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftAWSLambdaRuntime project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// ===----------------------------------------------------------------------===//
+
+import AWSLambdaEvents
+import AWSLambdaRuntime
+import Foundation
+
+@main
+struct SQSLambda: SimpleLambdaHandler {
+    typealias Event = SQSEvent
+    typealias Output = Void
+
+    init() {}
+    init(context: LambdaInitializationContext) async throws {
+        context.logger.info(
+            "Log Level env var : \(ProcessInfo.processInfo.environment["LOG_LEVEL"] ?? "info" )")
+    }
+
+    func handle(_ event: Event, context: AWSLambdaRuntimeCore.LambdaContext) async throws -> Output {
+
+        context.logger.info("Log Level env var : \(ProcessInfo.processInfo.environment["LOG_LEVEL"] ?? "not defined" )" )
+        context.logger.debug("SQS Message received, with \(event.records.count) record")
+
+        for msg in event.records {
+            context.logger.debug("Message ID   : \(msg.messageId)")
+            context.logger.debug("Message body : \(msg.body)")
+        }
+    }
+}

Examples/SAM/Tests/LambdaTests/HttpApiLambdaTest.swift

@@ -0,0 +1,46 @@
+// ===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftAWSLambdaRuntime project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// ===----------------------------------------------------------------------===//
+
+import AWSLambdaEvents
+import AWSLambdaRuntime
+import AWSLambdaTesting
+import XCTest
+@testable import HttpApiLambda
+
+class HttpApiLambdaTests: LambdaTest {
+
+    func testHttpAPiLambda() async throws {
+
+            // given 
+            let eventData = try self.loadTestData(file: .apiGatewayV2)
+            let event = try JSONDecoder().decode(APIGatewayV2Request.self, from: eventData)
+
+            do {
+                // when 
+                let result = try await Lambda.test(HttpApiLambda.self, with: event)
+
+                // then   
+                XCTAssertEqual(result.statusCode.code, 200)
+                XCTAssertNotNil(result.headers)
+                if let headers = result.headers {
+                    XCTAssertNotNil(headers["content-type"])
+                    if let contentType = headers["content-type"] {
+                        XCTAssertTrue(contentType == "application/json")
+                    }
+                }
+            } catch {
+                XCTFail("Lambda invocation should not throw error : \(error)")
+            }
+        }
+}

Examples/SAM/Tests/LambdaTests/LambdaTest.swift

@@ -0,0 +1,22 @@
+import Foundation 
+import XCTest
+
+enum TestData : String {
+    case apiGatewayV2 = "apiv2"
+    case sqs = "sqs"
+}
+
+class LambdaTest: XCTestCase {
+    // return the URL of a test file
+    // files are copied to the bundle during build by the `resources` directive in `Package.swift`
+    private func urlForTestData(file: TestData) throws -> URL {
+        let filePath = Bundle.module.path(forResource: file.rawValue, ofType: "json")!
+        return URL(fileURLWithPath: filePath)
+    }
+
+    // load a test file added as a resource to the executable bundle
+    func loadTestData(file: TestData) throws -> Data {
+        // load list from file
+        return try Data(contentsOf: urlForTestData(file: file))
+    }
+}

Examples/SAM/Tests/LambdaTests/SQSLambdaTest.swift

@@ -0,0 +1,40 @@
+// ===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftAWSLambdaRuntime project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// ===----------------------------------------------------------------------===//
+
+import AWSLambdaEvents
+import AWSLambdaRuntime
+import AWSLambdaTesting
+import XCTest
+@testable import SQSLambda
+
+class SQSLambdaTests: LambdaTest {
+
+    func testSQSLambda() async throws {
+
+            // given 
+            let eventData = try self.loadTestData(file: .sqs)
+            let event = try JSONDecoder().decode(SQSEvent.self, from: eventData)
+
+            // when 
+            do {
+                try await Lambda.test(SQSLambda.self, with: event)
+            } catch {
+                XCTFail("Lambda invocation should not throw error : \(error)")
+            }
+
+            // then   
+            // SQS Lambda returns Void
+
+        }
+}