I’ve been hard at work on a web based prototype for Sol Trader recently in order to test some game mechanics ideas.1 I’ve been building the web app in a slight different way to the normal process I use to build web software, and it’s high time I started talking about it.
The examples are written using Sinatra as the web layer and MongoDB as the persistence layer, but you could use any web framework, persistence mechanism, or language for that matter, to express the same concepts. In fact, that’s really the point.
Step 1: Classic Ruby web app design
When I originally started up the project. I threw up a few different Mongo persisted objects to get myself going:
This is pretty typically how I’ve organised my self in the past when writing an app: I’d have a Game model, and a Character model, and I have a Joining model to link the two together. These objects responsible for handling their own persistence. I’m using Mongoid, but this could just as easily be ActiveRecord. Here’s the joining model, for example:
Step 2: Extracting the behaviour from the action
When thinking this over, I realised that there were entirely different concerns going on here:
- I’m creating a relationship between a new character and the game that they’re joining,
- I’m persisting that relationship in a database,
- I’m responding to the result of that process in my web app.
Time to seperate some of those concerns from the web layer. Following Graham Ashton’s excellent recent blog post2, I decided to introduce
GameJoiner class to the procedings to improve the join action. Here’s the
CharacterCreator class (the
GameJoiner is similar):
Here’s the action which uses it:
Instead of the logic existing entirely inside the action itself, the logic has been moved into a seperate class, which calls back into the app class to make the changes that are required. This removed most of the logic from the action at the bottom, and allows us to test the
CharacterCreator in isolation without having to fire up the whole web app.
Step 3: Extreme isolation: separating arrangement and work
So far, so good: but it’s not perfect. The persistence is still very much embedded inside the character class, and it’s necessary to use mocks for testing. I wanted to see how far I could push the tests without needing to use mocks at all, as they are sometimes a code smell for tight coupling. This means that you need to completely avoid callbacks, use dependency injection throughout and rely on passing simple structures between your methods. This means I couldn’t use a Publish/Subscribe model either: I wanted to see just how far I could take isolation and code decoupling.
So how about disconnecting characters and games from the persistence mechanism entirely, and just using a queue to communicate between them?3
This is quite a departure. Let’s take each line of the new action in turn.
After creating an empty array to store a set of changes, we then create a character, which is defined as a simply ruby
Struct.4 We then grab the latest game and call
join, which represents the actual work of the class.
Game#join is defined as follows:
Note that we’re not changing the object here: we are treating the game object as immutable. We instead create a new copy of the object and then return it. We also return a change object and add the new copy of the game object to it. This is all domain logic: there’s no mention of any implementation details.
apply method is very simple. it loops through the changes asking them to perform an operation on the current object. Depending on the type of the change, this will call a different method on the object:
We’ve now built a generic handler for the different things that can happen when a join is performed. As long as we include the
apply method in our controller object, and define the
character_joined methods, we can handle a joining change in any other object. The apply mechanism shown here can easily be abstracted away so we don’t have to worry about it.5
Handling the changes
There are two subsystems I want to be able to handle a joining change: the game repository (so that it can save the new character to the database), and the web action itself (so that we can show the relevant page to the user). Both these systems are at the ‘edges’ of the system, whilst the game object sits in the middle. This turns out very similar to the “Ports and Adaptors” or “Hexagonal” approach Matt’s been talking about recently.6 It also has similarities to the Actor model of concurrency used in Erlang.7
GameRepository defines the relevant methods like this:
Note that the joining_error isn’t interesting to the
GameRepository class, so we don’t do anything with that message.
And the web action in our Sinatra class defines them like this:
We have now seperated the arrangement of the operations which need to be performed (the saving, rendering web pages, joining games) from the work itself: they are all completely and totally isolated from each other. This has a number of advantages:
- The web action and repository steps can be performed independently from each other, and neither cares about the implementation of the other.
- The join method in the plain ruby game object cares nothing for its own persistence, and knows exactly zero about web applications, which is just as it should be. It’s like putting your systems in solitary confinement, with no access to the outside world.
- Having Cucumber documentation hitting the web app was very useful as I made bigger changes, as I could still verify that everything was working. This gave me courage to proceed with something a little different.8
- There’s nothing to stop me making the queues proper
Queueobjects, and start running the system in parallel in future, to take advantage of multiple cores.
I love working in this way. It’s very freeing not having to think about persistence or web apps when trying to reason about complex domain concepts. It scales well, too: I’ve now built most of the protoype using a form of this approach. The domain logic is about 1,000 lines of code, my entire persistence layer still sits in one 200 line file, and the main web app is another 200 line file. These files are manageable because there isn’t much going on in them: they’re just handling lots of different types of changes by defining a few methods. In fact the real
GameRepository class has a lot of lines which look like this:
What do you think of this approach? Is it an improvement, or does it just obfuscate logic? I’d be grateful for feedback.
More to come
Next time I plan to talk about how I’m performing more complex operations by feeding changes back into the domain to allow reactions to behaviour. Stay tuned!
Sol Trader is the space trading and piracy game I’ve been writing for the last year or so. The online version I’m describing in this post will be available at http://online.soltrader.net once it’s ready. ↩
In the real system this all exists in Modules. I’m only showing it long-hand here for clarity. ↩