Safe from the Losing Fight

Reading and writing files in Swift async/await

Andy — Mon, 22 Apr 2024 19:50:17 -0400

Because of habits ingrained in me, by default I tend to reach for synchronous, blocking APIs when reading and writing data to and from disk. This causes problems with Swift’s cooperatively scheduled Tasks. In this post, I examine the various async-safe approaches I’ve discovered to hitting disk, and end with a general approach that I ended up using.

The synchronous way

If I’m loading up data from disk to decode from JSON or decode into a UIImage, then my go to has been:


let data = try Data(contentsOf: fileURL)

Similarly, if I’m writing said JSON or image data out to disk, I’ll use write:


try data.write(to: fileURL)

These are simple and easy to use. They also create problems with Swift async/await.

When I look at the Swift Foundation implementation of these methods, I can see by default they do blocking I/O operations. This is a problem because Tasks are cooperatively scheduled over kernel threads. (I know this is probably an over-simplification, but stick with me.) If a Task traps to the kernel on a blocking call (like the blocking I/O calls), the kernel doesn’t know anything about the Task it only sees the system thread blocking, and therefore suspends it. This robs Swift’s async runtime from the opportunity to just suspend the Task making the I/O call and pick up a different Task that is available to run. i.e. this takes away one of the system threads Swift async/await can use for the duration of the blocking I/O call.

So while simple, it would probably be best if I didn’t use them in the async/await world.

Option 1: side step the issue via memory mapping

If all I care about is reading in data, I can consider asking Data to memory map the file. Depending on the access patterns of the end user, this might actually be the fastest way anyway. The read accesses become implicit whenever someone touches the contents of Data and the kernel faults in the appropriate pages.


let data = try Data(contentsOf: fileURL, options: .mappedIfSafe)

A caveat is not all files can be memory mapped. There’s also no automatic way to use memory mapping for writes using Data APIs. While I could roll my own, I’m not sure what the benefit of that would be.

Option 2: use URLSession

The next option I discovered was leveraging URLSession to do asynchronous reads from file URLs.

Like this:


let (data, _) = try await URLSession.shared.data(from: fileURL)

For reading the entire file in one go, this works well. Unfortunately, I couldn’t find a way to “upload” to a file URL. Probably for good reason. So this is a read-only solution.

Quick aside about async URLSession: you probably don’t want to use the bytes method.

Option 3: wrap up FileHandle

This is the first solution I found that handles both asynchronous reads and writes. The basic principle is simple: create a FileHandle then use the readabilityHandler or writeabilityHandler properties to either read data out or write data into it. For reading, I returned an AsyncStream<Data> that the readabilityHandler yields to.

Side note: I do not recommend using the bytes property to iterate one byte at a time.

I got really far with this approach and had it working. However, for files, I found it clunky. Namely:

When reading, I had to get the size of the file first so I knew when the readabilityHandler got called the last time. A lot of sample code assumes that the availableData will be isEmpty on the last call. However, in my testing, I found that was true for Pipes but not for files.
When writing, the call to write was still synchronous. Since I was doing it inside the writeabilityHandler, presumably it wouldn’t actually block but that’s not really clear.

After getting FileHandle to work, I decided it was too clunky and went for a different approach. But it is an option.

Option 4: DispatchIO

This is the approach I ended up using. DispatchIO is low-level, but its API was consistent and straight forward to wrap up. The basic principle is to use DispatchIO to get non-blocking reads/writes and then wrap those in checked continuations. That way Swift async/await knows when to suspend or resume the calling Task. Below I go into detail on my implementation. As an added bonus to the async/await, this is my first go at a non-copyable type.

I’ll start with the type declarations:


/// A phantom type used by AsyncFileStream to restrict methods to read mode
public enum ReadMode {}
/// A phantom type used by AsyncFileStream to restrict methods to write mode
public enum WriteMode {}

public struct AsyncFileStream<Mode>: ~Copyable {
    // ...
}

The actual type of AsyncFileStream is complicated by the fact that I’m trying to make invalid operations impossible for the caller. I achieve this two ways:

I use a phantom type called Mode that can either be ReadMode or WriteMode. Read methods are only available when Mode == ReadMode and write methods only when Mode == WriteMode
I mark AsyncFileStream as non-copyable with ~Copyable. This means there can be only one copy, preventing multiple Tasks/threads/whatever from calling it at the same time. It also means I get a nice deinit method to clean up in, and I can mark my close() method as consuming. This means the instance can’t be used after close() is called, or the compiler at compile time will emit an error.

AsyncFileStream has the properties you’d probably expect if you’ve used DispatchIO before:


/// The queue to run the operations on
private let queue: DispatchQueue
/// The unix file descriptor for the open file
private let fileDescriptor: Int32
/// The DispatchIO instance used to issue operations
private let io: DispatchIO
/// If the file is open or not; used to prevent double closes()
private var isClosed = false

If you haven’t used DispatchIO before, don’t worry, these properties will make sense when I use them.

Creating an instance is actually the most involved part of this whole type, but it’s a good place to start:


fileprivate init(url: URL, mode: Int32) throws {
    guard url.isFileURL else {
        throw AsyncFileStreamError.notFileURL
    }
    // Since we're reading/writing as a stream, keep it a serial queue
    let queue = DispatchQueue(label: "AsyncFileStream")
    let fileDescriptor = open(url.absoluteURL.path, mode, 0o666)
    // Once we start setting properties, we can't throw. So check to see if
    //  we need to throw now, then set properties
    if fileDescriptor == -1 {
        throw AsyncFileStreamError.openError(errno)
    }
    self.queue = queue
    self.fileDescriptor = fileDescriptor
    io = DispatchIO(
        type: .stream,
        fileDescriptor: fileDescriptor,
        queue: queue,
        cleanupHandler: { [fileDescriptor] error in
            // Unfortunately, we can't seem to do anything with `error`.
            // There are no guarantees when this closure is invoked, so
            //  the safe thing would be to save the error in an actor
            //  that the AsyncFileStream holds. That would allow the caller
            //  to check for it, or the read()/write() methods to check
            //  for it as well. Howevever, having an actor as a property
            //  on a non-copyable type appears to uncover a compiler bug.

            // Since we opened the file, we need to close it
            Darwin.close(fileDescriptor)
        }
    )
}

First, notice the init is fileprivate. I’m going to provide much more ergonomic APIs for creating an instance than knowing how to fill out mode correctly. But there’s a lot of shared code, so this init takes care of that. Error handling in the init of a non-copyable type is tricky. I can only throw errors up to the point that it starts setting up stored properties. Once that starts the init must guarantee success (i.e. no throws after) or its a compile time error. So early on I verify I have a file URL and that the open happened successfully.

Otherwise, I set up DispatchIO. I create my DispatchQueue to execute the IO operations on. Since I’m going to be reading and writing as a stream, I might as well keep a serial queue. I open the file using the POSIX open() API, using the passed in mode, and set the permissions to 0o666, which should give read/write to all. As mentioned before, I create DispatchIO as a .stream since I’m going to sequentially read through the file or write it out.

The cleanupHandler is another tricky bit. It’s called once DispatchIO is done with our fileDescriptor. e.g. after someone’s called close(). Since we opened the file, we take care of closing it. I’m also given an error as a parameter to my closure; if it’s non-zero something went wrong. Unfortunately, I ran into a compiler bug (according to the compiler itself) in trying to handle it.

A slight diversion about said compiler bug

What I’d like to do to handle the cleanupHandler error is to have a private actor like this:


final actor AsyncError {
    private(set) var error: AsyncFileStreamError?

    func setError(_ error: AsyncFileStreamError) {
        self.error = error
    }
}

I always create an instance in the init and have it as a property on AsyncFileStream. Inside of my cleanupHandler I could set the actual error on it:


cleanupHandler: { [fileDescriptor] error in
    if error != 0 {
        Task {
            await asyncError.setError(error)
        }
    }
    // Since we opened the file, we need to close it
    Darwin.close(fileDescriptor)
}

Since it’s a property, the read and write methods could check it in a guard statement or the caller could explicitly read it off to check for an error. Unfortunately, when I actually implement this, attempting to touch the actor instance leads to:

Usage of a noncopyable type that compiler can't verify. This is a compiler bug. Please file a bug with a small example of the bug

Welp.

Moving on…

Creating an instance

I wanted to be able to create an instance of an AsyncFileStream without remembering all the various mode flags for open(). Also, I added the Mode phantom type, but I’d rather that be invisible to the caller. i.e. they don’t have to type out the Mode explicitly somewhere. If I use a direct init though, they would, as there’s no way to infer it. For those reasons, I added an extension to URL to create AsyncFileStream:


public extension URL {
    /// Create an instance from the URL for reading only
    func openForReading() throws -> AsyncFileStream<ReadMode> {
        try AsyncFileStream<ReadMode>(url: self, mode: O_RDONLY)
    }

    /// Create an instance from the URL for writing. It will overwrite if the file
    /// already exists or create it if it does not exist.
    func openForWriting() throws -> AsyncFileStream<WriteMode> {
        try AsyncFileStream<WriteMode>(url: self, mode: O_WRONLY | O_TRUNC | O_CREAT)
    }
}

If I have a URL, I just have to call openForReading() or openForWriting(). Does what it says on the tin.

Cleaning up safely

Next, I’ll cover the parts of the type that are available regardless of Mode, namely closing the file. Because this is a non-copyable type, close() gets interesting (in a good way):


/// Close the file. Consuming method
public consuming func close() {
    isClosed = true
    io.close()
}

The body is a bit boring — it marks itself as closed so deinit doesn’t close again, and then closes the DispatchIO object. The fact that this is marked consuming is interesting though. Specifically, in that position, it means self is consumed. Which means the caller can’t call any methods after it without getting a compiler error. For example:


let stream: AsyncFileStrea<ReadMode> // ... assume initialized
stream.close() // stream is now consumed

stream.readToEnd() // this is a compiler error!

That’s pretty neat! I’ve prevented an illegal operation a compile time.

To circle back to marking isClosed to true so deinit doesn’t try to close it. In a consuming method, I could — if the type is right — call discard self. That destroys self and means deinit doesn’t get called. Unfortunately, it only works if the type only contains “trivial” types, and AsyncFileStream contains non-trivial types, apparently. From what I can discern “trivial” means you can do a bit-by-bit copy on the type, no reference counting. In any case, since I can’t discard self, we need to mark something so deinit knows not to try to call ios.close() a second time.

Speaking of deinit:


deinit {
    // Ensure we've closed the file if we're going out of scope
    if !isClosed {
        io.close()
    }
}

Since I’ve got a non-copyable type, I get a deinit, which is just the bee’s knees. If I haven’t closed the file already, I do so now so I don’t leak anything.

Reading

If I create the type in ReadMode, there are a couple of read methods available.


public extension AsyncFileStream where Mode == ReadMode {
    /// Read the entire contents of the file in one go
    func readToEnd() async throws -> DispatchData { ... }

    /// Read the next `length` bytes.
    func read(upToCount length: Int) async throws -> DispatchData { ... }
}

Like marking close() as consuming, the goal of putting the methods in a conditional extension is to prevent misuse. Unless I open AsyncFileStream in ReadMode, I simply can’t call any read methods at compile time because they aren’t available.

As mentioned at the start of this section, the basic idea of read is to wrap DispatchIO’s read in a continuation:


/// Read the next `length` bytes.
func read(upToCount length: Int) async throws -> DispatchData {
    try await withCheckedThrowingContinuation { continuation in
        var readData = DispatchData.empty
        io.read(offset: 0, length: length, queue: queue) { done, data, error in
            if let data {
                readData.append(data)
            }
            guard done else {
                return // not done yet
            }
            if error != 0 {
                continuation.resume(throwing: AsyncFileStreamError.readError(error))
            } else {
                continuation.resume(returning: readData)
            }
        }
    }
}

This is straight forward: wrap up io.read() in checked throwing continuation. For my purposes I built up a single DispatchData and returned it when finished. That’s because I want to use the entire contents as a single Data instance. However, I could have returned an AsyncStream<DispatchData> and streamed out the data as I got it in the callback. I’m also going to note DispatchIO explicitly marks the read as done with a done flag. Glaring at you, FileHandle.

Also note that since I’m using the stream mode of DispatchIO, so offset is ignored, which is why its always 0.

Since my goal was to read the entire file at once, I added a helper method to do that:


/// Read the entire contents of the file in one go
func readToEnd() async throws -> DispatchData {
    try await read(upToCount: .max)
}

It just calls through to the normal read().

Writing

Like reading, writing is gated based on the Mode. Writing also works the same as reading: I wrap up a non-blocking call with a callback in a checked throwing continuation. Ugly, but straight forward and effective (like me!):


public extension AsyncFileStream where Mode == WriteMode {
    /// Write the data out to file async
    func write(_ data: DispatchData) async throws {
        try await withCheckedThrowingContinuation { continuation in
            io.write(
                offset: 0,
                data: data,
                queue: queue
            ) { done, _, error in
                guard done else {
                    return // not done yet
                }
                if error != 0 {
                    continuation.resume(throwing: AsyncFileStreamError.writeError(error))
                } else {
                    continuation.resume(returning: ())
                }
            }
        } as Void
    }
}

The main difference from the structure of the read is I ignore the second parameter in the callback, which is the data remaining to write out.

Some Data convenience

Finally, I get back to where I started. Namely, I want convenience methods on Data that read and write entire files, but asynchronously. All I do is wrap up the methods I just defined:


public extension Data {
    /// Asynchronously read from the contents of the fileURL. This method
    /// will throw an error if it's not a file URL.
    init(asyncContentsOf url: URL) async throws {
        let stream = try url.openForReading()
        self = try await Data(stream.readToEnd())
    }

    /// Asynchronously write the contents of self into the fileURL.
    func asyncWrite(to url: URL) async throws {
        // This line makes me sad because we're copying the data. I'm not
        //  currently aware of a way to not copy these bytes.
        let dispatchData = withUnsafeBytes { DispatchData(bytes: $0) }
        let stream = try url.openForWriting()
        try await stream.write(dispatchData)
    }
}

The one thing of note is in the asyncWrite() method I make a copy of the bytes when I instantiate DispatchData. I would really like to not have to do that, but I couldn’t find a way. If you know a way, please tap on the "Contact" button at the top of this page and send me an email or message me on Mastodon.

And that’s it!

Conclusion

In this post, I started with a couple of very convenient methods on Data that make it easy to read or write entire files. However, I pointed out they’re synchronous, which can cause problems in Swift’s async/await world. I then walked through various async-safe ways or reading and writing files. Finally, I built out a general solution for async file I/O by wrapping up DispatchIO in checked continuations.

Swift async/await: do you even need a queue?

Andy — Sun, 14 Apr 2024 17:35:58 -0400

Alternative title: A concurrency limiter for Swift async/await

This post is really for me and my future self to help clarify my thinking about modeling asynchronous operations in Swift async/await. But I suppose you can read along as well.

In the world prior to async/await I used dispatch queues and OperationQueues to model asynchronous operations. As a result, my thinking about async naturally reverts to the hammer of execution queues. However, I’m starting to realize execution queues are sometimes not a good fit for modeling async operations in Swift async/await. In this post, I’m going to walk through an example where I found that an execution queue wasn’t what I wanted. Instead I wanted to simply limit the number of Tasks that could concurrently pass through a certain block of code. I’ll end with how I solved the limiter problem.

An example of my broken thinking

To return to my previous post’s example, let’s say I’m building an image cache. Part of the caching infrastructure is to actually download the image from the network. Since I can overload the network if I try to download too many images at once, I want to limit this part to ensure only so many download operations are happening concurrently.

The “classic” way to handle the limiting is to schedule the image download operation in an OperationQueue and make sure it has its maxConcurrentOperationCount set appropriately. Therefore, naturally, I turned to execution queues as a way to solve my concurrent downloads problem. I tried to build a Swift async/await “native” version of a concurrent execution queue. It got something that “mostly” worked, for some definition of “mostly”. And “work”. But what I couldn’t make work is a clean way to get the downloaded image back to the caller.

When I run into difficulties like this, I stop and try to figure out why it’s difficult. Usually it’s because there’s a mismatch between my mental models, and I’m trying to force a square peg into a round hole.

For my image cache, each fetch image operation is modeled as a Task. In pseudo-code something like this:


Task.detached {
    if let image = await memoryCache.image(for: url) {
        return image
    }
    if let image = await diskCache.image(for: url) {
        return image
    }

    downloadQueue.run {
        // This block actually runs in Task created by the Queue
        let image = await network.downloadImage(for: url)

        // TODO: how do I get `image` back to the calling Task?
    }

    //...
}

Things flow well until I need to actually download the image and want to limit how many concurrent ones via the downloadQueue. How do I get the image back to the calling Task? I mean, I guess I might figure out a way to make a callback work? That feels super janky, and possibly not safe.

However, looking at this code is when I first realized a couple of things. First, I was switching execution contexts to do the download. Why? I have a perfectly good detached Task already that I would prefer to be executing in. Tasks are supposed to be “recipes”, i.e. a list of steps to perform, which should include the actual download. So, I didn’t need the execution part of an execution queue. Second, what I actually needed it for was limiting the number of concurrent operations; that was its real purpose.

Therefore, my actual problem is I need a way to limit how many concurrent Tasks are calling await network.downloadImage(for: url) at the same time. Can I solve that problem instead?

A concurrency limiter

I’m going to solve this problem of queues with a queue. Obviously. The difference is this queue won’t provide any execution. The calling Task will do that.

I like starting with what I’d like to have at the call site:


Task.detached {
    if let image = await memoryCache.image(for: url) {
        return image
    }
    if let image = await diskCache.image(for: url) {
        return image
    }

    let image = downloadLimiter.run {
        // This runs on the calling task. No extra tasks!
        await network.downloadImage(for: url)
    }

    //...
}

The key bit is the closure is passed to run is executed on the calling Task. That makes returning the image back trivial. A call site like the above example would imply an interface something like:


public final class ConcurrencyLimiter {
    /// Concurrency is the maximum number of concurrent blocks to allow to run
    public init(concurrency: Int) 

    /// Execute the given block on the calling Task. It may wait first if there
    /// are already the maximum blocks running.
    public func run<Value>(_ block: @escaping () async throws -> Value) async throws -> Value
}

It has an init so it can know the maximum number of concurrent blocks, and then just a run method that executes the passed in closure. There’s also a non-throwing variant of run but it’s a simplified version of the throwing one, so it’s less interesting.

I’ll start on the outside and work my way inside to the details of the implementation. Here’s how I built run:


public func run<Value>(_ block: @escaping () async throws -> Value) async throws -> Value {
    let condition = await counter.enterLimiting()
    await condition.wait()

    do {
        let value = try await block()
        await counter.exitLimiting()
        return value
    } catch {
        await counter.exitLimiting()
        throw error
    }
}

First things first: counter is an actor owned by the ConcurrencyLimiter. It does all the… counting… of how many tasks are running at one time. It’ll also decide which task goes next. So maybe I should have called it Scheduler? This is chaos that happens when you don’t have code reviews. smh.

run calls into counter to ask to enter the limited section. The counter returns a Condition which the calling Task immediately waits on. The Condition is described in my previous post, and is what allows Counter to control which Task goes next. Once the Task returns from the call to condition.wait() it executes its code. Before returning or throwing it calls back into counter on exitLimiting() to let it know this Task is done.

That’s it for run. Most of the heavy lifting is in Counter so I’ll look at that next.


final actor Counter {
    /// The maximum amount of currency allowed
    private let concurrency: Int
    /// How many blocks are currently in flight
    private var inflightCount = 0
    /// Pending (blocked) blocks in a FIFO queue.
    private var pending = [Signal]()

    init(concurrency: Int) {
        self.concurrency = concurrency
    }
}

There’s not much data needed by the scheduler. Um… I mean Counter. Counter. It has the maximum number of concurrent tasks allowed, how many are actually in flight right now, then an array of Tasks in priority order represented by the Signal that will unblock them. That’s it.

enterLimiting() is called by the Task when it wants to enter the limited section:


func enterLimiting() -> Condition {
    let shouldWait = inflightCount >= concurrency

    let (condition, signal) = Condition.makeCondition()
    if shouldWait {
        pending.append(signal)
    } else {
        // immediately signal and let it run
        inflightCount += 1
        signal.signal()
    }

    return condition
}

This method is in an actor, and there are no awaits in here, so this method happens without reentrancy. That’s important. It computes if the caller can immediately execute or it should wait. Either way, it creates a Condition/Signal pair so it can return the Condition. If the calling Task can execute immediately, it acts like it has already started by incrementing in the inflight count and pre-signaling (i.e. unblocking) the Condition. If the calling Task needs to wait, the Signal is appended to the end of the waiting queue.

The other end of the process is when the calling Task leaves the limited section.


func exitLimiting() {
    inflightCount -= 1
    let shouldUnblock = inflightCount < concurrency

    guard shouldUnblock, let firstPending = pending.first else {
        return
    }
    pending.removeFirst()
    inflightCount += 1
    firstPending.signal()
}

It immediately updates the inflight count and determines if it can unblock any of the pending Tasks. If it can and there are tasks waiting, it counts the Task as started and unblocks by signaling the Task‘s condition.

You might have noticed this is a simple FIFO queue for prioritization. However, really any prioritization scheme could be substituted in.

Finally, I put a little bit of “what if” insurance in the deinit of the actor. Basically, what happens if the Counter goes out of scope, but there are still Tasks blocked on it?


deinit {
    let localPending = pending
    pending.removeAll()
    for local in localPending {
        local.signal()
    }
}

I make a local copy because I’m just extra paranoid (probably don’t need that), then go through and unblock everything. Presumably no callers care anymore if we’re going out of scope, but I don’t want to leave any Tasks blocked.

(As an aside, I remember from my undergrad days this kind of data structure being called a “monitor.” But Wikipedia says I’m wrong.)

Conclusion

In this post, I described my learning journey where I realized that I didn’t need an execution queue like OperationQueue for my particular problem. Instead, I wanted to let each Task bring its own execution, and just needed a queue to limit the number of concurrent executions. Finally, I demonstrated a simple implementation of a ConcurrencyLimiter using the Condition/Signal pair I introduced in my previous post.

Modeling condition variables in Swift async/await

Andy — Sun, 14 Apr 2024 15:56:19 -0400

In the brave new world of Swift async/await, a problem I sometimes encounter is how to communicate between Tasks. More specifically, if I need one Task to wait on a condition to be true as a result of work that’s done by another set of Tasks. In this post I’ll cover how I eventually ended up solving this using something like a condition variable.

Refining the problem scope

There’s more than one way to handle Task synchronization, so I want to start by refining the problem that I’m trying to solve. The hope is it’ll be clearer why I chose the solution I did.

One of the easiest ways to have one Task wait on another’s work is to package up that work in it’s own Task then just await that. Here’s a oversimplified example of a pattern that I’ve used:


final actor Thingy {
    private let loadTask: Task<Void, Never>

    /// User might call this at some point, repeatedly
    func processData() async {
        // Waiting on the task to ensure it's done before continuing
        await loadTask.value

        // Ok, now I can do my processing safe that we've loaded
    }
}

In this example, loading the data can take a while and I want to make sure it’s loaded before doing any on-demand processing of it. I also don’t want to do the load repeatedly, so I wrap it up in Task and set it as a property. Any Task that needs load to be completed just awaits the value. (This is an extremely contrived example to demonstrate a pattern. Don’t email how you’d refactor it.) The point here is awaiting the result of a Task is a nice, straight forward mechanism for synchronizing work between two tasks.

However, there’s a variation of this problem that I want to solve in this post. It’s not that a specific task has completed, but a condition has become true. That sounds subtle, but there’s actually a big difference. Multiple Tasks may be working and any one them might make the condition become true.

For example, suppose I want to limit the number of concurrent Tasks that are downloading images to be no more than 10. When a Task starts to download an image it needs to know if there’s less than 10. If there are 10 or more, it wants to wait until one of the existing Task has finished. This is where awaiting on a single Task as a solution falls apart. The waiting Task actually wants to know when the concurrency count goes below 10, not when a specific Task completes (although they are correlated). It can’t await all the executing Tasks because it doesn’t need to wait until all Tasks complete. If it awaits a single Task, it also might wait longer than necessary if a different Task from the one its awaiting completes first. Of course this is all ignoring that there could be many Tasks waiting for the concurrency count to go below 10, and how do I ensure only one of them continues when it drops to 9 concurrent?

(Also, I know the classic way to solve the image download concurrency limiting is to use OperationQueue. But in a future post, I’m going to argue that’s not ideal in an async/await world for this problem.)

To summarize: I want to have a Task to wait on a condition to become true, which isn’t the same as waiting on a Task to complete.

Classic approach

If I was still in the bad old days of pthreads, I’d reach for a condition variable. I’d have the queued Task wait on it, and when the concurrent count dropped below 10, the just completed download Task would signal the condition variable. But I can’t actually use pthread condition variables because they’d block the underlying system thread, which would hang one of the thread resources used by Swift’s cooperative pool. Then everybody would just be sad.

However, what if I could construct something similar to a condition variable that stays in async/await land? It wouldn’t actually need to do everything a traditional pthread condition does, like make sure only one Task unblocks because I could handle that manually.

Let me sketch out what that might look like:


struct Condition {
    func wait() async {}

    static func makeCondition() -> (Condition, Signal)
}

final class Signal {
    func signal() {}
}

With this approach, the Task that wants to download an image can call into the queue that knows how many downloads are currently going. The queue constructs a Condition/Signal pair, keeps the Signal and returns back the Condition to the calling Task. The calling Task then wait()s on that Condition. When the queue decides it’s time for that specific Task to go (it can keep a prioritized array of Signals), it calls signal() on the Signal and the paired Condition unblocks.

This behavior would solve my stated problem: my Task could wait on a condition to become true, instead of waiting on a specific Task.

Implementation

I chose to use an AsyncStream to build this functionality. Basically, the Condition.wait() is going to sit in an async/await loop waiting on the AsyncStream to complete. The Signal.signal() calls finish() on the AsyncStream‘s continuation to unblock it.


/// Signal is used in conjunction with Condition. Together they allow
/// one Task to wait on anther Task.
public final class Signal {
    private let stream: AsyncStream<Void>.Continuation

    /// Private init, don't call directly. Instead, use Condition.makeCondition()
    fileprivate init(stream: AsyncStream<Void>.Continuation) {
        self.stream = stream
    }

    /// Signal the waiter (who has the Condition) that they're good to go
    public func signal() {
        stream.finish()
    }
}

/// Condition allows two async Tasks to coordinate. Use `makeCondition()` to
/// create a Condition/Signal pair. The Task that wants to wait on something to
/// happen takes the Condition, the Task that notifies of the condition takes
/// the Signal.
public struct Condition {
    private let waiter: () async -> Void

    /// Private init; create a closure that will can be waited on
    fileprivate init(waiter: @escaping () async -> Void) {
        self.waiter = waiter
    }

    /// Wait on the condition to become true
    public func wait() async {
        await waiter()
    }

    /// Construct a Condition/Signal pair. The Task that wants to wait on something to
    /// happen takes the Condition, the Task that notifies of the condition takes
    /// the Signal.
    public static func makeCondition() -> (Condition, Signal) {
        let (stream, continuation) = AsyncStream<Void>.makeStream()
        let condition = Condition {
            for await _ in stream {}
        }
        let signal = Signal(stream: continuation)
        return (condition, signal)
    }
}

Conclusion

In this post I described a variation of a Task synchronization problem. In this variation a Task wants to wait on a condition to become true, as opposed to a Task being completed. I then introduced simplified version of a traditional synchronization mechanism called a condition variable as a mechanism for solving this problem. Finally, I demonstrated a working async/await solution using AsyncStream.

Read the follow up post.

Updating NativeMarkKit for SwiftUI and iOS 14

Andy — Sat, 14 Nov 2020 14:47:15 -0500

I’ve pushed a small update to NativeMarkKit, my native Markdown rendering framework. It adds some SwiftUI wrappers that incorporate workarounds for the UIKit-SwiftUI interop bugs. It also fixes a bug introduced by iOS/tvOS 14 that prevented inline backgrounds from being rendered.

Enjoy!

Introducing NativeMarkKit, native Markdown rendering

Andy — Sat, 29 Aug 2020 10:15:17 -0400

I’d like to announce the release of one of my side projects: NativeMarkKit. NativeMarkKit is a Swift package implementing the rendering of NativeMark. What’s NativeMark? Well, it’s a flavor of Markdown designed to be rendered by native iOS, macOS, or tvOS apps. i.e. it compiles down to NSAttributedString (mostly) instead of HTML and CSS. It’s basically CommonMark, but without the raw HTML tag support.

I often get mockups from designers who want to style text like they would on web. So they mix in bold, italics, links and other things within the copy. While that can be done natively, it’s a hassle, requiring manually building up NSAttributedStrings and concat-ing them together. NativeMarkKit allows me to have one localized Markdown string, and let the framework figure out how to render that down into a NSAttributedString. As a bonus, NativeMarkKit supports Dynamic Type and Dark Mode. I can also style the Markdown using whatever app-branded NS/UIColors I have in the app.

UIViewRepresentable doesn't respect intrinsicContentSize invalidation

Andy — Sat, 22 Aug 2020 12:07:32 -0400

This is a quick write-up of an unexpected SwiftUI limitation I encountered recently. In my own searching, I couldn’t find it documented anywhere so I’m hoping this post will help someone in the future.

Problem summary

You can’t wrap a UIView in SwiftUI’s UIViewRepresentable if that UIView changes its intrinsicContentSize based in its frame width, because UIViewRepresentable will ignore invalidateIntrinsicContentSize(). As a result, the UIView will have its height clipped.

To make it a bit more concrete, imagine you have a UIView that draws multiline text that can line wrap. UILabel would be an example. If you were to adjust the label’s frame width, it would reflow the text and the intrinsic content height would change to reflect that.

During SwiftUI layout, what UIViewRepresentable does is ask the UIView for its intrinsic content size before it has set the UIView‘s frame. It then takes the minimum of the available size from the superview and the UIView‘s intrinsicContentSize, and sets that as the UIView‘s frame. This causes the UIView to reflow the text and invalidate its intrinsic content size. UIViewRepresentable ignores this, and as a result the UIView is clipped too short.

You can find a simplified version of this bug using UILabel on Github.

Investigation

I tried many suggestions from Stack Overflow, and override any size or layout related UIView method that I could. None of the suggestions worked, and almost none of the UIView methods were ever called during layout. I felt I was probably missing something obvious, so I filed a Developer Tech Support incident with Apple to get an official answer. My submission is summarized in the Github repo.

Results

Here’s the official response from Apple:

Hello Andy,

Thank you for contacting Apple Developer Technical Support (DTS). We have reviewed your request and have concluded that there is no supported way to achieve the desired functionality given the currently shipping system configurations.

If you would like for Apple to consider adding support for such features in the future, please submit an enhancement request via Feedback Assistant (https://feedbackassistant.apple.com). For more information on Feedback Assistant, please visit https://developer.apple.com/bug-reporting/.

While a Technical Support Incident (TSI) was initially debited from your Apple Developer Program account for this request, we have assigned a replacement incident back to your account.

Best Regards,

Developer Technical Support
Worldwide Developer Relations
Apple, Inc.

According to the response this is expected behavior, so any change would an enhancement request. I have since filed the enhancement request as feedback FB8499811.

Moment of Zen

I have the exact same view on macOS as an NSView wrapped up in an NSViewRepresentable. It works great. When the NSView invalidates its intrinsic size, NSViewRepresentable re-queries the intrinsic size and updates the frame appropriately.

I guess someone already filed that enhancement request.

Sharing HTTP API bindings between Swift Vapor and iOS/macOS apps

Andy — Mon, 21 Jan 2019 11:23:51 -0500

I’ve been building a macOS/iOS front for my Swift Vapor side project. When I first started I simply duplicated the API HTTP request and response information between the client and server. But, as the project has grown, this has become more tedious. Since both client and server are in Swift, it seems like I should be able to come up with a more scalable solution. Ideally, I’d like to define an API in one place and have both the client and server code use it. So in this post, I will: figure out what’s shareable, wrestle with package managers to share it, and finally integrate the API component into both the server and client.

What can be shared

I first had to determine what parts of the API made sense to share between the client and server. Both would need the same information, but they encode that information in different ways, and those ways might not be compatible. In my thinking there are five pieces of API information: the URL path, HTTP method, query parameters, request body, and response body.

While it would be nice to share the URL path, the client and server encoded them in very different ways. The client used a raw string for the entire path, while the server implicitly encoded the path, one component at a time, in a declarative router. The HTTP method was treated similarly. The client had an enum for the method, while the server encoded the method implicitly in the routing table. So I couldn’t easily share paths and methods. Or, perhaps more accurately, I didn’t feel I could share them without making the client and server code worse.

Query parameters are special in that they are not declared on either side. The server checks for their existence down in the controller code, but there’s no standard declaration or deserialization of them. So currently, I can’t share them. However, I feel like this could be improved somehow using Codable to define all the possible query parameters. I will likely revisit this in the future.

I found that only the request body and the response bodies were used similarly enough on both sides to be sharable. Both declared them as Codable structs, albeit with slightly different names. But I felt like I could consolidate on a naming scheme that would make sense for both sides.

I also briefly thought about putting the sending and receiving of responses into the shareable library. But that didn’t work easily because it would require importing the Vapor framework for the server support, which I didn’t want to do for a Cocoa app. Perhaps more importantly, that part of the code wouldn’t actually be shared; only one side would be using it. So my decision was to only share data structures and not code.

Structure and naming in the shared component

Now that I had decided that I only wanted to share the request and response data structures, I needed to figure out a way to build that. I had a few requirements. First, I needed to minimize name collisions; the library was to be imported into both the client and server apps, which increased the odds of a collision. Second, I needed to name the data structures in a way that wasn’t client or server centric, which was their current state. The names needed to make sense on both the client and server. Thirdly, I needed to name things consistently so they were discoverable. Finally, there were some functional requirements, such as the requests and responses needed to be Codable and Equatable.

First, to solve global name collisions, I nested everything in a namespace. Since Swift doesn’t have real namespaces, I used an enum:


import Foundation

public enum MyAppAPI {

}

I put the app name in the namespace name because my client app already had a type named API. It also would allow the client to import multiple API bindings in the future without collisions.

As far as structuring the API bindings consistently, I decided to group things by REST resource. As an example, here’s the bindings for the user resource:


import Foundation

public extension MyAppAPI {
    public enum User {
        public struct Envelope<T>: Codable, Equatable where T: Codable, T: Equatable {
            public let user: T

            public init(user: T) {
                self.user = user
            }
        }

        public struct ShowResponse: Codable, Equatable {
            public let id: UUID
            public let email: String

            public init(id: UUID, email: String) {
                self.id = id
                self.email = email
            }
        }

        public struct UpdateRequest: Codable, Equatable {
            public let resetTokens: Bool

            public init(resetTokens: Bool) {
                self.resetTokens = resetTokens
            }
        }
    }
}

There’s a lot to unpack. First, I put each resource into its own file. Second, I created a “namespace” (i.e. a Swift enum) for each resource inside the main API namespace. Inside the resource namespace, I created the individual requests and resource bodies. My naming convention was REST verb + Request or Response. My hope was this would make them easily discoverable. I also used envelopes in my APIs for clarity, so I declared my envelope for each resource as well.

In doing this work, I ran into a few practical considerations, aka things I had to do to appease Swift. The first thing was making everything public, which was a bit tedious. This had a knock-on effect in that the struct default inits didn’t work because they’re implicitly internal. I had to go through and manually implement the inits so that I could declare them public. This was enough overhead that I briefly reconsidered if having a sharable API component was worth doing. In the end I decided it was worth it, but I really wish there was a way to specify the access level of the implicit init on a struct.

One thing I didn’t attempt to deal with was API versioning. That’s only because I haven’t had to deal with it yet. I suspect I’ll add a namespace under the resource namespace for each non-v1 version, and add the updated request and response bodies there.

How to share

I had a plan of what to share, but I needed to figure out the mechanics of how to share. In most languages, this is done by a package manager, and Swift is no different. In fact, for Swift, there’s at least three package managers that can be chosen: Swift Package Manager (SwiftPM), Carthage, and Cocoapods. Ideally, I would like to use only one for both client and server. Unfortunately, each package manager has its own limitations, which made using only one undesirable.

SwiftPM has Linux support, but Carthage and Cocoapods don’t, meaning SwiftPM is the only viable option for my Swift Vapor app. However, SwiftPM doesn’t currently have the ability to generate Cocoa frameworks or apps, only Swift static libraries or command line apps. Since my API component doesn’t have any resources that require a framework, and Xcode can link against static Swift libraries for Cocoa apps, SwiftPM is a technical possibility. However, there is a decent amount of inconvenience involved with this approach (Googling can turn up tutorials on how). One is that my client apps would need two package managers (SwiftPM and either Carthage or Cocoapods). That’s because outside of my shared API component, all of the other packages my client app needs are only available as Carthage or Cocoapods packages. SwiftPM is supposedly going to get the ability to build Cocoa apps and frameworks sometime in the future, but not today.

In the end, I decided to make my API component both a SwiftPM package and a Carthage package. My Swift Vapor app would use the SwiftPM package, and my Cocoa apps would use the Carthage package. Although this meant a higher up front cost of setting up both, my thinking is it shouldn’t noticeably increase the maintenance burden afterwards. The benefit is each app can use the package manager best suited for its platform, which should make updating the API component easier when changes are made.

Between the two package managers, SwiftPM is stricter, requiring a specific directory hierarchy. Since Carthage uses an Xcode project, it could adapt to any hierarchy. For that reason, I tackled setting the SwiftPM package up first.

Refactoring the Swift Vapor app

In my apps, the server app was the source of truth for API information. It had the full definitions of the request and response bodies, and was the most up-to-date. So my plan was to pull the definitions out of the Vapor app into the API component, publish the component, then have the Vapor app import that component. Later, I could figure out how to refactor the Cocoa client apps.

First I created a SwiftPM package for the API component from the command line, and committed it to a git repo.


> mkdir MyAppAPI
> cd MyAppAPI
> swift package init
> git init
> git commit -am "Initial commit"

Next, I moved over the API request and response definitions from the Vapor app, and modified them to fit the structure and naming conventions I defined earlier. I’d use swift build periodically to make sure everything was valid Swift code from SwiftPM’s perspective. Since I prefer Xcode’s editor to a command line editor, I used swift package generate-xcodeproj to create a project, and then made my changes in Xcode. When I was done, I committed my changes in git.


> git commit -am "Adding API definitions"

To share the package, I needed a remote git repo that both client and server could pull from, plus a version number. Since Bitbucket offers free private repos, I created one there, and added it as the remote origin. (Github recently announced free private repos, too.) Then I tagged my repo with a version, and pushed it to the remote:


> git remote add origin <MyAppAPI bitbucket git URL>
> git tag 0.0.1
> git push origin master --tags

Note that SwiftPM version tags are just the version number, sans any prefix or suffix.

I was now ready to refactor my Vapor app to pull in this shared package and use it instead. First, I modified the Package.swift file to include it as a dependency:


    dependencies: [
        ...
        .package(url: "<MyAppAPI bitbucket git URL>", from: "0.0.1"),
        ...
    ],
    ...
    targets: [
        ...
        .target(name: "App", dependencies: [
            ...
            "MyAppAPI",
            ...
            ]),
        ...
    ]

Running vapor update from the command line pulled down the package and updated all my dependencies.

Swift Vapor needs one more thing on the API request and responses before they are useable. Namely, it needs the top-level type of the request and response to conform to the Content protocol that Vapor defines. Fortunately, it’s just an subprotocol of Codable that provides some extra methods, so the requests and responses only need to be declared as conforming. Further, since it’s only the top level types, and I used envelopes to wrap my request and response, for me I only needed to conform the envelopes. I decided to do this all in one file, with the hopes it would be easier to keep up-to-date.


import Foundation
import Vapor
import MyAppAPI

extension MyAppAPI.Session.Envelope: Content {}
extension MyAppAPI.User.Envelope: Content {}
...

This is a bit tedious, but I didn’t find it overly so. In hindsight, using envelopes saved me a bit of work. If I hadn’t used envelopes each individual request and response would have been the top-level type, and I would have had to conform each to Content.

The last piece was to go through all my controllers and have them import MyAppAPI and use the structs defined there.

In doing this part of the work, I learned a couple of things. First, all the namespacing does make using the shared package a bit verbose. Second, separating out the request and response models from the server helped clarify what was a server model and what was a response payload. I felt this work improved the server codebase.

Refactoring the Cocoa/CocoaTouch app

To get my API package working the Cocoa clients, I needed to make the API package a proper Carthage package, then import that into the Cocoa app. Since Carthage works by building an Xcode project, my first job was to create an Xcode project that built both iOS and macOS targets. This was straight forward, although tedious, since the default Xcode templates create a different folder layout than SwiftPM requires.

First, in order to create a Carthage Xcode project, I deleted the existing Xcode project that the SwiftPM had built. It builds a static Swift library, but Carthage needs an iOS/macOS framework. Second, I needed to commit the Xcode project to git for Carthage, but SwiftPM generates a .gitignore file that excludes Xcode projects. So I removed the *.xcodeproject line from .gitignore. Finally, I created an iOS framework project in Xcode with the same name as my package (e.g. MyAppAPI).

While I now had an Xcode project, it was using the Xcode generated files and not the actual files I wanted. Fixing this took several manual steps. First I closed Xcode, then moved the project file itself to the root folder of the package. I moved the framework header (e.g. MyAppAPI.h) and the Info.plist file into the source folder (e.g. Sources/MyAppAPI). Then I deleted all of the other Xcode generated files. Next I opened the project in Xcode. I removed all of the existing file references that were now broken, and then added all of Swift files, the framework header, and the Info.plist to the project. I had to mark the framework header as public, and then go into the Build Settings to update the path to the Info.plist to be correct. At this point I could build an iOS framework.

The second step was to create a macOS framework. It was similarly messy. First, in Xcode, I created a new target for a macOS framework named MyAppAPI-macOS. I went through and deleted all the files Xcode created in performing that, then pointed the macOS target to all the same files that the iOS target had. The Info.plist and framework header were sharable between iOS and macOS. I did have to update the framework header to import Foundation/Foundation.h instead of UIKit/UIKit.h. In the Build Settings, I had to update the path to the Info.plist. Additionally, I needed the iOS and macOS frameworks to have the same name and bundle identifier so the client code could import using the same name. To do that, I modified the Product Name and the Product Bundle Identifier to manually be the same as the iOS target. Building the macOS target now worked for me.

Xcode also defines a test target and files, but since I was only defining types, I didn’t feel I needed unit tests, so I deleted it.

To verify that Carthage would be able to build my project file, from the root of the package I ran:


> carthage build --no-skip-current

When everything successfully built, I was ready to publish my Carthage package.

Carthage is decentralized like SwiftPM, so to publish my package I just needed to tag a version and the push that to the remote git repository. Unfortunately, Carthage and SwiftPM use two different formats for version tags. Carthage prefixes it’s version tags with “v”, while SwiftPM has no prefix. So I committed all my Carthage changes, tagged both Carthage and SwiftPM, then pushed.


> git commit -am "Adding Carthage support"
> git tag 0.0.2
> git tag "v0.0.2"
> git push origin master --tags

Finally, I could pull the shared API package into my Cocoa apps. That involved adding it as a dependency in Carthage and updating. I added the repo to my Cartfile:


git "<MyAppAPI bitbucket git URL>"

Then updated Carthage from the command line.


> carthage update

Carthage doesn’t modify project files (which I consider a feature), so I went and added the MyAppAPI.framework to both my iOS and macOS client app targets.

Using the shared API package was straight forward in the client apps. It was simply importing the MyAppAPI framework, then using the types. I did end up using some typealiases to rename some of the API responses. This was because the client app’s model was the same as the response model. To me this makes sense, because the server is publishing a REST-ful interface, meaning the response model should be the resource model.

And, with that, I was done!

Conclusion

My side project has both server and client apps, all written in Swift. Because they share a common language, I wanted to leverage that to share HTTP API information between the two. My hope was to reduce redundant definitions that could get out of sync. To accomplish this, I created an API repo that contained the API request and response bodies. The repo was both a valid SwiftPM package and a valid Carthage package at the same time. This allowed both the Swift Vapor server and the Cocoa iOS/macOS apps to include the same shared API package.

Handling periodic tasks in Swift Vapor

Andy — Sun, 13 Jan 2019 10:13:37 -0500

In my Swift Vapor side project, there have been a couple of instances where I wanted to run some periodic tasks. My needs were pretty simple: every X amount of time, I wanted to run a closure that would perform some database operations. On top of that, it would be nice to have a tiny bit of infrastructure to make periodic jobs require less boilerplate, have visibility in production (i.e. logging if the job was successful or not), and the ability to verify the jobs in integration tests.

In this post, I’m going to flesh out a periodic job interface, lay out some implementation approaches, talk through what I actually did, and finally how I tested it.

A periodic example

First, I’ll define how I’d like to be able to schedule a periodic task in client code. Here’s an except from my app:


func boot(_ app: Application) throws {
    let jobQueue = try app.make(JobQueue.self)
    jobQueue.schedule(initialDelay: .hours(1),
                      delay: .hours(24),
                      withName: "Accounts.cleanup") { container, connection -> Future<Void> in
        return self.cleanup(with: container, on: connection)
    }
}

private func cleanup(with container: Container, on connection: DatabaseConnectable) -> Future<Void> {
    return // task that performs clean up
}

I didn’t need a complicated interface to schedule a periodic job. The initial delay and repeated delay are givens for any periodic task. The name is a bit extra, but it turned out to be quite helpful when testing and logging. Finally, the “job” itself is a closure that’s passed a dependency injection container and a database connection. Those two things are needed for just about any meaningful work in Vapor. Finally, the closure will return a Void promise, which is used by the job infrastructure to know when it is complete, and if it was successful or not.

Although the JobQueue interface is inferable from the example above, here’s exactly how I’ve defined it for my app:


import Foundation
import Vapor

typealias Job = (Container, DatabaseConnectable) -> Future<Void>

protocol JobQueue: Service {
    func schedule(initialDelay: TimeAmount, delay: TimeAmount, withName name: String, _ job: @escaping Job)
}

I’ve defined it as a protocol because I’ll inject a fake implementation in my integration tests. Since I’m taking advantage of the dependency injection system in Vapor, I conform the protocol to Service. But all I needed was one method on the protocol to actually schedule the periodic job. The TimeAmount is a datatype defined down in the NIO framework.

JobQueue Decisions

Now that I’ve defined the JobQueue interface, I need to figure out how to implement it. I thought of a few options.

One option was to register a timer in my app at the given interval, and run the periodic job closure then and there. The benefit of this is it simple to understand and implement. The downside is it doesn’t scale up or down very well. If my host spins up more than one instance of my app, both instances will try to run this periodic task. Or, if I’m on a hobbyist plan, and my host spins down all my instances because of lack of requests, then my periodic task won’t run at all.

Another option was to find or build something like Ruby’s Resque but for Swift, and use a timer to schedule a background job on Resque-but-for-Swift to perform the periodic job. The benefit would be the job would only be run once no matter how many instances of my app were spun up, plus job persistence. The downside is, as far as my Google searches show, such a thing does not exist, and building it myself would be a significant undertaking.

There were also some options that didn’t fit the interface I gave above, but could be legitimate solutions. First up, I could define a Vapor command that’s invokable from my app’s command line that performs the periodic job. Then, using my host’s infrastructure, manually invoke the command when I think it needs to be run. The downside is it relies on me remembering to run the command. However, it wouldn’t need any internal job infrastructure, and would only run on the instance I wanted. A second option would be to do nothing. If my periodic job didn’t run nothing bad would happen for a very long time. The upside to this is it cost nothing to implement. The downside is there is a timebomb in my app that will one day go off. But that might be fine because the app might not last that long, or be completely redesigned so the periodic job is unnecessary.

In the end, I went with the first solution of registering a timer in my app, and running the closure when it triggered. I decided this for a few reasons. First, I’m lazy and forgetful and won’t remember to run some manual command. Second, my side project probably won’t ever scale beyond one instance. Third, even if it did scale up, the periodic tasks running concurrently wouldn’t hurt anything. Finally, this solution did something (so no timebomb), but was the least investment that did something.

As far as using a timer in my Vapor app, my first attempt was to use a 3rd party Swift library that implemented periodic jobs on top of DispatchQueue. That did seem to work, but it happened outside of Vapor’s EventLoops, which always seemed a little janky to me. Later, I discovered that the NIO framework offered RepeatedTasks on their EventLoops, so I used those instead.

Implementing JobQueue

I had an approach now, I just needed to implement it. First up, building the production implementation of JobQueue.


import Foundation
import Vapor

final class ProductionJobQueue: JobQueue {
    private let eventLoop: EventLoop
    private let container: Container
    private let logger: Logger

    init(eventLoop: EventLoop, container: Container, logger: Logger) {
        self.eventLoop = eventLoop
        self.container = container
        self.logger = logger
    }
    ...
}

The ProductionJobQueue needed a few things in order to function. First, it needs an EventLoop so it can schedule RepeatedTasks. Second, it needs a dependency injection Container so it can get a database connection later to hand to a periodic job. Finally, it takes a Logger because the app logs any periodic job invocation to provide some insight into what’s going on in the deployed app.

The only required method of the JobQueue protocol is the schedule() method:


final class ProductionJobQueue: JobQueue {
    ...
    func schedule(initialDelay: TimeAmount, delay: TimeAmount, withName name: String, _ job: @escaping Job) {
        eventLoop.scheduleRepeatedTask(initialDelay: initialDelay, delay: delay) { repeatedTask -> EventLoopFuture<Void> in
            return self.execute(job, withName: name, on: repeatedTask)
        }
    }
    ...
}

This is a thin wrapper around EventLoop.scheduleRepeatedTask(). All the interesting bits of the implementation are in the execute() method which actually calls the job closure.


final class ProductionJobQueue: JobQueue {
    ...
    private func execute(_ job: @escaping Job, withName name: String, on repeatedTask: RepeatedTask) -> Future<Void> {
        let startTime = Date()
        return container.withPooledConnection(to: .psql) { connection -> Future<Void> in
            return job(self.container, connection)
        }.map {
            self.logSuccess(for: name, whichStartedAt: startTime)
        }.catch { error in
            self.logFailure(error, for: name, whichStartedAt: startTime)
        }
    }
    ...
}

The execute() method provides most of the value add functionality of the JobQueue. First off, it grabs a database connection for the job, so the job doesn’t have to itself. Once it has a connection, it invokes the job closure with the container and database connection. It waits on the job to complete, then logs the success or failure of the job.


final class ProductionJobQueue: JobQueue {
    ...
    private func logSuccess(for name: String, whichStartedAt startTime: Date) {
        let time = Date().timeIntervalSince(startTime).asFormattedMilliseconds
        logger.info("JOB \(name) -> SUCCESS [\(time)]")
    }

    private func logFailure(_ error: Error, for name: String, whichStartedAt startTime: Date) {
        let time = Date().timeIntervalSince(startTime).asFormattedMilliseconds
        logger.info("JOB \(name) -> FAILURE [\(time)]")
    }
}

The logging of jobs is simple, but provides some necessary transparency. It just logs the name of the job, whether it was a success or failure, and the time it took to complete. Even though I capture the error in the failure case, I don’t log it for now. That’s because it might possibly have sensitive info in it (like database connection info) that I don’t want being saved out to a log. In the future, I might log out the name of the error type, if I discovered I needed more information when debugging production issues.

The asFormattedMilliseconds property above is an extraction of code from my earlier Swift Vapor logging post:


extension TimeInterval {
    private static let intervalFormatter: NumberFormatter = {
        let formatter = NumberFormatter()
        formatter.numberStyle = .decimal
        formatter.maximumFractionDigits = 2
        formatter.multiplier = 1000
        return formatter
    }()

    var asFormattedMilliseconds: String {
        return TimeInterval.intervalFormatter.string(for: self).map { $0 + "ms" } ?? "???ms"
    }
}

Finally, I needed to implement the Service protocol so the class could be used in the dependency injection system.


extension ProductionJobQueue: ServiceType {
    static var serviceSupports: [Any.Type] {
        return [JobQueue.self]
    }

    static func makeService(for worker: Container) throws -> ProductionJobQueue {
        return try ProductionJobQueue(eventLoop: worker.eventLoop, container: worker, logger: worker.make())
    }
}

As usual, I used ServiceType to conform to the Service protocol. This allowed me to register with only the type, plus have a dependency injection container available when the instance was created. This implementation was a bit different than usual, in that I needed to override the static serviceSupports property to include the JobQueue protocol. This is needed because by default ServiceType only registers the concrete type. By listing JobQueue as supported, client code can ask the container for JobQueue and they’ll get a ProductionJobQueue in the production app. The makeService() method takes full advantage of being given a Container: it passes in the event loop from it, the container itself, and creates a logger from the container.

Finally, ProductionJobQueue is registered as a service from the ProductionConfiguration. At this point, periodic jobs should work in production. But it would be nice to test them.

Testing

I spent some time thinking about what and how to test periodic jobs. I knew I wanted integration level testing, and that I’d facilitate that by building a fake implementation of JobQueue. I needed a fake because waiting on timers to fire in a test isn’t a viable option, especially if they’re only firing once a day. Also, for me, integration testing meant I should be able to verify that the periodic job was both registered and it performed what it was supposed to. I considered two possible solutions.

The first idea was to have a fake job queue that individual tests could manipulate the clock on. That is, a test could say “pretend two hours have elapsed” to the fake job queue, and the job queue would go look through the registered jobs and fire the ones that should have fired by then. The upside to this approach is it could be used to validate the initial and repeating delays given at registration were working. The downside is this would require a sophisticated fake that could do time calculations reliably. This would give me less confidence that I was testing production code, as opposed to testing my fake job queue.

The second idea was to require each periodic job to provide a unique name. Then individual tests could ask the fake job queue to invoke a periodic job by that name. The upside is the fake is simple and predictable. The downside is jobs have to have globally unique names, which is a bit of overhead.

I decided on the second option to invoke jobs by name. Because of the logging done in production, the requirement that jobs have globally unique names was already there, so the downside was moot. Additionally, the “upside” of the first option was validating the delay values. But in my case, they were always constants, so there seemed to be little value in validating them. Finally, the ease of implementing the second option was hard to ignore.

This approach turned out to be easy to use in my tests. As an example:


func testRemoveExpiredChallenges() throws {
    // setup

    try app.jobQueue.execute("Accounts.cleanup", container: app.container, connection: connection)

    // validate here
}

I ended up redacting all the setup and validation code for this test for succinctness, and because all of it was specific to the app and not that interesting. The only part left is invoking the periodic job on the fake job queue, which is done by passing the job name, a Container and a connection to the database. The app seen here is a TestApplication, which I covered in a post about integration testing Swift Vapor.

Because of my selected testing approach, TestJobQueue was easy to implement. Here’s how I conformed it to the JobQueue protocol:


import Foundation
import Vapor

final class TestJobQueue: JobQueue {
    struct Entry {
        let initialDelay: TimeAmount
        let delay: TimeAmount
        let name: String
        let job: Job
    }

    var schedule_wasCalled = false
    var schedule_wasCalled_withEntries = [Entry]()
    func schedule(initialDelay: TimeAmount, delay: TimeAmount, withName name: String, _ job: @escaping Job) {
        schedule_wasCalled = true
        let entry = Entry(initialDelay: initialDelay, delay: delay, name: name, job: job)
        schedule_wasCalled_withEntries.append(entry)
    }
    ...
}

The schedule() method is just a recorder. It creates an entry for each scheduled job and stores it in an array. The important bits that are used later are the name and job. I ended up storing the initialDelay and delay so if a test actually wanted to validate them, they could.

The other interesting piece to the TestJobQueue class is the execute() method that tests call when they want to fake a periodic job being triggered.


final class TestJobQueue: JobQueue {
    ...
    func execute(_ name: String, container: Container, connection: DatabaseConnectable) throws {
        guard let entry = schedule_wasCalled_withEntries.first(where: { $0.name == name }) else {
            return
        }

        try entry.job(container, connection).wait()
    }
}

My implementation is as simple as I could make it. It searches the array of entries looking for the first job with the matching name. If it can’t find a matching job, it silently fails. This is intentional: it mimics what would happen in production if a periodic job wasn’t properly registered. Namely, nothing would happen. It is up to the individual test cases to verify that a job’s side effects are happening. However, execute() does wait on the job to complete before returning, just to make the tests simpler.

The last bit needed for TestJobQueue is registering it with the dependency injection system. I did it differently from the production job queue, however. ProductionJobQueue conformed to ServiceType because it needed access to a dependency injection container to initialize. TestJobQueue doesn’t have the same requirement to instantiate. Further, it would be useful to the tests if the TestJobQueue were exposed to them as that type — so they can access the execute() method. Otherwise they’d have to force cast a JobQueue to a TestJobQueue, and I find that more than a little gross.

For that reason, I modified TestingConfiguration to hold an exact instance:


struct TestingConfiguration: ConfigurationType {
    ...
    let jobQueue = TestJobQueue()

    func configure(_ services: inout Services) throws {
        ...
        services.register(jobQueue, as: JobQueue.self)
        ...
    }
    ...
}

This is the TestingConfiguration that I described in how I do environment configuration for Swift Vapor. Here, it registered a member variable of type TestJobQueue as a JobQueue. By making it publicly available on TestingConfiguration, the TestApplication has easy access to it.

The final piece is exposing the TestJobQueue on TestApplication so it’s convenient for tests to use.


class TestApplication {
    ...
    var jobQueue: TestJobQueue {
        return configuration.jobQueue
    }
    ...
}

Since the TestApplication already has a reference to TestingConfiguration, it can return that instance. The test code now works.

Conclusion

My Swift Vapor app had a need to run some clean up jobs periodically. The requirements were simple: it was ok if the job ran on multiple instances or not at all, but it should make a good faith effort to run at least once. I wanted a class that reduced the necessary boilerplate for scheduling a job, while adding logging to the jobs, and being testable. I settled on NIO‘s RepeatedTasks to implement timers to run the periodic tasks in each app instance. For testing, I kept the testing fake simple: the tests could invoke jobs by name, and then validate the side effects.

Building a declarative router for Swift Vapor

Andy — Sun, 06 Jan 2019 10:59:23 -0500

As I’ve been using Swift Vapor 3, one of the things that I felt could be better was the way routes were declared. So I built a framework to meet my Vapor routing needs. If you’d like to try it out, go to the Github page and checkout the README. For the rest of this post, I’m going to talk about what my goals were, and highlight parts of the implementation that were interesting to me.

But first, to whet your appetite, here’s a tiny example of declaring routes using my framework:


import Vapor
import RoutingTable

public func routes(_ router: Router) throws {
    let table = RoutingTable(
        .scope("api", middleware: [ApiKeyMiddleware()], children: [
            .resource("users", parameter: User.self, using: UserController.self, children: [
                .resource("sprockets", parameter: Sprocket.self, using: SprocketController.self),
                .resource("widgets", using: WidgetController.self)
            ]),
            .resource("sessions", using: SessionController.self),
            .post("do_stuff", using: StuffController.doStuff)
        ])
    )
    table.register(routes: router)
}

Goals

I had four goals when creating my routing framework:

All routes in one file

One of the challenges I ran into was determining what all the routes in the app were and how they fit together. It is possible to print out all the routes by running a command line tool, but that didn’t help me with finding where the associated code was.

I also attempted to take advantage of RouteCollections at one point in order to make my routes() method less verbose. It did improve the verbosity, but at the expense of all the routes in one place. Ideally, I’d like to have my cake and eat it, too: all routes in one file, but expressed concisely.
Hierarchical declaration

Routes are hierarchical by nature, and I’d like to declare them that way. By that, I mean building a tree data type that is hierarchical in Swift syntax when declared, as opposed to calling a series of methods that build up a tree at runtime.

I see a couple of benefits from making the route declaration hierarchical. First, it’s easier for me to see how the endpoints fit together or relate to one another. I can see the hierarchy in the code syntax itself, instead of parsing method calls to build up the hierarchy in my head. Second, it can reduce boilerplate code by inheriting configuration from the parent to the child.
Re-usability of controllers

By re-usability of controllers, I mean a controller can be used in more than one place in the routing hierarchy. For example, maybe a controller implements managing sprockets. It could be exposed in one place in the routing hierarchy for normal users, but also in a different place for admin users. Part of making this useful would be allowing the routing declaration to specify which controller endpoints are available at each place in the hierarchy. e.g. the admin sub-hierarchy should allow the DELETEing of sprockets, but the normal user’s sub-hierarchy shouldn’t.

Being re-usable implies controllers don’t know where they are in the route hierarchy. To me, this makes sense because of my iOS/macOS background. In that context, view controllers don’t know where they appear in the app. Instead, app architecture relies on Coordinators (or a similar pattern) to know when and where to display the view controllers. Because of the separation of concerns, view controllers can be re-used in multiple places of the app. I think of API/web controllers in the same way.
Use higher level concepts

In my experience, few things reduce boilerplate code and increase readability like the introduction of higher level concepts. In the case of routing, I’m thinking about scopes and resources.

Scopes add the ability to group routes logically, so that the code maintainer knows they fit together to accomplish a common goal. It also means routes in a scope can inherit the same path prefix and/or middleware. Some examples of scopes could be an API scope or an admin user scope.

Resources allow me to describe REST-like resources in a succinct way. Although resource declaration can be succinct, the code maintainer can infer a lot about it. That’s because REST-like resources are known to support certain subpaths and HTTP methods that behave in specific ways. So although fewer things are declared about a resource, more is known about it than if I had declared each route individually.

The Results

Based on these goals, I came up with an idealized version of what I wanted route declaration to look like:


scope "api", [ApiMiddleware.self] {
    resource "users", parameter: User.self, using: UserController.self {
        resource "sprockets", using: SprocketsController.self
    }
}

What I like about the above is it has just enough punctuation and keywords to make it readable, but no more than that is unnecessary. It also makes use of curly braces to denote hierarchy. When I’m reading Swift code, curly braces make my brain think parent/child relationship in a way other punctuation doesn’t. It also seems to help make Xcode do sane things with indentation.

Here I’m going to admit that much of my inspiration for what routing could be came from Elixir’s Phoenix framework, and its routing library. I feel like its route declaration is very close to my ideal. In addition, it supports more features, including the ability to generate full URLs from a named resource.

Unfortunately, I couldn’t achieve my ideal in Swift. The example I gave above isn’t valid Swift, nor was there a way to extend Swift to support it. A lot of Phoenix’s elegance and power comes from Elixir’s hygienic macros, which Swift doesn’t have.

Instead, here’s the closest I could come in Swift:


.scope("api", middleware: [ApiKeyMiddleware()], children: [
    .resource("users", parameter: User.self, using: UserController.self, children: [
        .resource("sprockets", parameter: Sprocket.self, using: SprocketController.self)
    ]),
])

It has a lot more punctuation and keywords than is really necessary to convey what I want. It also uses square brackets for arrays to denote hierarchy, which are a bit clumsy especially when used in Xcode. But given Swift’s limitations, I feel like it comes pretty close.

Interesting Implementation Bits

When implementing my declarative router I ran into some implementation hurdles that I thought were interesting enough to write down.

Verbosity reduction

One of my stated goals was to reduce the verbosity needed to declare all my routes. Some of the reduction came for free just by using higher level concepts like scopes and resources, and making the declarations hierarchical so common configuration could be shared. But all that space savings could be undone if I messed up the declaration API. I paid particular attention to leveraging Swift’s type inference and default parameters.

I realized early on that I needed a tree that was homogenous in type, but polymorphic in behavior. There are three types that could appear in a routing declaration: a scope, a resource, and a raw endpoint (i.e. a GET, PUT, PATCH, POST, or DELETE). Each of those has its own properties, and handles registering routes differently. Of those, both scopes and resources could have children, which could themselves be scopes, resources, or raw endpoints. That left me with a couple of options.

The first option that I considered was using an enum to represent the three types (scope, resource, and raw endpoint). Since Swift enums can have associated data, each value could contain all their necessary properties. However, enums had a couple of problems. First, they don’t allow default values on construction. Which means each declaration would have to specify all values even if they weren’t used. Second, eventually each enum value would have to register all the routes it represented, and since each enum type had to do that differently, there would be a giant switch statement somewhere. That didn’t seem elegant to me, so I abandoned that approach.

The second option was to declare a common protocol (e.g. Routable) and have scope, resource, and raw endpoint types conform to that protocol. Then I had scopes and resources declare their children to be of type Routable so type homogenous trees could be built. That turned out to mostly work. The problem I ran into was the raw endpoints were more verbose than I wanted. For example:


Scope("api", middleware: [ApiMiddleware()], children: [
    RawEndpoint(.post, "do_stuff", using: StuffController.doStuff)
])

I felt having the typename RawEndpoint in the declaration was unnecessary and uninteresting. The important bit was the HTTP method, but that was obscured by the typename. My next thought was use the HTTP method name as the typename (e.g. Post, Get, etc). This worked, but at a cost. First, it meant I had five different types that all did the same thing, except for one parameter. Second, the HTTP method names are common words and had to exist at the top level scope. This made me worried about typename collisions.

I tried to fix those problems by adding static methods to my protocol as a shorthand way to create the raw endpoint type like so:


extension Routable {
    static func get<T>(_ path: String..., using controller: T) -> Routable {
        return RawEndpoint(.get, path, using: controller)
    }
}

However, when I tried to use the static methods in a declaration:


Scope("api", middleware: [ApiMiddleware()], children: [
    .post("do_stuff", using: StuffController.doStuff) // ERROR
])

Swift complained, seemingly because it couldn’t infer the type because the static methods were on a protocol. I could have specified the full type name to the method, but I felt that would have made the declaration too verbose. But I thought I was close to something that would work. I just needed the type inference to work on the static methods.

That lead me to the final option that I actually used. My hunch was I needed use a concrete type rather than a protocol in my declaration API. That would allow me to use static methods in the declaration and Swift’s type inference would work. To put it another way, I could make this work:


Scope("api", middleware: [ApiMiddleware()], children: [
    .post("do_stuff", using: StuffController.doStuff)
])

If children was declared to be an array of a concrete (i.e. non-protocol) type, and if post() were a static method on that concrete type.

The challenge now was I needed two seemingly opposed concepts. I needed each declaration item (i.e. scope, resource, raw endpoint) to be polymorphic since they each should act differently based on their type. I had achieved that via making them conform to a common protocol. However, in order to make Swift type inference happy, I needed a concrete type.

So I used type erasure, kind of. I wrapped the protocol Routable in a struct called AnyRoutable. It works like a type erasure datatype in that it implements the Routable protocol by calling the methods on the Routable instance it contains. This gave me a single concrete type while still allowing polymorphism.

To make this work, I essentially made AnyRoutable a facade to the rest of the framework. Every node in the routing tree would be declared as an AnyRoutable, which could, internal to the framework, wrap the correct declaration item type. To make building an entire tree from one type possible, I added static methods on AnyRoutable that created each declaration type: scope, resource, and each of the HTTP methods. For example, something like:


struct AnyRoutable {
    static func get<T>(_ path: String..., using controller: T) -> AnyRoutable {
        return AnyRoutable(RawEndpoint(.get, path, using: controller))
    }
}

The trick was I had the static methods deal only in AnyRoutable; children were declared as them, and the return types were AnyRoutable. Since all parameters and return types were a concrete type, Swift could easily infer the type, and the static methods could be called without them. Implementation wise, the static methods simply created the appropriate Routable subtype, then wrapped it in AnyRoutable. This had the added bonus of only needing to make AnyRoutable public in the framework. The Routable implementations for resource, scopes, and endpoints stayed hidden.

Although it took me a while to reach the final implementation, the pattern seems generally useful. It allows polymorphism in the implementation, while only exposing one concrete type to client code, which means type inference can be used. I suspect there might be other options for solving this problem. For example, I never tried a class hierarchy and I wonder if that could be made to work. However, I’m pretty happy with AnyRoutable since I got a facade pattern out of it as well.

Resource reflection

After designing the API interface, the next most difficult thing was figuring out how to implement controllers that managed REST-like resources. In a nutshell, if a router declares a resource, my framework should be able to look at the implementing controller and determine what verbs (i.e. index, show, update, create, delete, new, or edit) it supports, and automatically declare those routes. I wanted this to require as little boilerplate as possible. As a bonus, I wanted to determine the verb support at compile time.

I quickly realized that there would have to be some overhead no matter what, just because of the limitations of Swift. Swift has no way of asking “does this type implement this method” outside of having that type declare conformance to a protocol that requires the method. It doesn’t have a fully dynamic and reflective runtime like Objective-C, nor a structural type system. So I accepted that resource controllers would have to declare conformance to a protocol for each of the verbs it supported.

But even accepting that limitation, I still wanted to determine which verbs were available at compile time. Since the controller declared conformance to a protocol, and a generic method could require parameter conformance to a protocol, for a long time I held out hope this this was possible. For example, I could do this:


func indexRoutes<ControllerType: ResourceIndexable>(_ controller: ControllerType) -> [Route] {
    // generate route for index verb
} 

func indexRoutes<ControllerType>(_ controller: ControllerType) -> [Route] {
    return []
} 

class MyController: ResourceIndexable {
}

let controller = MyController()
let routes = indexRoutes(controller) // calls the correct method

The issue I ran into was trying to put all the verb routes together. The method that put all the routes together would have to know about all the resource verb protocols it conformed too. That’s because if the method didn’t require conformance to a verb protocol, Swift would act like it didn’t conform to that protocol regardless of it actually did or not. So for this to work, I would have to implement a generic method for every combination of the seven verb protocols that could occur. That seemed excessive to me. In the end, I simply had the code query at runtime which protocols the controller implemented.

This part was interesting to me because it seems like it should be solvable problem. However, in its current state, Swift doesn’t appear able to overcome it. I do wonder if a hygienic macro system would make it feasible.

Dependency injection woes

The next two implementation struggles relate to the implementation details of Vapor itself, and not something inherent to the issue of building a declarative router. But they still contained valuable learnings.

At a base level, the router connects routes with a controller that will handle requests to that route. To make the route declaration as concise as possible, I only required the type of the controller, as opposed to a live instance that might have be constructed and/or configured. I decided I would instantiate the controller later, when registering the route, using Vapor’s dependency injection system. The problem was when it came to register the route, Vapor’s dependency injection system was in the wrong state.

Vapor’s dependency injection effectively has two phases. The first phase is the setup phase, where it registers types it calls “services” which can be instantiated later, in the second phase. In the second phase, a “container” exists, and can be used to instantiate any of the service types registered in the first phase. When the router is being initialized, the system is in the setup phase, and can’t instantiate any of the controller types because there’s no container.

I considered using my own custom protocol on controllers that allowed them to be constructed without a dependency injection container. However, after trying that out, it seemed surprising in that everything else uses Vapor’s DI system. Plus my custom protocol would be more restrictive; it wouldn’t be able to allow custom init parameters to the controller (unless all controllers needed them), nor would it offer access to the DI system to allow construction of said parameters.

In the end, I was able to defer controller allocation until the first route was actually executed. By then, containers were available. Further, Vapor’s DI system took care of caching the controller for me.

This problem was interesting because I’ve run into it a few times in Vapor. I need to be on the lookout for different patterns to work around not having a DI container available when I need it.

Testing difficulties

The final issue I ran into was trying to unit test my framework. Since it’s implemented in Swift, my go to method is to define all dependencies as protocols, then for my tests to create fakes I can manipulate and observe.

Unfortunately, most of the Vapor types I had to interact with weren’t easily fakeable. The big one I needed to fake was Vapor’s Router protocol. Being a protocol, I thought it would be a slam dunk. Unfortunately, all the interesting methods on Router were in protocol extensions, meaning my testing fakes could not override those methods.

What I ended up doing was defining my own protocol for the methods on Router that I used, then using that everywhere in my code. Since the methods were declared in the protocol, they were overridable by my testing fakes. This allowed me to do the unit testing I wanted. That only left the issue of how to use Vapor’s Router in the non-testing version of the framework.

Indirection solves a lot of problems, this being another example. I declared a concrete type that conformed to my router protocol that my framework could use. I then had it wrap a Vapor Router, and implement the protocol by calling the corresponding methods on Router. Then, at the top level object, I hid the wrapping of Router behind a helper method, so it looked like my framework dealt with Routers natively.

The lesson I take from this is testing when relying on 3rd party frameworks is hard. Unit testing with UIKit and AppKit types is no different. Also, defining my own protocol and wrapping a 3rd party protocol in a concrete type to conform to it seems like a repeatable strategy.

Conclusion

When using Swift Vapor’s routing API, I discovered I wanted a few more things than it offered. Namely, I wanted all routes declared in one file, a hierarchal declaration, re-usability of controllers, and higher level concepts like scopes and resources. In building a framework to support these concepts, I ran into a few implementation concerns. The first was learning to design an API in such a way to reduce verbosity. The others were trying to determining protocol conformance at compile time, working around two-stage dependency injection limitations, and trying to test my code while not having fakeable protocols from 3rd party frameworks.

Sending email from Swift Vapor

Andy — Sun, 30 Dec 2018 09:37:11 -0500

Like most services these days, my Vapor side project needs to send welcome emails when a user signs up for the service. While I could write my own SMTP client, it would still require a lot of DNS setup to make sure those emails made it through various spam countermeasures. Given this is a side project, and sending email is a minor component of it, that didn’t seem worthwhile to me. So I decided to use a 3rd party service who would take care of all of that.

I chose Mailgun for a couple of reasons:

I’m hosting my side project on Heroku, and they provide a convenient Mailgun add on that I can provision.
Mailgun offers a free tier, appropriate for my side project
There’s already a Swift package for Mailgun’s API.

The Swift package for Mailgun got me most of the way there. However, I still needed a bit of infrastructure to render the emails, and then to validate the emails were correctly sent in my integration tests.

In this post I’m going to cover how I went about generating the email content, sending the email to Mailgun, and finally how I ensured I could test it all. I’m not going to cover how to set up Mailgun and all the DNS stuff because that’s very app specific, and is documented in Mailgun’s docs already.

Example use

I find it helpful when building a subsystem to sketch out what the use site will look like. It helps me determine if I’m building something that will meet my needs, and gives me a concrete target to build toward. With that in mind, I thought the ideal for my project was to define an email template for each kind of email I wanted to send, have a method that could render that down to a final email to send, then send it via an abstract email delivery service. The email body allows both text and html, and the body template was defined in Leaf.

Here’s how that looked in code:


struct WelcomeData: Encodable {
    let verifyLink: String

    init(user: User) {
        self.verifyLink = "myapp://verify/\(user.verifyToken)"
    }
}
...
let template = EmailTemplate(from: "donotreply@myapp.com",
                             to: email,
                             subject: "Welcome to MyApp!",
                             bodyTemplate: "WelcomeEmail")
let welcomeData = WelcomeData(user: user)
return template.render(welcomeData, on: container).flatMap { message -> Future<Void> in
    let deliveryService = try container.make(EmailDeliveryService.self)
    return deliveryService.send(message, on: container)
}

The first step is to create the EmailTemplate for the email I want to send and render it. The from, to, and subject properties are Strings that will be passed through unchanged to the final email. The bodyTemplate is the base name for the Leaf templates that will be rendered in the render() method. WelcomeData is the Leaf context for the templates; it defines anything that the the Leaf template will need. I like to think of it as a view model. It takes a model object and transforms it into values that the view (i.e. the Leaf template) needs. In this example, the WelcomeEmail template needs an email verification link, so WelcomeData constructs that based on a token assumed to be on the User model. To render the EmailTemplate into something that can be sent, render() is called, passing in WelcomeData.

The second step is to send the resulting EmailMessage. The dependency injection framework is asked to produce a EmailDeliveryService object, which can send an EmailMessage. EmailDeliveryService is a protocol, meaning it can be swapped out later, without the client code knowing or caring. This enables testing fakes to be injected during tests, as well as making it possible to move to a new email service should I ever decide to do that.

That covers the Swift code for creating and sending the email. I still need to define the Leaf templates though. I want to send both plain text and HTML MIME parts in my email, so regardless of the user’s email app they’ll see something reasonable. Since the email body template parts are Leaf templates, I put them in the standard location: Resources/Views. I also follow a naming convention so EmailTemplate.render() can find them at runtime.

Here’s the contents of WelcomeEmail.html.leaf:


<html>
<head></head>
<body>
<p>Hello!</p>

<p>Welcome to MyApp!</p>

<p><a href="#(verifyLink)">Verify your email address</a></p>

<p>The MyApp Team.</p>
</body>
</html>

And the contents of WelcomeEmail.text.leaf:


Hello!

Welcome to MyApp!

Verify your email address by clicking on this link: #(verifyLink)

The MyApp Team.

Both templates represent the same email, but the content changes based on the format they’re being rendered into. The #(verifyLink) placeholder is filled in with value in WelcomeData.verifyLink.

Now that I’ve defined my target API, I can start building the implementation.

Rendering email with Leaf

First I need to define what an email message is, because it is the type everything else is dependent on. The EmailTemplate needs to render to it, and EmailDeliveryService needs to send it. I decided to define my own types for this because it reduces coupling on a specific service, plus it more accurately represents what my app thinks an email is. Also, the necessary types are pretty simple, so I did’t think they’d increase my maintenance burden any.

Here’s my definition:


struct EmailBody {
    let text: String
    let html: String
}

struct EmailMessage {
    let from: String
    let to: String
    let subject: String
    let body: EmailBody
}

My app’s idea of an email is simple. It has a from, to, subject, and body fields. The only thing that might look out of the ordinary is the the body has two parts: HTML and plain text. My app doesn’t care about attachments or other features, so they don’t show up here.

With email defined, I could create the EmailTemplate which takes care of rendering Leaf templates down to a EmailMessage. I started by defining the properties of the EmailTemplate:


import Vapor
import Leaf
import TemplateKit

struct EmailTemplate {
    private let from: String
    private let to: String
    private let subject: String
    private let bodyTemplate: String

    init(from: String, to: String, subject: String, bodyTemplate: String) {
        self.from = from
        self.to = to
        self.subject = subject
        self.bodyTemplate = bodyTemplate
    }
    ...
}

The template is the same as the EmailMessage with the exception of bodyTemplate, which is the base name of the Leaf templates for the email body. Most of the work of EmailTemplate is to convert the bodyTemplate into a EmailBody. The top level render method looks like:


struct EmailTemplate {
    ...
    private static let htmlExtension = ".html"
    private static let textExtension = ".text"

    func render<E>(_ context: E, on container: Container) -> Future<EmailMessage> where E: Encodable {
        let htmlRender = render(bodyTemplate + EmailTemplate.htmlExtension, context, on: container)
        let textRender = render(bodyTemplate + EmailTemplate.textExtension, context, on: container)
        return htmlRender.and(textRender)
            .map { EmailBody(text: $1, html: $0) }
            .map { EmailMessage(from: self.from, to: self.to, subject: self.subject, body: $0) }
    }
    ...
}

The render() method takes the Leaf template context and a dependency injection container, and returns the promise of an EmailMessage. The implementation relies on a helper render() method that renders one Leaf template at a time. This top level render() calls it twice: once for the plain text template, and once for the html template. It uses the and operator to let the template renders run concurrently if possible, then combines the results into an EmailBody, before a final map that mixes in the from, to, and subject fields.

The helper render() method is similarly straight forward:


enum EmailError: Error {
    case invalidStringEncoding
    case emailProviderNotConfigured
}
...
struct EmailTemplate {
    ...
    private func render<E>(_ name: String, _ context: E, on container: Container) -> Future<String> where E: Encodable {
        do {
            let leaf = try container.make(LeafRenderer.self)
            return leaf.render(name, context).map { view in
                guard let str = String(data: view.data, encoding: .utf8) else {
                    throw EmailError.invalidStringEncoding
                }
                return str
            }
        } catch let error {
            return container.future(error: error)
        }
    }
}

The helper method here takes the full Leaf template name, its context, a dependency injection container and returns a promise of String, which is the fully rendered body. To achieve this, it creates a LeafRenderer and asks it to render the template. This results in view data, which it decodes into a String and returns. If any error is thrown, it’ll convert it into a rejected promise for convenience.

The email template rendering is fairly simple, but creating the EmailTemplate type reduces the boilerplate code needed for sending an email.

Sending email

I now have a fully rendered email message, and I need to send it. As I mentioned up top, I’m used a 3rd party Swift package to actually talk to Mailgun’s API. However, I wanted an easy way to inject testing fakes, and the ability to swap out email services later if necessary. So I’m first going to show how I integrated the Swift Mailgun package, then how I abstracted it with a generic interface that can be faked.

Since it’s a Swift package, I added it to my Package.swift file:


    dependencies: [
        ...
        .package(url: "https://github.com/twof/VaporMailgunService.git", from: "1.1.0"),
        ...
    ],
    ...
    targets: [
        ...
        .target(name: "App", dependencies: [
            ...
            "Mailgun",
            ...
            ]),
        ...
    ]

Running vapor update from the command line pulled down the package and updated all my dependencies. I decided to use a Provider to set up the Mailgun package in my app:


import Vapor
import Mailgun

struct MailgunProvider: Provider {
    private let config: MailgunConfigurationType

    init(mailgunConfig: MailgunConfigurationType) {
        self.config = mailgunConfig
    }

    func register(_ services: inout Services) throws {
        services.register(Mailgun(apiKey: config.apiKey, domain: config.domain), as: EmailDeliveryService.self)
    }

    func didBoot(_ container: Container) throws -> EventLoopFuture<Void> {
        return .done(on: container)
    }
}

There’s not much to this. The only interesting bit is the register() implementation. It registers the Mailgun service from the Mailgun framework as the implementation for the EmailDeliveryService protocol. It uses apiKey and domain fields from the configuration passed in, which will come from the appropriate environment configuration. In my case, since I’m using Heroku, the production environment configuration will pull from the MAILGUN_API_KEY and MAILGUN_DOMAIN environment variables. Additionally, the production configuration will take care of registering this provider.

I decided to use a provider pattern for the sake of the testing configuration. The production provider here doesn’t really need to be a provider; it only registers one service. But since the testing configuration does make full use of the Provider protocol, I decided to make the production configuration follow suite.

Now that I had Mailgun in my app, I needed to put it behind a generic protocol so all the client code could be agnostic about the email service being used. I started by defining a simple protocol:


import Vapor

protocol EmailDeliveryService: Service {
    func send(_ message: EmailMessage, on container: Container) -> Future<Void>
}

An EmailDeliveryService is a Service (in the dependency injection sense) that implements a send() method. The send() method takes an EmailMessage and returns a Void promise, which can be used to know if the send succeeded or failed.

For the final bit of sending an email, I need to conform the Mailgun service to my generic EmailDeliveryService protocol:


import Vapor
import Mailgun

extension Mailgun: EmailDeliveryService {
    func send(_ message: EmailMessage, on container: Container) -> Future<Void> {
        do {
            let mailgunMessage = Mailgun.Message(
                from: message.from,
                to: message.to,
                subject: message.subject,
                text: message.body.text,
                html: message.body.html
            )

            return try self.send(mailgunMessage, on: container).transform(to: ())
        } catch let error {
            return container.future(error: error)
        }
    }
}

The implementation is intentionally as thin as possible. This is partly because it’s hard to test protocol extensions. If I had needed anything more complicated, I would have opted to wrap Mailgun in another type that conformed to EmailDeliveryService. In any case, this simply converts my EmailMessage type into Mailgun’s version and sends it. It also wraps any thrown errors into a rejected promise for the convenience of any calling code.

And, with that, my app is now sending email via Mailgun! But is it sending the correct emails? Well…

Testing

The goal of a couple of design decisions was to make the testing of emails possible, or at least easier. The choice of abstracting out the email service into a generic protocol means I can inject a testing fake. Making the email template rendering separate from the email sending means I can still test the template rendering, even if I swap out the email service with a fake.

For my integration testing, I didn’t actually want to send any emails to Mailgun. That means my tests aren’t full integration tests, and won’t catch a misconfigured Mailgun setup. But I didn’t want my integration tests dependent on an external, non-local service to run; that would make them too flaky. Plus I’d likely run into an Mailgun API quota pretty quick. However, even with this limitation, I was able to verify that the correct emails got sent at the correct time.

Like with building the initial email types, I prefer to start out with what a final test might look like. Here’s a simplified test from my app that validates a welcome email was sent:


func testCreate_emailShouldSend() throws {
    app.emailDeliveryService.send_stubbed?.succeed()
    ...
    // Do something that should send an email
    ...
    XCTAssertTrue(app.emailDeliveryService.send_wasCalled)
    XCTAssertEqual(app.emailDeliveryService.send_wasCalled_withMessage!.to, "bob.jimbob@example.com")
    XCTAssertEqual(app.emailDeliveryService.send_wasCalled_withMessage!.from, "donotreply@myapp.com")
    XCTAssertEqual(app.emailDeliveryService.send_wasCalled_withMessage!.subject, "Welcome to MyApp!")

    let link = "myapp://verify/\(user!.verifyToken)"
    XCTAssertTrue(app.emailDeliveryService.send_wasCalled_withMessage!.body.html.contains(link))
    XCTAssertTrue(app.emailDeliveryService.send_wasCalled_withMessage!.body.text.contains(link))
}

The first line tells the email service testing fake that the next call to send() should return success. Next the test calls into the app in a way that should send a welcome email (as represented by the comment). The final lines assert that send was called, and with the correct parameters. The test also validates that the most important piece of information — the verify link — appears in both the plain text and HTML parts of the email message. I didn’t do a full text comparison because most of the body is static content, and comparing all of it makes the test more fragile than it needs to be.

With this test written, I can work backwards and define what my email service testing fake should implement.


import Vapor
import Mailgun

final class FakeEmailDeliveryService: EmailDeliveryService {
    var send_wasCalled = false
    var send_wasCalled_withMessage: EmailMessage?
    var send_stubbed: Promise<Void>?
    func send(_ message: EmailMessage, on container: Container) -> Future<Void> {
        send_wasCalled = true
        send_wasCalled_withMessage = message
        return send_stubbed!.futureResult
    }
    ...
}

The testing fake, FakeEmailDeliveryService, records if send() was called along with the EmailMessage it was called with. It only keeps track of the last message because my tests only send one at a time. The fake also has the ability to return a stubbed value from send(). This is useful for validating what happens if there’s a failure on the email service’s end. The fake send() assumes that the stubbed promise has been allocated elsewhere before it’s invoked.

Speaking of allocating the stubbed promise, there’s a bit of cleanup that’s required because of the way Vapor’s promises work:


final class FakeEmailDeliveryService: EmailDeliveryService {
    ...
    deinit {
        // Vapor does not like a promise created but not resolved before it is destroyed. It calls them "leaked" and crashes the tests. So make sure nothing is "leaked" in our tests.
        send_stubbed?.succeed()
    }
}

As the comment states, Vapor will crash a test if there are any promises left unresolved. This happens in any of my tests that don’t exercise the email functionality of the app. I could go through all of those tests and add code to resolve the send_stubbed promise, but that’d be verbose and tedious. Instead, I opted to have deinit forcefully resolve the promise if it hasn’t already been.

The FakeEmailDeliveryService needs to be registered with the dependency injection system so that code asking for a EmailDeliveryService will get an instance of it. As with the production version of EmailDeliveryService, I used a Provider:


struct TestMailProvider: Provider {
    var emailDeliveryService = FakeEmailDeliveryService()

    func register(_ services: inout Services) throws {
        services.register(emailDeliveryService, as: EmailDeliveryService.self)
    }

    func didBoot(_ container: Container) throws -> EventLoopFuture<Void> {
        emailDeliveryService.send_stubbed = container.eventLoop.newPromise()
        return .done(on: container)
    }
}

The first thing the provider does is create the FakeEmailDeliveryService and stash in a public member variable. It does this so tests can get ahold of it and validate the send() parameters, or resolve its return value. The register() method then registers the fake as the implementation of EmailDeliveryService. The didBoot() method takes care of creating the unresolved promise for send()‘s stubbed return value. Creating promises require an event loop, and didBoot() is the earliest place in the test code that I had access to one. I chose to allocate the stubbed promise this early because it allowed tests to assume its existence during set up without worrying about race conditions.

With the registering of TestMailProvider all of testing fakes are set up and ready to be used. However, FakeEmailDeliveryService wasn’t yet accessible to the test cases, which were expecting it as a property on TestApplication called emailDeliveryService. The rest of this section is showing the plumbing of TestMailProvider.emailDeliveryService property up through to TestApplication.

I started at the TestingConfiguration level, which is where the TestMailProvider is created and registered:


struct TestingConfiguration: ConfigurationType {
    ...
    let mailProvider = TestMailProvider()

    func configure(_ services: inout Services) throws {
        try services.register(mailProvider)
    }
    ...
}

This exposes TestMailProvider on the TestConfiguration, which TestApplication can then use:


class TestApplication {
    ...
    private let configuration: TestingConfiguration
    ...
    var emailDeliveryService: FakeEmailDeliveryService {
        return configuration.mailProvider.emailDeliveryService
    }
    ...
}

And now my tests could validate emails by using the FakeEmailDeliveryService exposed on TestApplication.

Conclusion

My Vapor side project needed to send emails on user registration, which could potentially be a complicated setup. Since email isn’t a major feature of my app, it made sense to delegate sending emails out to a third party service like Mailgun. Although there’s a convenient Mailgun Swift package, I still needed to build out infrastructure for rendering emails from Leaf templates and abstracting out the emailing sending so I can test my app’s email handling.

Safe from the Losing Fight

Reading and writing files in Swift async/await

The synchronous way

Option 1: side step the issue via memory mapping

Option 2: use URLSession

Option 3: wrap up FileHandle

Option 4: DispatchIO

A slight diversion about said compiler bug

Creating an instance

Cleaning up safely

Reading

Writing

Some Data convenience

Conclusion

Swift async/await: do you even need a queue?

An example of my broken thinking

A concurrency limiter

Conclusion

Modeling condition variables in Swift async/await

Refining the problem scope

Classic approach

Implementation

Conclusion

Updating NativeMarkKit for SwiftUI and iOS 14

Introducing NativeMarkKit, native Markdown rendering

UIViewRepresentable doesn't respect intrinsicContentSize invalidation

Problem summary

Investigation

Results

Moment of Zen

Sharing HTTP API bindings between Swift Vapor and iOS/macOS apps

What can be shared

Structure and naming in the shared component

How to share

Refactoring the Swift Vapor app

Refactoring the Cocoa/CocoaTouch app

Conclusion

Handling periodic tasks in Swift Vapor

A periodic example

JobQueue Decisions

Implementing JobQueue

Testing

Conclusion

Building a declarative router for Swift Vapor

Goals

All routes in one file

Hierarchical declaration

Re-usability of controllers

Use higher level concepts

The Results

Interesting Implementation Bits

Verbosity reduction

Resource reflection

Dependency injection woes

Testing difficulties

Conclusion

Sending email from Swift Vapor

Example use

Rendering email with Leaf

Sending email

Testing

Conclusion