Class EffectiveClientIpResolver

java.lang.Object

com.soklet.EffectiveClientIpResolver

@NotThreadSafe
public final class EffectiveClientIpResolver
extends Object

Resolves a client's effective IP address from a request's socket peer and forwarded headers.

Forwarded headers can be spoofed if Soklet is reachable directly. Choose a EffectiveOriginResolver.TrustPolicy that matches your deployment and, for EffectiveOriginResolver.TrustPolicy.TRUST_PROXY_ALLOWLIST, provide a trusted proxy predicate or allowlist. If the remote address is missing or not trusted, forwarded headers are ignored and the socket peer is returned when available.

Extraction order is: trusted Forwarded for= values, trusted X-Forwarded-For values, then the socket peer. Only IP literals are accepted from forwarded headers; hostnames, obfuscated identifiers, unknown, and malformed values are ignored.

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
@NonNull EffectiveClientIpResolver	remoteAddress(@Nullable InetSocketAddress remoteAddress)	The remote address of the client connection.
@NonNull Optional<InetAddress>	resolve()	Resolves the effective client IP address.
@NonNull EffectiveClientIpResolver	trustedProxyAddresses(@NonNull Set<@NonNull InetAddress> trustedProxyAddresses)	Allows specifying an IP allowlist for trusted proxies.
@NonNull EffectiveClientIpResolver	trustedProxyPredicate(@Nullable Predicate<InetSocketAddress> trustedProxyPredicate)	Predicate used when EffectiveOriginResolver.TrustPolicy.TRUST_PROXY_ALLOWLIST is in effect.
static @NonNull EffectiveClientIpResolver	withHeaders(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> headers, @NonNull EffectiveOriginResolver.TrustPolicy trustPolicy)	Acquires a resolver seeded with raw request headers and a trust policy.
static @NonNull EffectiveClientIpResolver	withRequest(@NonNull Request request, @NonNull EffectiveOriginResolver.TrustPolicy trustPolicy)	Acquires a resolver seeded with a Request and a trust policy.

Methods inherited from class Object

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

Method Details

withHeaders

public static @NonNull EffectiveClientIpResolver withHeaders(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> headers,
 @NonNull EffectiveOriginResolver.TrustPolicy trustPolicy)

Acquires a resolver seeded with raw request headers and a trust policy.

Parameters:

headers - HTTP request headers

trustPolicy - how forwarded headers should be trusted

Returns:

the resolver

withRequest

public static @NonNull EffectiveClientIpResolver withRequest(@NonNull Request request,
 @NonNull EffectiveOriginResolver.TrustPolicy trustPolicy)

Acquires a resolver seeded with a Request and a trust policy.

Parameters:

request - the current request

trustPolicy - how forwarded headers should be trusted

Returns:

the resolver

resolve

public @NonNull Optional<InetAddress> resolve()

Resolves the effective client IP address.

Returns:

the effective client IP address, or Optional.empty() if no client IP could be determined

remoteAddress

public @NonNull EffectiveClientIpResolver remoteAddress(@Nullable InetSocketAddress remoteAddress)

The remote address of the client connection.

Parameters:

remoteAddress - the remote address, or null if unavailable

Returns:

this resolver

trustedProxyPredicate

public @NonNull EffectiveClientIpResolver trustedProxyPredicate(@Nullable Predicate<InetSocketAddress> trustedProxyPredicate)

Predicate used when EffectiveOriginResolver.TrustPolicy.TRUST_PROXY_ALLOWLIST is in effect.

Parameters:

trustedProxyPredicate - predicate that returns true for trusted proxies

Returns:

this resolver

trustedProxyAddresses

public @NonNull EffectiveClientIpResolver trustedProxyAddresses(@NonNull Set<@NonNull InetAddress> trustedProxyAddresses)

Allows specifying an IP allowlist for trusted proxies.

Parameters:

trustedProxyAddresses - IP addresses of trusted proxies

Returns:

this resolver