Misleading docs for HttpClientTransportDynamic
#7575
Comments
|
@zUniQueX from the stack trace it seems you are using clear-text protocols, so When using clear-text, the client must know a priori what protocol is supported on the server port, because there is no negotiation. So if you know a server supports only Do you have suggestions on how to improve the documentation? |
I don't see this. Where it is exactly? |
Ah, sorry. I've been using I would suggest making the docs more explicit, i.e. to provide details on the implementation. For example: Protocol switching can be done from HTTP/1.1 to HTTP/2 using ALPN or using the HTTP |
I meant this line: https://github.com/eclipse/jetty.project/blob/jetty-10.0.x/jetty-client/src/main/java/org/eclipse/jetty/client/dynamic/HttpClientTransportDynamic.java#L58. Thereby the constant |
Improved documentation for the clear-text dynamic transport case. Fixed HttpClientTransportDynamic javadocs. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
joakime
moved this from In progress
to Review in progress
in Jetty 10.0.9/11.0.9 (FROZEN)
Are there any examples that show how this can be done? I have the same problem as the OP. I would like to configure an HttpClient such that it uses HTTP/2 if possible, falling back to HTTP/1.1 if needed. I don't need h2c. I tried using HttpClientTransportDynamic for this, but I get the same error. My intuition was that the client knows that HTTP/2 is only possible with HTTPS. So if I send a request via HTTPS, it could try HTTP/2, but if it's a clear text request, there is no point in even trying. Also, before looking into this, I expected that the HttpClient would support HTTP/2 out of the box. But then I checked and saw that it always uses HTTP/1.1 with default config. With HttpClientTransportDynamic as configured in the docs, it does use HTTP/2, but then unencrypted requests fail. Is there a way to configure a single client such that it works for (encrypted) HTTP/2 as well as encrypted and unencrypted HTTP/1.1? |
|
OK i digged further into the programming guide an found a solution: by simply reversing the order of h2 and h1, i.e. preferring h1 over h2, everything works as expected: var clientConnector = new ClientConnector();
var client = new HttpClient(new HttpClientTransportDynamic(
clientConnector,
HttpClientConnectionFactory.HTTP11, // preferred if no ALPN is used
new ClientConnectionFactoryOverHTTP2.HTTP2(new HTTP2Client(clientConnector))
));In unencrypted requests where ALPN is not used, the client uses h1. |
|
@mperktold do you have suggestions to make the documentation clearer? |
|
You could explicitly state that for the config in the example, clear-text connections will always use h2c, which might not be supported by the server and lead to errors. I would also add that the order can be reversed to use h1 for clear-text connections and still support h2 over TLS for servers that support it. Now as I understand, h2c is quite rare. I never worked with a server that supported that, let alone required it. If you agree with that assumption, you could first give the example that prefers h1, which should work as expected with most servers. And then you would go on to explain how to use h2c by reversing the order, and maybe even showing that in another example. More generally, it wasn't clear to me that the order of protocols doesn't matter over TLS, where ALPN takes care of selecting a protocol. My intuition was that I have to put h2 first as I prefer it. But since this preference only applies to TLS, the order doesn't matter. Maybe that could be clarified in the JavaDoc as well. |
Target Jetty version(s)
11.0.0 - 11.0.8
Enhancement Description
I wanted to integrate the Jetty
HttpClientinto a library, that needs to support both protocols HTTP/1.1 and HTTP/2. Therefore I tried using theHttpClientTransportDynamicand provided bothClientConnectionFactory.Infoobjects as described in the docs.When trying to request a server that doesn't supports the first protocol in the constructor of the
HttpClientTransportDynamicobject, the request fails instead of retrying with the other protocol. For example, when prefering HTTP/2 and requesting an HTTP/1.1 only server, the following exception gets thrown:I don't know, if I'm using this class correctly but in my opinion the documentation is misleading here.
If the client doesn't know, which protocols the server supports, the server could only support one of them and therefore the client could eventually fail. Therefore I'd suggest clarifying what this class actually supports and what it doesn't.
Additionally I recognized that the example contains a wrong constant name:
HttpClientConnectionFactory.HTTPshould be replaced byHttpClientConnectionFactory.HTTP11.The text was updated successfully, but these errors were encountered: