From 3cd116f247fa99c38d0f4059fca987463d9afb09 Mon Sep 17 00:00:00 2001 From: Gaius Novus Date: Sun, 31 May 2009 12:05:17 -0400 Subject: [PATCH] appended .rdoc to README so GitHub processes it properly --- README | 352 ----------------------------------------------------------- README.rdoc | 352 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 352 insertions(+), 352 deletions(-) delete mode 100644 README create mode 100644 README.rdoc diff --git a/README b/README deleted file mode 100644 index 5359f42..0000000 --- a/README +++ /dev/null @@ -1,352 +0,0 @@ -= Rack, a modular Ruby webserver interface - -Rack provides a minimal, modular and adaptable interface for developing -web applications in Ruby. By wrapping HTTP requests and responses in -the simplest way possible, it unifies and distills the API for web -servers, web frameworks, and software in between (the so-called -middleware) into a single method call. - -The exact details of this are described in the Rack specification, -which all Rack applications should conform to. - -== Specification changes in this release - -With Rack 1.0, the Rack specification (found in SPEC) changed in the -following backward-incompatible ways. This was done to properly -support Ruby 1.9 and to deprecate some problematic techniques: - -* Rack::VERSION has been pushed to [1,0]. -* Header values must be Strings now, split on "\n". -* rack.input must be rewindable and support reading into a buffer, - wrap with Rack::RewindableInput if it isn't. -* Content-Length can be missing, in this case chunked transfer - encoding is used. -* Bodies can now additionally respond to #to_path with a filename to - be served. -* String bodies are deprecated and will not work with Ruby 1.9, use an - Array with a single String instead. -* rack.session is now specified. - -== Supported web servers - -The included *handlers* connect all kinds of web servers to Rack: -* Mongrel -* EventedMongrel -* SwiftipliedMongrel -* WEBrick -* FCGI -* CGI -* SCGI -* LiteSpeed -* Thin - -These web servers include Rack handlers in their distributions: -* Ebb -* Fuzed -* Phusion Passenger (which is mod_rack for Apache and for nginx) -* Unicorn - -Any valid Rack app will run the same on all these handlers, without -changing anything. - -== Supported web frameworks - -The included *adapters* connect Rack with existing Ruby web frameworks: -* Camping - -These frameworks include Rack adapters in their distributions: -* Camping -* Coset -* Halcyon -* Mack -* Maveric -* Merb -* Racktools::SimpleApplication -* Ramaze -* Ruby on Rails -* Rum -* Sinatra -* Sin -* Vintage -* Waves -* Wee - -Current links to these projects can be found at -http://wiki.ramaze.net/Home#other-frameworks - -== Available middleware - -Between the server and the framework, Rack can be customized to your -applications needs using middleware, for example: -* Rack::URLMap, to route to multiple applications inside the same process. -* Rack::CommonLogger, for creating Apache-style logfiles. -* Rack::ShowException, for catching unhandled exceptions and - presenting them in a nice and helpful way with clickable backtrace. -* Rack::File, for serving static files. -* ...many others! - -All these components use the same interface, which is described in -detail in the Rack specification. These optional components can be -used in any way you wish. - -== Convenience - -If you want to develop outside of existing frameworks, implement your -own ones, or develop middleware, Rack provides many helpers to create -Rack applications quickly and without doing the same web stuff all -over: -* Rack::Request, which also provides query string parsing and - multipart handling. -* Rack::Response, for convenient generation of HTTP replies and - cookie handling. -* Rack::MockRequest and Rack::MockResponse for efficient and quick - testing of Rack application without real HTTP round-trips. - -== rack-contrib - -The plethora of useful middleware created the need for a project that -collects fresh Rack middleware. rack-contrib includes a variety of -add-on components for Rack and it is easy to contribute new modules. - -* http://github.com/rack/rack-contrib - -== rackup - -rackup is a useful tool for running Rack applications, which uses the -Rack::Builder DSL to configure middleware and build up applications -easily. - -rackup automatically figures out the environment it is run in, and -runs your application as FastCGI, CGI, or standalone with Mongrel or -WEBrick---all from the same configuration. - -== Quick start - -Try the lobster! - -Either with the embedded WEBrick starter: - - ruby -Ilib lib/rack/lobster.rb - -Or with rackup: - - bin/rackup -Ilib example/lobster.ru - -By default, the lobster is found at http://localhost:9292. - -== Installing with RubyGems - -A Gem of Rack is available. You can install it with: - - gem install rack - -I also provide a local mirror of the gems (and development snapshots) -at my site: - - gem install rack --source http://chneukirchen.org/releases/gems/ - -== Running the tests - -Testing Rack requires the test/spec testing framework: - - gem install test-spec - -There are two rake-based test tasks: - - rake test tests all the fast tests (no Handlers or Adapters) - rake fulltest runs all the tests - -The fast testsuite has no dependencies outside of the core Ruby -installation and test-spec. - -To run the test suite completely, you need: - - * camping - * fcgi - * memcache-client - * mongrel - * ruby-openid - * thin - -The full set of tests test FCGI access with lighttpd (on port -9203) so you will need lighttpd installed as well as the FCGI -libraries and the fcgi gem: - -Download and install lighttpd: - - http://www.lighttpd.net/download - -Installing the FCGI libraries: - - curl -O http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz - tar xzvf fcgi-2.4.0.tar.gz - cd fcgi-2.4.0 - ./configure --prefix=/usr/local - make - sudo make install - cd .. - -Installing the Ruby fcgi gem: - - gem install fcgi - -Furthermore, to test Memcache sessions, you need memcached (will be -run on port 11211) and memcache-client installed. - -== History - -* March 3rd, 2007: First public release 0.1. - -* May 16th, 2007: Second public release 0.2. - * HTTP Basic authentication. - * Cookie Sessions. - * Static file handler. - * Improved Rack::Request. - * Improved Rack::Response. - * Added Rack::ShowStatus, for better default error messages. - * Bug fixes in the Camping adapter. - * Removed Rails adapter, was too alpha. - -* February 26th, 2008: Third public release 0.3. - * LiteSpeed handler, by Adrian Madrid. - * SCGI handler, by Jeremy Evans. - * Pool sessions, by blink. - * OpenID authentication, by blink. - * :Port and :File options for opening FastCGI sockets, by blink. - * Last-Modified HTTP header for Rack::File, by blink. - * Rack::Builder#use now accepts blocks, by Corey Jewett. - (See example/protectedlobster.ru) - * HTTP status 201 can contain a Content-Type and a body now. - * Many bugfixes, especially related to Cookie handling. - -* August 21st, 2008: Fourth public release 0.4. - * New middleware, Rack::Deflater, by Christoffer Sawicki. - * OpenID authentication now needs ruby-openid 2. - * New Memcache sessions, by blink. - * Explicit EventedMongrel handler, by Joshua Peek - * Rack::Reloader is not loaded in rackup development mode. - * rackup can daemonize with -D. - * Many bugfixes, especially for pool sessions, URLMap, thread safety - and tempfile handling. - * Improved tests. - * Rack moved to Git. - -* January 6th, 2009: Fifth public release 0.9. - * Rack is now managed by the Rack Core Team. - * Rack::Lint is stricter and follows the HTTP RFCs more closely. - * Added ConditionalGet middleware. - * Added ContentLength middleware. - * Added Deflater middleware. - * Added Head middleware. - * Added MethodOverride middleware. - * Rack::Mime now provides popular MIME-types and their extension. - * Mongrel Header now streams. - * Added Thin handler. - * Official support for swiftiplied Mongrel. - * Secure cookies. - * Made HeaderHash case-preserving. - * Many bugfixes and small improvements. - -* January 9th, 2009: Sixth public release 0.9.1. - * Fix directory traversal exploits in Rack::File and Rack::Directory. - -* April 25th, 2009: Seventh public release 1.0.0. - * SPEC change: Rack::VERSION has been pushed to [1,0]. - * SPEC change: header values must be Strings now, split on "\n". - * SPEC change: Content-Length can be missing, in this case chunked transfer - encoding is used. - * SPEC change: rack.input must be rewindable and support reading into - a buffer, wrap with Rack::RewindableInput if it isn't. - * SPEC change: rack.session is now specified. - * SPEC change: Bodies can now additionally respond to #to_path with - a filename to be served. - * NOTE: String bodies break in 1.9, use an Array consisting of a - single String instead. - * New middleware Rack::Lock. - * New middleware Rack::ContentType. - * Rack::Reloader has been rewritten. - * Major update to Rack::Auth::OpenID. - * Support for nested parameter parsing in Rack::Response. - * Support for redirects in Rack::Response. - * HttpOnly cookie support in Rack::Response. - * The Rakefile has been rewritten. - * Many bugfixes and small improvements. - -== Contact - -Please post bugs, suggestions and patches to -the bug tracker at . - -Mailing list archives are available at -. - -Git repository (send Git patches to the mailing list): -* http://github.com/rack/rack -* http://git.vuxu.org/cgi-bin/gitweb.cgi?p=rack.git - -You are also welcome to join the #rack channel on irc.freenode.net. - -== Thanks - -The Rack Core Team, consisting of - -* Christian Neukirchen (chneukirchen) -* James Tucker (raggi) -* Josh Peek (josh) -* Michael Fellinger (manveru) -* Ryan Tomayko (rtomayko) -* Scytrin dai Kinthra (scytrin) - -would like to thank: - -* Adrian Madrid, for the LiteSpeed handler. -* Christoffer Sawicki, for the first Rails adapter and Rack::Deflater. -* Tim Fletcher, for the HTTP authentication code. -* Luc Heinrich for the Cookie sessions, the static file handler and bugfixes. -* Armin Ronacher, for the logo and racktools. -* Aredridel, Ben Alpert, Dan Kubb, Daniel Roethlisberger, Matt Todd, - Tom Robinson, Phil Hagelberg, and S. Brent Faulkner for bug fixing - and other improvements. -* Brian Candler, for Rack::ContentType. -* Graham Batty, for improved handler loading. -* Stephen Bannasch, for bug reports and documentation. -* Gary Wright, for proposing a better Rack::Response interface. -* Jonathan Buch, for improvements regarding Rack::Response. -* Armin Röhrl, for tracking down bugs in the Cookie generator. -* Alexander Kellett for testing the Gem and reviewing the announcement. -* Marcus Rückert, for help with configuring and debugging lighttpd. -* The WSGI team for the well-done and documented work they've done and - Rack builds up on. -* All bug reporters and patch contributers not mentioned above. - -== Copyright - -Copyright (C) 2007, 2008, 2009 Christian Neukirchen - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to -deal in the Software without restriction, including without limitation the -rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -sell copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER -IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -== Links - -Rack:: -Rack's Rubyforge project:: -Official Rack repositories:: -Rack Lighthouse Bug Tracking:: -rack-devel mailing list:: - -Christian Neukirchen:: - diff --git a/README.rdoc b/README.rdoc new file mode 100644 index 0000000..5359f42 --- /dev/null +++ b/README.rdoc @@ -0,0 +1,352 @@ += Rack, a modular Ruby webserver interface + +Rack provides a minimal, modular and adaptable interface for developing +web applications in Ruby. By wrapping HTTP requests and responses in +the simplest way possible, it unifies and distills the API for web +servers, web frameworks, and software in between (the so-called +middleware) into a single method call. + +The exact details of this are described in the Rack specification, +which all Rack applications should conform to. + +== Specification changes in this release + +With Rack 1.0, the Rack specification (found in SPEC) changed in the +following backward-incompatible ways. This was done to properly +support Ruby 1.9 and to deprecate some problematic techniques: + +* Rack::VERSION has been pushed to [1,0]. +* Header values must be Strings now, split on "\n". +* rack.input must be rewindable and support reading into a buffer, + wrap with Rack::RewindableInput if it isn't. +* Content-Length can be missing, in this case chunked transfer + encoding is used. +* Bodies can now additionally respond to #to_path with a filename to + be served. +* String bodies are deprecated and will not work with Ruby 1.9, use an + Array with a single String instead. +* rack.session is now specified. + +== Supported web servers + +The included *handlers* connect all kinds of web servers to Rack: +* Mongrel +* EventedMongrel +* SwiftipliedMongrel +* WEBrick +* FCGI +* CGI +* SCGI +* LiteSpeed +* Thin + +These web servers include Rack handlers in their distributions: +* Ebb +* Fuzed +* Phusion Passenger (which is mod_rack for Apache and for nginx) +* Unicorn + +Any valid Rack app will run the same on all these handlers, without +changing anything. + +== Supported web frameworks + +The included *adapters* connect Rack with existing Ruby web frameworks: +* Camping + +These frameworks include Rack adapters in their distributions: +* Camping +* Coset +* Halcyon +* Mack +* Maveric +* Merb +* Racktools::SimpleApplication +* Ramaze +* Ruby on Rails +* Rum +* Sinatra +* Sin +* Vintage +* Waves +* Wee + +Current links to these projects can be found at +http://wiki.ramaze.net/Home#other-frameworks + +== Available middleware + +Between the server and the framework, Rack can be customized to your +applications needs using middleware, for example: +* Rack::URLMap, to route to multiple applications inside the same process. +* Rack::CommonLogger, for creating Apache-style logfiles. +* Rack::ShowException, for catching unhandled exceptions and + presenting them in a nice and helpful way with clickable backtrace. +* Rack::File, for serving static files. +* ...many others! + +All these components use the same interface, which is described in +detail in the Rack specification. These optional components can be +used in any way you wish. + +== Convenience + +If you want to develop outside of existing frameworks, implement your +own ones, or develop middleware, Rack provides many helpers to create +Rack applications quickly and without doing the same web stuff all +over: +* Rack::Request, which also provides query string parsing and + multipart handling. +* Rack::Response, for convenient generation of HTTP replies and + cookie handling. +* Rack::MockRequest and Rack::MockResponse for efficient and quick + testing of Rack application without real HTTP round-trips. + +== rack-contrib + +The plethora of useful middleware created the need for a project that +collects fresh Rack middleware. rack-contrib includes a variety of +add-on components for Rack and it is easy to contribute new modules. + +* http://github.com/rack/rack-contrib + +== rackup + +rackup is a useful tool for running Rack applications, which uses the +Rack::Builder DSL to configure middleware and build up applications +easily. + +rackup automatically figures out the environment it is run in, and +runs your application as FastCGI, CGI, or standalone with Mongrel or +WEBrick---all from the same configuration. + +== Quick start + +Try the lobster! + +Either with the embedded WEBrick starter: + + ruby -Ilib lib/rack/lobster.rb + +Or with rackup: + + bin/rackup -Ilib example/lobster.ru + +By default, the lobster is found at http://localhost:9292. + +== Installing with RubyGems + +A Gem of Rack is available. You can install it with: + + gem install rack + +I also provide a local mirror of the gems (and development snapshots) +at my site: + + gem install rack --source http://chneukirchen.org/releases/gems/ + +== Running the tests + +Testing Rack requires the test/spec testing framework: + + gem install test-spec + +There are two rake-based test tasks: + + rake test tests all the fast tests (no Handlers or Adapters) + rake fulltest runs all the tests + +The fast testsuite has no dependencies outside of the core Ruby +installation and test-spec. + +To run the test suite completely, you need: + + * camping + * fcgi + * memcache-client + * mongrel + * ruby-openid + * thin + +The full set of tests test FCGI access with lighttpd (on port +9203) so you will need lighttpd installed as well as the FCGI +libraries and the fcgi gem: + +Download and install lighttpd: + + http://www.lighttpd.net/download + +Installing the FCGI libraries: + + curl -O http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz + tar xzvf fcgi-2.4.0.tar.gz + cd fcgi-2.4.0 + ./configure --prefix=/usr/local + make + sudo make install + cd .. + +Installing the Ruby fcgi gem: + + gem install fcgi + +Furthermore, to test Memcache sessions, you need memcached (will be +run on port 11211) and memcache-client installed. + +== History + +* March 3rd, 2007: First public release 0.1. + +* May 16th, 2007: Second public release 0.2. + * HTTP Basic authentication. + * Cookie Sessions. + * Static file handler. + * Improved Rack::Request. + * Improved Rack::Response. + * Added Rack::ShowStatus, for better default error messages. + * Bug fixes in the Camping adapter. + * Removed Rails adapter, was too alpha. + +* February 26th, 2008: Third public release 0.3. + * LiteSpeed handler, by Adrian Madrid. + * SCGI handler, by Jeremy Evans. + * Pool sessions, by blink. + * OpenID authentication, by blink. + * :Port and :File options for opening FastCGI sockets, by blink. + * Last-Modified HTTP header for Rack::File, by blink. + * Rack::Builder#use now accepts blocks, by Corey Jewett. + (See example/protectedlobster.ru) + * HTTP status 201 can contain a Content-Type and a body now. + * Many bugfixes, especially related to Cookie handling. + +* August 21st, 2008: Fourth public release 0.4. + * New middleware, Rack::Deflater, by Christoffer Sawicki. + * OpenID authentication now needs ruby-openid 2. + * New Memcache sessions, by blink. + * Explicit EventedMongrel handler, by Joshua Peek + * Rack::Reloader is not loaded in rackup development mode. + * rackup can daemonize with -D. + * Many bugfixes, especially for pool sessions, URLMap, thread safety + and tempfile handling. + * Improved tests. + * Rack moved to Git. + +* January 6th, 2009: Fifth public release 0.9. + * Rack is now managed by the Rack Core Team. + * Rack::Lint is stricter and follows the HTTP RFCs more closely. + * Added ConditionalGet middleware. + * Added ContentLength middleware. + * Added Deflater middleware. + * Added Head middleware. + * Added MethodOverride middleware. + * Rack::Mime now provides popular MIME-types and their extension. + * Mongrel Header now streams. + * Added Thin handler. + * Official support for swiftiplied Mongrel. + * Secure cookies. + * Made HeaderHash case-preserving. + * Many bugfixes and small improvements. + +* January 9th, 2009: Sixth public release 0.9.1. + * Fix directory traversal exploits in Rack::File and Rack::Directory. + +* April 25th, 2009: Seventh public release 1.0.0. + * SPEC change: Rack::VERSION has been pushed to [1,0]. + * SPEC change: header values must be Strings now, split on "\n". + * SPEC change: Content-Length can be missing, in this case chunked transfer + encoding is used. + * SPEC change: rack.input must be rewindable and support reading into + a buffer, wrap with Rack::RewindableInput if it isn't. + * SPEC change: rack.session is now specified. + * SPEC change: Bodies can now additionally respond to #to_path with + a filename to be served. + * NOTE: String bodies break in 1.9, use an Array consisting of a + single String instead. + * New middleware Rack::Lock. + * New middleware Rack::ContentType. + * Rack::Reloader has been rewritten. + * Major update to Rack::Auth::OpenID. + * Support for nested parameter parsing in Rack::Response. + * Support for redirects in Rack::Response. + * HttpOnly cookie support in Rack::Response. + * The Rakefile has been rewritten. + * Many bugfixes and small improvements. + +== Contact + +Please post bugs, suggestions and patches to +the bug tracker at . + +Mailing list archives are available at +. + +Git repository (send Git patches to the mailing list): +* http://github.com/rack/rack +* http://git.vuxu.org/cgi-bin/gitweb.cgi?p=rack.git + +You are also welcome to join the #rack channel on irc.freenode.net. + +== Thanks + +The Rack Core Team, consisting of + +* Christian Neukirchen (chneukirchen) +* James Tucker (raggi) +* Josh Peek (josh) +* Michael Fellinger (manveru) +* Ryan Tomayko (rtomayko) +* Scytrin dai Kinthra (scytrin) + +would like to thank: + +* Adrian Madrid, for the LiteSpeed handler. +* Christoffer Sawicki, for the first Rails adapter and Rack::Deflater. +* Tim Fletcher, for the HTTP authentication code. +* Luc Heinrich for the Cookie sessions, the static file handler and bugfixes. +* Armin Ronacher, for the logo and racktools. +* Aredridel, Ben Alpert, Dan Kubb, Daniel Roethlisberger, Matt Todd, + Tom Robinson, Phil Hagelberg, and S. Brent Faulkner for bug fixing + and other improvements. +* Brian Candler, for Rack::ContentType. +* Graham Batty, for improved handler loading. +* Stephen Bannasch, for bug reports and documentation. +* Gary Wright, for proposing a better Rack::Response interface. +* Jonathan Buch, for improvements regarding Rack::Response. +* Armin Röhrl, for tracking down bugs in the Cookie generator. +* Alexander Kellett for testing the Gem and reviewing the announcement. +* Marcus Rückert, for help with configuring and debugging lighttpd. +* The WSGI team for the well-done and documented work they've done and + Rack builds up on. +* All bug reporters and patch contributers not mentioned above. + +== Copyright + +Copyright (C) 2007, 2008, 2009 Christian Neukirchen + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to +deal in the Software without restriction, including without limitation the +rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +sell copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +== Links + +Rack:: +Rack's Rubyforge project:: +Official Rack repositories:: +Rack Lighthouse Bug Tracking:: +rack-devel mailing list:: + +Christian Neukirchen:: + -- 1.5.4