Under Puppet Server, users of the Puppet::Network::HttpPool class get clients that are instances of the Puppet::Server::HttpClient Ruby class. The Puppet::Server::HttpClient class makes outgoing HTTP client requests via the Java-based clj-http-client library. Any exceptions thrown for those requests are cascaded up to their Ruby layer callers as the JRuby form of the Java exception, i.e., possible to reference from a rescue block in Ruby code as Java::ComPuppetlabsHttpClient::HttpClientException so long as the underlying runtime is JRuby. However, it will still be possible for some time for the calling Ruby code to be run from under either an MRI Ruby or a JRuby runtime.
Given the continued need for MRI/JRuby compatibility, we should catch, inside of the Puppet::Server::HttpClient class, any Java-layer exceptions which might be thrown and re-raise them to callers as a more standard Ruby exception type. Ruby's standard SocketError is probably the best choice here as it is the type which would be thrown under MRI Ruby for HttpClient errors. The Puppet::Server::HttpClient class should only ever be run under a JRuby runtime, as part of Puppet Server, so this would be the best layer at which to abstract the underlying Java-related functionality from any callers.
The client calls occur from Puppet Server at the following locations:
Exception re-raising should be wrapped around the above calls.
Having the underlying HTTPClientException available to any callers running under JRuby, however, could still be useful - e.g., for introspecting into any nested inner exceptions to validate the root cause of a SocketError for testing. To allow for preserving this context in a way that would allow the base type of the exception raised to still be SocketError, we could define a new exception class in Puppet Server Ruby code which derives from SocketError, accepts the underlying Java exception as an argument in the constructor, and stores that argument into a field in the object with a public accessor for retrieval. Any callers that would want to interpret the exception as Puppet Server's custom SocketError class could then pull the Java exception back out of the object for inspection, as necessary.