Hobbit

A minimalistic microframework built on top of Rack.

Installation

Add this line to your application's Gemfile:

gem 'hobbit'
# or this if you want to use hobbit master
# gem 'hobbit', github: 'patriciomacadden/hobbit'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hobbit

Features

• DSL inspired by Sinatra.
• Speed.
• Extensible with standard ruby classes and modules, with no extra logic. See hobbit-contrib.
• Zero configuration.

Philosophy

• Don't repeat yourself
• Encourages the understanding and use of Rack and its extensions instead of providing such functionality.

Usage

Hobbit applications are just instances of classes that inherits from Hobbit::Base, which complies the Rack SPEC.

Hello World example

Create a file called app.rb:

require 'hobbit'

class App < Hobbit::Base
  get '/' do
    'Hello World!'
  end
end

Create a config.ru file:

require './app'

run App.new # or just `run App`

Run it with rackup:

$ rackup

View your app at http://localhost:9292.

Routes

Every route is composed of a verb, a path (optional) and a block. When an incoming request matches a route, the block is executed and a response is sent back to the client. The return value of the block will be the body of the response. The headers and status code of the response will be calculated by Hobbit::Response, but you could modify it anyway you want it.

See an example:

class App < Hobbit::Base
  get '/' do
    # ...
  end

  post '/' do
    # ...
  end

  put '/' do
    # ...
  end

  patch '/' do
    # ...
  end

  delete '/' do
    # ...
  end

  options '/' do
    # ...
  end
end

When a route gets called you have this methods available:

• env: The Rack environment.
• request: a Hobbit::Request instance.
• response: a Hobbit::Response instance.

And any other method defined in your application.

Available methods

• delete
• get
• head
• options
• patch
• post
• put

Note: Since most browsers don't support methods other than GET and POST you must use the Rack::MethodOverride middleware. (See Rack::MethodOverride).

Routes with parameters

Besides the standard GET and POST parameters, you can have routes with parameters:

require 'hobbit'

class App < Hobbit::Base
  # matches both /hi/hobbit and /hi/patricio
  get '/hi/:name' do
    # request.params is filled with the route paramters, like this:
    "Hello #{request.params[:name]}"
  end
end

Redirecting

If you look at Hobbit implementation, you may notice that there is no redirect method (or similar). This is because such functionality is provided by Rack::Response and for now we don't wan't to repeat ourselves (obviously you can create an extension!). So, if you want to redirect to another route, do it like this:

require 'hobbit'

class App < Hobbit::Base
  get '/' do
    response.redirect '/hi'
  end

  get '/hi' do
    'Hello World!'
  end
end

Halting

To immediately stop a request within route you can use halt.

require 'hobbit'

class App < Hobbit::Base
  use Rack::Session::Cookie, secret: SecureRandom.hex(64)

  def session
    env['rack.session']
  end

  get '/' do
    response.status = 401
    halt response.finish
  end
end

Built on top of rack

Each Hobbit application is a Rack stack (See this blog post for more information).

Mapping applications

You can mount any Rack application to the stack by using the map class method:

require 'hobbit'

class InnerApp < Hobbit::Base
  # gets called when path_info = '/inner'
  get do
    'Hello InnerApp!'
  end
end

class App < Hobbit::Base
  map('/inner') { run InnerApp.new }

  get '/' do
    'Hello App!'
  end
end

Using middleware

You can add any Rack middleware to the stack by using the use class method:

require 'hobbit'

class App < Hobbit::Base
  use Rack::Session::Cookie, secret: SecureRandom.hex(64)
  use Rack::ShowExceptions

  def session
    env['rack.session']
  end

  get '/' do
    session[:name] = 'hobbit'
  end

  # more routes...
end

run App.new

Security

By default, Hobbit (nor Rack) comes without any protection against web attacks. The use of rack-protection is highly recommended:

require 'hobbit'
require 'rack/protection'
require 'securerandom'

class App < Hobbit::Base
  use Rack::Session::Cookie, secret: SecureRandom.hex(64)
  use Rack::Protection

  get '/' do
    'Hello World!'
  end
end

See the rack-protection documentation for futher information.

Testing

rack-test is highly recommended. See an example:

In app.rb:

require 'hobbit'

class App < Hobbit::Base
  get '/' do
    'Hello World!'
  end
end

In app_spec.rb:

require 'minitest/autorun'
# imagine that app.rb and app_spec.rb are stored in the same directory
require 'app'

describe App do
  include Rack::Test::Methods

  def app
    App.new
  end

  describe 'GET /' do
    it 'must be ok' do
      get '/'
      last_response.must_be :ok?
      last_response.body.must_match /Hello World!/
    end
  end
end

See the rack-test documentation for futher information.

Extensions

You can extend Hobbit by creating standard ruby modules. See an example:

module MyExtension
  def do_something
    # do something
  end
end

class App < Hobbit::Base
  include MyExtension

  get '/' do
    do_something
    'Hello World!'
  end
end

Hobbit::Contrib

hobbit-contrib is a ruby gem that comes with a lot of hobbit extensions, such as:

• Hobbit::Render: provides basic template rendering.
• Hobbit::Session: provides helper methods for handling user sessions.
• Hobbit::Environment: provides helper methods for handling application environments.
• Hobbit::Filter: provides helper class methods for handling Sinatra-like filters.
• Hobbit::ErrorHandling: provides helper class methods for handling Sinatra-like error handling.

... And many more!

Community

• Wiki: Guides, how-tos and recipes
• IRC: #hobbitrb on http://freenode.net

Presentations

• Building web applications in Ruby, by Krzysztof Wawer (english, polish)

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

See the LICENSE.