URL Routing on macOS

Most iOS developers have probably dealt with URL schemes and URL routing at some point during their career. This topic became even more important after the introduction of deep linking in iOS 9. Today we’re going to take a look at how this works on the Mac and create a small URL routing library.

The iOS-way

If you’re familiar with URL schemes on iOS, skip to the next section. If you’re not, this is a brief overview of how it works:

You register a unique URL scheme for your app using the Info.plist file. Let’s call it

. If another application or website opens an URL with your scheme, e.g. , iOS either launches your application or brings it into foreground and notifies your application’s delegate by calling the following method:

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool

From there on it’s up to you to handle the received URL. You could parse the URL yourself or use one of the countless URL routing libraries that emerged during the years, my favorite being JLRoutes.

Back to the Mac

The Mac is a much older platform with tons of legacy APIs. Registering schemes works just like it does on iOS using the Info.plist, but receiving URLs is tricky. When I first took a look at this, I just assumed

would handle opened URLs, similar to iOS. That couldn’t have been farther from the truth.

After a quick StackOverflow search, I knew

is what I need. Now, what is you ask?

In case you want to know more about this, you can read about Apple Events in Cocoa here. This article just covers what we need to know in order to route URLs on macOS.

allows you to register one object (called handler later on), that implements a certain method, to receive events that are of a certain class and have a specific identifier. In our case the class is , which is a constant of the type , and the identifier is , a constant of the type AEEventID. The method signature we need in order to receive events must be equivalent to this:

func handleEvent(_ event: NSAppleEventDescriptor, with replyEvent: NSAppleEventDescriptor)

Notice that we receive events as

objects. is a nested type which stores other instances of as parameters, each one associated with a keyword. The URLs our application receives will be wrapped in a descriptor, which itself is stored inside the main event descriptor, and can be accessed using the keyword, a constant of the type .

let keyword = AEKeyword(keyDirectObject)
let urlDescriptor = event.paramDescriptor(forKeyword: keyword)
let urlString = urlDescriptor?.stringValue

Now that we know how to receive URLs, it’s time to create a class which is able to receive URLs and actually handle them. A

.

Swift, but…

While all the code is going to be written in Swift, the majority of my macOS projects are still Objective-C. Thus the Swift code I’m presenting here is intended to be compatible with Objective-C. We will not only use classes, as Swift structs are not compatible with Objective-C, but they will also all inherit from

. The code, however, doesn’t depend on or reference types. You could easily convert the code to use value types (to a certain extent) and Swift classes.

Router

The

will receive events, extract URLs from them and take appropriate actions depending on the content of the URLs.

public class Router: NSObject {
    
    public static let global = Router()
    
    public override init() {
        super.init()
        NSAppleEventManager.shared().setEventHandler(self, andSelector: #selector(handleEvent(_:with:)), forEventClass: AEEventClass(kInternetEventClass), andEventID: AEEventID(kAEGetURL))
    }
    
    deinit {
        NSAppleEventManager.shared().removeEventHandler(forEventClass: AEEventClass(kInternetEventClass), andEventID: AEEventID(kAEGetURL))
    }
  
    @objc
    private func handleEvent(_ event: NSAppleEventDescriptor, with replyEvent: NSAppleEventDescriptor) {
        guard let urlString = event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))?.stringValue else { return }
        guard let url = URL(string: urlString) else { return }
        print(url)
    }
  
}

This is the first implementation of our

class. Instances of this class will register themselves as handler for URL (that’s what I’m going to refer to from now on when talking about the combination of and ) during instantiation and unregister during deallocation. Incoming events will be handled, the URL will be extracted and printed to the console. So far so good!

Remember how I mentioned earlier that there can only be one handler per class/identifier combination? If we created two

instances, the second instance would replace the first one as handler for URL events. Going further, if the first instance got deallocated before the second instance, the first instance would actually unregister the second instance as handler and no one would receive URL events anymore. We’re going to solve this later on, for now we’ll only access the shared instance to avoid this.

Now, what should our URL routing actually look like? We want to run a certain

— a simple closure — when we receive an URL that matches a specified pattern — consisting of of a and a . We’re going to encapsulate this association of an action with a pattern in a separate class and call it .

RouteHandler

In order to match URLs, we’re going to need a

and a . The scheme used to open the app might be unimportant, so we’ll just make it optional and match any scheme if there’s none specified.

But hold on, what’s a

? You only mentioned a

path

earlier!

Imagine a

to be a pattern of a path. We need patterns for two things: placeholders and wildcards.

Placeholders

Let’s say you’re creating a social network app and want to add a route to view user profiles. Instead of registering paths for every user, which would be virtually impossible, you just register a route with a placeholder:

. When receiving an URL for this route, whatever is in place of the path component will be used as the parameter.

Wildcards

It’s possible you want to allow an unknown number of path components at the end of an URL because you’re not aware of all possible paths beforehand. In this case, you register a route with a wildcard at the end:

. In this case, only the first three path components need to be matched while the remaining components can be ignored.

I previously mentioned I’m using JLRoutes on iOS. For our Mac library, I’m going to shamelessly copy Joel’s idea of having priorities. The idea behind priorities is pretty self-explanatory, so I’m just going to leave you with an implementation of the concepts described above:

public typealias RouteHandlerAction = (URL) -> Bool
public typealias RouteHandlerID = Int

open class RouteHandler: NSObject {
    
    public let route: String
    public let scheme: String?
    public let priority: Int
    public let action: RouteHandlerAction
    
    var id: RouteHandlerID
    
    public required init(route: String, scheme: String?, priority: Int, action: @escaping RouteHandlerAction) {
        self.route = route
        self.scheme = scheme
        self.priority = priority
        self.action = action
        self.id = -1
        super.init()
    }
    
    @available(*, unavailable)
    public override init() {
        fatalError()
    }
  
    public func handle(url: URL) -> Bool {
        if let scheme = self.scheme {
            guard scheme == url.scheme else { return false }
        }
        // … route matching
        
        return self.action(url)
    }
  
}

After making the default initializer unavailable, we provide a new designated initializer that allows us to set all required properties.

will first check if an URL can be handled by the handler and then do so in case of a match. The returned boolean lets the caller, which is going to be our , know, whether the URL was handled successfully or not.

RouteHandlerID

Yeah, I kind of sneaked this into my code. We’re going to use handler IDs later so users can identify handlers without storing them.

Back to the Router

Our

class will act as a storage and manager for objects.

public class Router: NSObject {
    // …
    private(set) var handlers: [RouteHandlerID: RouteHandler] = [:]
    private var currentHandlerIndex = -1 
  
    @discardableResult
    public func register(_ handler: RouteHandler) -> RouteHandlerID {
        self.currentHandlerIndex += 1
        let id = self.currentHandlerIndex
        self.handlers[id] = handler
        handler.id = id
        
        return id
    }
    // …
}

We’ll store handlers in a simple dictionary and use their IDs as keys. Later on, this will allow us to unregister handlers super fast if we know their IDs. If you imagined some super fancy calculation happening to create IDs you were wrong — it’s as boring as it can get, an increasing integer.

Registering a handler using our current implementation looks like this:

let handler = RouteHandler(route: "/", scheme: nil, priority: 0) { url in
    return true
}
Router.global.register(handler)

A bit cumbersome, right? We’re not even using default parameters! Let’s solve this by adding two convenience methods to our

:

public class Router: NSObject {
    // …
    @discardableResult
    public func register(_ route: String, for scheme: String? = nil, priority: Int = 0, action: @escaping RouteHandlerAction) -> RouteHandlerID {
        return self.register(RouteHandler(route: route, scheme: scheme, priority: priority, action: action))
    }
  
    @discardableResult
    public func register(_ routes: [String], for scheme: String? = nil, priority: Int = 0, action: @escaping RouteHandlerAction) -> [RouteHandlerID] {
        return routes.map { self.register($0, for: scheme, priority: priority, action: action) }
    }
    // …
}

With this in place, registration will be much cleaner:

Router.global.register("/") { url in
    return true
}
Router.global.register(["/entrance", "/backdoor"], for: "secret") { url in
    return true
}

The first example, just like the one above, will match any route at its root:

, … With the second example we can even match two routes for a specific scheme: and .

Now we got our fancy registration and everything set up, but none of our handlers will ever be called. To do so, we need to first sort all registered handlers by their priority in a descending order and then give each handler a chance to handle the URL:

public class Router: NSObject {
    // …
    @objc
    private func handleEvent(_ event: NSAppleEventDescriptor, with replyEvent: NSAppleEventDescriptor) {
        guard let urlString = event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))?.stringValue else { return }
        guard let url = URL(string: urlString) else { return }
        
        let handlers = self.handlers.sorted {
            return ($0.1.priority > $1.1.priority)
        }
        for (_, handler) in handlers {
            guard handler.handle(url: url) else { continue }
            break
        }
    }
    // …
}

When sorting a dictionary, the result will be an array of tuples, each consisting of the key and value of an entry. In our concrete case, the return type is

. This forces us to use the syntax you see in the code snippet above. While we could use to get an array of handlers as opposed to an array of tuples, this would add an unnecessary loop.

After sorting our handlers, we iterate through them and let each handler try to handle the URL. As soon as we find a matching handler, we break the loop. The only issue now is that we don’t actually perform any URL parsing or route matching yet. If you look closely at the current code of our

class, you see we’re only matching the scheme but don’t look at the contents of the URL before passing it to our . With the current implementation, the first handler matching a certain scheme will be called and the route will be completely ignored.

To match routes with URLs, we need to parse incoming URLs and compare their components with the components of all routes. If we performed the parsing of the received URL inside our

class, we’d do the same work each time we call on a object. To avoid this unnecessary repetition, we’re going to move all the work we can do beforehand into a separate class.

RoutingRequest

objects can be instantiated using a . The initializer is failable due to the fact that the object could be formatted in a way unsuitable for our purposes. The class is going to handle the very basic parsing and validation for us, we then only save the properties which we later need to match routes.

public final class RoutingRequest: NSObject, NSCopying {
    
    public let url: URL
    public let scheme: String
    public private(set) var parameters: [String: String?]?
    public private(set) var wildcardComponents: URLComponents?
    
    let pathComponents: [String]
    let queryItems: [URLQueryItem]?
  
    public init?(url: URL) {
        guard var components = URLComponents(url: url, resolvingAgainstBaseURL: true) else { return nil }
        self.url = url
        
        guard let scheme = components.scheme else { return nil }
        self.scheme = scheme
        
        components.moveHostToPath()
        self.pathComponents = components.pathComponents
        self.queryItems = components.queryItems
        
        super.init()
    }
    // …
}

If you’re familiar with the

class, you probably noticed our initializer is using methods or properties not supplied by the standard library. The code is using a small extension on which you’ll find along with the full implementation of the library on GitHub. The final implementation will also provide some options to control the URL parsing.

The

and properties are not set during instantiation as they depend on the of the object. Matching a with the of a will be called fulfillment, as the request is incomplete before being matched with a route.

public final class RoutingRequest: NSObject, NSCopying {
    // …
    func fulfill(with route: String) -> Bool {
        var parameters = [String: String?]()
        
        for (index, component) in self.pathComponents.enumerated() {
            // route parsing …
        }
      
        if let queryItems = self.queryItems {
            for item in queryItems {
                parameters[item.name] = (item.value?.characters.count != 0) ? item.value : nil
            }
        }
        
        if parameters.count != 0 {
            self.parameters = parameters
        }
        
        return true
    }
    // …
}

The

method takes a route as parameter and returns a boolean which indicates whether the request could be fulfilled using the given route or not. We also append the we extracted during the instantiation to the so users only need to deal with a single dictionary. If you read carefully, you might’ve already discovered that is an internal property anyway, so this implementation detail will not be exposed to the user of the library. What’s still missing here is the actual route parsing. Let’s recap what it will look like using the following example:

let url = URL(string: "scheme://view/someuser?referrer=otheruser")!
let request = RoutingRequest(url: url)!
_ = request.fulfill(with: "/view/:user")

This means we need to split the given route into its components, separated by a

. Each component can be one of three things:

Doesn’t this practically scream Enumeration?

RouteComponent

enum RouteComponent {
    case path(String)
    case placeholder(String)
    case wildcard
}

The

type can not be exposed to Objective-C, but that’s okay because we’re only going to use it internally. The names of placeholder and path components will be stored using associated values. In terms of parsing, we only allow wildcards at the end of a route and when we encounter a placeholder, we need to strip off the leading before saving the name.

enum RouteComponent {
    // …
    static func components(of route: String) -> [RouteComponent] {
        let pathComponents = route.pathComponents
        var components = [RouteComponent]()
        
        for (index, component) in pathComponents.enumerated() {
            if component == "*", index == pathComponents.count-1 {
                components.append(.wildcard)
                break
            }
            
            if component.characters.first == ":" {
                let parameterName = String(component.characters.dropFirst())
                components.append(.placeholder(parameterName))
                continue
            }
            
            components.append(.path(component))
        }
        
        return components
    }

}

Now that we have our route parsing in place, we need to actually make use of it! To avoid unnecessary work, we should do this as soon as possible. Let’s refactor and parse our routes when instantiating our

objects:

open class RouteHandler: NSObject {
    // …
    let routeComponents: [RouteComponent]
  
    public required init(route: String, scheme: String?, priority: Int, action: @escaping RouteHandlerAction) {
        // …
        self.routeComponents = RouteComponent.components(of: route)
        super.init()
    }
    // …
}

Back to the

. Fulfilling a request looks really straightforward when using our type instead of a plain string:

public final class RoutingRequest: NSObject, NSCopying {
    // …
    func fulfill(with routeComponents: [RouteComponent]) -> Bool {
        var parameters = [String: String?]()
        var remainingRouteComponents = routeComponents
        
        pathLoop: for (index, component) in self.pathComponents.enumerated() {
            guard routeComponents.count >= index+1 else { return false }
            let routeComponent = routeComponents[index]
            remainingRouteComponents.remove(at: 0)
            
            switch routeComponent {
            case .path(let name):
                guard name == component else { return false }
            case .placeholder(let name):
                parameters[name] = component
            case .wildcard:
                let remainingPath = self.pathComponents[index...self.pathComponents.endIndex-1].joined(separator: "/")
                self.wildcardComponents = URLComponents(string: remainingPath)
                break pathLoop
            }
        }
        
        if remainingRouteComponents.count > 0 {
            guard remainingRouteComponents.count == 1, case .wildcard = remainingRouteComponents[0] else { return false }
        }
        // …
    }
    // …
}

We iterate through all path components of our URL. First, we need to make sure a route component exists at the index of our current path component. If there are more path components than route components, we fail (wildcards are an exception, we’ll get there in a second).

Using the

array we keep track of the route components we didn’t match yet. During each iteration we remove the first remaining route component.

A

component is the easiest to handle. We simply check if the name of the route component is equal to the path component. If it’s not, we fail immediately.

components don’t require any matching, we only need to save the path component as a parameter with the name of the placeholder as the key.

Matching a

is probably the trickiest case. First of all, we get the remaining path components using a range starting with our current and ending with the of our array. To create a string from this subset of components — an array of strings — we join them with as separator. We assign a new object to the wildcardComponents property to make it easier for the user to access e.g. the path of the matched wildcard. Lastly we make use of a somewhat lesser known feature in Swift: Labeled Statements. After matching a wildcard, we don’t need to — and can’t, as line 8 would make the fulfillment fail immediately— continue the loop. But if we just called , this would only affect the switch statement and not our loop. Thus we label the loop as and tell Swift to break it using .

Hold on, the matching isn’t done yet! We’re not handling the case of having more route components than path components. That’s where the

array comes into play. If there are any unmatched components, that’s generally a bad sign, with the exception of a single leftover . A indicates that the remainder doesn’t matter. In this specific case, the remainder is empty, which is just fine.

Making Requests

The first implementation of

used objects because the type didn’t exist yet. Time to refactor!

public typealias RouteHandlerAction = (RoutingRequest) -> Bool
// …
open class RouteHandler: NSObject {
    // …
    public func handle(request: RoutingRequest) -> Bool {
        if let scheme = self.scheme {
            guard scheme == request.scheme else { return false }
        }
        let request = request.copy() as! RoutingRequest
        guard request.fulfill(with: self.routeComponents) else { return false }
        
        return self.action(request)
    }
  
}

After matching the scheme, we make a copy of the request object. We need to do this because calling

on a request object can mutate its state, but the request passed to by the could be reused with another handler. This way, we don’t mutate the request object used by the and it can be reused safely. In order for this to work, needs to implement . We could avoid this by using value types, but they would remove the Objective-C compatibility.

If the request is fulfilled we pass it to our

, otherwise we fail.

The

class will be the next target of our refactoring. First, we extract the actual routing into its own method. This doesn’t only make the code cleaner, but it will also allow users of the library to route URLs manually without making a round trip to the system. We also add two convenience methods which can be called with just a raw URL.

public class Router: NSObject {
    // …
    @discardableResult
    public func route(request: RoutingRequest) -> Bool {
        let handlers = self.handlers.sorted {
            return ($0.1.priority > $1.1.priority)
        }
        for (_, handler) in handlers {
            guard handler.handle(request: request) else { continue }
            return true
        }
        
        return false
    }
  
    @discardableResult
    public func route(urlString: String) -> Bool {
        guard let request = RoutingRequest(string: urlString) else { return false }
        return self.route(request: request)
    }
  
    @discardableResult
    public func route(url: URL) -> Bool {
        guard let request = RoutingRequest(url: url) else { return false }
        return self.route(request: request)
    }
    // …
}

The

methods also looks much cleaner after adopting the convenience method:

public class Router: NSObject {
    // …
    @objc
    private func handleEvent(_ event: NSAppleEventDescriptor, with replyEvent: NSAppleEventDescriptor) {
        guard let urlString = event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))?.stringValue else { return }
        self.route(urlString: urlString)
    }
    // …
}

Looks good! We’re almost done, but…

We still can’t use multiple router instances at the same time! The easiest solution would be to make the initializer of

private, so no one, except the class itself, can create instances, which would force everyone to use the shared instance . It’s not my intention to start the whole singleton-debate now, but I believe there’s a better solution than this.

Due to this restriction of having only one handler for URL events, we will eventually need to introduce a singleton. However, we can refactor the event handling into a separate class and have a singleton there instead of in the

class.

URLEventHandler

The

class will, as the name suggests, handle URL events. We’re going to apply the solution mentioned above here and make the initializer private, so the only object that can ever be instantiated is the singleton.

public final class URLEventHandler: NSObject {
    
    public static let global = URLEventHandler()
    
    private override init() {
        super.init()
        NSAppleEventManager.shared().setEventHandler(self, andSelector: #selector(handleEvent(_:with:)), forEventClass: AEEventClass(kInternetEventClass), andEventID: AEEventID(kAEGetURL))
    }
    
    deinit {
        NSAppleEventManager.shared().removeEventHandler(forEventClass: AEEventClass(kInternetEventClass), andEventID: AEEventID(kAEGetURL))
    }
  
}

Objects which the

class notifies about URL events will be called listeners. Those listeners will need to adapt the protocol.

public protocol URLEventListener: class {
    func handleURL(_ url: String)
}

Types that implement the

protocol will need to be classes because we want to keep weak references to our listeners. Storing weak references inside an array isn’t supported out of the box, so we need a small helper:

private struct WeakObject<T: AnyObject> {
    private(set) weak var object: T?
    
    init(object: T) {
        self.object = object
    }
}

Instead of storing our listeners directly, we wrap them inside a

instance and store an array of those in our class:

public final class URLEventHandler: NSObject {
    // …
    private var listeners = [WeakObject<URLEventListener>]()
  
    public func addListener(_ listener: URLEventListener) {
        self.listeners.append(WeakObject(object: listener))
    }
    
    @discardableResult
    public func removeListener(_ listener: URLEventListener) -> Bool {
        guard let index = self.listeners.index(where: { $0.object === listener }) else { return false }
        self.listeners.remove(at: index)
        
        return true
    }
  
}

Handling URL events pretty much looks like it did originally in the

class, except we now need to notify each listener.

public final class URLEventHandler: NSObject {
    // …
    @objc
    private func handleEvent(_ event: NSAppleEventDescriptor, with replyEvent: NSAppleEventDescriptor) {
        guard let urlString = event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))?.stringValue else { return }
        for listener in self.listeners {
            listener.object?.handleURL(urlString)
        }
    }
    // …
}

Speaking of the

class, it still needs to adopt our new URL event handling.

public class Router: NSObject, URLEventListener {
    // …
    public override init() {
        super.init()
        URLEventHandler.global.addListener(self)
    }
    
    deinit {
        URLEventHandler.global.removeListener(self)
    }
  
    public func handleURL(_ url: String) {
        self.route(urlString: url)
    }
    // …
}

Now we can use multiple

instances at once without them interfering with each other.

About Testing

This is a small library and 33 tests were enough to achieve this test coverage. There are a couple of edges cases which aren’t being covered by the tests as of the time of writing.

Testing is boring and there’s nothing spectacular here either…except for this one thing: how do you test

?

I wouldn’t know how to create a mock application that receives URL events by the system (possibly using

?) and I’m afraid the overhead wouldn’t be feasible. As it turns out, we don’t need to worry about that because we can send events to manually!

I encountered this charming method while looking at the documentation:

func dispatchRawAppleEvent(UnsafePointer<AppleEvent>, withRawReply: UnsafeMutablePointer<AppleEvent>, handlerRefCon: SRefCon)

The mysterious

type is part of a typealias jungle that ultimately leads to ( → → → ). needs pointers to objects, which are C structs. To create these structs we need to use even more C pointers and deal with other fun methods like .

Luckily

provides a property, , that returns a pointer to an object. This means we only need to deal with and it will do the heavy lifting to create its C counterparts.

var url = …
let urlDescriptor = NSAppleEventDescriptor(applicationURL: url)
let event = NSAppleEventDescriptor(eventClass: AEEventClass(kInternetEventClass), eventID: AEEventID(kAEGetURL), targetDescriptor: nil, returnID: AEReturnID(kAutoGenerateReturnID), transactionID: AETransactionID(kAnyTransactionID))
event.setParam(urlDescriptor, forKeyword: keyDirectObject)
NSAppleEventManager.shared().dispatchRawAppleEvent(event.aeDesc!, withRawReply: UnsafeMutablePointer(mutating: NSAppleEventDescriptor.null().aeDesc!), handlerRefCon: &url)

Now we can test that

and work together 🎉

Final Words

I left out some small details which I didn’t find noteworthy (e.g. how the

deals with handler unregistration). The full source code is available on GitHub.

This was my first time writing about a technical topic, I appreciate all feedback whether it’s about my style of writing or my code.