Git Product home page Git Product logo

webmachine-ruby's Introduction

webmachine for Ruby Build Status

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 the procedures involved in handling requests directly and more with describing facts about 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.

Features

  • Handles the hard parts of content negotiation, conditional requests, and response codes for you.
  • Provides a base resource with points of extension to let you describe what is relevant about your particular resource.
  • Supports WEBrick, Reel, HTTPkit, and a Rack shim. Other host servers are being investigated.
  • Streaming/chunked response bodies are permitted as Enumerables, Procs, or Fibers!
  • Unlike the Erlang original, it does real Language negotiation.
  • Includes a visual debugger so you can look through the decision graph to determine how your resources are behaving.

Documentation & Finding Help

Getting Started

Below we go through some examples of how to do basic things with webmachine-ruby.

The first example defines a simple resource that doesn't demo the true power of Webmachine but perhaps gives a feel for how a Webmachine resource might look. Webmachine::Resource.run is available to provide for quick prototyping and development. In a real application you will want to configure what path a resource is served from. See the Router section in the README for more details on how to do that.

There are many other HTTP features exposed to a resource through {Webmachine::Resource::Callbacks}. A callback can alter the outcome of the decision tree Webmachine implements, and the decision tree is what makes Webmachine unique and powerful.

A simple static HTML resource

require 'webmachine'

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

# Start a web server to serve requests via localhost
MyResource.run

A simple dynamic JSON Resource

require 'webmachine'
require 'widget'

class MyResource < Webmachine::Resource

  # GET and HEAD are allowed by default, but are shown here for clarity.
  def allowed_methods
    ['GET','HEAD']
  end

  def content_types_provided
    [['application/json', :to_json]]
  end

  # Return a Truthy or Falsey value
  def resource_exists?
    widget
  end

  def widget
    @widget ||= Widget.find(request.path_info[:id])
  end

  def to_json
    widget.to_json
  end
end

Router

The router is used to map a resource to a given path. To map the class MyResource to the path /myresource you would write something along the lines of:

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

# Start a web server to serve requests via localhost
Webmachine.application.run

When the resource needs to be mapped with variables that will be passed into the resource, use symbols to identify which path components are variables.

Webmachine.application.routes do
  add ['myresource', :id], MyResource
end

To add more components to the URL mapping, simply add them to the array.

Webmachine.application.routes do
  add ['myparentresource', :parent_id, 'myresource', :id], MyResource
end

Read more about routing here.

Application/Configurator

There is a configurator that allows you to set what IP address and port a web server should bind to as well as what web server should serve a webmachine resource. Learn how to configure your application here.

Adapters

Webmachine provides adapters for many popular webservers. Learn more here.

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". Learn how to configure it here.

Related libraries

LICENSE

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

webmachine-ruby's People

Contributors

armin-joellenbeck avatar asmod4n avatar bernd avatar bernerdschaefer avatar bethesque avatar emmanuel avatar ian-plosker avatar jamis avatar jimvm avatar jjb avatar jurre avatar justinmcp avatar madlep avatar mostlyobvious avatar nyarly avatar petejohanson avatar rgarner avatar samwgoldman avatar seancribbs avatar sebastianedwards avatar secretfader avatar tarcieri avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.