Shipmind Labs

The bug report was one sentence: "the link in the email opens the home screen."

It did. For about four percent of the sends, which happens to be the share of traffic that lets a problem survive a release.

The parser was fine. It read the incoming URL, matched the route, pulled the identifier, handed it to the screen. We had tested that path for years.

The builder was where it broke. Somewhere else in the codebase, someone had written the outbound URL by hand, string concatenation, a template, a helper with a hardcoded path prefix. It was correct on the day it was written. Then a route gained a segment, the parser was updated, and the builder was not. Nobody caught it, because nothing connects a format string to a parser except a developer remembering they both exist.

We fixed it the way you fix things at midnight: patched the template. Then we went looking for how many other places built a link by hand. Enough that "audit the links" turned into its own ticket.

What we do differently now shows up in our open-source project deeplinkmap, where the router has one table and two methods against it. One resolves an incoming link. One builds an outbound link. Same table. They cannot disagree, because there is nothing to disagree with.

The part that mattered more than the symmetry was teaching the builder to refuse.

Ask for a route name that is not in the table and it throws instead of returning something plausible. Ask for a link form the route does not accept and it throws, and the error names the form so you can read it. Give it no form and it picks the first one it can actually address (universal link before custom scheme, scheme before insecure) instead of defaulting to whatever is cheapest. If it has no real host or scheme to put in front of the path, it throws rather than hand back an address the app may not own, which is the failure mode where your link opens a stranger's site.

Every placeholder in a route needs a value present on the params object, and the value gets validated against the same rule the parser enforces on the way in, and it gets URL-encoded. A params key that matches no placeholder is refused. So is a query key the route never declared. Validation failures print the key, and for anything the route marks as a secret the value prints as a mask, because a crash log is still a log.

That last part probably sounds strict until you have debugged a bad link in a sent email. There is no retry. The message is out.

For anyone running deep links at scale: the thing worth checking is where your outbound URLs get built, and whether that code shares a source of truth with the code that reads them.

Was this useful?

Building something similar?

or email hello@shipmindlabs.com