README.md in m2r-0.0.3 vs README.md in m2r-1.0.0

- old
+ new

@@ -1,55 +1,161 @@ m2r === -A [mongrel2](http://mongrel2.org/index) backend handler written in Ruby, based on [Zed's Python backend handler](http://mongrel2.org/dir?ci=1bdfff8f050b97df&name=examples/python/mongrel2). +A [Mongrel2](http://mongrel2.org/) [™](#legal) backend handler written in Ruby. Also includes Rack adpater to get you up and running quickly. -Usage/Examples ------ +[![Build Status](https://secure.travis-ci.org/perplexes/m2r.png)](http://travis-ci.org/perplexes/m2r) [![Dependency Status](https://gemnasium.com/perplexes/m2r.png)](https://gemnasium.com/perplexes/m2r) -* `examples/http_0mq.rb` is a test little servlet thing (based on what comes with mongrel2). -* `examples/rack_handler.rb` is a Mongrel2 ruby handler rack handler mouthful, whose variables are probably a little off. -* `examples/lobster.ru` is a rackup file using the Rack handler that'll serve Rack's funny little lobster app. +Installation +------------ -Running Examples ----------------- +You'll need following prerequisites first: -* `ruby examples/http_0mq.rb`, which with Mongrel2's test config will serve up at http://localhost:6767/handlertest -* `rackup examples/lobster.ru`, ditto, http://localhost:6767/handlertest +* [Mongrel2](http://mongrel2.org/downloads) +* [ØMQ](http://www.zeromq.org/area:download) -With rails3: -Add this to your Gemfile: +Next, in your `Gemfile` add: - gem 'ffi' - gem 'ffi-rzmq' - gem 'json' +```ruby +gem 'm2r' +``` -And this to your config.ru: +And finally run: - $: << location_to_m2r + '/example' - require 'rack_handler' - - Rack::Handler::Mongrel2.run YourRailsAppName::Application - -Then do all like `bundle exec rackup` +``` +bundle install +``` -Installation ------------- +Guides +------ -* JRuby 1.5+ (don't use MRI - it will crash horribly, check the ISSUES file) -* [FFI](http://github.com/ffi/ffi), `gem install ffi` should be fine. -* [Zero MQ](http://www.zeromq.org/area:download), you'll need to compile and install to get the headers and such for: -* [ffi-rzmq](http://github.com/chuckremes/ffi-rzmq), which you'll have to build. The native zmq didn't work for me, but if you want to fix it, please do! -* [json](http://github.com/genki/json), since the headers are returned in JSON, which is RAD. (Really Awesome, Dude) -* Rack `gem install rack` if you want to run the rack example. +### Running Rack Application +#### Gemfile + +Add `m2r` to `Gemfile` and run `bundle install` + +#### Mongrel 2 + +[Configure `Handler`](http://mongrel2.org/static/book-finalch4.html#x6-260003.4) for your application: + +``` +rack_example = Handler( + send_spec = "tcp://127.0.0.1:9997", + send_ident = "14fff75f-3474-4089-af6d-bbd67735ab89", + recv_spec = "tcp://127.0.0.1:9996", + recv_ident = "" +) +``` + +#### Start + +```bash +[bundle exec] rackup -s mongrel2 application.ru +``` + +Add `-O option_name` to provide options for m2r handler: + +```ruby +[bundle exec] rackup -s mongrel2 another.ru -O recv_addr=tcp://127.0.0.1:9995 -O send_addr=tcp://127.0.0.1:9994 +``` + +#### Options + +* `recv_addr` - This is the `send_spec` option from `Handler` configuration in `mongrel2.conf`. Default: `tcp://127.0.0.1:9997` +* `send_addr` - This is the `recv_spec` option from `Handler` configuration in your `mongrel2.conf`. Default: `tcp://127.0.0.1:9996` + +#### Processing HTTPS requests from Mongrel2 1.7 + +Set `HTTPS` env to `true`. + +```bash +HTTPS=true [bundle exec] rackup -s mongrel2 application.ru +``` + +For Mongrel2 1.8 and newer this is not necessary. + +### Developing custom bare Handler + +TBD + +Versioning +---------- + +Starting from version `0.1.0` this gem follows [semantic versioning](http://semver.org) policy. + +Usage/Examples +----- + +* [examples/http\_0mq.rb](https://github.com/perplexes/m2r/blob/master/example/http_0mq.rb) is a test little servlet thing (based on what comes with mongrel2) +* [examples/lobster.ru](https://github.com/perplexes/m2r/blob/master/example/lobster.ru) is a rackup file using the Rack handler that'll serve Rack's funny little lobster app + + Contributing ------------ -Once you've made your great commits: +In the spirit of [free software][free-sw], **everyone** is encouraged to help +improve this project. -1. Fork m2r -2. Create a topic branch - `git checkout -b my_branch` -3. Push to your branch - `git push origin my_branch` -4. Send a pull request +[free-sw]: http://www.fsf.org/licensing/essays/free-sw.html +Here are some ways *you* can contribute: +* by using alpha, beta, and prerelease versions +* by reporting bugs +* by suggesting new features +* by writing or editing documentation +* by writing tests +* by writing code (**no patch is too small**: fix typos, add comments, clean up + inconsistent whitespace) +* by refactoring code +* by closing [issues][] +* by reviewing patches + +[issues]: https://github.com/perplexes/m2r/issues + +[Read Contributing page](https://github.com/perplexes/m2r/wiki/Contributing) before sending Pull Request :) + +Submitting an Issue +------------------- + +We use the [GitHub issue tracker][issues] to track bugs and features. Before +submitting a bug report or feature request, check to make sure it hasn't +already been submitted. When submitting a bug report, please include a [Gist][] +that includes a stack trace and any details that may be necessary to reproduce +the bug, including your gem version, Ruby version, and operating system. +Ideally, a bug report should include a pull request with failing tests. + +[gist]: https://gist.github.com/ + +Submitting a Pull Request +------------------------- +0. [Read Contributing page](https://github.com/perplexes/m2r/wiki/Contributing) +1. [Fork the repository.][fork] +2. [Create a topic branch.][branch] +3. Add tests for your unimplemented feature or bug fix. +4. Run `bundle exec rake`. If your test pass, return to step 3. +5. Implement your feature or bug fix. +6. Run `bundle exec rake`. If your tests fail, return to step 5. +7. Add, commit, and push your changes. +8. [Submit a pull request.][pr] + +[fork]: http://help.github.com/fork-a-repo/ +[branch]: http://learn.github.com/p/branching.html +[pr]: http://help.github.com/send-pull-requests/ + + +Supported Ruby Versions +----------------------- + +This library aims to support and is [tested against](http://travis-ci.org/perplexes/m2r) the following Ruby implementations: + +- Ruby 1.9.2 +- Ruby 1.9.3 +- JRuby +- Rubinius + + +legal +----------------------- + +Mongrel2 is a registered trademark of [Zed A. Shaw](http://zedshaw.com/) who wrote it. And it is awesome.