v2 Plugin System: lambda-init, lambda-build, lambda-deploy by sebsto · Pull Request #567 · awslabs/swift-aws-lambda-runtime

sebsto · 2025-09-23T19:27:59Z

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

# 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: Swift Build 6.4: duplicate libc++abi symbols when statically linking two C++ targets swiftlang/swift-package-manager#10237.
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: Compiler crash on main (6.5-dev): SIL verification error (debug_value undef) on Mutex captured in nested Task inside task group 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)
The shared documentation soundness check is temporarily disabled (docs_check_enabled: false). A regression in swiftlang/github-workflows (fix concurrency api usage #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: Update dock check syntax issue swiftlang/github-workflows#290 (tracked in docs-check broken by #282: quoted doc target + docs_check_targets input ignored in containers swiftlang/github-workflows#291).

The SotoCore LoginCredentialProvider token-persistence issue in the SwiftPM sandbox is now resolved upstream (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

…6 from CryptoSwift

sebsto · 2025-09-23T19:29:15Z

Issue tracker #566

tkrajacic · 2025-11-01T19:10:03Z

Could we add the ability to pass build options. Sometimes it is nice to optimize for size and we can use

-Xlinker -s -Xswiftc -Osize

Copilot

Pull request overview

This PR introduces the v2 SwiftPM plugin system for the Swift AWS Lambda Runtime by splitting the legacy archive workflow into three focused commands (lambda-init, lambda-build, lambda-deploy) backed by a shared AWSLambdaPluginHelper executable, and updates docs/examples/CI accordingly.

Changes:

Add AWSLambdaPluginHelper executable and new SwiftPM command plugins (lambda-init, lambda-build, lambda-deploy), keeping archive as a deprecated passthrough.
Add generated lightweight AWS service clients (Lambda/IAM/S3/STS) plus new argument-parsing tests and an end-to-end integration script.
Refresh DocC + README + examples + CI workflows to use the new plugin commands and Amazon Linux 2023 defaults.

Reviewed changes

Copilot reviewed 74 out of 75 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
Tests/AWSLambdaPluginHelperTests/Placeholder.swift	Keeps test target valid
Tests/AWSLambdaPluginHelperTests/DeployerS3Tests.swift	S3/deploy parsing tests
Tests/AWSLambdaPluginHelperTests/DeployerConfigurationTests.swift	Deployer CLI parsing tests
Tests/AWSLambdaPluginHelperTests/BuilderConfigurationTests.swift	Builder CLI parsing tests
Sources/AWSLambdaRuntime/Docs.docc/tutorials/04-deploy-function.tutorial	Tutorial updated for AL2023 + lambda-build
Sources/AWSLambdaRuntime/Docs.docc/tutorials/03-write-function.tutorial	Tutorial text updated for AL2023
Sources/AWSLambdaRuntime/Docs.docc/Resources/code/04-01-04-plugin-archive.sh	Doc snippet updated to lambda-build
Sources/AWSLambdaRuntime/Docs.docc/Resources/code/04-01-03-plugin-archive.sh	Doc snippet updated to lambda-build
Sources/AWSLambdaRuntime/Docs.docc/Resources/code/04-01-02-plugin-archive.sh	Doc snippet updated to lambda-build
Sources/AWSLambdaRuntime/Docs.docc/quick-setup.md	Quick setup updated to lambda-build/lambda-deploy
Sources/AWSLambdaRuntime/Docs.docc/Deployment.md	Deployment guide updated for lambda-deploy
Sources/AWSLambdaPluginHelper/Process.swift	New process execution + output capture
Sources/AWSLambdaPluginHelper/lambda-init/Template.swift	Scaffold templates for init
Sources/AWSLambdaPluginHelper/lambda-init/Initializer.swift	Scaffold logic + entrypoint detection
Sources/AWSLambdaPluginHelper/GeneratedClients/STS/STSShapes.swift	Generated STS shapes
Sources/AWSLambdaPluginHelper/GeneratedClients/STS/STSErrors.swift	Generated STS errors
Sources/AWSLambdaPluginHelper/GeneratedClients/STS/STSClient.swift	Generated STS client
Sources/AWSLambdaPluginHelper/GeneratedClients/S3/S3Shapes.swift	Generated S3 shapes
Sources/AWSLambdaPluginHelper/GeneratedClients/S3/S3Errors.swift	Generated S3 errors
Sources/AWSLambdaPluginHelper/GeneratedClients/S3/S3Client.swift	Generated S3 client
Sources/AWSLambdaPluginHelper/GeneratedClients/Lambda/LambdaShapes.swift	Generated Lambda shapes
Sources/AWSLambdaPluginHelper/GeneratedClients/Lambda/LambdaErrors.swift	Generated Lambda errors
Sources/AWSLambdaPluginHelper/GeneratedClients/Lambda/LambdaClient.swift	Generated Lambda client
Sources/AWSLambdaPluginHelper/GeneratedClients/IAM/IAMShapes.swift	Generated IAM shapes
Sources/AWSLambdaPluginHelper/GeneratedClients/IAM/IAMErrors.swift	Generated IAM errors
Sources/AWSLambdaPluginHelper/GeneratedClients/IAM/IAMClient.swift	Generated IAM client
Sources/AWSLambdaPluginHelper/Extensions.swift	Data/String helpers
Sources/AWSLambdaPluginHelper/AWSLambdaPluginHelper.swift	Helper command dispatch
Sources/AWSLambdaPluginHelper/ArgumentExtractor.swift	CLI argument extraction helper
scripts/integration-test.sh	End-to-end plugin integration test
scripts/generate-aws-clients.sh	Maintainer client generation script
readme.md	Top-level README updated to new plugins
Plugins/Documentation.docc/Proposals/0001-v2-plugins.md	Proposal doc updates
Plugins/AWSLambdaPackager/PluginUtils.swift	Guard legacy plugin utils by swift version
Plugins/AWSLambdaPackager/Plugin@swift-6.4.swift	archive passthrough to helper (6.4+)
Plugins/AWSLambdaPackager/Plugin.swift	archive implementation (swift < 6.4)
Plugins/AWSLambdaInitializer/Plugin.swift	lambda-init SwiftPM plugin
Plugins/AWSLambdaDeployer/Plugin.swift	lambda-deploy SwiftPM plugin
Plugins/AWSLambdaBuilder/Plugin.swift	lambda-build SwiftPM plugin
Package@swift-6.4.swift	Swift 6.4 manifest gating new plugins
Package.swift	Dependency version bumps
Examples/Streaming+FunctionUrl/README.md	Example updated to new plugins
Examples/Streaming+Codable/README.md	Example updated to new plugins
Examples/Streaming+APIGateway/README.md	Example updated to new plugins
Examples/ServiceLifecycle+Postgres/README.md	Example updated to new plugins
Examples/S3EventNotifier/README.md	Example updated to new plugins
Examples/S3_Soto/README.md	Example updated to new plugins
Examples/S3_AWSSDK/README.md	Example updated to new plugins
Examples/ResourcesPackaging/README.md	Example updated to new plugins
Examples/README.md	Examples index updated (docker/container + aws configure)
Examples/MultiTenant/README.md	Example updated to new plugins
Examples/MultiSourceAPI/README.md	Example updated to new plugins
Examples/ManagedInstances/README.md	Example updated to new plugins
Examples/JSONLogging/README.md	Example updated to new plugins
Examples/HummingbirdLambda/README.md	Example updated to new plugins
Examples/HelloWorldNoTraits/README.md	Example updated to new plugins
Examples/HelloWorld/README.md	Example updated to new plugins
Examples/HelloJSON/README.md	Example updated to new plugins
Examples/CDK/README.md	Example updated to new plugins
Examples/BackgroundTasks/README.md	Example updated to new plugins
Examples/APIGatewayV2+LambdaAuthorizer/README.md	Example updated to new plugins
Examples/APIGatewayV2/README.md	Example updated to new plugins
Examples/APIGatewayV1/README.md	Example updated to new plugins
Examples/_MyFirstFunction/create_function.sh	Script updated for new flow
Examples/_MyFirstFunction/create_and_deploy_function.sh	Legacy script removed
Examples/_MyFirstFunction/clean.sh	Cleanup script updated to lambda-deploy --delete
.swiftformatignore	swiftformat ignore updates
.licenseignore	License ignore updates
.gitignore	Ignore .kiro/.claude, etc.
.github/workflows/scripts/check-archive-plugin-swift64.sh	New Swift 6.4 packaging test
.github/workflows/pull_request.yml	CI adjustments (docs check disabled, swift64 packaging test)
.github/workflows/integration_tests.yml	Add Swift 6.4 packaging plugin job

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The label still used the legacy plugin name; align it with the helper for clearer debugging/log correlation. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Previously a failed template write was printed but swallowed, so the SwiftPM plugin exited 0 and could not detect that scaffolding failed. Re-throw so the failure surfaces as a non-zero exit. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The function re-read CommandLine.arguments instead of using its arguments parameter, contradicting its signature and hurting testability. Use the parameter. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

URL(string:) is for URLs, not filesystem paths, and can mis-handle absolute paths containing spaces. Use URL(fileURLWithPath:). Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The lambda-init plugin's command type was named AWSLambdaPackager (copy-paste leftover). Rename it to match the plugin so diagnostics and stack traces are unambiguous. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The lambda-build plugin's command type was named AWSLambdaPackager (copy-paste leftover). Rename it to match the plugin. The default output directory is derived from the type name, so it moves from outputs/AWSLambdaPackager to outputs/AWSLambdaBuilder; update the Swift 6.4 archive-plugin CI script accordingly. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

sed -i '' is BSD/macOS-specific and fails on GNU sed (Linux). Use sed -i.bak, which works on both, and remove the backup file afterward. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The ignore entry pointed at Plugins/AWSLambdaInitializer/Template.swift, which does not exist. The scaffold template lives at Sources/AWSLambdaPluginHelper/lambda-init/Template.swift; point the ignore there. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Renaming the lambda-build plugin type to AWSLambdaBuilder (Copilot review) changed its default output directory from .build/plugins/AWSLambdaBuilder/outputs/AWSLambdaPackager to .build/plugins/AWSLambdaBuilder/outputs/AWSLambdaBuilder. Update every lambda-build reference to match: - Deployer.swift: the default builderPath lookup (the legacy archive packagerPath fallback is left pointing at AWSLambdaPackager). - All example READMEs, SAM templates, CDK stack, and DocC docs/tutorials. The archive-verb references (check-archive-plugin.sh, the archive path in the Swift 6.4 CI script, and the Deployer legacy fallback) intentionally keep the AWSLambdaPackager/AWSLambdaPackager path.

sebsto added 17 commits November 7, 2024 10:00

WIP : init plugin

2b5405a

WIP deploy plugin

cc08a9a

Merge branch 'main' into sebsto/plugin-scaffold

405906f

change plugin invocation name for consistency

9f7b043

Merge branch 'main' into sebsto/plugin-scaffold

9361bed

add implementation of AWS v4 Signer from aws-signer-v4 and HMAC+SHA25…

bd46345

…6 from CryptoSwift

swift format

90517ad

WIP : migrate archive plugin to new lambda-build

2bdd645

use Foundation to access Process on Linux

47dd245

add --with-url option

0665430

swift format

0bdc813

Merge branch 'main' into sebsto/new-plugins

0518a48

Merge branch 'main' into sebsto/new-plugins

3a5ef4e

Merge branch 'main' into sebsto/new-plugins

062c496

Merge branch 'main' into sebsto/new-plugins

32a0062

minor wording changes

e3a579c

Merge branch 'main' into sebsto/new-plugins

63702a5

sebsto added this to the 2.1 milestone Sep 23, 2025

sebsto self-assigned this Sep 23, 2025

sebsto added 🆕 semver/minor Adds new public API. kind/feature New feature. size/L Large task. (A couple of weeks of work.) kind/usability Usability of generated code, ergonomics. labels Sep 23, 2025

sebsto marked this pull request as draft September 23, 2025 19:28

sebsto linked an issue Sep 23, 2025 that may be closed by this pull request

[plugin] refactor the archive plugin #566

Closed

Merge branch 'main' into sebsto/new-plugins

bf83300

sebsto added 2 commits November 2, 2025 21:29

Merge branch 'main' into sebsto/new-plugins

781bf3b

Merge branch 'main' into sebsto/new-plugins

088ac9b

sebsto added 3 commits June 25, 2026 22:19

fix CI on static SDK build on Swift 6.4

079fea2

fix CI : plugin test on swift 6.4

a16f430

ignore .claude

8f5b559

sebsto mentioned this pull request Jun 25, 2026

Compiler crash on main (6.5-dev): SIL verification error (debug_value undef) on Mutex captured in nested Task inside task group swiftlang/swift#90211

Open

sebsto added 4 commits June 25, 2026 22:58

fix CI : doc

cb6aa73

fix ci : build plugin on swift 6.4

fb2f203

fix ci : workaround for swiftlang/github-workflows#291

1ace25c

fix ci : try to fix the docc regression

9207246

sebsto force-pushed the sebsto/new-plugins branch from d419e52 to 9207246 Compare June 25, 2026 21:43

sebsto added 2 commits June 25, 2026 23:55

fix ci : docc check

2294d2d

fix ci : exclude nightly-main

415b7ec

sebsto marked this pull request as ready for review June 25, 2026 22:23

sebsto requested review from Copilot and manojmahapatra June 25, 2026 22:23

Copilot started reviewing on behalf of sebsto June 25, 2026 22:28 View session

Copilot AI reviewed Jun 25, 2026

View reviewed changes

sebsto and others added 12 commits June 26, 2026 08:02

fix typo in Process.swift comment (save -> safe)

40f8034

Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

rename output dispatch queue label to AWSLambdaPluginHelper

4df8ea2

The label still used the legacy plugin name; align it with the helper for clearer debugging/log correlation. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

use URL(fileURLWithPath:) for --output-path in archive plugin

413e23b

URL(string:) is for URLs, not filesystem paths, and can mis-handle absolute paths containing spaces. Use URL(fileURLWithPath:). Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

use URL(fileURLWithPath:) for --output-path in lambda-build plugin

3bed4f8

URL(string:) is for URLs, not filesystem paths, and can mis-handle absolute paths containing spaces. Use URL(fileURLWithPath:). Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

make sed -i portable in integration-test.sh

c37a930

sed -i '' is BSD/macOS-specific and fails on GNU sed (Linux). Use sed -i.bak, which works on both, and remove the backup file afterward. Addresses Copilot review comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

fix ci : improve build time for plugin test on swift 6.4

4bcbb6b

sebsto merged commit 0528feb into main Jun 26, 2026
53 checks passed

sebsto deleted the sebsto/new-plugins branch June 26, 2026 07:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

v2 Plugin System: lambda-init, lambda-build, lambda-deploy#567
sebsto merged 67 commits into
mainfrom
sebsto/new-plugins

sebsto commented Sep 23, 2025 •

edited

Loading

Uh oh!

sebsto commented Sep 23, 2025

Uh oh!

tkrajacic commented Nov 1, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

sebsto commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Quick Start

Key Changes

Architecture

Builder (lambda-build)

Deployer (lambda-deploy)

Initializer (lambda-init)

Dependencies

Backward Compatibility

Documentation

Known Limitations

Testing

Uh oh!

sebsto commented Sep 23, 2025

Uh oh!

tkrajacic commented Nov 1, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sebsto commented Sep 23, 2025 •

edited

Loading

Builder (`lambda-build`)

Deployer (`lambda-deploy`)

Initializer (`lambda-init`)