Class SafeHttpClient

java.lang.Object

com.kingsrook.qqq.backend.core.utils.http.SafeHttpClient

All Implemented Interfaces:

AutoCloseable

public final class SafeHttpClient
extends Object
implements AutoCloseable

An HTTP client for calling URLs that users typed in (webhook endpoints, callbacks), which must not be usable to reach the internal network (SSRF).

• HTTPS only unless the policy allows http; no user-info in the URL.
• The host is resolved once. Every resolved address is checked against AddressRules (private, loopback, link-local, metadata and reserved ranges are blocked unless on the allowlist), and the request is refused if any address is blocked. The connection is then pinned to exactly those addresses through the client's DNS resolver, so a DNS answer that changes between the check and the connect (DNS rebinding) cannot redirect it.
• Redirects are never followed: a 3xx is returned to the caller.
• TLS 1.2 or 1.3, the JVM trust store and standard host name verification.
• Connect, read and total timeouts; at most maxResponseBytes of the response body is read.

One instance holds one connection pool for one policy; share it and close() it when done. It is thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	SafeHttpClient.HostResolver	Resolves a host name to addresses (replaceable in tests to simulate DNS).

Constructor Summary

Constructors

Constructor	Description
SafeHttpClient(SafeHttpPolicy policy)	Client using the system resolver.
SafeHttpClient(SafeHttpPolicy policy, SafeHttpClient.HostResolver resolver)	Client with a resolver.

Method Summary

Modifier and Type	Method	Description
void	checkUrl(String url)	Check a URL against the policy without sending anything (for validating a URL when it is saved).
void	close()	Close the connection pool.
SafeHttpResponse	post(String url, Map<String,String> headers, byte[] body)	POST a body.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SafeHttpClient

public SafeHttpClient(SafeHttpPolicy policy)

Client using the system resolver.

SafeHttpClient

public SafeHttpClient(SafeHttpPolicy policy,
 SafeHttpClient.HostResolver resolver)

Client with a resolver.

Method Details

checkUrl

public void checkUrl(String url)
              throws SafeHttpException

Check a URL against the policy without sending anything (for validating a URL when it is saved). Resolves DNS.

Throws:

SafeHttpException - when it would be refused

post

public SafeHttpResponse post(String url,
 Map<String,String> headers,
 byte[] body)
                      throws SafeHttpException

POST a body.

Parameters:

url - target

headers - request headers (Content-Type included by the caller)

body - bytes to send

Throws:

SafeHttpException - when refused, or on a network failure; any HTTP status (including 3xx, 4xx and 5xx) is a response, not an exception

close

public void close()

Close the connection pool.

Specified by:

close in interface AutoCloseable