Update the tutorial for v2 (#450)

Update the text, code sample, and screenshots for runtime v2

Address
#371

Author: sebsto

.github/workflows/pull_request.yml

@@ -36,7 +36,7 @@ jobs:
       # We pass the list of examples here, but we can't pass an array as argument
       # Instead, we pass a String with a valid JSON array.
       # The workaround is mentioned here https://github.com/orgs/community/discussions/11692
-      examples: "[ 'APIGateway', 'BackgroundTasks', 'HelloJSON', 'HelloWorld', 'S3_AWSSDK', 'S3_Soto', 'Streaming', 'Testing' ]"
+      examples: "[ 'APIGateway', 'BackgroundTasks', 'HelloJSON', 'HelloWorld', 'S3_AWSSDK', 'S3_Soto', 'Streaming', 'Testing', 'Tutorial' ]"
 
       archive_plugin_enabled: true
 

Examples/Tutorial/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+/.build
+/Packages
+xcuserdata/
+DerivedData/
+.swiftpm/configuration/registries.json
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.netrc

Examples/Tutorial/Package.swift

@@ -0,0 +1,51 @@
+// swift-tools-version: 6.0
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+import struct Foundation.URL
+
+let package = Package(
+    name: "Palindrome",
+    platforms: [.macOS(.v15)],
+    dependencies: [
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", branch: "main")
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products from dependencies.
+        .executableTarget(
+            name: "Palindrome",
+            dependencies: [
+                .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime")
+            ]
+        )
+    ]
+)
+
+if let localDepsPath = Context.environment["LAMBDA_USE_LOCAL_DEPS"],
+    localDepsPath != "",
+    let v = try? URL(fileURLWithPath: localDepsPath).resourceValues(forKeys: [.isDirectoryKey]),
+    v.isDirectory == true
+{
+    // when we use the local runtime as deps, let's remove the dependency added above
+    let indexToRemove = package.dependencies.firstIndex { dependency in
+        if case .sourceControl(
+            name: _,
+            location: "https://github.com/swift-server/swift-aws-lambda-runtime.git",
+            requirement: _
+        ) = dependency.kind {
+            return true
+        }
+        return false
+    }
+    if let indexToRemove {
+        package.dependencies.remove(at: indexToRemove)
+    }
+
+    // then we add the dependency on LAMBDA_USE_LOCAL_DEPS' path (typically ../..)
+    print("[INFO] Compiling against swift-aws-lambda-runtime located at \(localDepsPath)")
+    package.dependencies += [
+        .package(name: "swift-aws-lambda-runtime", path: localDepsPath)
+    ]
+}

Examples/Tutorial/Sources/main.swift

@@ -0,0 +1,48 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) 2025 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 AWSLambdaRuntime
+
+// the data structure to represent the input parameter
+struct Request: Decodable {
+    let text: String
+}
+
+// the data structure to represent the response parameter
+struct Response: Encodable {
+    let text: String
+    let isPalindrome: Bool
+    let message: String
+}
+
+// the business function
+func isPalindrome(_ text: String) -> Bool {
+    let cleanedText = text.lowercased().filter { $0.isLetter }
+    return cleanedText == String(cleanedText.reversed())
+}
+
+// the lambda handler function
+let runtime = LambdaRuntime {
+    (event: Request, context: LambdaContext) -> Response in
+
+    let result = isPalindrome(event.text)
+    return Response(
+        text: event.text,
+        isPalindrome: result,
+        message: "Your text is \(result ? "a" : "not a") palindrome"
+    )
+}
+
+// start the runtime
+try await runtime.run()

Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/.shellcheckrc

@@ -0,0 +1 @@
+disable=all

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

@@ -1,3 +1,2 @@
-# shellcheck disable=all
 # Create a project directory
-mkdir SquareNumber && cd SquareNumber
+mkdir Palindrome && cd Palindrome

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

@@ -1,5 +1,5 @@
-# shellcheck disable=all
 # Create a project directory
-mkdir SquareNumber && cd SquareNumber
+mkdir Palindrome && cd Palindrome
+
 # create a skeleton project
-swift package init --type executable 
+swift package init --type executable 

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

@@ -1,7 +1,8 @@
-# shellcheck disable=all
 # Create a project directory
-mkdir SquareNumber && cd SquareNumber
+mkdir Palindrome && cd Palindrome
+
 # create a skeleton project
 swift package init --type executable 
+
 # open Xcode in the current directory
-xed .
+xed .

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

@@ -1,9 +1,11 @@
-# shellcheck disable=all
 # Create a project directory
-mkdir SquareNumber && cd SquareNumber
+mkdir Palindrome && cd Palindrome
+
 # 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

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

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

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

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

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

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

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

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

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

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

@@ -1,2 +1,4 @@
-@main
-struct SquareNumberHandler: SimpleLambdaHandler {}
+// the data structure to represent the input parameter
+struct Request: Decodable {
+    let text: String
+}

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

@@ -1,4 +1,11 @@
-import AWSLambdaRuntime
+// the data structure to represent the input parameter
+struct Request: Decodable {
+    let text: String
+}
 
-@main
-struct SquareNumberHandler: SimpleLambdaHandler {}
+// the data structure to represent the response parameter
+struct Response: Encodable {
+    let text: String
+    let isPalindrome: Bool
+    let message: String
+}

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

@@ -1,6 +1,17 @@
-import AWSLambdaRuntime
+// the data structure to represent the input parameter
+struct Request: Decodable {
+    let text: String
+}
+
+// the data structure to represent the response parameter
+struct Response: Encodable {
+    let text: String
+    let isPalindrome: Bool
+    let message: String
+}
 
-@main
-struct SquareNumberHandler: SimpleLambdaHandler {
-    func handle(_ event: Event, context: LambdaContext) async throws -> Output {}
+// the business function
+func isPalindrome(_ text: String) -> Bool {
+    let cleanedText = text.lowercased().filter { $0.isLetter }
+    return cleanedText == String(cleanedText.reversed())
 }

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

@@ -1,14 +1,19 @@
 import AWSLambdaRuntime
 
-struct Input: Codable {
-    let number: Double
+// the data structure to represent the input parameter
+struct Request: Decodable {
+    let text: String
 }
 
-struct Number: Codable {
-    let result: Double
+// the data structure to represent the response parameter
+struct Response: Encodable {
+    let text: String
+    let isPalindrome: Bool
+    let message: String
 }
 
-@main
-struct SquareNumberHandler: SimpleLambdaHandler {
-    func handle(_ event: Event, context: LambdaContext) async throws -> Output {}
+// the business function
+func isPalindrome(_ text: String) -> Bool {
+    let cleanedText = text.lowercased().filter { $0.isLetter }
+    return cleanedText == String(cleanedText.reversed())
 }

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

@@ -1,17 +1,25 @@
 import AWSLambdaRuntime
 
-struct Input: Codable {
-    let number: Double
+// the data structure to represent the input parameter
+struct Request: Decodable {
+    let text: String
 }
 
-struct Number: Codable {
-    let result: Double
+// the data structure to represent the response parameter
+struct Response: Encodable {
+    let text: String
+    let isPalindrome: Bool
+    let message: String
 }
 
-@main
-struct SquareNumberHandler: SimpleLambdaHandler {
-    typealias Event = Input
-    typealias Output = Number
+// the business function
+func isPalindrome(_ text: String) -> Bool {
+    let cleanedText = text.lowercased().filter { $0.isLetter }
+    return cleanedText == String(cleanedText.reversed())
+}
+
+// the lambda handler function
+let runtime = LambdaRuntime {
+    (event: Request, context: LambdaContext) -> Response in
 
-    func handle(_ event: Event, context: LambdaContext) async throws -> Output {}
 }