Swift Lambda App

Template to build an Amazon Lambda app in Swift

Overview

This repo contains code and scripts to quickly get you started with writing Swift apps for AWS Lambda, Amazon's serverless computing platform. It contains:

A sample Lambda app that implements a custom skill for Amazon's Alexa Voice Service using AlexaSkillsKit
A setup to develop and test the app in your development environment
Scripts to build the app for the Lambda target environment
Integration tests to proof you app is working before deploying to Lambda
Instructions on deploying the app to Lambda (either manually or using Serverless)

swift-lambda-app has been inspired by SwiftOnLambda, which provided the initial working code to execute Swift programs on Lambda.

Also see the article Serverless Swift for a detailed introduction to running Swift on Lambda.

Using this Repo as a Template

Tools: Serverless (optional)

Simply fork this repo to start developing your own Lambda function in Swift. Alternatively, you can use Serverless to make a copy of this repo for you by using serverless install --url https://github.com/choefele/swift-lambda-app

Development

Tools: Xcode, ngrok (optional)

The sample app in this repo uses a standard Swift Package Manager directory layout and package file thus swift build, swift test and swift package generate-xcodeproj work as expected. Check out the SPM documentation for more info.

There are three targets:

AlexaSkill: this is a library with the code that implements the custom Alexa skill. It's a separate library so it can be used by the other two targets. Also, libraries have ENABLE_TESTABILITY enabled by default which allows you to use @testable import in your unit tests.
Lambda: The command line executable for deployment to Lambda. This program uses stdin and stdout for processing data.
Server (macOS only): To simplify implementing a custom Alexa Skill, the Server target provides an HTTP interface to the AlexaSkill library. This HTTP server can be exposed publicly via ngrok and configured in the Alexa console, which enables you to develop and debug an Alexa skill with code running on your development server. This target is macOS only because it wasn't possible to cleanly separate target dependencies and I didn't want to link libraries intended for server development to the Lambda executable used for deployment.

For development, I recommend a TDD approach against the library target because this results in the quickest turnaround for code changes. Uploading to Lambda to quickly verify changes isn't really an option because of slow updating times. Exposing your functionality via HTTPS as described below, however, enables you to test and debug your functionality in a slightly different way.

To run a local HTTPS server:

Make sure the sample builds by running swift build
Generate an Xcode project with swift package generate-xcodeproj
Open the generated Xcode project, select the Server scheme and run the product (CMD-R). This will start a server at port 8090
Install ngrok via brew cask install ngrok. This tool allows you to expose a local HTTP server to the internet
Run ngrok http 8090 and copy the HTTPS URL generated by ngrok (it looks similar to https://258ba658.ngrok.io)
To create an Alexa skill
Go to the Alexa console and create a new skill
Skill type: Custom Interaction Model
Intent: { "intents": [{"intent": "TestIntent"}]}
Sample utterances: "TestIntent test swift"
SSL Certificate: Select "My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority"
Service endpoint type: HTTPS (use the URL from ngrok)

Now you can test the skill in the Alexa Console using the utterance "test swift". This will call your local HTTP server allowing you to modify and debug your code with the Alexa service.

Integration

Tools: Docker, Travis

Before uploading to Lambda, it's worthwhile to run the unit tests in a Linux environment and run integration tests that simulate the execution environment. This repo provides run-unit-tests.sh to do the former and run-integration-tests.sh to do the latter.

run-unit-tests.sh builds and tests the Lambda target inside a Swift Docker container based on Ubuntu because there's currently no Swift compiler for Amazon Linux (based on RHEL). Executables built on different Linux distributions are compatible with each other if you provide all dependencies necessary to run the program. For this reason, the script captures all shared libraries required to run the executable using ldd.

To prove that the resulting package works, run-integration-tests.sh runs a release build of the Swift code inside a Docker container that comes close to Lambda’s execution environment (unfortunately, Amazon only provides a few Docker images that don't necessarily match what Lambda is using).

The integration with Lambda is done via a small Node.js script that uses the child_process module to run the Swift executable. The script follows Amazon's recommendations to run arbitrary executables in AWS Lambda.

After configuring Travis, you can run the same integration script also for every commit.

Deploying the Lambda Function

Deployment Using the Serverless Framework

Tools: Serverless

This project contains a serverless.yml configuration file for the Serverless Framework, which automates uploading and configuring the Lambda function:

Make sure you have your [AWS credentials configured] for Serverless(https://serverless.com/framework/docs/providers/aws/guide/credentials/)
Run run-integration-tests.sh to produce a zip file at .build/lambda/lambda.zip with all required files to upload to Lambda
Run sls deploy to upload and configure the Lambda function

To verify that the Lambda function works, run sls invoke -f alexaSkill -p session_start.json

Manual Deployment

To deploy your code to Lambda manually:

Run run-integration-tests.sh to produce a zip file at .build/lambda/lambda.zip with all required files to upload to Lambda
Create a new Lambda function in the AWS Console in the US East/N. Virginia region (for Europe use EU/Ireland)
Use an Alexa Skills Kit trigger
Runtime: NodeJS 4.3
Code entry type: ZIP file (upload the lambda.zip file from the previous step)
Handler: index.handler
Role: Create from template or use existing role

To verify that the Lambda function works, condigure a test event with the contents of session_start.json in the AWS console.

Creating an Alexa Skill

After creating the Lambda function, you can now create an Alexa skill:

Go to the Alexa console and create a new skill
Skill type: Custom Interaction Model
Intent: { "intents": [{"intent": "TestIntent"}]}
Sample utterances: "TestIntent test swift"
Service endpoint type: AWS Lambda ARN (use the ARN from the AWS Console)

Now you can test the skill in the Alexa Console using the utterance "test swift". More details on configuring Alexa skills can be found on Amazon's developer portal.