It's been a while since I posted anything to my blog. I thought I would write this article though because it has been an issue that has had a lot of discussion among key members of the swift on server community.

We recently released version 2.0 of Hummingbird the swift server framework. During its development the thing that has probably taken the most of my head space is how to return an HTTP response with a streamed payload within the structured concurrency paradigm.

To provide some context, each request to the server is processed by a middleware stack and then an endpoint that returns a response which will be processed by the middleware stack in the reverse order. One of the key features is that each middleware must be able to process the response payload as it traverses back down the stack.

The example route I'm going to use to demonstrate the issues will return a response where the payload consists of 10 chunks of data, each 1K of random bytes, with a one second pause between sending each chunk.

AsyncSequence

The first tool in the box that most people will reach for in this situation is an AsyncSequence of byte buffers. It seems obvious they allow us to provide a stream of data over time. In middleware you can process the contents of the response payload by mapping the results of one AsyncSequence onto another.

But in this situation it is not the right tool. You need to return from your endpoint handler back to the server level of your application to read your AsyncSequence and write the results out to the underlying transport, but you also need a task to feed the AsyncSequence with buffers, but if you have already returned from your endpoint that task cannot be generated in a structured way. Below is an example demonstrating the issue.

func stream(request: Request) async throws -> Response {
    let (stream, cont) = AsyncStream.makeStream(of: [UInt8].self)
    // the only way I can feed the AsyncStream is with an unstructured
    // task.
    Task {
        for _ in 0..<10 {
            try await Task.sleep(for: .seconds(1))
            let buffer = (0..<size).map { _ in UInt8.random(in: 0...255) }
            cont.yield(buffer)
        }
        cont.finish()
    }
    return Response(status: .ok, body: stream)
}

Response body writer with closure

The second solution is to use a closure that accepts a writer type for the response body. The endpoint returns the closure and at the server level this closure is called with a writer type that writes data to the underlying transport.

func stream(request: Request) async throws -> Response {
    let responseBody = ResponseBody { writer in 
        for _ in 0..<10 {
            try await Task.sleep(for: .seconds(1))
            let buffer = (0..<size).map { _ in UInt8.random(in: 0...255) }
            try await writer.write(buffer)
        }
    }
    return Response(status: .ok, body: responseBody)
}

Using this method it is easy to add shortcuts to ResponseBody to make it easy to return single buffers, sequences of buffers etc

extension ResponseBody {
    public init(buffer: ByteBuffer) {
        self.init { writer in
            try await writer.write(buffer)
        }
    }

    public func init(contentsOf buffers: some Sequence<ByteBuffer>) {
        self.init { writer in
            for buffer in buffers {
                try await writer.write(buffer)
            }
        }
    }
}

By creating a new writer type that processes your response payload and passes it onto the original writer provided you can process the response body in a middleware as well. For this to work though you need a protocol defining the requirements for your writer type and then accept an existential of this protocol in your response closure so any writer can be used.

let newResponseBody = ResponseBody { writer in
    let newWriter = TransformingWriter(writer)
    try await oldResponseBody.write(newWriter)
}

This isn't strictly true structured concurrency though. The closure you construct in your endpoint function isn't being run while you are in that function. The idea behind structured concurrency is that all the code encapsulated inside a single function has finished by the time you leave that function.

Passing in a response writer

The third solution allows you to write endpoint functions in a completely structured way. We do this by passing the writer into the endpoint function and have the function write the response itself.

func stream(request: Request, responseWriter: ResponseWriter) async throws {
    try await responseWriter.writeHead(status: .ok)
    for _ in 0..<10 {
        try await Task.sleep(for: .seconds(1))
        let buffer = (0..<size).map { _ in UInt8.random(in: 0...255) }
        try await responseWriter.writeBody(buffer)
    }
    responseWriter.finish()
}

By the time we leave this function we know for sure all response writing has finished. It passes all the requirements of structured concurrency. It is the most flexible method and allows us to do more complex things like sending informational status (1xx) responses separately from the main response.

But it also passes a lot of the complexity of writing the response onto the end user. Ergonomically it is more awkward to write than just returning a Response. Error handling is complex, you have to keep track of what parts of the response you have written. You have to differentiate between errors generated that you want to provide responses for eg authentication errors and errors that occurred when writing the response to the underlying transport. Some of this can be caught at compile time with clever usage of non-copyable types, but even so this doesn't reduce the complexity pushed onto your endpoint function.

I don't know of a solution for implementing middleware processing of response payloads using this method though. I haven't looked into it too hard but I imagine it would involve passing in a new response writer type that wraps the original response write.

Hummingbird

So what did I end up going for in Hummingbird? I ended up going for a combination of the third and second methods. I don't think most end users want the added complexity, so at the router level where most users will experience Hummingbird we use a version of method 2. We can hide the complexity of the response writing as it is encapsulated in one type but still allows users to do more complex things.

It is possible to implement method 2 on top of a server using method 3. If you return a response which consists of the response head and body writing closure, you can use a response writer to write the returned head, then pass a response body writer that writes to the response writer into the response body closure. Because of this at the server level we have implemented method 3.

If someone wants to write a server that uses response writers they can still use the Hummingbird server, they'll just need to write their own Router.

You find the Hummingbird implementation here.

Other packages

What are other packages in the Swift on server eco-system doing? There are two other packages I know that are tackling this issue at the moment. Version 2.0 of gRPC currently in development is using a version of method 2. The proposal for v2 of swift-aws-lambda-runtime is considering something similar to method 3. So there is no correct way to do this, it just depends on your preferences.

For most of this year I have been working on the Swift extension for Visual Studio Code. The work is part of the Swift Server Workgroup push to improve the Swift development experience outside of the Apple eco-system. In July I posted an article on the swift.org website giving an overview of the extension and what functionality it provides. Given this was a general overview a number of the more minor features were not included in that article. Below is a list of some of those, plus some new features that have been added since the original article was written.

Local editing of packages

The extension provides the ability to replace a package dependency with a locally edited version of that dependency via a context menu in the package dependency view. Right click on the dependency you want to replace and select Use Local Version. A file dialog will come up. Select the folder for the local version of the dependency and you will now be using that version of the dependency. If you want to edit the code in the local version, right click on the dependency again and select Add to Workspace. This will add the package to your workspace. To revert to using the the original version of the dependency there is a context menu entry Revert to Original Version.

I would have included this in the original swift.org article except with Swift 5.6 the feature is a bit flakey. Sometimes the edit state would be changed without any user input. This has since been resolved in Swift 5.7.

Commands

The VS Code Swift extension adds a number of Swift related commands. To bring up the command list press Cmd+Shift+P (Ctrl+Shift+P on Linux). Then type "swift" in the filter bar at the top. This will display the list of commands available to you given the current context. Some commands are only available in certain situations.

Running Swift Scripts

The command Run Swift Script will use the contents of the current editor that has focus and run it as a Swift script. It is not necessary to have a file that backs up the editor contents. This means you can open a new file, set its type to Swift and treat its contents as if it is a Swift Playground. With this you can test new Swift features quickly and easily or maybe remind yourself how an API works. Swift scripts are limited to only importing frameworks that come with your Swift installation like Foundation.

Running/Debugging Swift Snippets

A Swift Snippet is a new feature of Swift 5.7. They are single Swift files meant to demonstrate features of a Swift package. They can be used to provide code to be display inline in documentation, or complete sample projects. The extension provides two functions to ensure Snippets work as expected. Run Swift Snippet which will run the Snippet and display its output in the terminal and Debug Swift Snippet which will run the Snippet inside a debugger. Both of these commands and the Run Swift Script command are available via the Swift submenu of the editor context menu.

Select Xcode Install

On macOS Visual Studio Code gets its Swift toolchain/SDK from your Xcode installation. By default it will use the toolchain included in your active Xcode installation ie the one returned from xcode-select -p. If you would like to use a toolchain from a different Xcode installation there is a command Select Xcode Developer Dir. This will display a list of all the Xcode installations on your system. Selecting one will set the toolchain for your current workspace.

Comment Completion

Documenting your code is important and there is a standard method to provide inline documentation for functions in Swift. It involves a block comment with each line prefixed by ///. it includes a description of your function, the parameters passed in and the return value. Remembering the format for this comment can be a pain. So the extension provides a text completion snippet to generate this block comment. Type /// above a function and an option to insert the block comment will appear next to your cursor. Press return and it will be inserted. You can move between the function description, parameter descriptions and return value description by pressing tab.

Swift Log

Go to the output pane (Cmd+Shift+U). In the drop down box on the right hand of the screen select Swift. This will show a log of many of the operations the Swift extension has performed. You can extend this log by enabling the Swift: Diagnostics setting. If you are having an issue with the extension and want to add an Issue to the GitHub repository, it is very helpful if you also provide the contents of this log.

Swift Command Plugins

The extension will create a Task for each Swift command plugin. Select Run Task... from the Terminal menu and type swift-plugin in the filter bar. A list of the Command Plugins attached to the Swift Packages you have in your workspace will appear. Select one to run it. You can edit the options for a plugin by pressing the cog icon on the right hand side of the menu. This will generate an entry in the tasks.json file which you can edit. Below you can see an edited task for building documentation for the MQTTNIO package.

The list of features above alongside the swift.org article cover most of the features of the Visual Studio Code Swift extension. Hopefully this article has give some exposure to some of those lesser known features.

In this article I am going to cover how to build a HTTP Proxy server using Swift. We will use the Hummingbird HTTP server framework as the basis for the server and use the Swift server AsyncHTTPClient HTTP client to forward on requests to the target service.

What is a proxy server

A proxy server is a service that sits between a client and another service. It forwards messages from the client onto the other service and returns the responses received back to the client. Before forwarding messages it may process these in some manner and similarly it can process responses returned.

Uses

Proxy servers can be used for many purposes: as a gateway between different domains, providing an authentication layer to a service, allowing anonymous access to services, logging API calls, load balancing by passing requests to one of many instances of a service, caching responses, decrypting TLS requests and encrypting responses.

Let’s build one

In this article we are going to build a proxy server that just forwards HTTP packets on to the target service. You can find the sample code for the article here.

Creating the project

We will use the Hummingbird template project as the starting point for our server. We can either clone this repository, or press the use this template button on the GitHub web page for the project and create our own repo. The template project creates a server and starts it, provides command line options and a place to configure our application. More can be found out about it here.

Add AsyncHTTPClient

We are using AsyncHTTPClient in our project so we need to add it as a dependency in Package.swift.

First add it as a Package dependency

dependencies: [
    ...
    .package(url: "https://github.com/swift-server/async-http-client.git", from: "1.6.0"),
],

And then add it as a target dependency

targets: [
    .executableTarget(name: "App",
        dependencies: [
            ...
            .product(name: "AsyncHTTPClient", package: "async-http-client"),
        ],

We are going to store the HTTPClient as an extension to the HBApplication. This allows us to manage the HTTPClient's lifecycle and call syncShutdown on it before it is deleted.

extension HBApplication {
    var httpClient: HTTPClient {
        get { self.extensions.get(\.httpClient) }
        set { self.extensions.set(\.httpClient, value: newValue) { httpClient in
            try httpClient.syncShutdown()
        }}
    }
}

The closure at the end of the set function is called on HBApplication shutdown. This also means we have access to the HTTPClient whenever we have a reference to the HBApplication although we are not going to use this here.

Add middleware

We are going to implement our proxy server as middleware. The middleware will take a request, send it on to the target service and then respond with the response from the target service. Here is our initial version of the middleware. It will require the HTTPClient and the URL of the target service.

struct HBProxyServerMiddleware: HBMiddleware {
    let httpClient: HTTPClient
    let target: String

    func apply(to request: HBRequest, next: HBResponder) -> EventLoopFuture<HBResponse> {
        return httpClient.execute(
            request: request,
            eventLoop: .delegateAndChannel(on: request.eventLoop),
            logger: request.logger
        )
    }
}

Now we have the HTTPClient and the HBProxyServerMiddleware middleware we add them to application in HBApplication.configure. Lets set the target of our proxy to be http://httpbin.org.

func configure(_ args: AppArguments) throws {
    self.httpClient = HTTPClient(eventLoopGroupProvider: .shared(self.eventLoopGroup))
    self.middleware.add(HBProxyServerMiddleware(httpClient: self.httpClient, target: "http://httpbin.org"))
}

Converting types

When we build the above, it fails to compile. This is because we need to convert between Hummingbird and AsyncHTTPClient Request and Response types. Also we need to incorporate the target service URL into the request.

Request conversion

To convert from a Hummingbird HBRequest to a AsyncHTTPClient HTTPClient.Request we first need to collate the HBRequest body which may still be loading. This makes the conversion process asynchronous. So it needs to return an EventLoopFuture which will be fulfilled with the result of the conversion later on. Lets add a conversion function to HBRequest

extension HBRequest {
    func ahcRequest(host: String) -> EventLoopFuture<HTTPClient.Request> {
        // consume request body and then construct AHC Request once we have the
        // result. The URL for the request is the target server plus the URI from
        // the `HBRequest`.
        return self.body.consumeBody(on: self.eventLoop).flatMapThrowing { buffer in
            return try HTTPClient.Request(
                url: host + self.uri.description,
                method: self.method,
                headers: self.headers,
                body: buffer.map { .byteBuffer($0) }
            )
        }
    }
}

Response conversion

The conversion from HTTPClient.Response to HBResponse is considerably simpler.

extension HTTPClient.Response {
    var hbResponse: HBResponse {
        return .init(
            status: self.status,
            headers: self.headers,
            body: self.body.map { HBResponseBody.byteBuffer($0) } ?? .empty
        )
    }
}

We can now add these two conversion steps into the apply function of HBProxyServerMiddleware. While we are at it, lets also add some logging.

func apply(to request: HBRequest, next: HBResponder) -> EventLoopFuture<HBResponse> {
    // log request
    request.logger.info("Forwarding \(request.uri.path)")
    // convert to HTTPClient.Request, execute, convert to HBResponse
    return request.ahcRequest(host: target).flatMap { ahcRequest in
        httpClient.execute(
            request: ahcRequest,
            eventLoop: .delegateAndChannel(on: request.eventLoop),
            logger: request.logger
        )
    }.map { response in
        return response.hbResponse
    }
}

Now everything should compile. The middleware will collate the HBRequest body, convert it to a HTTPClient.Request, send this request to the target service using HTTPClient and then convert the response to a HBResponse which is then returned back to the application.

Run the application, open a web browser and type in localhost:8080. We should see the httpbin.org web site which we set as the proxy target earlier on.

Streaming

The setup above is not very optimal. It waits until a request is fully loaded before forwarding it on to its target service and similarly in the other direction it waits until the response has loaded before sending that back to the client. This slows down the forwarding process and also can use a lot of memory if request or response payloads are large.

We can improve this by streaming request and response payloads. Start sending the request to the target service as soon as we have its head and stream the body parts as they are received. Similarly in the other direction start sending the response back once we have its head. Removing that wait for a full request or response will improve the performance of the proxy server.

We can still have memory issues though if communication between the client and the proxy and communication between the proxy and target service run at different speeds. Data will start to back up if we are receiving it faster than we are processing it. To avoid this happening we need to be able to apply back pressure to stop reading in additional data until we have processed enough of the data that is in memory. With this we can keep the amount of memory used by the proxy to a minimum.

Streaming requests

Streaming the request payload is a fairly easy process. In actual fact it simplifies the construction of the HTTPClient.Request as we don't need to wait for the request to be fully loaded. How we construct the HTTPClient.Request body though will be based on whether the full HBRequest is already in memory. If we return a streaming request, back pressure is automatically applied as the Hummingbird server framework does this for us.

func ahcRequest(host: String, eventLoop: EventLoop) throws -> HTTPClient.Request {
    let body: HTTPClient.Body?

    switch self.body {
    case .byteBuffer(let buffer):
        body = buffer.map { .byteBuffer($0) }
    case .stream(let stream):
        body = .stream { writer in
            // as we consume buffers from `HBRequest` we write them to
            // the `HTTPClient.Request`.
            return stream.consumeAll(on: eventLoop) { byteBuffer in
                writer.write(.byteBuffer(byteBuffer))
            }
        }
    }
    return try HTTPClient.Request(
        url: host + self.uri.description,
        method: self.method,
        headers: self.headers,
        body: body
    )
}

Streaming responses

Streaming responses requires a class conforming to HTTPClientResponseDelegate. This will receive data from the HTTPClient response as soon as it is available. The response body is received as a series of ByteBuffers. We can feed these ByteBuffers to a HBByteBufferStreamer. The HBResponse we return is constructed with this streamer instead of a static ByteBuffer.

If we combine the request streaming with the response streaming code our final apply function should look like this

func apply(to request: HBRequest, next: HBResponder) -> EventLoopFuture<HBResponse> {
    do {
        request.logger.info("Forwarding \(request.uri.path)")
        // create request
        let ahcRequest = try request.ahcRequest(host: target, eventLoop: request.eventLoop)
        // create response body streamer. maxSize is the maximum size of object it can process
        // maxStreamingBufferSize is the maximum size of data the streamer is allowed to have
        // in memory at any one time
        let streamer = HBByteBufferStreamer(eventLoop: request.eventLoop, maxSize: 2048*1024, maxStreamingBufferSize: 128*1024)
        // HTTPClientResponseDelegate for streaming bytebuffers from AsyncHTTPClient
        let delegate = StreamingResponseDelegate(on: request.eventLoop, streamer: streamer)
        // execute request
        _ = httpClient.execute(
            request: ahcRequest,
            delegate: delegate,
            eventLoop: .delegateAndChannel(on: request.eventLoop),
            logger: request.logger
        )
        // when delegate receives head then signal completion
        return delegate.responsePromise.futureResult
    } catch {
        return request.failure(error)
    }
}

You'll notice in the code above we don't wait on the result of httpClient.execute. This is because if we did, the function would wait for the whole response body to be in memory before continuing. We want to be processing the response straight away so instead we add a promise to the delegate that is fulfilled with a HBResponse holding the head details and the streamer as soon as we receive the head. The EventLoopFuture of this promise is what we pass back from the apply function.

I haven't included the code for StreamingResponseDelegate here as it is not small, but you can find it in the full sample code.

Sample code additions

The sample code has a few changes to what is detailed above.

1. The default bind address port is 8081 instead of 8080. Most Hummingbird examples run on 8080 so to use the proxy alongside those examples it needs to bind to a different port.
2. I added a location option which allows us to forward only requests from a particular base URL
3. I added command line options for both target and location so these can be changed without rebuilding the application
4. I remove the host header or request so it can be filled out with the correct value
5. When converting a streaming request if the content-length header was provided I pass that along to the HTTPClient streamer to ensure the content-length header is set correctly for the request to the target server.

Alternatives

Instead of using Hummingbird for the Proxy server we could use HummingbirdCore instead. This would provide a bit of extra performance as it would remove extra layers of code but at the expense of flexibility. Adding any extra routing or middleware would require a lot more work. I have example code for a proxy server using only HummingbirdCore here.

Of course the other alternative would be to use Vapor. I would imagine an implementation in Vapor would look very similar to what is described above and shouldn't be too hard. I'll leave that to someone else though.

The Hummingbird server framework is designed to be flexible. It imposes as little structure as possible on how you build your application, but sometimes you need some structure. Do you really want to build all your application setup boilerplate every time you create a new app? To avoid this I have written a hummingbird project template which can be your starting point for your next app.

Template repository

GitHub has a feature called template repositories. These allow you to create a new project repository setup for a particular type of project. I have created a Hummingbird template here.

To create your Hummingbird project you go to the template project in GitHub and press the Use this template button. You now have the basis for building your next great server application.

Details

Here I will go into a bit of detail of what is involved in the template.

Package.Swift

The project is setup with the Swift Package Manager. The Package.swift file defines all the project dependencies and targets.

// swift-tools-version:5.5
import PackageDescription

let package = Package(
    name: "hummingbird-template",
    products: [
        .executable(name: "App", targets: ["App"]),
    ],
    dependencies: [
        .package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "0.15.0"),
        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.0.0")
    ],
    targets: [
        .executableTarget(name: "App",
            dependencies: [
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
                .product(name: "Hummingbird", package: "hummingbird"),
            ],
            swiftSettings: [
                // Enable better optimizations when building in Release configuration. Despite the use of
                // the `.unsafeFlags` construct required by SwiftPM, this flag is recommended for Release
                // builds. See <https://github.com/swift-server/guides#building-for-production> for details.
                .unsafeFlags(["-cross-module-optimization"], .when(configuration: .release))
            ]
        ),
        .testTarget(name: "AppTests",
            dependencies: [
                .byName(name: "App"),
                .product(name: "HummingbirdXCT", package: "hummingbird")
            ]
        )
    ]
)

In this file you can see we have

1. The project name, currently hummingbird-template
2. The name of the executable, App and the targets it requires
3. The packages we are dependent on ie hummingbird and also Apple's swift-argument-parser to ease reading of command line arguments.
4. Two targets, the application App and the test project AppTests.

Source code

The App source code consists of two files.

1. App.swift this is the entrypoint for your application. It defines the commandline arguments and starts and stops your application. If you need to add more commandline arguments to your application do it here.
2. Application+configure.swift which is where you configure your application, add routes, add middleware and any other general HBApplication setup. There is one default route added GET /health which return .ok.

The AppTests source code consists of one set of tests AppTests.swift. It has one example test in there using the HummingbirdXCT framework to test the GET health route setup in your App.

Other files

The project template also includes the following files.

1. Dockerfile for building and running docker images of your project
2. .dockerignore file containing folders you don't need to sync when building your docker images
3. .gitignore with a list of standard files to not include in your project
4. README.md for you to tell everyone about your great project

This is all the boilerplate you should need to start your application. How you structure the rest of it is up to you. Now, let's get creating!

Swift 5.5 has been released. This new release includes a series of new concurrency features including, async/await, structured concurrency and actors. Probably one of the most exciting series of additions to Swift in a long time (and this is from a language with new features appearing, what seems like, every other week).

The recently released version of Hummingbird (v0.13.0) includes new APIs that allow you to take advantage of some of these new concurrency features. You can add async route handlers functions, add middleware using async functions and various systems have been augmented with new async apis.

Async route handlers

Where previously an asynchronous route handler function would return an EventLoopFuture it is now possible instead to use an async handler function. Adding an async handler is as easy as adding any other handler.

app.router.get("test-async") { request -> String in
    // the await means this is an async function
    let result = await asyncOperation()
    return result.description
}

Async middleware

There is a new protocol HBAsyncMiddleware. This requires an async apply method be implemented instead of the standard HBMiddleware which requires a method returning an EventLoopFuture. Below is an example session middleware using HBAsyncMiddleware, HummingbirdAuth framework and persist system for storing persistent data between requests. A session cookie is extracted from the request, this is then used to get the authenticatable type Session from the persist system which is then attached to the request using authLogin.

struct AsyncSessionMiddleware: HBAsyncMiddleware {
    public func apply(to request: HBRequest, next: HBResponder) async throws -> HBResponse {
        var request = request
        if let sessionCookie = request.cookies["_SESSION_ID"] {
            // persist system has an async/await api
            let session = try await request.persist.get(key: sessionCookie.value, as: Session.self)
            if let session = session {
                request.authLogin(session)
            }
        }
        return try await next.respond(to: request)
    }
}

Normally when using the HummingbirdAuth package for building authentication middleware you would use an HBAuthenticator. The HummingbirdAuth package also includes the HBAsyncAuthenticator protocol to implement authenticators with async/await.

Streaming request body

Streamed request bodies can now be access via an AsyncSequence of ByteBuffers. You can get access to this via HBRequest.body.stream?.sequence. There has also been a change to the flag to indicate you want a streamed request. The body parameter has been changed into an options parameter that can include other route options. The example below uses the new AsyncSequence to return the size of the buffer supplied.

app.router.post("stream", options: .streamBody) { request -> String in
    guard let stream = request.body.stream else { throw HBHTTPError(.badRequest) }
    var size = 0
    // for buffers in AsyncSequence
    for try await buffer in stream.sequence {
        size += buffer.readableBytes
    }
    return size.description
}

Request and Response struct

The new release of Hummingbird includes a couple of version breaking changes. Unfortunate as this is I believe they are necessary to ensure Hummingbird is used in a thread/task safe manner.

Previously both HBRequest and HBResponse were classes. These have now been changed to structs. Making them value types instead of reference types removes a whole class of race conditions that could occur. These changes don’t come without some cost though. You can only modify a struct from mutating methods that are members of that struct. This affected HummingbirdAuth which used an internal type Auth to mutate the HBRequest. This is no longer possible so the internal type has been removed and calls like HBRequest.auth.login have been replaced with HBRequest.authLogin.

Performance

The performance of the new concurrency features are not in line with what the SwiftNIO is capable of. At the moment there is no way to ensure what EventLoop you are running on and tasks can move about threads. This has a performance impact. This hopefully will be resolved over time though as custom executors are implemented, allowing SwiftNIO to implement an EventLoop model within Swift concurrency. Nothing is guaranteed though.

At the same time it is a lot easier writing async/await code than getting lost in chaining various EventLoopFuture.flatMaps together. The loss in code performance has to be measured against the gain in development performance. Many people won't need the code performance and should probably move across to async/await now, but there will be systems that still need the performance of SwiftNIO and should stick with the EventLoopFuture routes for the moment.

What is it?

JMESPath is a query language for JSON. WIth it you can script searching large JSON datasets and transform the results.

Basic queries

A search can be as simple as a single field name. result would return the object attached to the result field at the top level of a JSON file. This can be specialized to return an object inside result by added a dot and then another field name eg result.object.

Queries can index arrays as follows

users[0].name

Which will return the name field of the first element of the array users. You can use a negative index to access an array from the end, so the index of -1 will give you the last element of an array.

Projection queries

Projections allow you to apply a query to multiple objects. The left hand side of a projection query defines the projection and the right hand side defines the query to apply to each object returned by the projection. Using the example from above by replacing the array index with a * we create a list projection users[*] which we then apply the query name to. The following returns the name field from every element in the users array.

users[*].name

There are five different types of projection:

• list: applies query to each object in array as demonstrated above.
• slice: applies query to each object in a slice from an array
• flatten: applies query to each object in an array and flattens the result into a parent array
• object: applies query to all the child objects
• filter: applies query to a filtered version of the object

As this article isn't meant to cover the full spec of JMESPath but just give you a feel for what can be done with it I'll only cover filter projections here. A filter projection allows you to filter the left hand side of the projection before the query on the right hand side is applied to it. For example the following will return all the entries in the users array that have the field country set to USA.

users[?country=="USA"]

Functions

JMESPath has a number of standard functions that can be applied to results within a query. Using the same users example we have been using throughout we can sort the results by placing it inside the sort function.

sort(users[*].name)

You can also use functions inside filter projections. The following would return all the users whose names start with A.

users[?starts_with(name, "A")]

Transforming the results

If you want the results of your query in a specific format you can use multi-select queries. These can be used to create arrays or objects from your results. If I'm only interested in the name and age fields of the entries in my users array I can transform the list query results using a multi-select hash

users[*].{"name": name, "age": age}

Why am I telling you this

Well, AWS uses JMESPath in their SDK generation. If you have used their CLI tool you might recognise the syntax from the --query option. So far in my work on Soto (a third party Swift SDK for AWS) I have been able to hardcode the queries I came across and write custom code for them. Through recent work though, I have found a number of queries that were too complex. So I took the leap and decided to implement JMESPath for Swift. You can find the code here. Given there are versions of JMESPath for a number of languages already I had a lot of prior art to help in my implementation. The Swift version is based off the Rust version and follows its implementation fairly closely. The JMESPath site provides a comprehensive set of compliance tests and my version passes them all so I am fairly confident it is up to scratch.

The Swift code works as follows. You create a compiled Expression and then use Expression.search to apply the expression to your JSON.

let expression = try JMESExpression.compile("users[*].name")
let result = try expression.search(json: myjson)

The above will return Any as it is undefined what type the expression will return. You can pass this straight into JSONSerialization.data to get the result as JSON if desired. Or if you know the type that the search will return you can add it into the search call as follows

let result = try expression.search(json: myjson, as: [String].self)

In addition to parsing JSON I've added Mirror reflection to search objects of any type. This means the Swift implementation of JMESPath isn't restricted to just querying JSON data it can be used to query any data structure. Below is a sample where we have a struct Service which includes an array of User. We use JMESPath to create a sorted list of all the User member name.

struct Service {
    struct User {
        let name: String
    }
    let users: [User]
}
let service = Service(
    users: [
        .init(name: "james"),
        .init(name: "anne"),
        .init(name: "tom")
    ]
)
let expression = try JMESExpression.compile("users[*].name | sort(@)")
let result = try expression.search(object: service, as: [String.self])
assert(result == ["anne", "james", "tom"])

The expression used here includes two new pieces of grammar | which pipes the result of the expression on the left hand side into the expression on the right hand side and @ which indicates the current result being evaluated. So above the array of names returned by users[*].name is passed into the sort function.

Usage

JMESPath provides an easy way to script filtering and transforming of JSON responses from different services. It can be used to parse responses from cloud providers and other services from your backend into the formats that your client expects.

More Information

This article only details a small sample of the possibilities with JMESPath. If you'd like to find out more about JMESPath you can go the website jmespath.org. It has a great tutorial section where you can test out different queries.

You can checkout the Swift version of JMESPath here https://github.com/adam-fowler/jmespath.swift.

Almost 8 weeks back I published a post announcing the release of my Swift based http application framework hummingbird. This post is to update everyone on all the new stuff that has been added since that first post.

Web Application Layer (Hummingbird)

The web application layer has had a number of changes. Much of these have been API changes as I continue to refine the interfaces. I apologize to anymore who might have been using the framework and having to fix up their code on new releases. I promise the APIs will stabilise in the near future. Although async/await will probably cause some considerable changes.

The library has had a number of optimisations to improve performance. It is now according to The Benchmarker the fastest Swift server framework out there, if you want a 200 response with an empty body. I know these numbers don't necessarily mean much but its still nice to be in that position. TechEmpower report similar results from their Live results.

One minor addition, although I think it is worth noting, is a new protocol for defining a route. A route handler HBRouteHandler allows you to encapsulate all the components required for a route, and provide separation of the extraction of input parameters from the request and the processing of those parameters. For example

struct AddOrder: HBRouteHandler {
    struct Input: Decodable {
        let name: String
        let amount: Double
    }
    struct Output: HBResponseEncodable {
        let id: String
    }
    let input: Input
    let user: User

    init(from request: HBRequest) throws {
        self.input = try request.decode(as: Input.self)
        self.user = try request.auth.require(User.self)
    }
    func handle(request: HBRequest) -> EventLoopFuture<Output> {
        let order = Order(user: self.user.id, details: self.input)
        return order.save(on: request.db)
            .map { .init(id: order.id) }
    }
}
application.router.put("order", use: AddOrder.self)

HBRouteHandler doesn't provide a great deal of extra functionality, but it does provide a place to centralize all the components that make up a route.

WebSockets

Just after the initial release of Hummingbird I released a websocket library. The first release included a websocket server accessed via HBApplication.ws. Here is a basic example of a websocket server that returns everything that is sent to it

let app = HBApplication()
// add HTTP to WebSocket upgrade
app.ws.addUpgrade()
// on websocket connect. 
app.ws.on("/ws") { req, ws in
    // send ping and wait for pong and repeat every 60 seconds
    ws.initiateAutoPing(interval: .seconds(60))
    // on read from client send the same data back
    ws.onRead { data, ws in
        ws.write(data)
    }
}
app.start()
app.wait()

Given the code for a websocket client and server is almost identical setting up a client didn't take too much effort either and was included in a later release. I included a simple chat server example using websockets in the examples repository hummingbird-examples.

Mustache templating engine

Mustache is a "logicless" templating engine that can be used to create dynamic HTML. I have provided a Swift implementation of the engine HummingbirdMustache as a separate standalone project. It is a full implementatin of the mustache spec along with some additional bells and whistles. It supports all the standard tags along with transforms for transforming objects before being rendered, sequence context objects for rendered content based on position within a sequence, template inheritance for overriding sections of a partial and pragmas for setting implementation specific configuration parameters.

Future

I guess the next big change is async/await. The initial release of swift including async/await will probably not have the support that Swift NIO needs to create an optimal HTTP server pipeline. So any initial release of Hummingbird with async/await will only include additive elements and will keep the Swift NIO EventLoopFuture interfaces. Async/await style routes and middleware will be available but I can't guarantee how performant they will be.

Along with Hummingbird, my web application framework, comes HummingbirdLambda. This allows you to take your Hummingbird application and run it on an AWS Lambda with API Gateway as an interface.

As long as all the services your application uses are accessible from AWS Lambda and your application doesn't have any internal persistent state moving to Lambda should be fairly easy. You should be able to move your application setup, middleware, routes to your Lambda with very little change.

In a standard server based Hummingbird application you create your HBApplication, set it up and then call HBApplication.start. Instead in a Hummingbird Lambda you create an HBLambda object which is initialized with an already created HBApplication which you then setup. Do NOT call HBApplication.start on this though.

Where you were doing the following for your server app.

let app = HBApplication()
// set encoder and decoder
app.encoder = JSONEncoder()
app.decoder = JSONDecoder()
// middleware
app.middleware.add(HBLogRequestsMiddleware(.debug))
app.router.get("/") { _ in
    return "hello"
}
...
app.start()
app.wait()

On Lambda you would replace this with

struct MyHandler: HBLambda {
    // define input and output
    typealias In = APIGateway.Request
    typealias Out = APIGateway.Response
    
    init(_ app: HBApplication) {
        app.encoder = JSONEncoder()
        app.decoder = JSONDecoder()
        // middleware
        app.middleware.add(HBLogRequestsMiddleware(.debug))
        app.router.get("/") { _ in
            return "hello"
        }
        ...
    }
}

Lambda.run { context in
    return HBLambdaHandler<MyHandler>(context: context)
}

The exact same application setup is used it is just inside the MyHandler.init function. In this situation we are using an APIGateway REST interface to invoke the Lambda so we need to define the In and Out types to be the APIGateway input and output types. You can set these to APIGateway.V2.Request and APIGateway.V2.Response if you want to use an APIGateway HTML interface.

Building and uploading

You will need to build your Lambda with the swift-aws-lambda-runtime. There are numerous articles on doing this. You can read Fabian Fett's article here for details on how to build and upload your Lambda.

APIGateway

Once you have a Lambda uploaded, you need to setup your API Gateway interface. Go to the APIGateway console and create a new REST API. Once in the editor for your API you need to replicate the routes you setup in your Hummingbird Lambda and have them invoke the Lambda.

Click on the "Actions" dropdown.

You create path elements through Create Resource. If you have a route "/user" create a resource with path "user". If you have another route "/user/:id" create a resource inside the "user" resource with the path "{id}". This is the syntax for URI parameters. For each path you have methods, select the path and then choose Create Method, select the method you want in the dropdown. In the method creation dialog choose Lambda Function, enable Use Lambda Proxy Integration and select the Lambda Function you setup earlier. Once you have setup a method you can add validation for request inputs. This isn't truely necessary as Hummingbird will do this for you, but it does mean not invoking your Lambda when clients send bad requests which is a cost saving for you.

Once your resources and methods are entered select Deploy API. You should be able to invoke your Hummingbird Lambda using the endpoint provided to you and hey presto you've gone serverless.

Example

The hummingbird-examples repository has two examples: todos-dynamodb and todos-lambda. These are both the same application one written to be run as a server and one to be run serverless on AWS Lambda. The code for these two examples is almost exactly the same. There is one minor difference where I needed to workout the host name. The Lambda example also includes a Swagger file you can use to initialize your API Gateway setup with the required resources and methods. You just need to wire up the methods to your Lambda. Please take a look and see how easy it can be to go serverless.

Hey, I wrote a new SwiftNIO based HTTP server framework. What'd you do that for Adam? Well I guess I like making tech, but also I thought there was a gap in the market for something a little more slimline than the "market leader". Yes you guessed it Vapor. I don't think anyone can really consider building a Swift server framework without trying to differentiate themselves from Vapor.

Welcome to Hummingbird. Hummingbird is a lightweight, flexible server framework. It is split into three section. HummingbirdCore: the HTTP server, Hummingbird: the web application framework and finally the extension modules.

Hummingbird Core

Hummingbird Core is a SwiftNIO based HTTP server. It abstracts all the Swift NIO server code away. You just need to provide it with an object conforming to protocol HBHTTPResponder when you start the server. This protocol requires one function to be implemented:

func respond(
    to request: HBHTTPRequest, 
    context: ChannelHandlerContext
) -> EventLoopFuture<HBHTTPResponse>

You are provided with an HTTP request object HBHTTPRequest as a parameter and are expected to return an EventLoopFuture holding a HBHTTPResponse. With this you have the core of a web server, that receives incoming requests and sends outgoing responses.

The idea behind splitting off the web server element of Hummingbird is to provide people with a starting point to write their own frameworks without having to worry about all the Swift NIO server code.

Hummingbird

Hummingbird is the web application framework that sits atop of HummingbirdCore. It is designed to require the minimum of dependencies: swift-backtrace, swift-log, swift-nio, swift-nio-extras, swift-service-lifecycle and swift-metrics and makes no use of Foundation. This is where I hope to provide something different. Vapor is heavyweight. It brings in a lot of dependencies and has a lot of code that possibly won't be used in many projects. Hummingbird is trying to do the exact opposite. You get a minimal core framework which can be extended through separate modules.

The framework provides a standard set of features: a router for directing endpoints to their handlers, middleware for processing requests before they reach their handlers and processing the responses returned, custom channel handlers to extend the HTTP server (TLS, HTTP2 and compression are already implemented), extending the core HBApplication, HBRequest and HBResponse classes and providing custom encoding/decoding of Codable objects.

The interface is fairly standard. Anyone with experience of Vapor, Express.js etc will recognise most of the APIs. You could construct a simple example that returns the string "Hello" in the response payload as follows.

import Hummingbird

let app = Application(configuration: .init(address: .hostname("127.0.0.1", port: 8080)))
app.router.get("hello") { _ in
    return "Hello"
}
app.start()
app.wait()

Hummingbird extensions

Because of the desire to keep the core library dependencies to a minimum I provide extension libraries for features that bring in additional dependencies. HummingbirdFoundation provides features I couldn't implement without Foundation. These include JSON encoding/decoding, URL encoded form encoding/decoding, static file serving and cookies.

Additional extensions are available in separate repositories.

• HummingbirdAuth: An authentication framework with supporting libraries.
• HummingbirdCompression: Request decompression and response compression support.
• HummingbirdFluent: Hummingbird doesn't provide a database ORM, so I have taken the liberty to provide an interface to Vapor's Fluent.
• HummingbirdRedis: Hummingbird interface to Redis, using RediStack.
• HummingbirdWebSocket: Adds support for WebSocket connection upgrades.

Thanks

I am very thankful for the work the Vapor team have done and to say Vapor hasn't influenced some of the choices made when developing Hummingbird would be a lie. Also given Hummingbird doesn't provide a database solution we are dependent on the one provided by Vapor. Thankfully they have been forward thinking enough and generous to ensure many of their modules can be used separate from Vapor.

Without the Swift NIO team, Hummingbird would not exist. Swift NIO does all the hard work, Hummingbird is just trying to bring it all together and present it in an easy to use package.

Hummingbird is in its infancy at the moment and many features are still to be implemented, but a standard web app can be built with it. You can find the code for Hummingbird here.

I recently wrote a MQTT client with Swift NIO. You can find it here. This article covers how to create a simple chat client using said library.

For those who don't know MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol used extensively in IoT (Internet of Things) technologies. The MQTT protocol defines two types of network entities: a message broker and a client. The broker receives all the messages from the clients and then routes these to the appropriate destination clients based on whether they are subscribed to the relevant message topic. The protocol is lightweight making it ideal for IoT devices which don't necessarily have a great deal of processing power.

Swift NIO is a low level event driven networking library written by Apple. It is described as being like Netty but written for Swift. I have had a fair amount of experience using Swift NIO with my work on Soto but I have never implemented a client for a specific protocol with it. Given this I thought I would use this as an excuse to learn a little more about both Swift NIO and MQTT. The result was MQTT NIO

Concept

We'll keep this fairly simple. We are going to create a console application that will allow you to connect to a MQTT server and particular topic, with a username. You will be able to send messages to a topic and receive all other messages published to the same topic. Originally I wrote an article detailing all the code in the chat client but ditched that in favour of something that concentrates just on the MQTT elements of client. You can see full source for the client here.

Client initialization

The MQTT client is setup with the default configuration but could be configured to connect to a websocket or TLS connection if required. You need an identifier for your client. If you connect with an identifier already used, the broker will disconnect the other client using that identifier. We prefix the identifier with "MQTTNIOChat-" to avoid clashing with other systems using the MQTT broker.

self.mqttClient = MQTTClient(
    host: command.servername,
    port: command.port,
    identifier: "MQTTNIOChat-\(command.username)",
    eventLoopGroupProvider: .createNew,
    configuration: .init()
)

Connection

The first thing we need to do is connect to the MQTT broker. In the sample I use a locally running broker but you could use your own, or a public broker. Please note if you use a public broker all your messages will visible to the rest of the world.

func setup() -> EventLoopFuture<Void> {
    // connect, subscribe and publish joined message
    self.mqttClient.connect(cleanSession: true).flatMap { hasSession -> EventLoopFuture<Void> in
        let subscription = MQTTSubscribeInfo(topicFilter: self.topicName, qos: .exactlyOnce)
        return self.mqttClient.subscribe(to: [subscription])
    }
    .flatMap { _ in
        self.addListeners()
        return self.sendMessage("Joined!")
    }
}

In mqttClient.connect we set cleanSession to true. This means if there is already an existing session for this user (identifier) then we will ditch it. The existing session will include subscriptions to topics we are maybe no longer interested in. We then subscribe to the topic we are interested in. In the subscription we set qos to .exactlyOnce to ensure we only receive published messages once. If we set it to .atLeastOnce we could receive messages twice if there are connection issues. We would need to keep a record of previously received messages to avoid outputting them twice. If we set it to .atMostOnce we could miss messages if there are connection issues.

Receiving messages

Once the subscription has gone through we call addListeners(). This adds a listener waiting for PUBLISH events from the broker. For every PUBLISH event the callback is called.

func addListeners() {
    self.mqttClient.addPublishListener(named: "ListenForChat") { result in
        switch result {
        case .failure:
            self.closePromise.fail(error)
        case .success(let publishInfo):
            if publishInfo.topicName == self.topicName {
                receiveMessage(publishInfo.payload)
            }
        }
    }
}

If the listener calls the callback with an error we fail the closePromise EventLoopPromise setup in the chat client object. If we receive a message packet and the message topic is equal to the topic we are subscribed to then we call the receiveMessage function. This parses the message packet (it is formatting in JSON), and as long as you didn't send it, outputs it to the console.

Sending messages

The main loop of the client reads from stdin using readLine and then creates a message packet and uses MQTTClient.publish to publish the packet to the MQTT broker. The sendMessage function is as follows.

func sendMessage(_ message: String) -> EventLoopFuture<Void> {
    let packet = ChatPacket(from: command.username, message: message)
    var buffer = ByteBufferAllocator().buffer(capacity: 0)
    try? JSONEncoder().encode(packet, into: &buffer)
    return self.mqttClient.publish(to: self.topicName, payload: buffer, qos: .exactlyOnce)
}

Construct ChatPacket, encode into JSON formatted ByteBuffer and then publish the ByteBuffer to the topic.

Errors

I run the mainloop on the global default system queue using DispatchQueue and leave the main thread waiting on a result from the closePromise. If there is an error the client will exit as the closePromise is fulfilled with an error. We can also catch a disconnection from the broker using a closeListener which fails the closePromise.

func addListeners() {
    ...
    self.mqttClient.addCloseListener(named: "CheckForClose") { result in
        self.closePromise.fail(MQTTChatClientError(message: "Lost connection"))
    }
}

Extending

This is a really simple example of how MQTT can be used. I probably spent more time trying to get the ANSI escape sequences working (for overwriting the prompt with new messages) than the chat functionality. It has no real user management or access control. You would need additional services for that. But it gives you a quick idea what an MQTT broker can be used for. Please go to https://github.com/adam-fowler/mqtt-nio-chat and checkout the full running example.