h1. [+*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":http://github.com/kayaman/optionsful2

h1. "-No! No! No! *-Show me the code!*" 

h2. Playing HTTP OPTIONS via telnet:

<pre>
$ 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"

</pre>
~*Note the empty line which is part of the HTTP protocol.*~

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

    For testing purposes you would like better using an HTTP client software. 
    I use "HTTP Client":http://ditchnet.org/httpclient/ on my Mac OS X and "cURL":http://curl.haxx.se/ anywhere else.
    And on real life, you are free to create your own usage scenario.

h1. INSTALLATION:

# Change directory to your Ruby on Rails web application
# Add gem dependency to @Gemfile@:
<pre>gem 'optionsful'</pre>
# Add it to the stack at @config/application.rb@:
<pre>class Application < Rails::Application
  config.middleware.use ::Baurets::Optionsful::Server
  ...</pre>
# To install it, run @bundle install@ or:
<pre>$ gem install optionsful</pre>
# Enjoy! And give feedback! :)

h1. CONFIGURATION

h2. 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:
<pre>development:
 link: true
 host: auto
 base_path: /api
 propagate: true</pre>

h2. Possible values and effects: (the underline 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*)
<pre>Link: "<http://localhost:3000/api/posts/1/comments>; type=text/html; rel=help"</pre>

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

h2. KNOWN ISSUES
* Rails route recognition still need some work

h2. Development notes

* To bleed on the edge, at your Rails 3 application's @Gemfile@:
<pre>gem 'optionsful', :path => "~/your_workspace/optionsful/"</pre>

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

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

Copyright (c) 2010 Marco Antonio Gonzalez Junior, kayaman@baurets.net, released under the MIT license.