Throwable::X: common behavior for thrown exceptions

When I first wrote about Test::Routine, I said it was a way of building a replacement for Test::Class that relied on Moose for all of its class composition. I compared it to replacing Exception::Class with Throwable, which let me get rid of a lot of features that were oriented toward building classes, and which were different from and inferior to those provided by Moose.

The thing you find out when you strip Exception::Class of all its sugar for building classes is that there isn’t much else there. Throwable does nearly nothing; it mostly just gives you a throw method that calls new and passes the result to die. Throwable also ships with StackTrace::Auto, which captures a stack trace reflecting that stack at the point where your object was created, which is also useful. Still, there are a number of things I wanted to get out of an exception that were specifically features for exceptions, not just general purpose class construction things like adding attributes.

We sat down one day to talk about the things we needed from our exceptions, both looking back at shortcomings in our existing exceptions and at features we knew we would want based on planned future work. We hashed out a basic design, and now I’ve put together a basic implementation, available on the CPAN, for review and improvement. Throwable::X is a combination of roles providing solutions for common problems in handling exceptions.

Identifying

We wanted to be able to know what exception we’d encountered, when our catch block fired. This seems pretty simple, right? Well, it’s really not. There are basically two tactics for this that I see often. One is to check the string form of the exception against a regex. This is awful: if the error message is changed, the error handling fails. It’s problematic to respond by never changing error messages, because they may contain typos or grammatical errors that are confusing to users reading the message. Inspecting the stringified form of the exception forces the value to be equally useful to both computers and humans, which is nearly always a mistake.

Another tactic is to check the exception’s class. This is much better, but it means that to make any given case identifiable, you need one class per exception, which is not maintainable in practice. Even if you were to write sugar for auto-generating classes for each possible throw, it would become difficult to track and read.

Throwable::X provides a few solutions to exception identification which work together to make it possible to identify ranges of exceptional conditions on several scales. First, all exceptions still are members of classes, which means that for very low-resolution checks, isa still works. Further, Throwable::X is a role, and it’s easy to write additional behavior for groups of exceptions as roles, so does can also be used. On smaller scales, though, these are still something of a pain. Throwable::X adds unique identifiers and tags to exceptions.

The unique identifier is just a string. There’s no real effort made to make sure you can’t throw the same identifier in more than one place, but by setting aside an attribute of the exception as “for computers to know exactly what happened,” it’s much easier for the programmer to provide a useful value. What should the value be? There are a lot of potentially good answers to this, and I’d rather not say. It could be a URL following an in-house convention to help prevent accidental collisions. It could be a GUID entered in a global table – or just useful for grepping. I think I’ll probably end up just using a short string, or maybe a URL.

The ident is the only part of the exception you absolutely must provide, and since that’s true, you can provide it as a single argument:

Some::Exception->throw($ident); # same as...
Some::Exception->throw({ ident => $ident });

The exception is tagged with a list of simple strings. These can be provided as arguments to throw, but the list also includes tags provided by any of the classes or roles contributing to the exception being thrown. This lets you refactor your exceptions later without breaking a lot of does checks. You just ensure that the new roles add up to the same tags.

We can define several units of behavior:

package OurException::Role::Network;
use Moose::Role;
sub x_tags { qw(network) }

package OurException::ServerDown;
use Moose;
with 'OurException::Role::Common', 'OurException::Role::Network';
sub x_tags { qw(unavailable) }

has service_name => (...);

…and then easily see what’s what:

OurException::ServerDown->throw({
  ident => ...,
  tags  => [ 'memcached' ],
  service_name => 'cache',
});

# the exception has tags: memcached network unavailable

Tags are easy to check with the has_tag method.

So, we have a bunch of ways for our code to identify what kind of exception has been encountered. Now we need to make it easy for humans. To do this, we added a simple string formatting system, something like sprintf with a pared down set of conversions and named parameters. It makes it easy to write an error message that will have access to a lot of the exception’s data, even computed or implicit attributes.

We mark attributes that we want to be available in formats with the Payload trait:

package OurException::OnThisHost;
use Moose;
use Throwable::X -all;
with 'Throwable::X';

has hostname => (
  is => 'ro',
  default  => sub { Sys::Hostname::hostname },
  traits   => [ Payload ],
  init_arg => undef,
);

Then, when an exception is thrown:

OurException::OnThisHost->throw({
  ident   => ...,
  message => "can't connect to gopher server from %{hostname}s",
});

# $err->message will be "can't connect to gopher server from real-hostname"

Serializing and Presenting

Like a lot of services with web interfaces, we’re adding more and more Ajax to our web site. We have some conventions for how we communicate successes or errors, but they’re not great, and they’re not universally applicable. The identification features of a Throwable::X exception actually make it much easier for us to communicate exceptions. Imagine that the web application runs its actions in a try (which of course it has to, anyway) and, in some circumstances, just communicates the exception directly to the client. The first question is, how do we know it’s safe to do so? We don’t want to send back “no space left on device” and look like a bunch of idiots. It’s easy: we just assume all exceptions are private unless marked otherwise. Throwable::X has a public attribute. If an exception does Throwable::X, and if it is_public, you can show the exception to the user.

So, how do we communiate it to the web client? This is easy, too. Everything we’ve done so far works nicely to make our exceptions easy to represent with a simple data structure:

{
  ident       => $err->ident,
  tags        => [ $err->tags ],
  message_fmt => $err->message_fmt,
  payload     => $err->payload,  # the attr values available in message_fmt
}

Since we rely on tags and ident for identification, we don’t need to worry about indicating any sort of class hierarchy or role inclusion. Anything that needs to be communicated will have been communicated by the tags and ident.

If our user experience team decide that they dislike the message_fmt that we’ve sent, they can fix it. They just tell the client-side code that when encountering errors with ident X, they should use a new format instead of the format given in the exception. There’s no need to alter the code, although it can be altered later to improve the error message in places that haven’t been tweaked by UX. If no message was given during exception construction, it defaults to the ident. Of course you usually want to provide a message, but if you’ve got a unique ident and the user complains about getting “General Error: -1203182012” you can grep for that (awful) ident and add a message everywhere without breaking anything.

Refactoring

Finally, all of these features are implemented individually as roles, so you can pick and choose which ones to offer in your own exceptions, in the event that you don’t care for them all.

One thing that has still not been reconstructed, which was present in Exception::Class, is an exception factory that builds all the classes desired from a structure describing the exception class hierarchy. For now, I’m not sure I need something like that, but it should quite simple to build something like that without altering Throwable::X, and to discard it later if it is determined to be a mistake.

I think it’s likely that we’ll find a few more common patterns worth coding up, but for now I think these can help to solve a lot of problems.

Written on October 19, 2010
🐪 perl
🧑🏽‍💻 programming