This article is also available in Chinese.
Part of the promise of Swift is the ability to write simple, correct, and expressive code. Swift’s error system is no exception, and clever usage of it vastly improves the code on the server. Our app Beacon uses Vapor for its API. Vapor provides a lot of the fundamental components to building an API, but more importantly, it provides the extension points for adding things like good error handling yourself.
The crucial fact is that pretty much every function in your server app is marked as throws. At any point, you can throw an error, and that error will bubble all the way through any functions, through the response handler that you registered with the router, and through any registered middlewares.
Vapor typically handles errors by loading an HTML error page. Because the Beacon’s server component is a JSON API, we need some middleware that will translate an AbortError (Vapor’s error type, which includes a message and a status code) into usable JSON for the consumer. This middleware is pretty boilerplate-y, so I’ll drop it here without much comment.
public final class JSONErrorMiddleware: Middleware {
public func respond(to request: Request, chainingTo next: Responder) throws -> Response {
do {
return try next.respond(to: request)
} catch let error as AbortError {
let response = Response(status: error.status)
response.json = try JSON(node: [
"error": true,
"message": error.message,
"code": error.code,
"metadata": error.metadata,
])
return response
}
}
}
In Vapor 1.5, you activate this middleware by adding it to the droplet, which is an object that represents your app.
droplet.middleware.append(JSONErrorMiddleware())
Now that we have a way to present errors, we can start exploring some useful errors. Most of the time when something on the server fails, that failure is represented by a nil where there shouldn’t be one. So, the very first thing I added was the unwrap() function:
struct NilError: Error { }
extension Optional {
func unwrap() throws -> Wrapped {
guard let result = self else { throw NilError() }
return result
}
}
This function enables you to completely fail the request whenever a value is nil and you don’t want it to be. For example, let’s say you want to find an Event by some id.
let event = Event.find(id)
Unsurprisingly, the type of event is Optional<Event>. Because an event with the given ID might not exist when you call that function, it has to return an optional. However, sometimes this doesn’t make for the best code. For example, in Beacon, if you try to attend an event, there’s no meaningful work we can do if that event doesn’t exist. So, to handle this case, I call unwrap() on the value returned from that function:
let event = Event.find(id).unwrap()
The type of event is now Event, and if the event doesn’t exist, function will end early, and bubble the error up until it hits the aforementioned JSONErrorMiddleware, ultimately resulting in error JSON for our user.
The problem with unwrap() is that it lacks any context. What failed to unwrap? If this were Ruby or Java, we’d at least have a stack trace and we could figure out what series of function calls led to our error. This is Swift, however, and we don’t have that. The most we can really do is capture the file and line of the faulty unwrap, which I’ve done in this version of NilError.
In addition, because there’s no context, Vapor doesn’t have a way to figure out what status code to use. You’ll notice that our JSONErrorMiddleware pattern matches on the AbortError protocol only. What happens to other errors? They’re wrapped in AbortError conformant-objects, but the status code is assumed to be 500. This isn’t ideal. While unwrap() works great for quickly getting stuff going, it quickly begins to fall apart once your clients start expecting correct status codes and useful error messages. To this end, we’ll be exploring a few useful custom errors that we built for this project.
Missing Resources
Let’s tackle our missing object first. This request should probably 404, especially if our ID comes from a URL parameter. Making errors in Swift is really easy:
struct ModelNotFoundError: AbortError {
let status = Status.notFound
var code: Int {
return status.statusCode
}
let message: String
public init<T>(type: T) {
self.message = "\(typeName) could not be found."
}
}
In future examples, I’ll leave out the computed code property, since that will always just forward the statusCode of the status.
Once we have our ModelNotFoundError, we can guard and throw with it.
guard let event = Event.find(id) else {
throw ModelNotFoundError(type: Event)
}
But this is kind of annoying to do every time we want to ensure that a model is found. To solve that, we package this code up into an extension on every Entity:
extension Entity {
static func findOr404(_ id: Node) throws -> Self {
guard let result = self.find(id) else {
throw ModelNotFoundError(type: Self.self)
}
return result
}
}
And now, at the call site, our code is simple and nice:
let event = try Event.findOr404(id)
Leveraging native errors on the server yields both more correctness (in status codes and accurate messages) and more expressiveness.
Authentication
Our API and others use require authenticating the user so that some action can be performed on their behalf. To execute this cleanly, we use a middleware to fetch to the user from some auth token that the client passes us, and save that user data into the request object. (Vapor includes a handy dictionary on each Request called storage that you can use to store any additional data of your own.) (Also, Vapor includes some authentication and session handling components, but it was easier to write this than to try to figure out how to use Vapor’s built-in thing.)
final class CurrentSession {
init(user: User? = nil) {
self.user = user
}
var user: User?
@discardableResult
public func ensureUser() throws -> User {
return user.unwrap()
}
}
Every request will provide a Session object like the one above. If you want to ensure that a user has been authenticated (and want to work with that user), you can call:
let currentUser = try request.session.ensureUser()
However, this has the same problem as our previous code. If the user isn’t correctly authed, the consumer of this API will see a 500 with a meaningless error about nil objects, instead of a 401 Unauthorized code and a nice error message. We’re going to need another custom error.
struct AuthorizationError: AbortError {
let status = Status.unauthorized
var message = "Invalid credentials."
}
Vapor actually has a shorthand for this kind of simple error:
Abort.custom(status: .unauthorized, message: "Invalid credentials.")
Which I used until I needed the error to be its own object, for reasons that will become apparent later.
Our function ensureUser() now becomes:
@discardableResult
public func ensureUser() throws -> User {
guard let user = user else {
throw AuthorizationError()
}
return user
}
Bad JSON
Vapor’s JSON handling leaves much to be desired. Let’s say you want a string from the JSON body that’s keyed under the name “title”. Look at all these question marks:
let title = request.json?["title"]?.string
At the end of this chain, of course, title is an Optional<String>. Even throwing an unwrap() at the end of this chain doesn’t solve our problem: because of Swift’s optional chaining precedence rules, it will only unwrap the last component of the chain, .string. We can solve this in two ways. First, by wrapping the whole expression in parentheses:
let title = try (request.json?["title"]?.string).unwrap()
or unwrapping at each step:
let title = try request.json.unwrap()["title"].unwrap().string.unwrap()
Needless to say, this is horrible. Each unwrap represents a different error: the first represents a missing application/json Content-Type (or malformed data), the second, the absence of the key, and the third, the expectation of the key’s type. All that data is thrown away with unwrap(). Ideally, our API would have a different error message for each error.
enum JSONError: AbortError {
var status: Status {
return .badRequest
}
case jsonMissing
case missingKey(keyName: String)
case typeMismatch(keyName: String, expectedType: String, actualType: String)
}
These cases represent the three different errors from above. We need to add a function to generate a message depending on the case, but that’s really all this need. We have errors that are a lot more expressive, and ones that help the client debug common errors (like forgetting a Content-Type).
These errors, combined with NiceJSON (which you can read more about it in this post), result in code like this:
let title: String = try request.niceJSON.fetch("title")
Much easier on the eyes. title is also usually an instance variable (of a command) with a pre-set type, so the : String required for type inference can be omitted as well.
By making the “correct way” to write code the same as the “nice way” to write code, you never have to make a painful trade-off between helpful error messages or type safety, and short easy-to-read code.
Externally Visible Errors
By default, Vapor will wrap an error that fails into an AbortError. However, many (most!) errors reveal implementation details that users shouldn’t see. For example, the PostgreSQL adapter’s errors reveal details about your choice of database and the structure of your tables. Even NilError includes the file and line of the error, which reveals that the server is built on Swift and is therefore vulnerable to attacks targeted at Swift.
In order to hide some errors and allow others to make it through the user, I made a new protocol.
public protocol ExternallyVisibleError: Error {
var status: Status { get }
var externalMessage: String { get }
}
Notice that ExternallyVisibleError doesn’t inherit from AbortError. Once you conform your AbortError to this protocol, you have to provide one more property, externalMessage, which is the message that will be shown to users.
Once that’s done, we need a quick modification to our JSONErrorMiddleware to hide the details of the error if it’s not an ExternallyVisibleError:
public func respond(to request: Request, chainingTo next: Responder) throws -> Response {
do {
return try next.respond(to: request)
} catch let error as ExternallyVisibleError {
let response = Response(status: error.status)
response.json = try JSON(node: [
"error": true,
"message": error.externalMessage,
"code": error.status.statusCode,
])
return response
} catch let error as AbortError {
let response = Response(status: error.status)
response.json = try JSON(node: [
"error": true,
"message": "There was an error processing this request.",
"code": error.code,
])
return response
}
}
I also added some code that would send down the AbortError’s message as long as the environment wasn’t .production.
Swift’s errors are a powerful tool that can store additional data, metadata, and types. A few simple extensions to Vapor’s built-in types will enable you to write better code along a number of axes. For me, the ability to write terse, expressive, and correct code is the promise that Swift offered from the beginning, and this compact is maintained on the server as much as it is on the client.
