Quickstart¶
swift-lambda brings the power and ease-of-use of the Swift programming language to the scalability and buzzword-compliance of AWS Lambda. Use the tools you already know and love to power the backend of your mobile application.
Installation¶
swift-lambda can be installed using Homebrew:
$ brew install --HEAD awswift/swift-lambda/swift-lambda
Pre-requisites¶
A Swift programming environment. On macOS, this means installing Xcode. On Linux, it means downloading Swift from the official website.
Docker. We use Docker to emulate a local version of the Linux-y AWS Lambda runtime environment. Because Swift compiles to native code, we need to compile the code on a computer that is as similar to Lambda as possible.
Note that this is still needed even if you are running on Ubuntu, because Lambda is different enough from Ubuntu that compiling on your own machine won’t work.
Interim: The AWS CLI. Porting the AWS APIs is still a work in progress in the
awswift/Awswift
repo. Until that is complete we have relied on shelling out to the CLI tool for the alpha release.Interim: The
stackup
Ruby gem. This is a great utility for dealing with CloudFormation and we are shelling out to it until such functionality has been replicated in a Swift library.
Usage¶
swift lambda setup
¶
setup
is a once-off command that will get an AWS account ready for Swift-powered
AWS Lambda functions. Right now it creates an S3 bucket for storing your code and
an IAM execution role to grant your Lambda functions permission
to write logs.
swift lambda init <name>
¶
init
will initialise a brand-new Hello, World! Swift-powered AWS Lambda
function. Everything you need to get up and running will be created for you.
<name>
is how you tell the init
command what you want your function to
be called!
swift lambda build
¶
build
will create the Zip archive that you upload to AWS Lambda in order
to run your code. swift-lambda will compile your code in a Lambda-like Docker
container, zip it up (alongside the Swift runtime) and stick in a few extra
files that Lambda requires you to have.
swift lambda deploy [--new-version] [--skip-libs]
¶
deploy
is how you get the Zip file from the previous command onto Lambda
itself. You could upload the zip using the AWS web console, but we provide
this convenience helper so you can iterate on your code as quickly as you
can type.
--skip-libs
skips uploading the native libraries that the Swift function
depends on. This makes for a much faster deployment process. Note that this
flag is temporary and will be automatically calculated and hence removed soon.
~~--new-version
lets you take advantage of AWS Lambda function versioning.
It will increment your function’s version number with this latest upload.~~
swift lambda logs [--tail]
¶
logs
allows you to see everything you print()
in your Lambda function from
the comfort of your terminal. This can be invaluable while debugging to see
what is going on.
--tail
will output log lines to your terminal as they happen in real-time.
swift lambda destroy
¶
destroy
deletes all artifacts of your Lambda function on AWS. Maybe you’re
done with a dev version of your code and ready to start a new project -
stop paying for storage and cluttering up your Lambda web console.
swift lambda debug
¶
debug
allows you to step through your Lambda function from within Xcode,
as if you were running it locally.
swift lambda invoke [--async] [--local]
¶
invoke
will execute your Lambda function and return its output to your
terminal.
--async
can be used for long-running Lambda functions where you don’t want
to wait for it to finish. You can still monitor its progress using logs
.
--local
will run your Lambda function inside a Lambda-like Docker container
on your own computer. This might be preferable if you have no Internet
connectivity and can’t upload your function to AWS.
Function structure¶
Beyond the Swift code itself, swift-lambda also needs a swift-lambda.json
file to know
a bit about your intentions for this code. It is a JSON file that has some of
the values required for publishing your code to Lambda. The structure is as
follows:
{
"Name": "Swifty McLambdaface",
"Description": "My awesome new backend function written in Swift",
"Memory": 128,
"Timeout": 30
}
You will also have a Package.swift
as per Swift Package Manager
conventions. It can be as simple as:
import PackageDescription
let package = Package(
name: "lambdaface",
dependencies: [
.Package(url: "https://github.com/awswift/swift-lambda-runtime", majorVersion: 0, minor: 1)
]
)
Finally, the last required piece is Sources/main.swift
. This is the entrypoint
to the Swift executable that swift-lambda will call. An example file would be:
import Foundation
import SwiftLambdaRuntime
SwiftLambdaRuntime().run { event, context, callback in
let name = event["name"] ?? "World"
callback(["output": "Hello, \(name)"])
}