You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jul 14, 2020. It is now read-only.
AWS unfortunately does not provide an official swift runtime for its [Lambda](https://en.wikipedia.org/wiki/AWS_Lambda) offering. Therefore someone needs to do this, if we want to use the benefits of lambda and swift on the server. That's why this project exists. Hopefully this is sherlocked by AWS sooner rather than later. re:Invent is just around the corner. 🙃
10
+
AWS unfortunately does not provide an official Swift runtime for its [Lambda](https://en.wikipedia.org/wiki/AWS_Lambda) offering. To leverage the benefits of Lambda and Swift on the server, someone needs to build this. That's what this project is about. Hopefully it is [sherlocked](https://www.urbandictionary.com/define.php?term=sherlocked) by AWS sooner rather than later. re:Invent is just around the corner. 🙃
9
11
10
-
In order to achieve our goal this project consists out ot two parts:
12
+
In order to achieve the goal, this project consists out ot two parts:
11
13
12
-
1. A swift layer to run swift code within lambda. In other words: Without this your swift code won't run.
13
-
1. A swift package that you can use to get your next invocation from the lambda runtime and to post your lambda result back to lambda. In other words: Without this your swift code will not be able to process any tasks.
14
+
1. A Swift [layer](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html#runtimes-custom-build) to run Swift code within lambda. This provides the necessary libs for your Swift code to link against. In other words: without it, your Swift code won't run.
15
+
2. A Swift package that you can be used to retrieve your next invocation from the lambda runtime and to post your lambda result back to lambda. In other words: without it, your Swift code will not be able to process any tasks.
14
16
15
-
This project uses [Swift-NIO](https://github.com/apple/swift-nio). Therefore the developer facing API of this package expects to be initialized with an EventLoopGroup, exposes an `EventLoop` during an invocation as a property on the [`Context`](https://github.com/fabianfett/swift-aws-lambda/blob/5405bd30737a7347a95c7024bcb6f0a8fafb3931/Sources/AWSLambda/Context.swift#L16) and expects an `EventLoopFuture` to be returned. If you are not familiar with Swift-NIO, I highly encourage you to learn about [this first](https://github.com/apple/swift-nio#basic-architecture).
17
+
This project uses [Swift-NIO](https://github.com/apple/swift-nio). Therefore the developer facing API of this package expects to be initialized with an `EventLoopGroup`, exposes an `EventLoop` during an invocation as a property on the [`Context`](https://github.com/fabianfett/swift-aws-lambda/blob/5405bd30737a7347a95c7024bcb6f0a8fafb3931/Sources/AWSLambda/Context.swift#L16) and expects an `EventLoopFuture` to be returned. If you are not familiar with Swift-NIO, I recommend that you learn about [this first](https://github.com/apple/swift-nio#basic-architecture).
16
18
17
-
Your lambda needs to be build in the linux environment. Therefore we need[Docker](https://en.wikipedia.org/wiki/Docker_(software)) to compile your lambda. If you don't have Docker yet, now is a good time to go look for that.
19
+
Your lambda needs to be built in the linux environment. So we use[Docker](https://en.wikipedia.org/wiki/Docker_(software)) to compile your lambda. If you don't have Docker yet, now is a good time to go and learn about that.
18
20
19
21
## Status
20
22
21
-
-[x]A number of examples to get you on the run as fast as possible (including an [API-Gateway TodoList](http://todobackend.com/client/index.html?https://mwpixnkbzj.execute-api.eu-central-1.amazonaws.com/test/todos) example)
22
-
-[x] Tested integration with aws-swift-sdk
23
+
-[x][Two examples](https://github.com/fabianfett/swift-aws-lambda/tree/master/Examples) to get you up and running as fast as possible (including an [API-Gateway Todo-List](http://todobackend.com/client/index.html?https://mwpixnkbzj.execute-api.eu-central-1.amazonaws.com/test/todos))
24
+
-[x][Tested integration](https://github.com/fabianfett/swift-aws-lambda/blob/master/Examples/TodoAPIGateway/Sources/TodoAPIGateway/main.swift) with [`aws-swift-sdk`](https://github.com/swift-aws/aws-sdk-swift)
23
25
-[x] Unit and End-to-end Tests
24
26
-[x] CI Workflow with GitHub Actions
25
-
-[x] Wrapper functions to build a synchronous lambda
26
-
-[ ] Ready to use AWS Events structs to get you started as fast as possible
27
+
-[x] Wrapper function to build [a synchronous lambda](https://github.com/fabianfett/swift-aws-lambda/blob/7b542c1edf58b59cc7610cc1a9515f0b03332879/Sources/AWSLambda/Runtime%2BCodable.swift#L29)
28
+
-[ ] Ready to use [AWS Events](https://github.com/fabianfett/swift-aws-lambda/tree/master/Sources/AWSLambda/Events) structs to get you started as fast as possible
27
29
28
-
Alternatives: There is another project to get Swift to work within AWS-Lambda: [Swift-Sprinter](https://github.com/swift-sprinter/aws-lambda-swift-sprinter) If you don't like this project, maybe your needs get better addressed over there.
30
+
Alternatives: There is another project to run Swift within AWS-Lambda: [Swift-Sprinter](https://github.com/swift-sprinter/aws-lambda-swift-sprinter).
29
31
30
32
## Create and run your first Swift Lambda
31
33
32
-
This should help you to get started with the swift on lambda in AWS. We focus primarily on the AWS console. Of course you can use the aws-cli, sam-cli or cloudformation. At every step of your way.
34
+
This should help you to get started with Swift on AWS Lambda. We focus primarily on the AWS console, since it is the easiest way to begin with. Of course you can use the [aws-cli](https://aws.amazon.com/cli/), [sam-cli](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-layers.html), the [serverless-framework](https://serverless.com/framework/docs/providers/aws/guide/layers/), [cloudformation](https://aws.amazon.com/cloudformation/) or whatever tooling you prefer at every step of your way. We even encourage you to do so in a production environment. Noone likes clicky architectures. 🤯 If you are looking for an example check out the [sam-template](https://github.com/fabianfett/swift-aws-lambda/blob/master/Examples/TodoAPIGateway/template.yaml) in the [TodoBackend](https://github.com/fabianfett/swift-aws-lambda/tree/master/Examples/TodoAPIGateway) example.
33
35
34
-
### Step 1: Setup your layer (Prepare AWS Lambda to run swift)
36
+
*Note: The following instructions were recorded on 21.11.2019 and the GUI may have changed since then. Feel free to create an issue if you notice something different.*
35
37
36
-
Check out this repo and create layer yourself within this project:
38
+
### Step 1: Create & setup your layer (Prepare AWS Lambda to run Swift)
39
+
40
+
Check out the repo and create a layer yourself within the project:
37
41
38
42
```bash
39
43
$ cd Layer
40
44
$ make package_layer
41
45
```
42
46
43
-
The makefile uses Docker under the hood. So, you need to have this installed by now. You can change the swift version of your layer by using the enviornment variable `SWIFT_DOCKER_IMAGE`. Example:
47
+
The makefile uses Docker under the hood. So, you need to have it installed by now. You can change the swift version of your layer by using the enviornment variable `SWIFT_DOCKER_IMAGE`. Example:
44
48
45
49
```bash
46
50
$ SWIFT_DOCKER_IMAGE=5.1.2 make package_layer
47
51
```
48
52
49
-
In the `Layer` directory you will now have an `swift-lambda-runtime.zip`.
53
+
In the `Layer` directory you will now find an `swift-lambda-runtime.zip`.
50
54
51
-
Open your AWS Console and navigate to lambda. Select "Layers" in the side navigation and click on "Create Layer" in the upper right corner. Give your runtime a name. I suggest: "Swift [Version]". Upload your zip layer from the `Layer` folder and click "Create".
55
+
Open your AWS Console and navigate to [Lambda](https://console.aws.amazon.com/lambda/home). Select "Layers" in the side navigation and click on "Create Layer" in the upper right corner. Give your runtime a name. I suggest: "Swift [Version]" (Sadly dots are not allowed in the name. 😞). Upload your zip layer from the `Layer` folder and click "Create".
52
56
53
-
Next you will see this screen. Note the selected `Version ARN`. Please copy & paste that somewhere. You'll need this later.
57
+
Next you will see the following screen. Note the selected `Version ARN`. Please copy & paste that somewhere. You'll need it later.
54
58
55
59
56
60
@@ -79,7 +83,7 @@ let package = Package(
79
83
)
80
84
```
81
85
82
-
Then open your `main.swift` and create your function. Your function can do whatever you like. In this example we just want to square numbers.
86
+
Then open your `main.swift` and create your function. Your function can do whatever you like. In this example we just want to square numbers although your function can do whatever you like.
83
87
84
88
```swift
85
89
importAWSLambda
@@ -115,7 +119,7 @@ catch {
115
119
116
120
### Step 3: Build your lambda
117
121
118
-
Your lambda needs to be compiled in the linux environment. That's why we use Docker to compile your lambda.
122
+
Your lambda needs to be build for the linux environment. So we use Docker to compile the lambda. Please be aware that you need to use the same Swift version for compiling your lambda as you will use for running it (See Step 1 - Create & setup your layer). [ABI Stability is not a thing on Linux](https://swift.org/blog/abi-stability-and-more/).
119
123
120
124
```bash
121
125
# build your lambda in the linux environment
@@ -127,41 +131,60 @@ $ zip -j lambda.zip .build/release/$(EXAMPLE_EXECUTABLE)
127
131
128
132
### Step 4: Create your lambda on AWS
129
133
130
-
Open your AWS Console and navigate to lambda. Select "Functions" in the side navigation and click on "Create function" in the upper right corner. Give your function a name! I'll choose "SquareNumbers". And select the runtime "Provide your own bootstrap".
134
+
Open your AWS Console and navigate to [Lambda](https://console.aws.amazon.com/lambda/home). Select "Functions" in the side navigation and click on "Create function" in the upper right corner. Give your function a name! I'll choose "SquareNumbers". And select the runtime "Provide your own bootstrap".
131
135
132
136
You'll see a screen that looks like this.
133
137
134
138
135
139
136
-
First we need to select our lambda swift runtime. We do so by clicking "Layers" below the function name in the center of the screen. The lower part of the screen changes and we can see an "Add Layer" button in the center. On the next screen we need to select "Provide a layer version ARN" and then we enter the ARN that we saved, when we created the layer. Next we click "Add".
140
+
First we need to select our Swift runtime. We do so by clicking "Layers" below the function name in the center of the screen. The lower part of the screen changes and we can see an "Add Layer" button in the center. Let's click that button. On the next screen we need to select "Provide a layer version ARN" and there we enter the ARN that we saved, when we created the layer. Next we click "Add".
137
141
138
-
142
+
139
143
140
-
Now we should see a layer below our function. Next we click our function and select, in the lower screen we have the section "Function Code". Select "Upload a zip file" in the "Code entry type". Click on "Upload" and select your `lambda.zip`. In the Handler fill in your `ExecutableName.FunctionName`. In my case this is `SquareNumber.squareNumber`. Next hit "Save".
144
+
Now we should see a layer below our function. Next we click on the function name. Now we should see the section "Function Code" in the lower part of the screen. Select "Upload a zip file" in the "Code entry type". Click on "Upload" and select your `lambda.zip`. In the "Handler" fill in your `ExecutableName.FunctionName`. In my case it is `SquareNumber.squareNumber`. Next hit "Save".
141
145
142
146
143
147
144
148
### Step 5: Invoke your lambda
145
149
146
-
Now the only thing left, is to invoke your lambda. Select "Test" (in the upper right corner) and change your test payload to whatever json you want to supply to your function. Since I want numbers squared mine is.
150
+
The only thing left, is to invoke your lambda. Select "Test" (in the upper right corner) and change your test payload to whatever json you want to supply to your function. Since I want numbers squared mine is as follows:
147
151
148
152
```json
149
153
{
150
154
"number": 3
151
155
}
152
156
```
153
157
154
-
Also you need to give your Event a name. Mine is "Number3". Click "Save" and you can click "Test" again, and this time your lambda will execute. If everything went well you should see a scren like this:
158
+
Since AWS wants to reuse your event for tests over and over again, you need to give your test event a name. Mine is "Number3". Click "Save" and you can click "Test" again, and this time your lambda will execute. If everything went well you should see a scren like this:
155
159
156
160
157
161
162
+
## What's next.
163
+
164
+
Great! You made it so far. In my point of view you should now familiarize yourself with some tooling around AWS Lambda.
165
+
166
+
### Lambda deployment/testing tooling
167
+
168
+
May it be [serverless] or aws-sam. Because noone wants or should do build Lambda services by clicking around in the AWS Console. The TodoList example is [setup with aws-sam](https://github.com/fabianfett/swift-aws-lambda/blob/master/Examples/TodoAPIGateway/template.yaml). If you need more help about how to get started with aws-sam, please reach out by opening a GitHub issue.
169
+
170
+
### aws-sdk
171
+
172
+
There are two projects providing you an API to interact with AWS resources.
173
+
174
+
-[`aws-sdk-swift`](https://github.com/swift-aws/aws-sdk-swift) A community driven effort. The [TodoList example](https://github.com/fabianfett/swift-aws-lambda/tree/master/Examples/TodoAPIGateway) uses this sdk to [query DynamoDB](https://github.com/fabianfett/swift-aws-lambda/blob/master/Examples/TodoAPIGateway/Sources/TodoService/DynamoTodoStore.swift).
175
+
-[`smoke-aws`](https://github.com/amzn/smoke-aws) An amazon (not AWS 😉) driven effort. Please be aware that this sdk does not return `EventLoopFuture`s. Therefore integrating it may be a little tricky. Not tested.
176
+
158
177
## Contributing
159
178
160
-
All developers should feel welcome and encouraged to contribute to swift-aws-lambda. The current version of swift-aws-lambda has a long way to go before being ready for production use and help is always welcome.
179
+
Please feel welcome and encouraged to contribute to swift-aws-lambda. The current version of swift-aws-lambda has a long way to go before being ready for production use and help is always welcome.
161
180
162
-
If you've found a bug, have a suggestion or need help getting started, please open an Issue or a PR. If you use this package, please reach out and share your experience.
181
+
If you've found a bug, have a suggestion or need help getting started, please open an Issue or a PR. If you use this package, I would love you to reach out and share your experience.
182
+
183
+
Focus areas for the time being:
184
+
- A slim runtime layer without FoundationNetworking and libCurl.
185
+
- Implementing [all aws lambda resource events](https://github.com/aws/aws-lambda-go/tree/master/events). Those should be quite easy for a first PR. Just grab one and go!
186
+
- Fixing all the bugs and performance bottlenecks that came to be with the first release.
163
187
164
188
## Credits
165
189
166
190
-[Toni Suter](https://github.com/tonisuter/aws-lambda-swift) created the original makefile that creates the layer to run the lambda.
0 commit comments