[doc] Getting Started documentation and tutorial (swift-server#300)

improved getting started documentation, with DocC

.gitignore

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

Sources/AWSLambdaRuntimeCore/Documentation.docc/Documentation.md

@@ -0,0 +1,24 @@
+# ``AWSLambdaRuntimeCore``
+
+An AWS Lambda runtime for the Swift programming language
+
+## Overview
+
+Many modern systems have client components like iOS, macOS or watchOS applications as well as server components that those clients interact with. Serverless functions are often the easiest and most efficient way for client application developers to extend their applications into the cloud.
+
+Serverless functions are increasingly becoming a popular choice for running event-driven or otherwise ad-hoc compute tasks in the cloud. They power mission critical microservices and data intensive workloads. In many cases, serverless functions allow developers to more easily scale and control compute costs given their on-demand nature.
+
+When using serverless functions, attention must be given to resource utilization as it directly impacts the costs of the system. This is where Swift shines! With its low memory footprint, deterministic performance, and quick start time, Swift is a fantastic match for the serverless functions architecture.
+
+Combine this with Swift's developer friendliness, expressiveness, and emphasis on safety, and we have a solution that is great for developers at all skill levels, scalable, and cost effective.
+
+Swift AWS Lambda Runtime was designed to make building Lambda functions in Swift simple and safe. The library is an implementation of the [AWS Lambda Runtime API](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html) and uses an embedded asynchronous HTTP client based on [SwiftNIO](https://github.com/apple/swift-nio) that is fine-tuned for performance in the AWS Lambda Runtime context. The library provides a multi-tier API that allows building a range of Lambda functions: from quick and simple closures to complex, performance-sensitive event handlers.
+
+## Topics
+
+### Essentials
+
+- <doc:quick-setup>
+- <doc:/tutorials/table-of-content>
+ - ``LambdaHandler`` 
+

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-01-01-package-init.sh

@@ -0,0 +1,2 @@
+# Create a project directory
+mkdir SquareNumber && cd SquareNumber

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-01-02-package-init.sh

@@ -0,0 +1,4 @@
+# Create a project directory
+mkdir SquareNumber && cd SquareNumber
+# create a skeleton project
+swift package init --type executable 

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-01-03-package-init.sh

@@ -0,0 +1,6 @@
+# Create a project directory
+mkdir SquareNumber && cd SquareNumber
+# create a skeleton project
+swift package init --type executable 
+# open Xcode in the current directory
+xed .

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-01-04-package-init.sh

@@ -0,0 +1,8 @@
+# Create a project directory
+mkdir SquareNumber && cd SquareNumber
+# create a skeleton project
+swift package init --type executable 
+# open Xcode in the current directory
+xed .
+# alternatively, you may open VSCode
+code .

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-01-package.swift

@@ -0,0 +1,8 @@
+// swift-tools-version:5.8
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SquareNumberLambda",
+)

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-02-package.swift

@@ -0,0 +1,11 @@
+// swift-tools-version:5.8
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SquareNumberLambda",
+    platforms: [
+        .macOS(.v12),
+    ],
+)

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-03-package.swift

@@ -0,0 +1,14 @@
+// swift-tools-version:5.8
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SquareNumberLambda",
+    platforms: [
+        .macOS(.v12),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", from: "1.0.0-alpha"),
+    ],
+)

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-04-package.swift

@@ -0,0 +1,17 @@
+// swift-tools-version:5.8
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SquareNumberLambda",
+    platforms: [
+        .macOS(.v12),
+    ],
+    products: [
+        .executable(name: "SquareNumberLambda", targets: ["SquareNumberLambda"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", from: "1.0.0-alpha"),
+    ],
+)

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-05-package.swift

@@ -0,0 +1,26 @@
+// swift-tools-version:5.8
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SquareNumberLambda",
+    platforms: [
+        .macOS(.v12),
+    ],
+    products: [
+        .executable(name: "SquareNumberLambda", targets: ["SquareNumberLambda"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", from: "1.0.0-alpha"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "SquareNumberLambda",
+            dependencies: [
+                .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"),
+            ],
+            path: "."
+        ),
+    ]
+)

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-01-main.swift

@@ -0,0 +1,3 @@
+
+@main
+struct SquareNumberHandler: SimpleLambdaHandler {}

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-02-main.swift

@@ -0,0 +1,4 @@
+import AWSLambdaRuntime
+
+@main
+struct SquareNumberHandler: SimpleLambdaHandler {}

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-03-main.swift

@@ -0,0 +1,6 @@
+import AWSLambdaRuntime
+
+@main
+struct SquareNumberHandler: SimpleLambdaHandler {
+    func handle(_ event: Event, context: LambdaContext) async throws -> Output {}
+}

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-04-main.swift

@@ -0,0 +1,14 @@
+import AWSLambdaRuntime
+
+struct Input: Codable {
+    let number: Double
+}
+
+struct Number: Codable {
+    let result: Double
+}
+
+@main
+struct SquareNumberHandler: SimpleLambdaHandler {
+    func handle(_ event: Event, context: LambdaContext) async throws -> Output {}
+}

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-05-main.swift

@@ -0,0 +1,17 @@
+import AWSLambdaRuntime
+
+struct Input: Codable {
+    let number: Double
+}
+
+struct Number: Codable {
+    let result: Double
+}
+
+@main
+struct SquareNumberHandler: SimpleLambdaHandler {
+    typealias Event = Input
+    typealias Output = Number
+
+    func handle(_ event: Event, context: LambdaContext) async throws -> Output {}
+}

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-06-main.swift

@@ -0,0 +1,19 @@
+import AWSLambdaRuntime
+
+struct Input: Codable {
+    let number: Double
+}
+
+struct Number: Codable {
+    let result: Double
+}
+
+@main
+struct SquareNumberHandler: SimpleLambdaHandler {
+    typealias Event = Input
+    typealias Output = Number
+
+    func handle(_ event: Event, context: LambdaContext) async throws -> Output {
+        Number(result: event.number * event.number)
+    }
+}

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-04-03-console-output.sh

@@ -0,0 +1,5 @@
+2023-04-14T11:42:21+0200 info LocalLambdaServer : [AWSLambdaRuntimeCore] LocalLambdaServer started and listening on 127.0.0.1:7000, receiving events on /invoke
+2023-04-14T11:42:21+0200 info Lambda : [AWSLambdaRuntimeCore] lambda runtime starting with LambdaConfiguration
+  General(logLevel: info))
+  Lifecycle(id: 104957691689708, maxTimes: 0, stopSignal: TERM)
+  RuntimeEngine(ip: 127.0.0.1, port: 7000, requestTimeout: nil

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-04-04-curl.sh

@@ -0,0 +1,5 @@
+curl --header "Content-Type: application/json" \
+     --request POST                            \
+     --data '{"number": 3}'                    \
+     http://localhost:7000/invoke
+

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-04-05-curl.sh

@@ -0,0 +1,6 @@
+curl --header "Content-Type: application/json" \
+     --request POST                            \
+     --data '{"number": 3}'                    \
+     http://localhost:7000/invoke
+
+{"result":9}

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-04-06-terminal.sh

@@ -0,0 +1,2 @@
+export LOCAL_LAMBDA_SERVER_ENABLED=true
+

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-04-07-terminal.sh

@@ -0,0 +1,2 @@
+export LOCAL_LAMBDA_SERVER_ENABLED=true
+swift run

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-04-08-terminal.sh

@@ -0,0 +1,10 @@
+export LOCAL_LAMBDA_SERVER_ENABLED=true
+swift run
+
+Building for debugging...
+Build complete! (0.20s)
+2023-04-14T10:52:25+0200 info LocalLambdaServer : [AWSLambdaRuntimeCore] LocalLambdaServer started and listening on 127.0.0.1:7000, receiving events on /invoke
+2023-04-14T10:52:25+0200 info Lambda : [AWSLambdaRuntimeCore] lambda runtime starting with LambdaConfiguration
+  General(logLevel: info))
+  Lifecycle(id: 102943961260250, maxTimes: 0, stopSignal: TERM)
+  RuntimeEngine(ip: 127.0.0.1, port: 7000, requestTimeout: nil

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-01-02-plugin-archive.sh

@@ -0,0 +1,2 @@
+swift package --disable-sandbox plugin archive
+

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-01-03-plugin-archive.sh

@@ -0,0 +1,19 @@
+swift package --disable-sandbox plugin archive
+
+-------------------------------------------------------------------------
+building "squarenumberlambda" in docker
+-------------------------------------------------------------------------
+updating "swift:amazonlinux2" docker image
+  amazonlinux2: Pulling from library/swift
+  Digest: sha256:5b0cbe56e35210fa90365ba3a4db9cd2b284a5b74d959fc1ee56a13e9c35b378
+  Status: Image is up to date for swift:amazonlinux2
+  docker.io/library/swift:amazonlinux2
+building "SquareNumberLambda"
+  Building for production...
+...
+-------------------------------------------------------------------------
+archiving "SquareNumberLambda"
+-------------------------------------------------------------------------
+1 archive created
+  * SquareNumberLambda at /Users/YourUserName/SquareNumberLambda/.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/SquareNumberLambda/SquareNumberLambda.zip
+

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-01-04-plugin-archive.sh

@@ -0,0 +1,21 @@
+swift package --disable-sandbox plugin archive
+
+-------------------------------------------------------------------------
+building "squarenumberlambda" in docker
+-------------------------------------------------------------------------
+updating "swift:amazonlinux2" docker image
+  amazonlinux2: Pulling from library/swift
+  Digest: sha256:5b0cbe56e35210fa90365ba3a4db9cd2b284a5b74d959fc1ee56a13e9c35b378
+  Status: Image is up to date for swift:amazonlinux2
+  docker.io/library/swift:amazonlinux2
+building "SquareNumberLambda"
+  Building for production...
+...
+-------------------------------------------------------------------------
+archiving "SquareNumberLambda"
+-------------------------------------------------------------------------
+1 archive created
+  * SquareNumberLambda at /Users/YourUserName/SquareNumberLambda/.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/SquareNumberLambda/SquareNumberLambda.zip
+
+
+cp .build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/SquareNumberLambda/SquareNumberLambda.zip ~/Desktop

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-03-01-aws-cli.sh

@@ -0,0 +1 @@
+aws --version

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-03-02-lambda-invoke-hidden.sh

@@ -0,0 +1,7 @@
+#
+# --region            the AWS Region to send the command
+# --function-name     the name of your function
+# --cli-binary-format tells the cli to use raw data as input (default is base64)
+# --payload           the payload to pass to your function code
+# result.json         the name of the file to store the response from the function
+

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-03-02-lambda-invoke.sh

@@ -0,0 +1,14 @@
+#
+# --region            the AWS Region to send the command
+# --function-name     the name of your function
+# --cli-binary-format tells the cli to use raw data as input (default is base64)
+# --payload           the payload to pass to your function code
+# result.json         the name of the file to store the response from the function
+
+aws lambda invoke                                \
+           --region us-west-2                    \
+           --function-name SquaredNumberLambda   \
+           --cli-binary-format raw-in-base64-out \
+           --payload '{"number":3}'              \
+           result.json
+

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-03-03-lambda-invoke.sh

@@ -0,0 +1,18 @@
+#
+# --region            the AWS Region to send the command
+# --function-name     the name of your function
+# --cli-binary-format tells the cli to use raw data as input (default is base64)
+# --payload           the payload to pass to your function code
+# result.json         the name of the file to store the response from the function
+
+aws lambda invoke                                \
+           --region us-west-2                    \
+           --function-name SquaredNumberLambda   \
+           --cli-binary-format raw-in-base64-out \
+           --payload '{"number":3}'              \
+           result.json
+
+{
+    "StatusCode": 200,
+    "ExecutedVersion": "$LATEST"
+}

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-03-04-lambda-invoke.sh

@@ -0,0 +1,20 @@
+#
+# --region            the AWS Region to send the command
+# --function-name     the name of your function
+# --cli-binary-format tells the cli to use raw data as input (default is base64)
+# --payload           the payload to pass to your function code
+# result.json         the name of the file to store the response from the function
+
+aws lambda invoke                                \
+           --region us-west-2                    \
+           --function-name SquaredNumberLambda   \
+           --cli-binary-format raw-in-base64-out \
+           --payload '{"number":3}'              \
+           result.json
+
+{
+    "StatusCode": 200,
+    "ExecutedVersion": "$LATEST"
+}
+
+cat result.json

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-03-05-lambda-invoke.sh

@@ -0,0 +1,22 @@
+#
+# --region            the AWS Region to send the command
+# --function-name     the name of your function
+# --cli-binary-format tells the cli to use raw data as input (default is base64)
+# --payload           the payload to pass to your function code
+# result.json         the name of the file to store the response from the function
+
+aws lambda invoke                                \
+           --region us-west-2                    \
+           --function-name SquaredNumberLambda   \
+           --cli-binary-format raw-in-base64-out \
+           --payload '{"number":3}'              \
+           result.json
+
+{
+    "StatusCode": 200,
+    "ExecutedVersion": "$LATEST"
+}
+
+cat result.json
+{"result":9}
+