Thursday, March 19, 2009

Webmachine One Point Oh!

I am happy to announce the release of Webmachine 1.0.

In its short public life so far, Webmachine has already been used to build a range of Web applications, including a sales productivity tool, an SMS gateway, an HTTP caching intermediary, a content management system, the front end to a decentralized key/value data store, and more. It has been used as a central element in Erlang training courses, enabling students to write working, Web-friendly applications after only a day or two of exposure to the language. Some of its users have been delivering customer-facing Webmachine applications for nearly a year and a half now.

However, the 1.0 release isn't just an acknowledgment of that stability. It also introduces two major changes that are very beneficial to developers. One of these is a new debugging tool that is unlike anything we've seen elsewhere, allowing you to visualize in great detail how your Web resources process requests. Bryan Fink did most of the work on the debugging and tracing tool, and is the best person to explain how it works.

The other major change is to the developer API for resources, helping to make your resource functions to be referentially transparent. In case that phrase is new to you, it really means something quite simple. Resource functions no longer interact with a Req object that manipulates the response via side effects and stored state. Instead, the behavior is defined purely in terms of its input parameters and return value. For any given input a given function ought to return the same output and the side effects will be insignificant from the point of view of Webmachine's execution. This might not sound like a huge deal, but the difference it makes in terms of testability and re-use is huge.

Unit testability is vastly improved because the functions are fully isolated. You can write test inputs for your (e.g.) is_authorized function (and verify that it only returns true in the cases you want it to) without having those tests have to interact with anything else in the application. There's no need for anything resembling a "mock object" or other such silliness; when the inputs and outputs are simple records as opposed to gen_servers with side effects, you can just construct whole records for your test inputs, and inspect the output records for checking test results.

Referential transparency also enables much more in the way of static analysis. One item on the roadmap for a future version of Webmachine is a type analysis tool that can verify at compile time that the type signatures of your resource functions can only lead to valid HTTP behavior.

It's also worth noting that the backward incompatibility is well-contained and easy to get past. Our production application was switched entirely to the new API by one person in a day, and Bryan also converted all of BeerRiot in under two hours. A handy guide to upgrading shows just how simple it is.

As of the 1.0 release we're also moving Webmachine from Google Code to Bitbucket. The main reason for this is that we vastly prefer Mercurial to Subversion, but a number of other features on Bitbucket have also turned out to be nice. We're leaving the old version up on Google Code for a while, so that people with running applications can access both the old and new versions.



bsdemon said...

Webmachine seems to be my erlang webframework of choice! Thanks for it!

Unknown said...

Congrats on the new release.

Unknown said...

Great work guys. Just tried this release, it works beautifully.

Larry White said...

Interesting product, but the documentation is incredibly sparce for something labeled 1.0., unless I'm missing something.

Justin Sheehy said...


Please let us know where you got stuck, as we're always happy to improve the documentation. I am guessing that you started at

and that you couldn't find something you were looking for on

but I don't know where you ran into trouble. Feel free to send me email if you'd like to be more detailed.

Of course, Webmachine isn't a "framework" -- it's something conceptually much simpler, so it doesn't have quite as many details to document.

Goose said...

I am excited to give this a whirl. I tried one of the web frameworks, and it made me want to kill myself.

korihor said...

Hi :D what webmachine SMS gateway was build? is it OSS? I would like to contribute. Thank you.

Justin Sheehy said...


The SMS gateway I was referring to has not been released as open source that I know of. An ISP developed it for their own use. If I hear of it being openly released, I will be sure to say so.