io.micronaut.http.server.netty

Interface NettyServerCustomizer

public interface NettyServerCustomizer

Interface implemented by users to hook into the pipeline setup of the netty HTTP server.
The internal pipeline of our HTTP server is by necessity complex and unstable across versions. While we strive to retain compatibility, please do not make too many assumptions about the Micronaut HTTP server pipeline structure when implementing this interface.
Implementations of this interface are scoped to different lifetimes. The root customizers can be added through the NettyServerCustomizer.Registry, and live while the server is running. Customizers with narrower scope are created from the root customizers through specialization when new netty channels are created by the server, e.g. when a client connects. These specialized customizers will then receive notifications when a certain step in the pipeline setup is reached, so they can do their own customizations on the channel and the channel pipeline they received in the specialization step.

Since:

3.6.0

Author:

yawkat

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	NettyServerCustomizer.ChannelRole Enum to describe the role of the channel passed to specializeForChannel(Channel, ChannelRole).
static interface	NettyServerCustomizer.Registry Interface implemented by the HTTP server to register customizers.

Method Summary

Modifier and Type	Method and Description
default void	onInitialPipelineBuilt() Called when the initial connection pipeline has been built, before any incoming data has been processed.
default void	onStreamPipelineBuilt() Called when the "final" stream pipeline has been built for processing http requests.
default NettyServerCustomizer	specializeForChannel(io.netty.channel.Channel channel, NettyServerCustomizer.ChannelRole role) Specialize this customizer for the given channel.

Method Detail

specializeForChannel

@NonNull
default NettyServerCustomizer specializeForChannel(@NonNull
                                                            io.netty.channel.Channel channel,
                                                            @NonNull
                                                            NettyServerCustomizer.ChannelRole role)

Specialize this customizer for the given channel. In the "boring" case, the customizer will first be specialized for a ServerSocketChannel when the server binds to a configured TCP port, and then to a SocketChannel when a client connects to that port.
However, there are a lot of weird cases where the actual behavior might diverge from this. For example, the channel types will different if the server is bound to a unix domain socket (ServerDomainSocketChannel and DomainSocketChannel respectively). In the case of an EmbeddedChannel used for testing, there might not be a listener channel at all. For HTTP/2, each HTTP stream may get its own channel that is specialized from the overall connection channel. And finally, HTTP/3 support has to use datagram channels instead of the socket-based ones.

Parameters:

channel - The new channel to specialize for.

role - The role (or scope) of the channel.

Returns:

The new customizer, or this if no specialization needs to take place.

onInitialPipelineBuilt

default void onInitialPipelineBuilt()

Called when the initial connection pipeline has been built, before any incoming data has been processed.

onStreamPipelineBuilt

default void onStreamPipelineBuilt()

Called when the "final" stream pipeline has been built for processing http requests. For HTTP/1, this is immediately after onInitialPipelineBuilt(). For TLS-based HTTP/2 support, where HTTP/1 or HTTP/2 is negotiated through TLS ALPN, this will be called when negotiation is complete. However for HTTP/2 specifically, this may be changed in the future when we switch to netty channel multiplexing, where each HTTP/2 stream gets its own channel.
Another case is h2c with upgrade from HTTP/1. As with ALPN this method will be called after we know whether to use HTTP/1 or HTTP/2. At that point, the first request (that potentially contained the upgrade request) is already "in flight" inside the channel pipeline. It will be forwarded downstream from the upgrade handler after this method is called.