People should be free to mutate the header object, but not to set a new
header object.  That header object may be specific to the webserver, and
we need to hide it's internals.

this way we don't have to mutate the instance (as much) when writing a
rack response

[Robin Dupret & Shunsuke Aida]

These methods had defined in 2004 by dhh in initial commit and `ActionDispatch::Request`
class has been inherited from `Rack::Request` class in 2009 by josh.
In 2014 these methods and more of them defined in `Rack::Request` class
so we don't need them anymore in rails codebase.

add missing dot to end of the doc

I should have deleted this earlier with 42e66fac

this way we can keep the knowledge of `env` hash keys in one place.

spelling fix [ci skip]

example to be consistent [ci skip]

grammatical fix

typo fixes [ci skip]

Recently rack was changed to have a second argument on the `parse_query`
method (in rack/rack#781). Rails relies on this and it's `parse_query`
method was complaining about missing the second argument. I changed the
arguments to `*` so we don't have this issue in the future.

Wrapping an array in an `ArrayInquirer` gives a friendlier way to check its
string-like contents. For example, `request.variant` returns an `ArrayInquirer`
object. To check a request's variants, you can call:

    request.variant.phone?
    request.variant.any?(:phone, :tablet)

...instead of:

    request.variant.include?(:phone)
    request.variant.any? { |v| v.in?([:phone, :tablet]) }

`Array#inquiry` is a shortcut for wrapping the receiving array in an
`ArrayInquirer`:

    pets = [:cat, :dog]
    pets.cat?    # => true
    pets.ferret? # => false
    pets.any?(:cat, :ferret} # => true

Closes #18933.

Previously, an empty X_FORWARDED_HOST header would cause
Actiondispatch::Http:URL.raw_host_with_port to return nil, causing
Actiondispatch::Http:URL.host to raise a NoMethodError.

The bug caused a segfault and you can find more info about it at:
https://bugs.ruby-lang.org/issues/10685.

We did a couple of work arounds, but 2.2.1 rolled out and those aren't
needed anymore.

Here are the reverted commits:

- Revert "Work around for upstream Ruby bug #10685",
  commit 707a4338.

- Revert "Fix segmentation fault in ActionPack tests",
  commit 22e0a22d.

I'm also bumping the Ruby version check to 2.2.1 to prevent future
segfaults.

this centralizes the logic for determining the script name key and drops
object allocations when calling `engine_script_name` (which is called on
each `url_for`).

```ruby
article = Article.new.tap(&:save!)
view.url_for article

result = ObjectSpace::AllocationTracer.trace do
  3000.times { view.url_for article }
end
p ObjectSpace::AllocationTracer.allocated_count_table[:T_STRING] / 3000
```

In f6e293ec we avoided a segfault in the
tests, however I think we should try to avoid the crash, as it may
happen in user code as well.

Here is what I distiled the bug down to:

```ruby
# Rails case - works on 2.0, 2.1; crashes on 2.2
require 'action_dispatch'

ActionDispatch::Response.new(200, "Content-Type" => "text/xml")

# General case - works on 2.0, 2.1; crashes on 2.2
def foo(optional = {}, default_argument: nil)
end

foo('quux' => 'bar')
```

Fixes regression in #18423. Merge default headers for new responses,
but don't merge when creating a response from the last session request.

hat tip @senny ❤

These requires were added only to change deprecation message

encapsulate env in the request so that we can eventually move away from
the env hash

this will help decouple us from using the rack env hash

Add docs for `extract_domain`, `extract_subdomains`, `extract_subdomain`.

Add doc examples for `url`, `protocol`, `raw_host_with_port`, `host`,
`host_with_port`, `port`, `standard_port`, `standard_port?`, `optional_port`,
`port_string`.

[ci skip]

The current implementation of `variants=` don't allow a resetting to nil, wich is the default value.

This results in the following code smell:
```ruby
case request.user_agent
when /iPhone/
  request.variants = :phone
when /iPad/
  request.variants = :ipad
end
```

With the ability to reset variants to nil, it could be:
```ruby
request.variants = case request.user_agent
when /iPhone/
  :phone
when /iPad/
  :ipad
end
```

Fixes https://github.com/rails/rails/issues/17714.

This patch uniformizes warning messages. I used the most common style
already present in the code base:

* Capitalize the first word.

* End the message with a full stop.

* "Rails 5" instead of "Rails 5.0".

* Backticks for method names and inline code.

Also, converted a few long strings into the new heredoc convention.

The current style for warning messages without newlines uses
concatenation of string literals with manual trailing spaces
where needed.

Heredocs have better readability, and with `squish` we can still
produce a single line.

This is a similar use case to the one that motivated defining
`strip_heredoc`, heredocs are super clean.