v2 Plugin System: lambda-init, lambda-build, lambda-deploy (#567)

This PR delivers the v2 plugin system, replacing the legacy
single-purpose `archive` plugin with three focused SwiftPM command
plugins that cover the end-to-end developer experience:

- **`lambda-init`** — Scaffold a new Lambda function from a template
- **`lambda-build`** — Compile and package for Amazon Linux 2023 (via
Docker or Apple container)
- **`lambda-deploy`** — Deploy to AWS Lambda (create, update, or delete)

The legacy `archive` command is preserved as a deprecated passthrough to
`lambda-build`.

## Quick Start

```bash
# Create a new project
swift package init --type executable --name MyLambda

# Scaffold a Lambda function
swift package lambda-init --allow-writing-to-package-directory

# Build for Amazon Linux
swift package --allow-network-connections docker lambda-build

# Deploy to AWS
swift package --allow-network-connections all:443 lambda-deploy

# Delete when done
swift package --allow-network-connections all:443 lambda-deploy --delete
```

## Key Changes

### Architecture
- All plugins are thin wrappers that spawn a shared
`AWSLambdaPluginHelper` executable
- The helper dispatches to `Initializer`, `Builder`, or `Deployer` based
on `argv[1]`
- AWS API calls use generated service clients (Lambda, IAM, S3, STS)
built on SotoCore

### Builder (`lambda-build`)
- Default base image changed from `amazonlinux2` to `amazonlinux2023`
- AL2 blanket deprecation warning removed; targeted warning only when
AL2 explicitly chosen
- New `--cross-compile` option (replaces `--container-cli`): `docker`,
`container`, `swift-static-sdk`, `custom-sdk`
- Default binary stripping with `-Xlinker -s` and `--no-strip` opt-out
- `--output-directory` accepted as deprecated alias for `--output-path`
- Container CLI existence check with helpful install URLs

### Deployer (`lambda-deploy`)
- Creates/updates/deletes Lambda functions with full IAM role lifecycle
- Auto-creates IAM role with `AWSLambdaBasicExecutionRole`
- S3 staging for archives > 50 MB
- Function URL support with IAM auth (account-scoped, not
world-accessible)
- Auto-detects `FunctionURLRequest` usage in source code to enable URL
without explicit `--with-url`
- Ready-to-use invocation commands in deploy output

### Initializer (`lambda-init`)
- Detects the actual entry point file (supports both
`Sources/main.swift` and `Sources/<Name>/<Name>.swift`)
- Backs up existing file before overwriting

### Dependencies
- Added `soto-core` for AWS credential management, SigV4 signing, and
HTTP transport
- Removed vendored crypto/signer/HTTP code under `Vendored/`
- Generated AWS service clients committed to the repository
(maintainer-run generation script)

### Backward Compatibility
- `swift package archive` preserved as deprecated alias (emits warning,
delegates to `lambda-build`)
- `--container-cli` accepted as deprecated alias for `--cross-compile`
- `--output-directory` accepted as deprecated alias for `--output-path`
- All original `archive` CLI options continue to work

## Documentation
- Updated DocC articles, tutorials, and quick-setup guide
- Updated all example READMEs with new plugin commands
- SAM/CDK examples preserved with their respective deployment tools

## Known Limitations
- Static Linux SDK CI uses `--build-system native`. On Swift 6.4 the new
default build system (Swift Build) fails to statically link
`AWSLambdaPluginHelper`: SotoCore transitively pulls in two vendored
BoringSSL copies (swift-crypto's `CCryptoBoringSSL` and swift-nio-ssl's
`CNIOBoringSSL`), and Swift Build emits duplicate C++ symbols at link
time. The legacy build system links the same package cleanly, so the CI
static build is pinned to `--build-system native` until the upstream
issue is fixed: https://github.com/swiftlang/swift-build/issues/1485.
- The `nightly-main` (6.5-dev) Linux job is expected to fail. The
6.5-dev compiler crashes while compiling `AWSLambdaRuntimeTests` (a SIL
verification error in the `OwnershipModelEliminator` pass on a `Mutex`
captured by a nested `Task` inside a task group). This is a toolchain
bug, not a problem in this PR: the same code compiles on 6.1 through
6.4. Reported upstream with a minimal reproducer:
swiftlang/swift#90211. `nightly-main` tracks
an unreleased toolchain and is not a release target, so we are not
working around it here.
- SwiftPM prompts for network permission on first run (known [SPM issue
swiftlang/swift#9763](swiftlang/swift-package-manager#9763))
- The shared documentation soundness check is temporarily disabled
(`docs_check_enabled: false`). A regression in
`swiftlang/github-workflows` (#282) passes the `.spi.yml` documentation
target to `--target` with literal quotes, so the check fails with `no
target named '"AWSLambdaRuntime"'`. Pinning the workflow version does
not help because the reusable workflow always fetches its
`check-docs.sh` from `main`. Re-enable once the upstream fix lands:
swiftlang/github-workflows#290 (tracked in
swiftlang/github-workflows#291).

The SotoCore `LoginCredentialProvider` token-persistence issue in the
SwiftPM sandbox is now resolved upstream
([soto-core#692](soto-project/soto-core#692),
released in soto-core 7.14.0), and this PR already requires `from:
"7.14.0"`.

## Testing
- Unit tests for BuilderConfiguration and DeployerConfiguration argument
parsing
- Property-based tests for correctness properties (alias equivalence,
cross-compile round-trip, mutual exclusion, bucket naming, archive
threshold, AL2 warning logic)
- End-to-end integration test script (`scripts/integration-test.sh`)
- Manually tested: full create → invoke → update → delete lifecycle on
AWS

---------

Co-authored-by: Sebastien Stormacq <stormacq@amazon.lu>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.github/workflows/integration_tests.yml

@@ -31,6 +31,14 @@ on:
         type: boolean
         description: "Boolean to enable the test of the archive plugin. Defaults to true."
         default: true
+      archive_plugin_swift64_enabled:
+        type: boolean
+        description: "Boolean to enable the Swift 6.4 packaging plugin test (archive + lambda-build). Defaults to true."
+        default: true
+      archive_plugin_swift64_container_image:
+        type: string
+        description: "Container image providing the Swift 6.4+ toolchain for the packaging plugin test."
+        default: "swiftlang/swift:nightly-6.4.x-bookworm"
       check_foundation_enabled:
         type: boolean
         description: "Boolean to enable the check for Foundation dependency. Defaults to true."
@@ -121,6 +129,69 @@ jobs:
         run: |
             .github/workflows/scripts/check-archive-plugin.sh
 
+  test-archive-plugin-swift64:
+    name: Test packaging plugins (Swift 6.4)
+    if: ${{ inputs.archive_plugin_swift64_enabled }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        examples: ${{ fromJson(inputs.archive_plugin_examples) }}
+    # Runs in the Swift 6.4 container so that `swift(>=6.4)` is true and the new
+    # helper-delegating `archive` verb and the new `lambda-build` verb are compiled.
+    #
+    # The packaging plugins shell out to the HOST docker daemon (socket mounted below).
+    # The plugin builds the example inside an Amazon Linux container and bind-mounts the
+    # checkout into it. Because the daemon runs on the host, the bind-mount source must be
+    # a HOST path: GitHub mounts the host work dir (/home/runner/work) at /__w inside this
+    # job container, so a path like /__w/... does not exist for the host daemon. We mount
+    # /home/runner/work at the SAME path here, and the test step runs the plugin from that
+    # host-equivalent path, so the inner `docker run -v <src>:/workspace` source resolves
+    # correctly on the host.
+    container:
+      image: ${{ inputs.archive_plugin_swift64_container_image }}
+      volumes:
+        - /var/run/docker.sock:/var/run/docker.sock
+        - /home/runner/work:/home/runner/work
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Cache SPM dependencies
+        uses: actions/cache@v5
+        with:
+          # Cache the whole .build, not just checkouts/repositories. The plugins
+          # delegate to AWSLambdaPluginHelper, which links the SotoCore/NIO stack;
+          # compiling that on the host takes ~220s per run. Caching .build lets
+          # SwiftPM reuse the unchanged dependency objects and rebuild only the
+          # sources that changed.
+          path: Examples/${{ matrix.examples }}/.build
+          key: spm-swift64-${{ runner.os }}-${{ matrix.examples }}-${{ hashFiles(format('Examples/{0}/Package.swift', matrix.examples)) }}
+          restore-keys: |
+            spm-swift64-${{ runner.os }}-${{ matrix.examples }}-
+
+      - name: Install dependencies
+        run: |
+          apt-get -qq update
+          apt-get -qq -y install docker.io zip unzip file libssl-dev
+
+      - name: Test the packaging plugins
+        env:
+          EXAMPLE: ${{ matrix.examples }}
+        run: |
+            # GitHub mounts the host work dir (/home/runner/work) at /__w inside this
+            # container, so $GITHUB_WORKSPACE is /__w/<repo>/<repo>. The plugin shells out
+            # to the host docker daemon, which cannot resolve /__w paths. We mounted
+            # /home/runner/work at the same path, so re-enter the checkout via the
+            # host-equivalent path before running the plugin.
+            # NOTE: this step runs under `sh` (dash) inside the container, so we use
+            # POSIX `sed` rather than a bash-only `${var/a/b}` substitution.
+            HOST_WORKSPACE=$(printf '%s\n' "$GITHUB_WORKSPACE" | sed 's#^/__w/#/home/runner/work/#')
+            cd "${HOST_WORKSPACE}"
+            .github/workflows/scripts/check-archive-plugin-swift64.sh
+
   check-foundation:
     name: No dependencies on Foundation
     if: ${{ inputs.check_foundation_enabled }}

.github/workflows/pull_request.yml

@@ -19,16 +19,34 @@ jobs:
       docs_check_container_image: "swift:6.3-noble"
       format_check_container_image: "swift:6.3-noble"
       yamllint_check_enabled: true
+      # Temporarily disabled: the shared docs check is broken upstream (it loads
+      # check-docs.sh from main, where #282 passes the .spi.yml doc target to
+      # `--target` JSON-quoted, failing with `no target named '"AWSLambdaRuntime"'`).
+      # Pinning the workflow version does not help because the script is always fetched
+      # from main. Re-enable once the upstream fix lands:
+      # https://github.com/swiftlang/github-workflows/pull/290 (tracked in #291)
+      docs_check_enabled: false
 
   unit-tests:
     name: Unit tests
     uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
     with:
       enable_windows_checks: false
-      linux_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}, {\"swift_version\": \"5.10\"}, {\"swift_version\": \"6.0\"}]"
+      # nightly-main (6.5-dev) is temporarily excluded: the compiler crashes with a SIL
+      # verification error while compiling AWSLambdaRuntimeTests. This is a toolchain bug
+      # (the same code compiles on 6.1-6.4), not an issue in this package. Remove the
+      # nightly-main entry once fixed upstream: https://github.com/swiftlang/swift/issues/90211
+      linux_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}, {\"swift_version\": \"5.10\"}, {\"swift_version\": \"6.0\"}, {\"swift_version\": \"nightly-main\"}]"
       swift_flags: "--explicit-target-dependency-import-check error"
       swift_nightly_flags: "--explicit-target-dependency-import-check error"
       enable_linux_static_sdk_build: true
+      # On 6.4+ the default build system (Swift Build) fails to statically link AWSLambdaPluginHelper
+      # against the static Linux SDK: SotoCore transitively pulls in two vendored BoringSSL forks
+      # (swift-crypto's CCryptoBoringSSL and swift-nio-ssl's CNIOBoringSSL), and Swift Build emits
+      # duplicate libc++abi symbols (set_new_handler, __cxa_*, ...) at link time. The legacy (native)
+      # build system links the same package cleanly. Force it here until the upstream issue is fixed:
+      # https://github.com/swiftlang/swift/issues/90196
+      linux_static_sdk_build_command: "swift build --build-system native"
 
   integration-tests:
     name: Integration Tests
@@ -43,6 +61,8 @@ jobs:
       examples: "[ 'APIGatewayV1', 'APIGatewayV2', 'APIGatewayV2+LambdaAuthorizer', 'BackgroundTasks', 'HelloJSON', 'HelloWorld', 'HelloWorldNoTraits', 'HummingbirdLambda', 'ManagedInstances', 'MultiSourceAPI', 'MultiTenant', 'ResourcesPackaging', 'S3EventNotifier', 'S3_AWSSDK', 'S3_Soto', 'Streaming+APIGateway', 'Streaming+FunctionUrl', 'Streaming+Codable', 'ServiceLifecycle+Postgres', 'Testing', 'Tutorial' ]"
       archive_plugin_examples: "[ 'HelloWorld', 'ResourcesPackaging' ]"
       archive_plugin_enabled: true
+      archive_plugin_swift64_enabled: true
+      archive_plugin_swift64_container_image: "swiftlang/swift:nightly-6.4.x-bookworm"
 
   semver-label-check:
     name: Semantic Version label check

.github/workflows/scripts/check-archive-plugin-swift64.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+##===----------------------------------------------------------------------===##
+##
+## This source file is part of the SwiftAWSLambdaRuntime open source project
+##
+## Copyright (c) 2017-2024 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
+##
+##===----------------------------------------------------------------------===##
+
+# This script validates the packaging plugins on Swift 6.4+, where the
+# 'archive' verb is reimplemented to delegate to the AWSLambdaPluginHelper and
+# the new 'lambda-build' verb is available. It exercises BOTH verbs against the
+# example to prove:
+#   1. the legacy 'archive' surface still produces a valid bootstrap + ZIP
+#      (existing behaviour is preserved on the new code path), and
+#   2. the new 'lambda-build' verb produces an equivalent artifact.
+
+set -euo pipefail
+
+log() { printf -- "** %s\n" "$*" >&2; }
+error() { printf -- "** ERROR: %s\n" "$*" >&2; }
+fatal() { error "$@"; exit 1; }
+
+test -n "${EXAMPLE:-}" || fatal "EXAMPLE unset"
+
+# Use the local checkout of swift-aws-lambda-runtime instead of the published release
+.github/workflows/scripts/use-local-deps.sh "Examples/${EXAMPLE}/Package.swift"
+
+# The product name is "MyLambda" in both HelloWorld and ResourcesPackaging.
+PRODUCT=MyLambda
+
+pushd "Examples/${EXAMPLE}" >/dev/null || exit 1
+
+# ---------------------------------------------------------------------------
+# Assert that a given output directory contains a valid Linux bootstrap and ZIP.
+# $1: human-readable label of the verb under test
+# $2: path to the plugin output directory (containing <PRODUCT>/)
+# ---------------------------------------------------------------------------
+verify_output() {
+    local label="$1"
+    local output_dir="$2"
+    local bootstrap="${output_dir}/${PRODUCT}/bootstrap"
+    local zip_file="${output_dir}/${PRODUCT}/${PRODUCT}.zip"
+
+    log "Verifying output of '${label}'"
+
+    # did the plugin generate a Linux binary?
+    [ -f "${bootstrap}" ] || fatal "${label}: bootstrap not found at ${bootstrap}"
+    file "${bootstrap}" | grep --silent ELF || fatal "${label}: bootstrap is not an ELF binary"
+
+    # did the plugin create a ZIP file?
+    [ -f "${zip_file}" ] || fatal "${label}: ZIP not found at ${zip_file}"
+
+    # does the ZIP file contain the bootstrap?
+    unzip -l "${zip_file}" | grep --silent bootstrap || fatal "${label}: bootstrap missing from ZIP"
+
+    # if EXAMPLE is ResourcesPackaging, check the ZIP file contains hello.txt
+    if [ "$EXAMPLE" == "ResourcesPackaging" ]; then
+        log "${label}: checking that the resource was added to the ZIP file"
+        if unzip -l "${zip_file}" | grep --silent hello.txt; then
+            log "✅ ${label}: resource found."
+        else
+            fatal "❌ ${label}: resource hello.txt not found in ZIP."
+        fi
+    fi
+
+    log "✅ ${label}: output is OK for example ${EXAMPLE}"
+}
+
+# ---------------------------------------------------------------------------
+# 1. Legacy 'archive' verb (now delegates to AWSLambdaPluginHelper on 6.4+)
+# ---------------------------------------------------------------------------
+log "Testing 'archive' verb"
+ARCHIVE_OUTPUT_DIR=.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager
+LAMBDA_USE_LOCAL_DEPS=../.. swift package archive \
+    --allow-network-connections docker \
+    --base-docker-image swift:amazonlinux2023 || fatal "'archive' verb failed"
+verify_output "archive" "${ARCHIVE_OUTPUT_DIR}"
+
+# ---------------------------------------------------------------------------
+# 2. New 'lambda-build' verb (Swift 6.4+ only)
+# ---------------------------------------------------------------------------
+log "Testing 'lambda-build' verb"
+BUILD_OUTPUT_DIR=.build/plugins/AWSLambdaBuilder/outputs/AWSLambdaBuilder
+LAMBDA_USE_LOCAL_DEPS=../.. swift package lambda-build \
+    --allow-network-connections docker \
+    --products "${PRODUCT}" \
+    --base-docker-image swift:amazonlinux2023 || fatal "'lambda-build' verb failed"
+verify_output "lambda-build" "${BUILD_OUTPUT_DIR}"
+
+echo "✅ Both 'archive' and 'lambda-build' are OK with example ${EXAMPLE} on Swift 6.4"
+popd >/dev/null || exit 1

.gitignore

@@ -12,6 +12,7 @@ Package.resolved
 .vscode
 .devcontainer
 .amazonq
-.kiro
 nodejs
-.ash
+.ash
+.kiro/
+.claude/

.licenseignore

@@ -36,4 +36,5 @@ Package.resolved
 **/.npmignore
 **/*.json
 **/*.txt
-*.toml
+*.toml
+.kiro/*

.swiftformatignore

@@ -0,0 +1 @@
+Sources/AWSLambdaPluginHelper/lambda-init/Template.swift

Examples/APIGatewayV1/README.md

@@ -25,11 +25,11 @@ To build the package, type the following commands.
 
 ```bash
 swift build
-swift package archive --allow-network-connections docker --base-docker-image swift:amazonlinux2023
+swift package --allow-network-connections docker lambda-build
 ```
 
 If there is no error, there is a ZIP file ready to deploy. 
-The ZIP file is located at `.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/APIGatewayLambda/APIGatewayLambda.zip`
+The ZIP file is located at `.build/plugins/AWSLambdaBuilder/outputs/AWSLambdaBuilder/APIGatewayLambda/APIGatewayLambda.zip`
 
 ## Deploy
 

Examples/APIGatewayV1/template.yaml

@@ -23,7 +23,7 @@ Resources:
   APIGatewayLambda:
     Type: AWS::Serverless::Function
     Properties:
-      CodeUri: .build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/APIGatewayLambda/APIGatewayLambda.zip
+      CodeUri: .build/plugins/AWSLambdaBuilder/outputs/AWSLambdaBuilder/APIGatewayLambda/APIGatewayLambda.zip
       Timeout: 60
       Handler: swift.bootstrap  # ignored by the Swift runtime
       Runtime: provided.al2023

Examples/APIGatewayV2+LambdaAuthorizer/README.md

@@ -19,11 +19,11 @@ To build the package, type the following commands.
 
 ```bash
 swift build
-swift package archive --allow-network-connections docker --base-docker-image swift:amazonlinux2023
+swift package --allow-network-connections docker lambda-build
 ```
 
 If there is no error, there are two ZIP files ready to deploy, one for the authorizer function and one for the business function.
-The ZIP file are located under `.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager`
+The ZIP file are located under `.build/plugins/AWSLambdaBuilder/outputs/AWSLambdaBuilder`
 
 ## Deploy
 

Examples/APIGatewayV2+LambdaAuthorizer/template.yaml

@@ -47,7 +47,7 @@ Resources:
   APIGatewayLambda:
     Type: AWS::Serverless::Function
     Properties:
-      CodeUri: .build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/APIGatewayLambda/APIGatewayLambda.zip
+      CodeUri: .build/plugins/AWSLambdaBuilder/outputs/AWSLambdaBuilder/APIGatewayLambda/APIGatewayLambda.zip
       Timeout: 60
       Handler: swift.bootstrap  # ignored by the Swift runtime
       Runtime: provided.al2023
@@ -72,7 +72,7 @@ Resources:
   AuthorizerLambda:
     Type: AWS::Serverless::Function
     Properties:
-      CodeUri: .build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/AuthorizerLambda/AuthorizerLambda.zip
+      CodeUri: .build/plugins/AWSLambdaBuilder/outputs/AWSLambdaBuilder/AuthorizerLambda/AuthorizerLambda.zip
       Timeout: 29  # max 29 seconds for Lambda authorizers
       Handler: swift.bootstrap  # ignored by the Swift runtime
       Runtime: provided.al2023