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

improved getting started documentation, with DocC

Author: sebsto

.gitignore

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

Sources/AWSLambdaRuntimeCore/Documentation.docc/Documentation.md

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

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-01-01-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-02-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-03-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-01-04-package-init.sh

@@ -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-01-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-02-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-03-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-04-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-02-05-package.swift

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

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

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

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-02-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-03-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-04-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-05-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-03-06-main.swift

@@ -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-03-console-output.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-04-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-05-curl.sh

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

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

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

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-04-07-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/03-04-08-terminal.sh

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

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-01-02-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-03-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-01-04-plugin-archive.sh

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

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/04-03-01-aws-cli.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-hidden.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-02-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-03-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-04-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}
+