webmachine for Ruby travis

webmachine-ruby is a port of Webmachine, which is written in Erlang. The goal of both projects is to expose interesting parts of the HTTP protocol to your application in a declarative way. This means that you are less concerned with handling requests directly and more with describing the behavior of the resources that make up your application. Webmachine is not a web framework per se, but more of a toolkit for building HTTP-friendly applications. For example, it does not provide a templating engine or a persistence layer; those choices are up to you.

A Note about Rack

Webmachine has a Rack adapter -- thanks to Jamis Buck -- but when using it, we recommend you ensure that NO middleware is used. The behaviors that are encapsulated in Webmachine could be broken by middlewares that sit above it, and there is no way to detect them at runtime. Caveat implementor. That said, Webmachine should behave properly when given a clear stack.

Getting Started

Webmachine is very young, but it's still easy to construct an application for it!

require 'webmachine'
# Require any of the files that contain your resources here
require 'my_resource'

# Create an application which encompasses routes and configruation
MyApp = Webmachine::Application.new do |app|
  app.routes do
    # Point all URIs at the MyResource class
    add ['*'], MyResource
  end
end

# Start the server, binds to port 8080 using WEBrick
MyApp.run

Your resource will look something like this:

class MyResource < Webmachine::Resource
  def to_html
    "<html><body>Hello, world!</body></html>"
  end
end

Run the first file and your application is up. That's all there is to it! If you want to customize your resource more, look at the available callbacks in lib/webmachine/resource/callbacks.rb. For example, you might want to enable "gzip" compression on your resource, for which you can simply add an encodings_provided callback method:

class MyResource < Webmachine::Resource
  def encodings_provided
    {"gzip" => :encode_gzip, "identity" => :encode_identity}
  end

  def to_html
    "<html><body>Hello, world!</body></html>"
  end
end

There are many other HTTP features exposed to your resource through Webmachine::Resource::Callbacks. Give them a try!

Application/Configurator

There's a configurator that allows you to set the ip address and port bindings as well as a different webserver adapter. You can also add your routes in a block (as shown above). Both of these call return the Webmachine::Application instance, so you could chain them if you like. If you don't want to create your own separate application object, Webmachine.application will return a global one.

require 'webmachine'
require 'my_resource'

Webmachine.application.routes do
  add ['*'], MyResource
end

Webmachine.application.configure do |config|
  config.ip = '127.0.0.1'
  config.port = 3000
  config.adapter = :Mongrel
end

# Start the server.
Webmachine.application.run

Webmachine includes adapters for Webrick, Mongrel, Reel, and Hatetepe. Additionally, the Rack adapter lets it run on any webserver that provides a Rack interface. It also lets it run on Shotgun (example).

Visual debugger

It can be hard to understand all of the decisions that Webmachine makes when servicing a request to your resource, which is why we have the "visual debugger". In development, you can turn on tracing of the decision graph for a resource by implementing the #trace? callback so that it returns true:

class MyTracedResource < Webmachine::Resource
  def trace?
    true
  end

  # The rest of your callbacks...
end

Then enable the visual debugger resource by adding a route to your configuration:

Webmachine.application.routes do
  # This can be any path as long as it ends with '*'
  add ['trace', '*'], Webmachine::Trace::TraceResource
  # The rest of your routes...
end

Now when you visit your traced resource, a trace of the request process will be recorded in memory. Open your browser to /trace to list the recorded traces and inspect the result. The response from your traced resource will also include the X-Webmachine-Trace-Id that you can use to lookup the trace. It might look something like this:

preview calls at decision

Refer to examples/debugger.rb for an example of how to enable the debugger.

Features

Caveats

Documentation & Finding Help

Related libraries

LICENSE

webmachine-ruby is licensed under the Apache v2.0 license. See LICENSE for details.

Changelog

1.1.0 January 12, 2013

1.1.0 is a major feature release that adds the Reel and Hatetepe adapters, support for "weak" entity tags, streaming IO response bodies, better error handling, a shortcut for spinning up specific resources, and a bunch of bugfixes. Added Tony Arcieri, Sebastian Edwards, Russell Garner, Justin McPherson, Paweł Pacana, and Nicholas Young as contributors. Thank you for your contributions!

1.0.0 July 7, 2012

1.0.0 is a major feature release that finally includes the visual debugger, some nice cookie support, and some new extension points. Added Peter Johanson and Armin Joellenbeck as contributors. Thank you for your contributions!

0.4.2 March 22, 2012

0.4.2 is a bugfix release that corrects a few minor issues. Added Lars Gierth and Rob Gleeson as contributors. Thank you for your contributions!

0.4.1 February 8, 2012

0.4.1 is a bugfix release that corrects a few minor issues. Added Sam Goldman as a contributor. Thank you for your contributions!

0.4.0 February 5, 2012

0.4.0 includes some important refactorings, isolating the idea of global state into an Application object with its own Dispatcher and configuration, and making Adapters into real classes with a consistent interface. It also adds some query methods on the Request object for the HTTP method and scheme and Route guards (matching predicates). Added Michael Maltese, Emmanuel Gomez, and Bernerd Schaefer as committers. Thank you for your contributions!

0.3.0 November 9, 2011

0.3.0 introduces some new features, refactorings, and now has 100% documentation coverage! Among the new features are minimal Rack compatibility, streaming responses via Fibers and a friendlier route definition syntax. Added Jamis Buck as a committer. Thank you for your contributions!

0.2.0 September 11, 2011

0.2.0 includes an adapter for Mongrel and a central place for configuration as well as numerous bugfixes. Added Ian Plosker and Bernd Ahlers as committers. Thank you for your contributions!

0.1.0 August 25, 2011

This is the initial release. Most things work, but only WEBrick is supported.