Add Unix domain socket support#637
Merged
Merged
Conversation
Member
|
@rschmitt It is a big one. Please allow me a few days to get around to it. |
Contributor
Author
|
I suggest reading the diff from the bottom up. It just flows more logically that way: example code, connection changes, routing changes, integration test changes. |
ok2c
reviewed
Jun 1, 2025
michael-o
requested changes
Jun 2, 2025
This change adds Unix domain socket support. The sync client uses JUnixSocket, which provides synchronous UDS support through the legacy `java.net.Socket` API; the async client uses the JEP 380 implementation of UDS through the `java.nio.channels.SocketChannel` API (requires JDK16 or later). Since the synchronous client is tightly coupled to the `Socket` API, we can't trivially use JEP 380 UDS support. We would first have to write an adapter to implement the `Socket` API, backed by a JEP 380 UDS `SocketChannel`. This would require us to implement features like socket option configuration, connection timeouts, and socket timeouts; we would also have to implement APIs like `getInetAddress()` which don't actually make sense in a UDS context. This is probably doable (JUnixSocket does it, albeit with a different implementation strategy based on native code), but it's not trivial. The asynchronous client is the other way around: it supports JEP 380, but not JUnixSocket. The issue here is more subtle: JDK and JUnixDomain channels cannot be mixed in the same selector, and since JUnixDomain does not provide an implementation of TCP/IP channels, supporting JUnixSocket in the async client would require substantial rework in the IO reactor. Since JDK8 is end-of-life next year, I doubt this is worth doing unless we can find some clever way of integrating the new channel type with minimal churn. Unix domain socket support is exposed through the `RequestConfig` API. A path to a Unix domain socket can be provided as a client-wide default through `setDefaultRequestConfig`, or on a per-request basis through `setConfig`. Currently, proxies and TLS are not supported through UDS. The former feature seems unnecessary, but the latter is likely worth adding at some point, since contacting an HTTPS endpoint over UDS (sometimes denoted by the URI scheme `https+unix`) is not unheard of.
michael-o
approved these changes
Jun 3, 2025
ok2c
approved these changes
Jun 4, 2025
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This change adds Unix domain socket support. The sync client uses JUnixSocket, which provides synchronous UDS support through the legacy
java.net.SocketAPI; the async client uses the JEP 380 implementation of UDS through thejava.nio.channels.SocketChannelAPI (requires JDK16 or later).Since the synchronous client is tightly coupled to the
SocketAPI, we can't trivially use JEP 380 UDS support. We would first have to write an adapter to implement theSocketAPI, backed by a JEP 380 UDSSocketChannel. This would require us to implement features like socket option configuration, connection timeouts, and socket timeouts; we would also have to implement APIs likegetInetAddress()which don't actually make sense in a UDS context. This is probably doable (JUnixSocket does it, albeit with a different implementation strategy based on native code), but it's not trivial.The asynchronous client is the other way around: it supports JEP 380, but not JUnixSocket. The issue here is more subtle: JDK and JUnixDomain channels cannot be mixed in the same selector, and since JUnixDomain does not provide an implementation of TCP/IP channels, supporting JUnixSocket in the async client would require substantial rework in the IO reactor. Since JDK8 is end-of-life next year, I doubt this is worth doing unless we can find some clever way of integrating the new channel type with minimal churn.
Unix domain socket support is exposed through the
RequestConfigAPI. A path to a Unix domain socket can be provided as a client-wide default throughsetDefaultRequestConfig, or on a per-request basis throughsetConfig. Currently, proxies and TLS are not supported through UDS. The former feature seems unnecessary, but the latter is likely worth adding at some point, since contacting an HTTPS endpoint over UDS (sometimes denoted by the URI schemehttps+unix) is not unheard of.