Repository navigation
docs: document JDK HttpClient's restricted Host header and the Vert.x alternative - #1180
Conversation
… alternative java.net.http.HttpClient rejects an explicit "Host" header with an IllegalArgumentException unless the JVM is started with -Djdk.httpclient.allowRestrictedHeaders=host. This is a JDK-wide restriction, not something JdkA2AHttpClient can work around per-instance, and it wasn't documented anywhere, so callers who need a custom Host header (e.g. to reach an instance directly while presenting the hostname a load balancer would normally supply) had no clear path forward. Document the restriction and the two ways around it: setting the JVM property, or using VertxA2AHttpClient (from the http-client-vertx extra), which does not build on java.net.http.HttpClient and has no such restriction. Add regression tests that lock in both behaviors: the JDK client rejecting the header, and the Vert.x client accepting it. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019bxqScUGdfjts6YHbLfUPs
kabir
left a comment
kabir
left a comment
There was a problem hiding this comment.
Hi @paulrutter thank you for the PR.
Codex found these two issues. Do you agree? Feel free to argue against what it found if you don't agree :-)
Findings
-
P2 — The Vert.x example leaks resources. docs/content/dev/client.md:169 creates a VertxA2AHttpClient but never closes it. Its no-
argument constructor starts a Vert.x instance, and JSONRPCTransport.close() does not close an injected HTTP client. Please show how
to close both clients, or state that the HTTP client must be closed separately. -
P3 — The JDK test fails when the documented workaround is enabled. JdkA2AHttpClientTest.java:80 always expects the Host header to be
rejected. With -Djdk.httpclient.allowRestrictedHeaders=host set for the test JVM, the JDK accepts it and this assertion fails. Please
make the test account for that supported configuration.
GitHub reports all PR checks passing. I did not run tests locally.
- docs/content/dev/client.md: show VertxA2AHttpClient being closed in the Host-header example. The no-args constructor owns a Vert.x instance, and JSONRPCTransport.close() is a no-op that never closes an injected A2AHttpClient, so the previous example leaked it. - JdkA2AHttpClientTest: skip testCustomHostHeaderRejectedByJdkHttpClient when the JVM already allows a restricted Host header via -Djdk.httpclient.allowRestrictedHeaders=host, since the JDK client then legitimately accepts the header instead of rejecting it. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019bxqScUGdfjts6YHbLfUPs
|
Thanks @paulrutter - I pushed a small fix regarding the closing of the clients to your branch. |
3 participants
java.net.http.HttpClient rejects an explicit "Host" header with an IllegalArgumentException unless the JVM is started with -Djdk.httpclient.allowRestrictedHeaders=host. This is a JDK-wide restriction, not something JdkA2AHttpClient can work around per-instance, and it wasn't documented anywhere, so callers who need a custom Host header (e.g. to reach an instance directly while presenting the hostname a load balancer would normally supply) had no clear path forward.
Document the restriction and the two ways around it: setting the JVM property, or using VertxA2AHttpClient (from the http-client-vertx extra), which does not build on java.net.http.HttpClient and has no such restriction. Add regression tests that lock in both behaviors: the JDK client rejecting the header, and the Vert.x client accepting it.