Extracting a Reusable Catalyst Model

The flexibility of the Catalyst offers a lot of value, though occasionally at a price. I've been impressed at the abstractions it offers, as I develop a couple of web applications that are growing in features and complexity.

One of those projects requires user registration. I've chosen an email verification system to help ensure that the system can notify users for the alerts they select. To make notifications work, I created a Catalyst model which sends emails. It looked something like this:

package Stockalyzer::Model::UserMail;
use strict;
use warnings;
use base 'Catalyst::Model::Adaptor';

package Stockalyzer::Mailer;

use MIME::Base64;
use Authen::SASL;
use Net::SMTP::SSL;

use base 'Mail::Builder::Simple';

sub send_verification
{
    my ($self, $c, $user) = @_;
    my $code              = $user->verification_code( force => 1 );
    my $email             = $user->email_address;
    my $register_link     = $c->uri_for(
        $c->controller( 'Users' )->action_for( 'verify' ),
        { VERIFY_USER_email => $email, VERIFY_USER_code => $code },
    );

    $self->send(
        subject   => ...,
        to        => ...,
        from      => ...,
        plaintext => ...,
    );
}

sub send_reset
{
    my ($self, $c, $user) = @_;
    my $code              = $user->reset_code;
    my $email             = $user->email_address;
    my $reset_link        = $c->uri_for(
        $c->controller( 'Users' )->action_for( 'reset_password' ),
        { USER_RESET_email => $email, USER_RESET_code => $code },
    );

    $self->send( ... );
}

sub send_feedback
{
    my ($self, $c, $params) = @_;
    $params->{path}       ||= 'no path found';
    $params->{details}    ||= '';
    $params->{type}       ||= 'severe type error';
    my $username            = $c->user ? $c->user->username : '(no user)';

    $self->send( ... );
}

1;

This is a standard Catalyst model. With the appropriate configuration (specifically setting the class attribute of the Model::UserMail model to Stockalyzer::Mailer, I can access the model from within Catalyst like:

sub send_feedback :Path('/send_feedback') :Args(0)
{
    my ($self, $c) = @_;
    my $method     = lc $c->req->method;

    return $c->res->redirect( '/users' ) unless $method eq 'post';

    my $params     = $self->get_params_for( $c, 'feedback' );
    $c->model( 'UserMail' )->send_feedback( $c, $params );

    return $c->res->redirect( $params->{path} || '/users' );
}

Then the time came to add a new feature—emailing users about event notifications. The event notification processing system runs every day in an automated process separated from the web application. It doesn't use Catalyst at all.

I was glad to have my mail configuration set up so easily within Catalyst, and I wanted to reuse that model for the offline mailer—keeping all of those actions in one place makes sense. That meant decoupling the mail sending actions from Catalyst altogether, both in the configuration system and in the arguments to the model's methods.

Changing the method signatures was easy. Instead of passing in the Catalyst request context, I changed them to pass in the URL:

sub send_verification
{
    my ($self, $uri, $user) = @_;
    my $code                = $user->verification_code( force => 1 );
    my $email               = $user->email_address;
    $uri->query_form( VERIFY_USER_email => $email, VERIFY_USER_code => $code );

    $self->send( ... );
}

The configuration was a little trickier. Configuration file parsers are like templating systems: everyone wants something a little different, and for every ten developers, twelve modules exist on the CPAN. In the interest of expedience (and with the knowledge that I'll change this later), I made the single place which instantiates my mailer object in the offline processing programs grab the existing configuration:

package Stockalyzer::App::Role::DailyUpdate;

use Modern::Perl;
use Moose::Role;
use Stockalyzer::Mailer;

has 'mailer', is => 'ro', lazy_build => 1;

sub _build_mailer
{
    my $self        = shift;
    my $config      = do 'stockalyzer_local.pl';
    my $mail_client = $config->{'Model::UserMail'}{mail_client};
    return Stockalyzer::Mailer->new( $mail_client );
}

As ugly as that is, the code already operates under the assumption that it's running from the root directory of the application. Besides that, any code which handles these updates already has to do something like this.

With those two changes made, I was able to send email from the offline process using the same underlying model that the web application uses. Extracting it took moments, and generalizing it to be independent of Catalyst took a couple of minutes.

Catalyst's tutorials suggest using an adaptor layer between your web application and your models, and they're correct—but even if you don't do things "right" from the start, being careful about defining the boundaries between layers of your system means that you can make these changes later.