Package org.mockserver.netty.proxy

Class TransparentProxyHandler

java.lang.Object

io.netty.channel.ChannelHandlerAdapter

io.netty.channel.ChannelInboundHandlerAdapter

org.mockserver.netty.proxy.TransparentProxyHandler

All Implemented Interfaces:

io.netty.channel.ChannelHandler, io.netty.channel.ChannelInboundHandler

public class TransparentProxyHandler
extends io.netty.channel.ChannelInboundHandlerAdapter

A Netty channel handler that resolves the original destination for transparently intercepted connections and stores it as the HttpActionHandler.REMOTE_SOCKET channel attribute. The downstream proxy/forward logic in HttpActionHandler then uses this address instead of requiring the Host header to determine the target.

Resolution is performed by a pluggable TransparentProxyHandler.OriginalDestinationResolver strategy (typically a CompositeOriginalDestinationResolver chain). The default chain contains, in order, the TPROXY resolver (when TPROXY mode is enabled), the SO_ORIGINAL_DST getsockopt resolver, the conntrack resolver, and the DNS-intent resolver. See CompositeOriginalDestinationResolver.defaultChain(Configuration) for the full chain ordering.

Resolution strategy (in order):

1. PROXY protocol v1 — handled by ProxyProtocolOriginalDestinationHandler earlier in the pipeline (reads inbound bytes, not channel metadata). If a PROXY header is present, the REMOTE_SOCKET is set before this handler fires.
2. Channel-level chain (this handler, at channelActive):
   • TproxyOriginalDestinationResolver — TPROXY local-address resolution (when transparentProxyTproxy=true; returns null otherwise)
   • SoOriginalDstResolver — O(1) getsockopt(SO_ORIGINAL_DST) via JNA (Linux + epoll transport only; returns null on NIO channels)
   • ConntrackOriginalDestinationResolver — Linux conntrack table
   • (future) eBPF
3. Host header fallback — if no strategy resolves the destination, the existing Host-based forwarding logic in HttpActionHandler applies.

This handler is only added to the pipeline when Configuration.transparentProxyEnabled() is true. It fires on channelActive (connection accepted) and sets the attribute before any HTTP data is processed.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TransparentProxyHandler.OriginalDestinationResolver	Strategy interface for resolving the original destination.

Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

io.netty.channel.ChannelHandler.Sharable

Field Summary

Fields

Modifier and Type	Field	Description
static final io.netty.util.AttributeKey<Boolean>	TRANSPARENT_ORIGINAL_DST_RESOLVED	Channel attribute indicating the transparent proxy original destination was resolved via SO_ORIGINAL_DST / conntrack (as opposed to Host header).

Constructor Summary

Constructors

Constructor	Description
TransparentProxyHandler(Configuration configuration, MockServerLogger logger)
TransparentProxyHandler(Configuration configuration, MockServerLogger logger, TransparentProxyHandler.OriginalDestinationResolver resolver)	Constructor with injectable resolver for unit testing.

Method Summary

Modifier and Type	Method	Description
void	channelActive(io.netty.channel.ChannelHandlerContext ctx)

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

channelInactive, channelRead, channelReadComplete, channelRegistered, channelUnregistered, channelWritabilityChanged, exceptionCaught, userEventTriggered

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

ensureNotSharable, handlerAdded, handlerRemoved, isSharable

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.netty.channel.ChannelHandler

handlerAdded, handlerRemoved

Field Details

TRANSPARENT_ORIGINAL_DST_RESOLVED

public static final io.netty.util.AttributeKey<Boolean> TRANSPARENT_ORIGINAL_DST_RESOLVED

Channel attribute indicating the transparent proxy original destination was resolved via SO_ORIGINAL_DST / conntrack (as opposed to Host header).

Constructor Details

TransparentProxyHandler

public TransparentProxyHandler(Configuration configuration,
 MockServerLogger logger)

TransparentProxyHandler

public TransparentProxyHandler(Configuration configuration,
 MockServerLogger logger,
 TransparentProxyHandler.OriginalDestinationResolver resolver)

Constructor with injectable resolver for unit testing.

Method Details

channelActive

public void channelActive(io.netty.channel.ChannelHandlerContext ctx)
                   throws Exception

Specified by:

channelActive in interface io.netty.channel.ChannelInboundHandler

Overrides:

channelActive in class io.netty.channel.ChannelInboundHandlerAdapter

Throws:

Exception