[plugin] Add a deployer plugin + Swift-based DSL + SAM example

Examples/SAM/.gitignore

@@ -0,0 +1,8 @@
+Makefile
+TODO
+notes.md
+sam.yaml
+sam.json
+template.yaml
+template.json
+samconfig.toml

Examples/SAM/Deploy.swift

@@ -0,0 +1,112 @@
+import AWSLambdaDeploymentDescriptor
+
+// example of a shared resource
+let sharedQueue = Queue(
+  logicalName: "SharedQueue",
+  physicalName: "swift-lambda-shared-queue")
+
+// example of common environment variables
+let sharedEnvironmentVariables = ["LOG_LEVEL": "debug"]
+
+let validEfsArn =
+  "arn:aws:elasticfilesystem:eu-central-1:012345678901:access-point/fsap-abcdef01234567890"
+
+// the deployment descriptor
+DeploymentDescriptor {
+
+  // an optional description
+  "Description of this deployment descriptor"
+
+  // Create a lambda function exposed through a REST API
+  Function(name: "HttpApiLambda") {
+
+    // an optional description
+    "Description of this function"
+
+    EventSources {
+
+      // example of a catch all api
+      HttpApi()
+
+      // example of an API for a specific HTTP verb and path
+      // HttpApi(method: .GET, path: "/test")
+
+    }
+
+    EnvironmentVariables {
+      [
+        "NAME1": "VALUE1",
+        "NAME2": "VALUE2",
+      ]
+
+      // shared environment variables declared upfront
+      sharedEnvironmentVariables
+    }
+  }
+
+  // Example Function modifiers:
+
+  // .autoPublishAlias()
+  // .ephemeralStorage(2048)
+  // .eventInvoke(onSuccess: "arn:aws:sqs:eu-central-1:012345678901:lambda-test",
+  //             onFailure: "arn:aws:lambda:eu-central-1:012345678901:lambda-test",
+  //             maximumEventAgeInSeconds: 600,
+  //             maximumRetryAttempts: 3)
+  // .fileSystem(validEfsArn, mountPoint: "/mnt/path1")
+  // .fileSystem(validEfsArn, mountPoint: "/mnt/path2")
+
+  // Create a Lambda function exposed through an URL
+  // you can invoke it with a signed request, for example
+  // curl --aws-sigv4 "aws:amz:eu-central-1:lambda"        \
+  //      --user $AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY \
+  //      -H 'content-type: application/json'              \
+  //      -d '{ "example": "test" }'                       \
+  //      "$FUNCTION_URL?param1=value1&param2=value2"
+  Function(name: "UrlLambda") {
+    "A Lambda function that is directly exposed as an URL, with IAM authentication"
+  }
+  .urlConfig(authType: .iam)
+
+  // Create a Lambda function triggered by messages on SQS
+  Function(name: "SQSLambda", architecture: .arm64) {
+
+    EventSources {
+
+      // this will reference an existing queue by its Arn
+      // Sqs("arn:aws:sqs:eu-central-1:012345678901:swift-lambda-shared-queue")
+
+      // // this will create a new queue resource
+      Sqs("swift-lambda-queue-name")
+
+      // // this will create a new queue resource, with control over physical queue name
+      // Sqs()
+      //     .queue(logicalName: "LambdaQueueResource", physicalName: "swift-lambda-queue-resource")
+
+      // // this references a shared queue resource created at the top of this deployment descriptor
+      // // the queue resource will be created automatically, you do not need to add `sharedQueue` as a resource
+      // Sqs(sharedQueue)
+    }
+
+    EnvironmentVariables {
+      sharedEnvironmentVariables
+    }
+  }
+
+  //
+  // Additional 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")
+
+  // example modifiers
+  // .provisionedThroughput(readCapacityUnits: 10, writeCapacityUnits: 99)
+}

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: LambdaHandler {
+    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 control 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/Package.swift

@@ -0,0 +1,80 @@
+// 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 class Foundation.ProcessInfo // needed for CI to test the local version of the library
+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"]),
+    .executable(name: "UrlLambda", targets: ["UrlLambda"])
+  ],
+  dependencies: [
+    .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", branch: "main"),
+    .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: "UrlLambda",
+      dependencies: [
+        .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"),
+        .product(name: "AWSLambdaEvents", package: "swift-aws-lambda-events")
+      ],
+      path: "./UrlLambda"
+    ),
+    .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"),
+      ],
+      // testing data 
+      resources: [
+        .process("data/apiv2.json"),
+        .process("data/sqs.json")
+      ]
+    )
+  ]
+)
+
+// for CI to test the local version of the library
+if ProcessInfo.processInfo.environment["LAMBDA_USE_LOCAL_DEPS"] != nil {
+    package.dependencies = [
+        .package(name: "swift-aws-lambda-runtime", path: "../.."),
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-events.git", branch: "main")
+    ]
+}

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: LambdaHandler {
+    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))
+    }
+}