Store Data Not Types

I successfully upgraded a Rails application from version 2.3 to 3.2. Or so I thought.

"The Best Laid Plans..."

Though I read lots of blog posts; though I watched the excellent videos from RailsCasts; though I used the rails_upgrade plugin; though I made and worked through my own checklist; though all the tests passed; though manual testing found no issues; it wasn't long after deploying to production that I received the first email from our exception notifier.

In brief, there was a problem sending email caused by an inability to deserialize DelayedMessage#message for old records.

Here's the simplified code for DelayedMessage and its use. Can you spot the problem?


message = SomeMailer.some_event some_object
DelayedMessage.create! :message => message

class DelayedMessage < ActiveRecord::Base
		serialize :message, TMail::Mail

		def deliver
				if message
						ActionMailer::Base.deliver message
						destroy
				end
		end
end

The Problem

Email is defined by the "Internet Message Format" specified in RFC 2282. But, the code above is not storing the email that way. It's storing a TMail::Mail, the type returned from the ActionMailer APIs in Rails 2. Why is this a problem? Rails 3 changed its implementation of email. It moved from the tmail gem to the mail gem. Consequently, the ActionMailer APIs now return a Mail::Message instead of a TMail::Mail.

How, then, can we change the system to (1) work with existing DelayedMessage records and (2) be more resilient to any future changes in the email implementation in Rails?

Step 1: Store Data Instead of a Type

Instead of storing an instance of the message, a TMail::Mail, we store the string representation of the message.


message = SomeMailer.some_event(some_object)
DelayedMessage.create! :message => message.to_s

We have two things working in our favor here. First, since DelayedMessage#message is a text column in our database, we don't have to change it to be able to store the message as a long string. Second, Mail::Message#to_s returns the message as a string that conforms to RFC 2282.

Step 2: Read Old and New Messages

Now that we store the message as a string, let's retrieve it as one, too. We take control of retrieval by providing our own implementation of DelayedMessage#message.

class DelayedMessage < ActiveRecord::Base
		def message
				m = read_attribute(:message).to_s
				return nil if m.blank?
				if in_earlier_serialized_format? m
						m = YAML.load m
				end
				Mail.read_from_string m.to_s
		end

		def deliver
				if m = message
						prepare_for_delivery m
						m.deliver
						destroy
				end
		end

		private

		def in_earlier_serialized_format?(m)
				m.start_with? '--- !ruby/object:TMail::Mail'
		end
end

By always converting the stored message to a string during retrieval, we can determine whether the message is in the old format, a serialized TMail::Mail. Either way, we can call #to_s on it to ensure we're working with a string representation that conforms to RFC 2282, since we either stored it that way (our earlier change) or obtain that result from TMail::Mail#to_s. Then, all we have to do is use Mail.read_from_string to parse the string into a Mail::Message instance, which we can then use with Rails 3.

The Only Constant in Life is Change

One of the many changes introduced in Rails 3 was the API for sending email. Though the API changed, the observable behavior, that an email was sent, remained the same. Rails 2 and 3 use an email implementation that conforms to the "Internet Message Format" in RFC 2282. Yet, the application managed to subvert that conformance by storing a type. While we can overcome such problems, it's best to avoid them by storing data instead.