nullable or exception-throwing getter methods in `Request/ResponseHeaders`

[trustin]

The getter methods of some mandatory headers such as:

• :status
• :method
• :scheme
• :authority

are either nullable or exception-throwing according to the Javadoc.

This can be confusing to a user because they must be always available according to HTTP specification.

The original reasons why they are nullable or exception-throwing are:

• A user should be able to build without specifying the properties like :scheme and :authority when constructing a client-side request, because Armeria can fill them automatically.
• When building headers, the getters in the builder will expose its partial state where some properties are not filled in yet.

In the short term, we could:

• Update our Javadoc to explicitly state when it is guaranteed to return non-null and not to throw an exception, such as when the request was created by Armeria server; and
• Override the declaration of some getters, annotate it with @Nonnull and remove @throws from the Javadoc where applicable.

In the long term, we could consider the following options:

• Disallow creating headers without mandatory headers at all.
  • We can still auto-fill them when using WebClient.prepare(), but users who created a request by themselves will suffer from migration.
• Just remove @Nullable from all of them and throw an IllegalStateException when they are missing. Document properly when the exception will be thrown.
• Introduce more types, e.g. PartialRequestHeaders vs. RequestHeaders.

[alexc-db]

To name a few examples that should not throw or be null on the server side:

• ctx.request().uri() should be always valid and should not throw
• ctx.request().uri().toURL() should never throw because ctx.request().uri() should be absolute and well-formed
• ctx.remoteAddress[InetSocketAddress]().getAddress() should not be null because InetAddress should be always resolved
• ctx.request().scheme() should not be null because schema should always be available on the server side