O p t i o n s f u l

Provide HTTP OPTIONS support for the Ruby on Rails framework.

Note for the impatient: installation instructions below.
Note for the dummies: change host names and paths properly.
Note for the unfaithful: run rake routes to validate the results.

WARNING: If your application is Rails 2.x please go to optionsful2

“-No! No! No! -Show me the code!”

Playing HTTP OPTIONS via telnet:


$ telnet localhost 3000 
OPTIONS /posts HTTP/1.1
Host: http://localhost:3000

HTTP/1.1 204 No Content 
Allow: GET, POST
Connection: close
Date: Thu, 22 Jul 2010 17:20:27 GMT
Link: "<http://localhost:3000/api/posts>; type=text/html; rel=help"

OPTIONS /posts/1 HTTP/1.1
Host: http://localhost:3000

HTTP/1.1 204 No Content 
Allow: GET, PUT, DELETE
Connection: close
Date: Thu, 22 Jul 2010 18:14:24 GMT
Link: "<http://localhost:3000/api/posts/1/>; type=text/html; rel=help"

OPTIONS /posts/1/comments HTTP/1.1
Host: http://localhost:3000

HTTP/1.1 204 No Content 
Allow: GET, POST
Connection: close
Date: Thu, 22 Jul 2010 18:12:43 GMT
Link: "<http://localhost:3000/api/posts/1/comments>; type=text/html; rel=help"

_{Note the empty line which is part of the HTTP protocol.}

I agree. Telnet is the geekest way.. ;-)

For testing purposes you would like better using an HTTP client software. I use HTTP Client on my Mac OS X and cURL anywhere else. And on real life, you are free to create your own usage scenario.

INSTALLATION:

Change directory to your Ruby on Rails web application
Add gem dependency to Gemfile:
```
gem ‘optionsful’
```

Add it to the stack at config/application.rb:

class Application < Rails::Application
  config.middleware.use ::Baurets::Optionsful::Server
  …

To install it, run bundle install or:
```
$ gem install optionsful
```
Enjoy! And give feedback! :)

CONFIGURATION:

Setting up the `Link` header

To enable and setup the response’s Link header, install and edit the configuration file:
- run rake optionsful:yml
- edit the ‘optionsful.yml’ file at your application’s ‘config’ folder.
Example:


development:
    link: true
    host: auto
    base_path: /api
    propagate: true

Possible values and effects: (the underlined values are the default ones)

link
- false: Do not include the “Link” in the response headers.
  - some other settings are then ignored
- true: Do include it!
  - build the URI based on the host, base_path, and propagate values, explained below.

host
- auto: Use the application’s own address and port.
- custom URI: point it to another location
  - Example: www.baurets.net
  - Note: do not include ‘http://’

base_path
- the path to be appended to the host.
  - Default is /api.
  - To disable it, use /
  - Example: /my_company_private_area/our_big_project/resources/api

propagate
- false: Do not append the request’s path info to the URI.
- true: Do append it, as it is.

Generated Link example: (link: true, host: auto, base_path: /api, propagate: true)

Link: “<http://localhost:3000/api/posts/1/comments>; type=text/html; rel=help”

Note: Allow and Link are expected headers on a response to an HTTP OPTIONS request.

KNOWN ISSUES

Rails route recognition still need some work

Developer notes


  $ cd ~/your_workspace
  $ git clone [email protected]:kayaman/optionsful.git
  $ cd optionsful
  $ rake

To bleed on the edge, add at your Rails 3 application’s Gemfile:

gem ‘optionsful’, :path => “~/your_workspace/optionsful/”

TODO: check dependencies.

TODOs

RSpec 2.0 => http://github.com/rspec/rspec-core/blob/master/Upgrade.markdown
spec_helper allow_only(headers, *method)

Get involved

Mailing list: http://groups.google.com/group/optionsful
Bug tracker : http://kayaman.lighthouseapp.com/projects/56438-optionsful/overview

CONTRIBUTORS

Me, myself and I, so far.
You are welcome, do it. ;-)