Improve ForwardRequestCustomizer authority priority

[joakime]

Jetty version
9.4.31

Description
The ForwardedRequestCustomizer has a torturous implementation of priority for how the authority (server name:port) is calculated.

We should improve this to implement a clear priority of what header fields are interrogated, and under what order they resolve to an authority.
Bonus is an improved javadoc that documents this behavior.
On a brief discussion with @gregw the following priority for the Authority Host and Port were proposed.

Authority Host

1. Forwarded (RFC7239) (left-most)
2. X-Forwarded-Host (left-most)
3. X-Forwarded-For (left-most)
4. Host
5. default to what? or ServerConnector localAddress? do we need this? No Host header is an error, right?

Authority Port

1. Forwarded (RFC7239) (left-most)
2. X-Forwarded-Host (left-most)
3. X-Forwarded-For (left-most)
4. X-Forwarded-Port (left-most)
5. Host
6. X-Forwarded-Proto (left-most) [https=443, http=80]
7. X-Proxied-Https (on=443, off=80)
8. default to 80? or ServerConnector localPort? (don't think we need to interrogate the ServerConnector)

I propose we track the authority host and port separately (not in a HostPort field).
Each with a priority int, that indicates where the last setting of those fields came from.
Then, we could change the MethodHandle calls to include a priority for when that specific field is encountered, ala handlePort(int priority, HttpField field), and if the field (port in this case) was set, and from a lower priority then this call, then override it's value.
When the full set of headers is done parsing, finally form the HostPort field from the separate host and port fields.

[peterlynch]

I noticed X-Forwarded-Server header was omitted from the opening issue description. It might need to be considered as well for Authority Host?

org.eclipse.jetty.server.ForwardedRequestCustomizer.setHostHeader(String) seems also designed to force the authority to be whatever an admin configures it to be, overriding inbound host inspection?

[joakime]

Opened PR #5247 to address this.

This is the search order for request.authority in an incoming request now.
(this same table is in the javadoc for ForwardedRequestCustomizer in PR #5247)

num	Value Origin	Host	Port	Notes
1	Forwarded Header	Required	Authoritative	From left-most host=[value] parameter (see rfc7239)
2	X-Forwarded-Host Header	Required	Optional	left-most value
3	X-Forwarded-Port Header	n/a	Required	left-most value (only if getForwardedPortAsAuthority() is true)
4	X-Forwarded-Server Header	Required	Optional	left-most value
5	Request Metadata	Optional	Optional	found in Request Line absolute path and/or Host client request header value as value host:port or host
6	X-Forwarded-Proto Header	n/a	standard	left-most value as http (implied port 80) or https (implied port 443)
7	X-Proxied-Https Header	n/a	boolean	left-most value as on (implied port 443) or off (implied port 80)

Key:

• "Required" means that if the origin exists, then the value (host or port) must exist and have a valid value.
• "Optional" means that if the origin exists, then the value (host or port) can be missing / empty and will result in no change to the authority
• "Authoritative" means that if the origin exists, then the value provided is taken as-is, even if it's missing / empty. (only relevant for port)
• "standard" means that the port comes from standards defined names (see notes).
• "boolean" means that the port comes from "on" and "off" values (see notes).

[joakime]

Merged #5251