← Back
Editing: page-README_rdoc.ri
U:RDoc::TopLevel[ i I"README.rdoc:ETcRDoc::Parser::Simpleo:RDoc::Markup::Document: @parts[�S:RDoc::Markup::Heading: leveli: textI".\Rack, a modular Ruby webserver interface;To: RDoc::Markup::BlankLine o: RDoc::Markup::Paragraph;[I"|{<img src="https://rack.github.io/logo.png" width="400" alt="rack powers web applications" />}[https://rack.github.io/];T@ o; ;[ I"w{<img src="https://circleci.com/gh/rack/rack.svg?style=svg" alt="CircleCI" />}[https://circleci.com/gh/rack/rack] ;TI"g{<img src="https://badge.fury.io/rb/rack.svg" alt="Gem Version" />}[http://badge.fury.io/rb/rack] ;TI"{<img src="https://api.dependabot.com/badges/compatibility_score?dependency-name=rack&package-manager=bundler&version-scheme=semver" alt="SemVer Stability" />}[https://dependabot.com/compatibility-score.html?dependency-name=rack&package-manager=bundler&version-scheme=semver] ;TI"|{<img src="http://inch-ci.org/github/rack/rack.svg?branch=master" alt="Inline docs" />}[http://inch-ci.org/github/rack/rack];T@ o; ;[ I"O\Rack provides a minimal, modular, and adaptable interface for developing ;TI"Jweb applications in Ruby. By wrapping HTTP requests and responses in ;TI"Hthe simplest way possible, it unifies and distills the API for web ;TI"Eservers, web frameworks, and software in between (the so-called ;TI"+middleware) into a single method call.;T@ o; ;[I"IThe exact details of this are described in the \Rack specification, ;TI"4which all \Rack applications should conform to.;T@ S; ; i; I"Supported web servers;T@ o; ;[I"GThe included *handlers* connect all kinds of web servers to \Rack:;T@ o:RDoc::Markup::List: @type: BULLET: @items[ o:RDoc::Markup::ListItem: @label0;[o; ;[I"-WEBrick[https://github.com/ruby/webrick];To;;0;[o; ;[I" FCGI;To;;0;[o; ;[I"CGI;To;;0;[o; ;[I" SCGI;To;;0;[o; ;[I".LiteSpeed[https://www.litespeedtech.com/];To;;0;[o; ;[I")Thin[https://rubygems.org/gems/thin];T@ o; ;[I"EThese web servers include \Rack handlers in their distributions:;T@ o;;;;[ o;;0;[o; ;[I"*Agoo[https://github.com/ohler55/agoo];To;;0;[o; ;[I"/Falcon[https://github.com/socketry/falcon];To;;0;[o; ;[I"0Iodine[https://github.com/boazsegev/iodine];To;;0;[o; ;[I"*{NGINX Unit}[https://unit.nginx.org/];To;;0;[o; ;[I"h{Phusion Passenger}[https://www.phusionpassenger.com/] (which is mod_rack for Apache and for nginx);To;;0;[o; ;[I"Puma[https://puma.io/];To;;0;[o; ;[I"'Unicorn[https://yhbt.net/unicorn/];To;;0;[o; ;[I"8uWSGI[https://uwsgi-docs.readthedocs.io/en/latest/];T@ o; ;[I"JAny valid \Rack app will run the same on all these handlers, without ;TI"changing anything.;T@ S; ; i; I" Supported web frameworks;T@ o; ;[I"<These frameworks and many others support the \Rack API:;T@ o;;;;[o;;0;[o; ;[I"*Camping[http://www.ruby-camping.com/];To;;0;[o; ;[I"2Coset[http://leahneukirchen.org/repos/coset/];To;;0;[o; ;[I""Hanami[https://hanamirb.org/];To;;0;[o; ;[I"#Padrino[http://padrinorb.com/];To;;0;[o; ;[I" Ramaze[http://ramaze.net/];To;;0;[o; ;[I".Roda[https://github.com/jeremyevans/roda];To;;0;[o; ;[I".{Ruby on Rails}[https://rubyonrails.org/];To;;0;[o; ;[I"/Rum[https://github.com/leahneukirchen/rum];To;;0;[o; ;[I"#Sinatra[http://sinatrarb.com/];To;;0;[o; ;[I"/Utopia[https://github.com/socketry/utopia];To;;0;[o; ;[I",WABuR[https://github.com/ohler55/wabur];T@ S; ; i; I",Available middleware shipped with \Rack;T@ o; ;[I"KBetween the server and the framework, \Rack can be customized to your ;TI"Papplications needs using middleware. \Rack itself ships with the following ;TI"middleware:;T@ o;;;;[ o;;0;[o; ;[I"CRack::Chunked, for streaming responses using chunked encoding.;To;;0;[o; ;[I"<Rack::CommonLogger, for creating Apache-style logfiles.;To;;0;[o; ;[I"RRack::ConditionalGet, for returning not modified responses when the response ;TI"has not changed.;To;;0;[o; ;[I"ORack::Config, for modifying the environment before processing the request.;To;;0;[o; ;[I"ORack::ContentLength, for setting Content-Length header based on body size.;To;;0;[o; ;[I"NRack::ContentType, for setting default Content-Type header for responses.;To;;0;[o; ;[I"9Rack::Deflater, for compressing responses with gzip.;To;;0;[o; ;[I":Rack::ETag, for setting ETag header on string bodies.;To;;0;[o; ;[I"GRack::Events, for providing easy hooks when a request is received ;TI"#and when the response is sent.;To;;0;[o; ;[I"+Rack::Files, for serving static files.;To;;0;[o; ;[I"?Rack::Head, for returning an empty body for HEAD requests.;To;;0;[o; ;[I";Rack::Lint, for checking conformance to the \Rack API.;To;;0;[o; ;[I"8Rack::Lock, for serializing requests using a mutex.;To;;0;[o; ;[I"ARack::Logger, for setting a logger to handle logging errors.;To;;0;[o; ;[I"QRack::MethodOverride, for modifying the request method based on a submitted ;TI"parameter.;To;;0;[o; ;[I"NRack::Recursive, for including data from other paths in the application, ;TI"+and for performing internal redirects.;To;;0;[o; ;[I"DRack::Reloader, for reloading files if they have been modified.;To;;0;[o; ;[I"KRack::Runtime, for including a response header with the time taken to ;TI"process the request.;To;;0;[o; ;[I"IRack::Sendfile, for working with web servers that can use optimized ;TI"(file serving for file system paths.;To;;0;[o; ;[I"@Rack::ShowException, for catching unhandled exceptions and ;TI"Hpresenting them in a nice and helpful way with clickable backtrace.;To;;0;[o; ;[I"IRack::ShowStatus, for using nice error pages for empty client error ;TI"responses.;To;;0;[o; ;[I"ARack::Static, for more configurable serving of static files.;To;;0;[o; ;[I"JRack::TempfileReaper, for removing temporary files creating during a ;TI" request.;T@ o; ;[I"HAll these components use the same interface, which is described in ;TI"Jdetail in the \Rack specification. These optional components can be ;TI" used in any way you wish.;T@ S; ; i; I"Convenience;T@ o; ;[ I"KIf you want to develop outside of existing frameworks, implement your ;TI"Lown ones, or develop middleware, \Rack provides many helpers to create ;TI"I\Rack applications quickly and without doing the same web stuff all ;TI" over:;T@ o;;;;[o;;0;[o; ;[I"ARack::Request, which also provides query string parsing and ;TI"multipart handling.;To;;0;[o; ;[I"CRack::Response, for convenient generation of HTTP replies and ;TI"cookie handling.;To;;0;[o; ;[I"FRack::MockRequest and Rack::MockResponse for efficient and quick ;TI"@testing of \Rack application without real HTTP round-trips.;To;;0;[o; ;[I"CRack::Cascade, for trying additional \Rack applications if an ;TI"Fapplication returns a not found or method not supported response.;To;;0;[o; ;[I"FRack::Directory, for serving files under a given directory, with ;TI"directory indexes.;To;;0;[o; ;[I"7Rack::MediaType, for parsing Content-Type headers.;To;;0;[o; ;[I"FRack::Mime, for determining Content-Type based on file extension.;To;;0;[o; ;[I"GRack::RewindableInput, for making any IO object rewindable, using ;TI" a temporary file buffer.;To;;0;[o; ;[I"MRack::URLMap, to route to multiple applications inside the same process.;T@ S; ; i; I"rack-contrib;T@ o; ;[I"KThe plethora of useful middleware created the need for a project that ;TI"Jcollects fresh \Rack middleware. rack-contrib includes a variety of ;TI"Jadd-on components for \Rack and it is easy to contribute new modules.;T@ o;;;;[o;;0;[o; ;[I")https://github.com/rack/rack-contrib;T@ S; ; i; I" rackup;T@ o; ;[I"Lrackup is a useful tool for running \Rack applications, which uses the ;TI"IRack::Builder DSL to configure middleware and build up applications ;TI" easily.;T@ o; ;[I"Hrackup automatically figures out the environment it is run in, and ;TI"Fruns your application as FastCGI, CGI, or WEBrick---all from the ;TI"same configuration.;T@ S; ; i; I"Quick start;T@ o; ;[I"Try the lobster!;T@ o; ;[I".Either with the embedded WEBrick starter:;T@ o:RDoc::Markup::Verbatim;[I"$ruby -Ilib lib/rack/lobster.rb ;T: @format0o; ;[I"Or with rackup:;T@ o;;[I")bin/rackup -Ilib example/lobster.ru ;T;0o; ;[I"?By default, the lobster is found at http://localhost:9292.;T@ S; ; i; I" Installing with RubyGems;T@ o; ;[I"lA Gem of \Rack is available at {rubygems.org}[https://rubygems.org/gems/rack]. You can install it with:;T@ o;;[I"gem install rack ;T;0S; ; i; I" Usage;T@ o; ;[I"$You should require the library:;T@ o;;[I"require 'rack' ;T;0o; ;[I"W\Rack uses autoload to automatically load other files \Rack ships with on demand, ;TI"Tso you should not need require paths under +rack+. If you require paths under ;TI"K+rack+ without requiring +rack+ itself, things may not work correctly.;T@ S; ; i; I"Configuration;T@ o; ;[I"TSeveral parameters can be modified on Rack::Utils to configure \Rack behaviour.;T@ o; ;[I" e.g:;T@ o;;[I"'Rack::Utils.key_space_limit = 128 ;T;0S; ; i; I"'`RACK_QUERY_PARSER_BYTESIZE_LIMIT`;T@ o; ;[ I"VThis environment variable sets the default for the maximum query string bytesize ;TI"Uthat `Rack::QueryParser` will attempt to parse. Attempts to use a query string ;TI"8that exceeds this number of bytes will result in a ;TI"T`Rack::QueryParser::QueryLimitError` exception. If this enviroment variable is ;TI"Uprovided, it must be an integer, or `Rack::QueryParser` will raise an exception.;T@ o; ;[I"RThe default limit can be overridden on a per-`Rack::QueryParser` basis using ;TI"Qthe `bytesize_limit` keyword argument when creating the `Rack::QueryParser`.;T@ S; ; i; I"%`RACK_QUERY_PARSER_PARAMS_LIMIT`;T@ o; ;[ I"PThis environment variable sets the default for the maximum number of query ;TI"Sparameters that `Rack::QueryParser` will attempt to parse. Attempts to use a ;TI"Mquery string with more than this many query parameters will result in a ;TI"T`Rack::QueryParser::QueryLimitError` exception. If this enviroment variable is ;TI"Uprovided, it must be an integer, or `Rack::QueryParser` will raise an exception.;T@ o; ;[I"RThe default limit can be overridden on a per-`Rack::QueryParser` basis using ;TI"Othe `params_limit` keyword argument when creating the `Rack::QueryParser`.;T@ o; ;[ I"OThis is implemented by counting the number of parameter separators in the ;TI"Nquery string, before attempting parsing, so if the same parameter key is ;TI"Oused multiple times in the query, each counts as a separate parameter for ;TI"this check.;T@ S; ; i; I"4`RACK_MULTIPART_BUFFERED_UPLOAD_BYTESIZE_LIMIT`;T@ o; ;[ I"OThis environment variable sets the maximum amount of memory Rack will use ;TI"Pto buffer multipart parameters when parsing a request body. This considers ;TI"Lthe size of the multipart mime headers and the body part for multipart ;TI"Kparameters that are buffered in memory and do not use tempfiles. This ;TI"&defaults to 16MB if not provided.;T@ S; ; i; I"key_space_limit;T@ o; ;[I"dThe default number of bytes to allow all parameters keys in a given parameter hash to take up. ;TI"aDoes not affect nested parameter hashes, so doesn't actually prevent an attacker from using ;TI"2more than this many bytes for parameter keys.;T@ o; ;[I""Defaults to 65536 characters.;T@ S; ; i; I"param_depth_limit;T@ o; ;[I":The maximum amount of nesting allowed in parameters. ;TI"BFor example, if set to 3, this query string would be allowed:;T@ o;;[I"?a[b][c]=d ;T;0o; ;[I"0but this query string would not be allowed:;T@ o;;[I"?a[b][c][d]=e ;T;0o; ;[I"SLimiting the depth prevents a possible stack overflow when parsing parameters.;T@ o; ;[I"Defaults to 100.;T@ S; ; i; I"multipart_file_limit;T@ o; ;[I"HThe maximum number of parts with a filename a request can contain. ;TI"PAccepting too many part can lead to the server running out of file handles.;T@ o; ;[I"dThe default is 128, which means that a single request can't upload more than 128 files at once.;T@ o; ;[I"Set to 0 for no limit.;T@ o; ;[I"NCan also be set via the +RACK_MULTIPART_FILE_LIMIT+ environment variable.;T@ o; ;[I"g(This is also aliased as +multipart_part_limit+ and +RACK_MULTIPART_PART_LIMIT+ for compatibility);T@ S; ; i; I" multipart_total_part_limit;T@ o; ;[I"TThe maximum total number of parts a request can contain of any type, including ;TI"(both file and non-file form fields.;T@ o; ;[I"TThe default is 4096, which means that a single request can't contain more than ;TI"4096 parts.;T@ o; ;[I"Set to 0 for no limit.;T@ o; ;[I"TCan also be set via the +RACK_MULTIPART_TOTAL_PART_LIMIT+ environment variable.;T@ S; ; i; I"Changelog;T@ o; ;[I"OSee {CHANGELOG.md}[https://github.com/rack/rack/blob/master/CHANGELOG.md].;T@ S; ; i; I"Contributing;T@ o; ;[I"USee {CONTRIBUTING.md}[https://github.com/rack/rack/blob/master/CONTRIBUTING.md].;T@ S; ; i; I" Contact;T@ o; ;[I"2Please post bugs, suggestions and patches to ;TI"Fthe bug tracker at {issues}[https://github.com/rack/rack/issues].;T@ o; ;[ I"KPlease post security related bugs and suggestions to the core team at ;TI"]<https://groups.google.com/forum/#!forum/rack-core> or rack-core@googlegroups.com. This ;TI"Tlist is not public. Due to wide usage of the library, it is strongly preferred ;TI"Mthat we manage timing in order to provide viable patches at the time of ;TI"Gdisclosure. Your assistance in this matter is greatly appreciated.;T@ o; ;[I",Mailing list archives are available at ;TI":<https://groups.google.com/forum/#!forum/rack-devel>.;T@ o; ;[I";Git repository (send Git patches to the mailing list):;T@ o;;;;[o;;0;[o; ;[I"!https://github.com/rack/rack;T@ o; ;[I"HYou are also welcome to join the #rack channel on irc.freenode.net.;T@ S; ; i; I" Thanks;T@ o; ;[I"'The \Rack Core Team, consisting of;T@ o;;;;[ o;;0;[o; ;[I"@Aaron Patterson (tenderlove[https://github.com/tenderlove]);To;;0;[o; ;[I"<Samuel Williams (ioquatix[https://github.com/ioquatix]);To;;0;[o; ;[I"?Jeremy Evans (jeremyevans[https://github.com/jeremyevans]);To;;0;[o; ;[I"CEileen Uchitelle (eileencodes[https://github.com/eileencodes]);To;;0;[o; ;[I";Matthew Draper (matthewd[https://github.com/matthewd]);To;;0;[o; ;[I"CRafael França (rafaelfranca[https://github.com/rafaelfranca]);T@ o; ;[I"and the \Rack Alumni;T@ o;;;;[o;;0;[o; ;[I"9Ryan Tomayko (rtomayko[https://github.com/rtomayko]);To;;0;[o; ;[I">Scytrin dai Kinthra (scytrin[https://github.com/scytrin]);To;;0;[o; ;[I"HLeah Neukirchen (leahneukirchen[https://github.com/leahneukirchen]);To;;0;[o; ;[I"3James Tucker (raggi[https://github.com/raggi]);To;;0;[o; ;[I".Josh Peek (josh[https://github.com/josh]);To;;0;[o; ;[I":José Valim (josevalim[https://github.com/josevalim]);To;;0;[o; ;[I"<Michael Fellinger (manveru[https://github.com/manveru]);To;;0;[o; ;[I"CSantiago Pastorino (spastorino[https://github.com/spastorino]);To;;0;[o; ;[I"3Konstantin Haase (rkh[https://github.com/rkh]);T@ o; ;[I"would like to thank:;T@ o;;;;[o;;0;[o; ;[I".Adrian Madrid, for the LiteSpeed handler.;To;;0;[o; ;[I"IChristoffer Sawicki, for the first Rails adapter and Rack::Deflater.;To;;0;[o; ;[I"4Tim Fletcher, for the HTTP authentication code.;To;;0;[o; ;[I"PLuc Heinrich for the Cookie sessions, the static file handler and bugfixes.;To;;0;[o; ;[I"0Armin Ronacher, for the logo and racktools.;To;;0;[o; ;[ I"EAlex Beregszaszi, Alexander Kahn, Anil Wadghule, Aredridel, Ben ;TI"GAlpert, Dan Kubb, Daniel Roethlisberger, Matt Todd, Tom Robinson, ;TI"IPhil Hagelberg, S. Brent Faulkner, Bosko Milekic, Daniel Rodríguez ;TI"KTroitiño, Genki Takiuchi, Geoffrey Grosenbach, Julien Sanchez, Kamal ;TI"JFariz Mahyuddin, Masayoshi Takahashi, Patrick Aljordm, Mig, Kazuhiro ;TI"BNishiyama, Jon Bardin, Konstantin Haase, Larry Siden, Matias ;TI"HKorhonen, Sam Ruby, Simon Chiang, Tim Connor, Timur Batyrshin, and ;TI"6Zach Brock for bug fixing and other improvements.;To;;0;[o; ;[I"GEric Wong, Hongli Lai, Jeremy Kemper for their continuous support ;TI"and API improvements.;To;;0;[o; ;[I"8Yehuda Katz and Carl Lerche for refactoring rackup.;To;;0;[o; ;[I"*Brian Candler, for Rack::ContentType.;To;;0;[o; ;[I"0Graham Batty, for improved handler loading.;To;;0;[o; ;[I"9Stephen Bannasch, for bug reports and documentation.;To;;0;[o; ;[I"BGary Wright, for proposing a better Rack::Response interface.;To;;0;[o; ;[I">Jonathan Buch, for improvements regarding Rack::Response.;To;;0;[o; ;[I"BArmin Röhrl, for tracking down bugs in the Cookie generator.;To;;0;[o; ;[I"JAlexander Kellett for testing the Gem and reviewing the announcement.;To;;0;[o; ;[I"GMarcus Rückert, for help with configuring and debugging lighttpd.;To;;0;[o; ;[I"JThe WSGI team for the well-done and documented work they've done and ;TI"\Rack builds up on.;To;;0;[o; ;[I"BAll bug reporters and patch contributors not mentioned above.;T@ S; ; i; I" Links;T@ o;;: NOTE;[ o;;[I" \Rack;T;[o; ;[I" <https://rack.github.io/>;To;;[I" Official \Rack repositories;T;[o; ;[I" <https://github.com/rack>;To;;[I"\Rack Bug Tracking;T;[o; ;[I"*<https://github.com/rack/rack/issues>;To;;[I" rack-devel mailing list;T;[o; ;[I"9<https://groups.google.com/forum/#!forum/rack-devel>;T@ S; ; i; I" License;T@ o; ;[I"T\Rack is released under the {MIT License}[https://opensource.org/licenses/MIT].;T: @file@:0@omit_headings_from_table_of_contents_below0
Save File
Cancel