RFR: 8368695: Support 101 switching protocol in jdk.httpserver [v5]

[Daniel Fuchs]

On Wed, 15 Oct 2025 14:17:20 GMT, Michael McMahon <michaelm at openjdk.org> wrote:

>> Josiah Noel has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   tab
>
> Here is a proposal for discussion. This would be added to the end of the class level docs for HttpExchange
> 
> 
>  <b>Upgrading HTTP/1.1 connections</b>
> 
> <br>Sending a 101 response to a request from the client to upgrade to some other protocol has the effect of detaching
>  the underlying connection from the HTTP stack. The {@link InputStream} and {@link OutputStream} returned from 
> {@link #getRequestBody()} and {@link #getResponseBody()} respectively, after sending the 101 response, returns raw
>  streams to the underlying socket. {@code sendResponseHeaders(101, -1)} must be called prior to obtaining the
>  detached input and output streams. It is also an error to send a 101 response if no {@code Upgrade} header was present
>  in the request, or the request was anything other than a GET (or CONNECT?) or to pass a content length other than
>  {@code -1}. Other than that, the library does not restrict or interpret the Upgrade header value. It is up to the calling
>  code to implement whatever higher level protocol is required over the underlying socket. It is up to the calling code to
>  eventually obtain and eventually close both the detached {@link #getRequestBody() InputStream} and
>  {@link#getResponseBody() OutputStream} to prevent resource leaks. Closing the exchange after {@code 
>  sendResponseHeaders(101, -1)} has been called has no effect on these streams. Terminating the server with {@link 
>  HttpServer.stop(int)} closes all sockets associated with the server including any sockets detached through this 
>  mechanism.
> 
> 
> The apidoc for HttpServer.stop would need to mention that sockets detached from the upgrade mechanism are also closed.

Thanks @Michael-Mc-Mahon for driving this discussion. Would this text be normative - that it - would any implementation plugged through the SPI need to support this? If not we should find some way to tie that to the JDK built-in implementation. I know that the HttpServer API itself is not part of the Java SE spec - but maybe we should set some expectations of what an implementation plugged through the SPI must, should, or might do.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/27751#issuecomment-3407011129