[Feature]: improve error messages for HTTP URL connections

[ascopes]

Brief description

HTTP URL connections that fail due to a 4xx or 5xx will currently raise a blind exception due to input streams being closed. This is overly unhelpful.

We should override the URL connection logic to handle the error stream sensibly, since this is a custom component of HTTP URL connections specifically.

Aims and goals

Provide better error messages for bad URLs.

Useful information to include in error messages

• Status code
• Reason, if provided
• Correlation ID headers if available (/.*Correlation[_-]?Id.*/i)
• Request ID headers if available (/.*Request[_-]Id.*/i)
• WWW-Authenticate header, if provided
• Proxy-Authenticate header, if provided
• Response body from error stream (truncate if too long)

Workarounds

Checking manually with cURL.

Considerations

It may be more erganomic to write a URLConnection that wraps the Java 11 HttpClient API instead of hacking around with wrapping the existing URLConnnection implementation.

• This will allow for using HTTP/2 as well (and eventually HTTP/3 over QUIC once OpenJDK supports it).
• HttpClient can be kept alive for the duration of the URLStreamHandlerFactory to share connections, although we will have to remember to create any shutdown hooks we require.

Assess during the implementation.

Requirements

• New class extending URLStreamHandlerFactory at https://github.com/ascopes/protobuf-maven-plugin/tree/main/protobuf-maven-plugin/src/main/java/io/github/ascopes/protobufmavenplugin/urls to wrap an HTTP(S) connection
  • Should open a regular HTTPURLConnection, but have logic in the .connect() method of the returned URL to handle reporting errors better.
  • 404s should raise FileNotFoundException as they already do internally
  • Add unit tests
• Register new class under "http" and "https" protocols in https://github.com/ascopes/protobuf-maven-plugin/tree/main/protobuf-maven-plugin/src/main/java/io/github/ascopes/protobufmavenplugin/urls/UrlFactory.java

Would you like to contribute to this feature?

• Yes, I'd like to contribute this change myself!

[desprd]

Hi @ascopes, I'd like to take this on. Could you assign it to me?

[ascopes]

Sure thing. Thanks!

[ascopes]

Assigned to you. If you need any info, please just ask.

Effectively we're just looking for clearer errors from URLs created from the UrlFactory class that use HTTP/HTTPS.

You can test this using WireMock to make a stub HTTP server. The UrlFactoryTest class does this for more general testing so you should be able to look at how that is set up and copy it, testing against some common scenarios for your class you write.

You can verify the entire Maven plugin still works once finished by finding an integration test that uses an HTTP URL internally and running it. I'd suggest the scalapb plugin test, which you can run with ./mvnw verify -DskipTests -Dinvoker.test=scalapb-plugin. If it starts to fail with your changes and you cannot find out why, you can attach a remote debugger to it and instruct IntelliJ or Eclipse to connect to that so you can make breakpoints and stuff.