This PR fixes an issue when the following situation occurs.
If you define a class like this

    class MyConstraint
      def call(*args)
        # for some reason this is defined
      end

      def matches?(*args)
        # checking the args
      end
    end

and try to use it as a constraint

    get "/", to: "home#show", constraints: MyConstraint.new

if its `matches?` method returns `false` there will be an error for the
mapper will ask for the constraint arity, thinking it is a proc, lambda
or method.

This PR checks for the presence of the `arity` method on the constraint
calling it only if present, preventing the error while keeping the basic
behavior.

This commit eagerly builds the route helper module after the routes have
been drawn and finalized.  This allows us to cache the helper module but
not have to worry about people accessing the module while route
definition is "in-flight", and automatically deals with cache
invalidation as the module is regenerated anytime someone redraws the
routes.

The restriction this commit introduces is that the url helper module can
only be accessed *after* the routes are done being drawn.

Refs #24554 and #32892

In Ruby 2.3 or later, `String#+@` is available and `+@` is faster than `dup`.

```ruby
# frozen_string_literal: true

require "bundler/inline"

gemfile(true) do
  source "https://rubygems.org"

  gem "benchmark-ips"
end

Benchmark.ips do |x|
  x.report('+@') { +"" }
  x.report('dup') { "".dup }
  x.compare!
end
```

```
$ ruby -v benchmark.rb
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux]
Warming up --------------------------------------
                  +@   282.289k i/100ms
                 dup   187.638k i/100ms
Calculating -------------------------------------
                  +@      6.775M (± 3.6%) i/s -     33.875M in   5.006253s
                 dup      3.320M (± 2.2%) i/s -     16.700M in   5.032125s

Comparison:
                  +@:  6775299.3 i/s
                 dup:  3320400.7 i/s - 2.04x  slower

```

In cases where the MatchData object is not used, this provides a speed-up:
https://github.com/JuanitoFatas/fast-ruby/#stringmatch-vs-stringmatch-vs-stringstart_withstringend_with-code-start-code-end

http links will be redirected to the https version, but still better to
just directly link to the https version.

The urls helpers module returned by Rails.application.routes.url_helpers
isn't cached so to prevent the cost of building the module cache it locally.

Some places we can't remove because Ruby still don't have a method
equivalent to strip_heredoc to be called in an already existent string.

[ci skip]

Particularly, the bulleted list was getting formatted as a code block because of the extra level of indentation.  Pulling it back to the left makes it render properly as a list instead.

[ci skip]

This basically reverts e9fca766, d08da958,
d1fe1dcf, and 68eaf7b4

We always plural form for `resources` method.

This reverts commit 3420a145, reversing
changes made to afb66a5a.

The current check for whether to add an optional format to the path
is very lax and will match things like `:format_id` where there are
nested resources, e.g:

    resources :formats do
      resources :items
    end

Fix this by using a more restrictive regex pattern that looks for
the patterns `(.:format)`, `.:format` or `/` at the end of the path.
Note that we need to allow for multiple closing parenthesis since
the route may be of this form:

    get "/books(/:action(.:format))", controller: "books"

This probably isn't what's intended since it means that the default
index action route doesn't support a format but we have a test for
it so we need to allow it.

Fixes #28517.

Since `ActionController:Parameters` does not inherit `Hash`, need to
explicitly convert it to `Hash`.
Also, `Parameters#to_h` returns `Hash` whose key is `String`. Therefore,
if merge as it is, the value will not be overwritten as expected.

Also correct use of `direct class:` to `resolve` in example.

Since a `direct` url helper block is evaluated using `instance_exec`
then methods that are available in the instance context can be
accessed, e.g. the params object in a controller action or view.

This wasn't clear from the example so expand on that point and add
a test case for this situation.

Use double quoted strings, come down hard on some typos.

Use a separate method called `resolve` for the custom polymorphic
mapping to clarify the API.

Allow the use of `direct` to specify custom mappings for polymorphic_url, e.g:

  resource :basket
  direct(class: "Basket") { [:basket] }

This will then generate the following:

  >> link_to "Basket", @basket
  => <a href="/basket">Basket</a>

More importantly it will generate the correct url when used with `form_for`.

Fixes #1769.

Allow the definition of custom url helpers that will be available
automatically wherever standard url helpers are available. The
current solution is to create helper methods in ApplicationHelper
or some other helper module and this isn't a great solution since
the url helper module can be called directly or included in another
class which doesn't include the normal helper modules.

Reference #22512.

This was preventing the test suite from being run in isolation