rack 3.0.15 → 3.2.6

data/README.md

@@ -1,17 +1,55 @@
 # ![Rack](contrib/logo.webp)
 
-> **_NOTE:_** Rack v3.0.0 was recently released. Please check the [Upgrade
-> Guide](UPGRADE-GUIDE.md) for more details about migrating your existing
-> servers, middlewares and applications. For detailed information on specific
-> changes, check the [Change Log](CHANGELOG.md).
-
 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 bridge between web servers, web
 frameworks, and web application into a single method call.
 
 The exact details of this are described in the [Rack Specification], which all
-Rack applications should conform to.
+Rack applications should conform to. Browse the [Documentation] for more
+information.
+
+## Version support
+
+| Version  | Support                            |
+|----------|------------------------------------|
+|    3.2.x | Bug fixes and security patches.    |
+|    3.1.x | Security patches only.             |
+|    3.0.x | End of support.                    |
+|    2.2.x | Security patches only.             |
+| <= 2.1.x | End of support.                    |
+
+**Rack 2.2.x is in security maintenance mode**. Please upgrade to Rack 3.1+ as soon
+as possible to ensure you are receiving the latest features and security patches.
+
+Please see the [Security Policy] for more information.
+
+## Change log
+
+See the [Changelog](CHANGELOG.md) for a detailed list of changes in each version of Rack.
+
+### Rack 3.2 (latest release)
+
+This version of rack contains bug fixes and security patches.
+
+### Rack 3.1
+
+This version of rack contains bug fixes and security patches.
+
+### Rack 3.0
+
+This version of rack contains significant changes which are detailed in the
+[Upgrade Guide](UPGRADE-GUIDE.md). It is recommended to upgrade to Rack 3 as soon
+as possible to receive the latest features and security patches.
+
+### Rack 2.2
+
+This version of Rack is receiving security patches only, and effort should be
+made to move to Rack 3.
+
+Starting in Ruby 3.4 the `base64` dependency will no longer be a default gem,
+and may cause a warning or error about `base64` being missing. To correct this,
+add `base64` as a dependency to your project.
 
 ## Installation
 
@@ -20,10 +58,10 @@ by a [supported web framework](#supported-web-frameworks):
 
 ```bash
 # Install it generally:
-$ gem install rack --pre
+$ gem install rack
 
 # or, add it to your current application gemfile:
-$ bundle add rack --version 3.0.0
+$ bundle add rack
 ```
 
 If you need features from `Rack::Session` or `bin/rackup` please add those gems separately.
@@ -48,6 +86,8 @@ server](#supported-web-servers).
 ```bash
 $ gem install rackup
 $ rackup
+
+# In another shell:
 $ curl http://localhost:9292
 Hello World
 ```
@@ -57,11 +97,12 @@ Hello World
 Rack is supported by a wide range of servers, including:
 
 * [Agoo](https://github.com/ohler55/agoo)
-* [Falcon](https://github.com/socketry/falcon) **(Rack 3 Compatible)**
+* [Falcon](https://github.com/socketry/falcon)
 * [Iodine](https://github.com/boazsegev/iodine)
 * [NGINX Unit](https://unit.nginx.org/)
 * [Phusion Passenger](https://www.phusionpassenger.com/) (which is mod_rack for
   Apache and for nginx)
+* [Pitchfork](https://github.com/Shopify/pitchfork)
 * [Puma](https://puma.io/)
 * [Thin](https://github.com/macournoyer/thin)
 * [Unicorn](https://yhbt.net/unicorn/)
@@ -84,18 +125,15 @@ These frameworks and many others support the [Rack Specification]:
 
 * [Camping](https://github.com/camping/camping)
 * [Hanami](https://hanamirb.org/)
+* [Ramaze](https://github.com/ramaze/ramaze)
 * [Padrino](https://padrinorb.com/)
-* [Roda](https://github.com/jeremyevans/roda) **(Rack 3 Compatible)**
+* [Roda](https://github.com/jeremyevans/roda)
 * [Ruby on Rails](https://rubyonrails.org/)
+* [Rum](https://github.com/leahneukirchen/rum)
 * [Sinatra](https://sinatrarb.com/)
-* [Utopia](https://github.com/socketry/utopia) **(Rack 3 Compatible)**
+* [Utopia](https://github.com/socketry/utopia)
 * [WABuR](https://github.com/ohler55/wabur)
 
-### Older (possibly unsupported) web frameworks
-
-* [Ramaze](http://ramaze.net/)
-* [Rum](https://github.com/leahneukirchen/rum)
-
 ## Available middleware shipped with Rack
 
 Between the server and the framework, Rack can be customized to your
@@ -114,11 +152,9 @@ middleware:
 * `Rack::ETag` for setting `etag` header on bodies that can be buffered.
 * `Rack::Events` for providing easy hooks when a request is received and when
   the response is sent.
-* `Rack::Files` for serving static files.
 * `Rack::Head` for returning an empty body for HEAD requests.
 * `Rack::Lint` for checking conformance to the [Rack Specification].
 * `Rack::Lock` for serializing requests using a mutex.
-* `Rack::Logger` for setting a logger to handle logging errors.
 * `Rack::MethodOverride` for modifying the request method based on a submitted
   parameter.
 * `Rack::Recursive` for including data from other paths in the application, and
@@ -132,7 +168,7 @@ middleware:
   a nice and helpful way with clickable backtrace.
 * `Rack::ShowStatus` for using nice error pages for empty client error
   responses.
-* `Rack::Static` for more configurable serving of static files.
+* `Rack::Static` for configurable serving of static files.
 * `Rack::TempfileReaper` for removing temporary files creating during a request.
 
 All these components use the same interface, which is described in detail in the
@@ -154,6 +190,8 @@ quickly and without doing the same web stuff all over:
   returns a not found or method not supported response.
 * `Rack::Directory` for serving files under a given directory, with directory
   indexes.
+* `Rack::Files` for serving files under a given directory, without directory
+  indexes.
 * `Rack::MediaType` for parsing content-type headers.
 * `Rack::Mime` for determining content-type based on file extension.
 * `Rack::RewindableInput` for making any IO object rewindable, using a temporary
@@ -165,6 +203,41 @@ quickly and without doing the same web stuff all over:
 Rack exposes several configuration parameters to control various features of the
 implementation.
 
+### `RACK_QUERY_PARSER_BYTESIZE_LIMIT`
+
+This environment variable sets the default for the maximum query string bytesize
+that `Rack::QueryParser` will attempt to parse.  Attempts to use a query string
+that exceeds this number of bytes will result in a
+`Rack::QueryParser::QueryLimitError` exception. If this enviroment variable is
+provided, it must be an integer, or `Rack::QueryParser` will raise an exception.
+
+The default limit can be overridden on a per-`Rack::QueryParser` basis using
+the `bytesize_limit` keyword argument when creating the `Rack::QueryParser`.
+
+### `RACK_QUERY_PARSER_PARAMS_LIMIT`
+
+This environment variable sets the default for the maximum number of query
+parameters that `Rack::QueryParser` will attempt to parse.  Attempts to use a
+query string with more than this many query parameters will result in a
+`Rack::QueryParser::QueryLimitError` exception. If this enviroment variable is
+provided, it must be an integer, or `Rack::QueryParser` will raise an exception.
+
+The default limit can be overridden on a per-`Rack::QueryParser` basis using
+the `params_limit` keyword argument when creating the `Rack::QueryParser`.
+
+This is implemented by counting the number of parameter separators in the
+query string, before attempting parsing, so if the same parameter key is
+used multiple times in the query, each counts as a separate parameter for
+this check.
+
+### `RACK_MULTIPART_BUFFERED_UPLOAD_BYTESIZE_LIMIT`
+
+This environment variable sets the maximum amount of memory Rack will use
+to buffer multipart parameters when parsing a request body. This considers
+the size of the multipart mime headers and the body part for multipart
+parameters that are buffered in memory and do not use tempfiles. This
+defaults to 16MB if not provided.
+
 ### `param_depth_limit`
 
 ```ruby
@@ -202,7 +275,6 @@ Can also be set via the `RACK_MULTIPART_FILE_LIMIT` environment variable.
 
 (This is also aliased as `multipart_part_limit` and `RACK_MULTIPART_PART_LIMIT` for compatibility)
 
-
 ### `multipart_total_part_limit`
 
 The maximum total number of parts a request can contain of any type, including
@@ -215,18 +287,12 @@ Set to 0 for no limit.
 
 Can also be set via the `RACK_MULTIPART_TOTAL_PART_LIMIT` environment variable.
 
-
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md).
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for specific details about how to make a
 contribution to Rack.
 
-Please post bugs, suggestions and patches to [GitHub
-Issues](https://github.com/rack/rack/issues).
+Please post bugs, suggestions and patches to [GitHub Issues](https://github.com/rack/rack/issues).
 
 Please check our [Security Policy](https://github.com/rack/rack/security/policy)
 for responsible disclosure and security bug reporting process. Due to wide usage
@@ -236,6 +302,13 @@ is greatly appreciated.
 
 ## See Also
 
+### `rackup`
+
+A useful tool for running Rack applications from the command line, including
+`Rackup::Server` (previously `Rack::Server`) for scripting servers.
+
+* https://github.com/rack/rackup
+
 ### `rack-contrib`
 
 The plethora of useful middleware created the need for a project that collects
@@ -306,4 +379,6 @@ would like to thank:
 
 Rack is released under the [MIT License](MIT-LICENSE).
 
-[Rack Specification]: SPEC.rdoc
+[Rack Specification]: https://rack.github.io/rack/main/SPEC_rdoc.html
+[Documentation]: https://rack.github.io/rack/
+[Security Policy]: SECURITY.md