Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: kirk-adapter

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 examples
Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .rspec
Octocat-spinner-32 .travis.yml
Octocat-spinner-32 Gemfile
Octocat-spinner-32 Guardfile
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 webmachine.gemspec
README.md

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.

NOTE: Webmachine is NOT compatible with Rack. This is intentional! Rack obscures HTTP in a way that makes it hard for Webmachine to do its job properly, and encourages people to add middleware that might break Webmachine's behavior. Rack is also built on the tradition of CGI, which is nice for backwards compatibility but also an antiquated paradigm and should be scuttled (IMHO). Rack may be supported in the future, but only as a shim to support other web application servers.

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' 

    # Point all URIs at the MyResource class
    Webmachine::Dispatcher.add_route(['*'], MyResource)

    # Start the server, binds to port 3000 using WEBrick
    Webmachine.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 callbacks. Give them a try!

Features

  • Handles the hard parts of content negotiation, conditional requests, and response codes for you.
  • Most callbacks can interrupt the decision flow by returning an integer response code. You generally only want to do this when new information comes to light, requiring a modification of the response.
  • Currently supports WEBrick. Other host servers are planned.
  • Streaming/chunked response bodies are permitted as Enumerables or Procs.
  • Unlike the Erlang original, it does real Language negotiation.

Problems/TODOs

  • Support streamed responses as Fibers.
  • Configuration, command-line tools, and general polish.
  • An effort has been made to make the code feel as Ruby-ish as possible, but there is still work to do.
  • Tracing is exposed as an Array of decisions visited on the response object. You should be able to turn this off and on, and visualize the decisions on the sequence diagram.
Something went wrong with that request. Please try again.