Package io.grpc.netty

Class NettyServerBuilder

    • Field Detail

      • DEFAULT_FLOW_CONTROL_WINDOW

        public static final int DEFAULT_FLOW_CONTROL_WINDOW
        See Also:
        Constant Field Values

      • MAX_CONNECTION_IDLE_NANOS_DISABLED

        static final long MAX_CONNECTION_IDLE_NANOS_DISABLED
        See Also:
        Constant Field Values

      • MAX_CONNECTION_AGE_NANOS_DISABLED

        static final long MAX_CONNECTION_AGE_NANOS_DISABLED
        See Also:
        Constant Field Values

      • MAX_CONNECTION_AGE_GRACE_NANOS_INFINITE

        static final long MAX_CONNECTION_AGE_GRACE_NANOS_INFINITE
        See Also:
        Constant Field Values

      • MIN_MAX_CONNECTION_IDLE_NANO

        private static final long MIN_MAX_CONNECTION_IDLE_NANO

      • MIN_MAX_CONNECTION_AGE_NANO

        private static final long MIN_MAX_CONNECTION_AGE_NANO

      • AS_LARGE_AS_INFINITE

        private static final long AS_LARGE_AS_INFINITE

      • DEFAULT_BOSS_EVENT_LOOP_GROUP_POOL

        private static final ObjectPool<? extends io.netty.channel.EventLoopGroup> DEFAULT_BOSS_EVENT_LOOP_GROUP_POOL

      • DEFAULT_WORKER_EVENT_LOOP_GROUP_POOL

        private static final ObjectPool<? extends io.netty.channel.EventLoopGroup> DEFAULT_WORKER_EVENT_LOOP_GROUP_POOL

      • listenAddresses

        private final java.util.List<java.net.SocketAddress> listenAddresses

      • channelFactory

        private io.netty.channel.ChannelFactory<? extends io.netty.channel.ServerChannel> channelFactory

      • channelOptions

        private final java.util.Map<io.netty.channel.ChannelOption<?>,​java.lang.Object> channelOptions

      • childChannelOptions

        private final java.util.Map<io.netty.channel.ChannelOption<?>,​java.lang.Object> childChannelOptions

      • bossEventLoopGroupPool

        private ObjectPool<? extends io.netty.channel.EventLoopGroup> bossEventLoopGroupPool

      • workerEventLoopGroupPool

        private ObjectPool<? extends io.netty.channel.EventLoopGroup> workerEventLoopGroupPool

      • forceHeapBuffer

        private boolean forceHeapBuffer

      • freezeProtocolNegotiatorFactory

        private final boolean freezeProtocolNegotiatorFactory

      • maxConcurrentCallsPerConnection

        private int maxConcurrentCallsPerConnection

      • autoFlowControl

        private boolean autoFlowControl

      • flowControlWindow

        private int flowControlWindow

      • maxMessageSize

        private int maxMessageSize

      • maxHeaderListSize

        private int maxHeaderListSize

      • keepAliveTimeInNanos

        private long keepAliveTimeInNanos

      • keepAliveTimeoutInNanos

        private long keepAliveTimeoutInNanos

      • maxConnectionIdleInNanos

        private long maxConnectionIdleInNanos

      • maxConnectionAgeInNanos

        private long maxConnectionAgeInNanos

      • maxConnectionAgeGraceInNanos

        private long maxConnectionAgeGraceInNanos

      • permitKeepAliveWithoutCalls

        private boolean permitKeepAliveWithoutCalls

      • permitKeepAliveTimeInNanos

        private long permitKeepAliveTimeInNanos

      • maxRstCount

        private int maxRstCount

      • maxRstPeriodNanos

        private long maxRstPeriodNanos

    • Constructor Detail

      • NettyServerBuilder

        private NettyServerBuilder​(java.net.SocketAddress address)

    • Method Detail

      • forPort

        public static NettyServerBuilder forPort​(int port)
        Creates a server builder that will bind to the given port.
        Parameters:
        port - the port on which the server is to be bound.
        Returns:
        the server builder.

      • forPort

        public static NettyServerBuilder forPort​(int port,
                                         ServerCredentials creds)
        Creates a server builder that will bind to the given port.
        Parameters:
        port - the port on which the server is to be bound.
        Returns:
        the server builder.

      • forAddress

        public static NettyServerBuilder forAddress​(java.net.SocketAddress address)
        Creates a server builder configured with the given SocketAddress.
        Parameters:
        address - the socket address on which the server is to be bound.
        Returns:
        the server builder

      • forAddress

        public static NettyServerBuilder forAddress​(java.net.SocketAddress address,
                                            ServerCredentials creds)
        Creates a server builder configured with the given SocketAddress.
        Parameters:
        address - the socket address on which the server is to be bound.
        Returns:
        the server builder

      • addListenAddress

        @CanIgnoreReturnValue
public NettyServerBuilder addListenAddress​(java.net.SocketAddress listenAddress)
        Adds an additional address for this server to listen on. Callers must ensure that all socket addresses are compatible with the Netty channel type, and that they don't conflict with each other.

      • channelType

        @CanIgnoreReturnValue
public NettyServerBuilder channelType​(java.lang.Class<? extends io.netty.channel.ServerChannel> channelType)
        Specifies the channel type to use, by default we use EpollServerSocketChannel if available, otherwise using NioServerSocketChannel.

        You either use this or channelFactory(io.netty.channel.ChannelFactory) if your ServerChannel implementation has no no-args constructor.

        It's an optional parameter. If the user has not provided an Channel type or ChannelFactory when the channel is built, the builder will use the default one which is static.

        You must also provide corresponding EventLoopGroup using workerEventLoopGroup(EventLoopGroup) and bossEventLoopGroup(EventLoopGroup). For example, NioServerSocketChannel must use NioEventLoopGroup, otherwise your server won't start.

      • channelFactory

        @CanIgnoreReturnValue
public NettyServerBuilder channelFactory​(io.netty.channel.ChannelFactory<? extends io.netty.channel.ServerChannel> channelFactory)
        Specifies the ChannelFactory to create ServerChannel instances. This method is usually only used if the specific ServerChannel requires complex logic which requires additional information to create the ServerChannel. Otherwise, recommend to use channelType(Class).

        It's an optional parameter. If the user has not provided an Channel type or ChannelFactory when the channel is built, the builder will use the default one which is static.

        You must also provide corresponding EventLoopGroup using workerEventLoopGroup(EventLoopGroup) and bossEventLoopGroup(EventLoopGroup). For example, if the factory creates NioServerSocketChannel you must use NioEventLoopGroup, otherwise your server won't start.

      • withOption

        @CanIgnoreReturnValue
public <T> NettyServerBuilder withOption​(io.netty.channel.ChannelOption<T> option,
                                         T value)
        Specifies a channel option. As the underlying channel as well as network implementation may ignore this value applications should consider it a hint.
        Since:
        1.30.0

      • withChildOption

        @CanIgnoreReturnValue
public <T> NettyServerBuilder withChildOption​(io.netty.channel.ChannelOption<T> option,
                                              T value)
        Specifies a child channel option. As the underlying channel as well as network implementation may ignore this value applications should consider it a hint.
        Since:
        1.9.0

      • bossEventLoopGroup

        @CanIgnoreReturnValue
public NettyServerBuilder bossEventLoopGroup​(io.netty.channel.EventLoopGroup group)
        Provides the boss EventGroupLoop to the server.

        It's an optional parameter. If the user has not provided one when the server is built, the builder will use the default one which is static.

        You must also provide corresponding Channel type using channelType(Class) and workerEventLoopGroup(EventLoopGroup). For example, NioServerSocketChannel must use NioEventLoopGroup for both boss and worker EventLoopGroup, otherwise your server won't start.

        The server won't take ownership of the given EventLoopGroup. It's caller's responsibility to shut it down when it's desired.

        Grpc uses non-daemon Threads by default and thus a Server will continue to run even after the main thread has terminated. However, users have to be cautious when providing their own EventLoopGroups. For example, Netty's EventLoopGroups use daemon threads by default and thus an application with only daemon threads running besides the main thread will exit as soon as the main thread completes. A simple solution to this problem is to call Server.awaitTermination() to keep the main thread alive until the server has terminated.

      • bossEventLoopGroupPool

        @CanIgnoreReturnValue
NettyServerBuilder bossEventLoopGroupPool​(ObjectPool<? extends io.netty.channel.EventLoopGroup> bossEventLoopGroupPool)

      • workerEventLoopGroup

        @CanIgnoreReturnValue
public NettyServerBuilder workerEventLoopGroup​(io.netty.channel.EventLoopGroup group)
        Provides the worker EventGroupLoop to the server.

        It's an optional parameter. If the user has not provided one when the server is built, the builder will create one.

        You must also provide corresponding Channel type using channelType(Class) and bossEventLoopGroup(EventLoopGroup). For example, NioServerSocketChannel must use NioEventLoopGroup for both boss and worker EventLoopGroup, otherwise your server won't start.

        The server won't take ownership of the given EventLoopGroup. It's caller's responsibility to shut it down when it's desired.

        Grpc uses non-daemon Threads by default and thus a Server will continue to run even after the main thread has terminated. However, users have to be cautious when providing their own EventLoopGroups. For example, Netty's EventLoopGroups use daemon threads by default and thus an application with only daemon threads running besides the main thread will exit as soon as the main thread completes. A simple solution to this problem is to call Server.awaitTermination() to keep the main thread alive until the server has terminated.

      • workerEventLoopGroupPool

        @CanIgnoreReturnValue
NettyServerBuilder workerEventLoopGroupPool​(ObjectPool<? extends io.netty.channel.EventLoopGroup> workerEventLoopGroupPool)

      • setForceHeapBuffer

        void setForceHeapBuffer​(boolean value)
        Force using heap buffer when custom allocator is enabled.

      • sslContext

        @CanIgnoreReturnValue
public NettyServerBuilder sslContext​(io.netty.handler.ssl.SslContext sslContext)
        Sets the TLS context to use for encryption. Providing a context enables encryption. It must have been configured with GrpcSslContexts, but options could have been overridden.

      • setTracingEnabled

        void setTracingEnabled​(boolean value)

      • setStatsEnabled

        void setStatsEnabled​(boolean value)

      • setStatsRecordStartedRpcs

        void setStatsRecordStartedRpcs​(boolean value)

      • setStatsRecordRealTimeMetrics

        void setStatsRecordRealTimeMetrics​(boolean value)

      • maxConcurrentCallsPerConnection

        @CanIgnoreReturnValue
public NettyServerBuilder maxConcurrentCallsPerConnection​(int maxCalls)
        The maximum number of concurrent calls permitted for each incoming connection. Defaults to no limit.

      • initialFlowControlWindow

        @CanIgnoreReturnValue
public NettyServerBuilder initialFlowControlWindow​(int initialFlowControlWindow)
        Sets the initial flow control window in bytes. Setting initial flow control window enables auto flow control tuning using bandwidth-delay product algorithm. To disable auto flow control tuning, use flowControlWindow(int). By default, auto flow control is enabled with initial flow control window size of DEFAULT_FLOW_CONTROL_WINDOW.

      • flowControlWindow

        @CanIgnoreReturnValue
public NettyServerBuilder flowControlWindow​(int flowControlWindow)
        Sets the flow control window in bytes. Setting flowControlWindow disables auto flow control tuning; use initialFlowControlWindow(int) to enable auto flow control tuning. If not called, the default value is DEFAULT_FLOW_CONTROL_WINDOW) with auto flow control tuning.

      • maxMessageSize

        @CanIgnoreReturnValue
@Deprecated
@InlineMe(replacement="this.maxInboundMessageSize(maxMessageSize)")
public NettyServerBuilder maxMessageSize​(int maxMessageSize)
        Deprecated.
        Call maxInboundMessageSize(int) instead. This method will be removed in a future release.
        Sets the maximum message size allowed to be received on the server. If not called, defaults to 4 MiB. The default provides protection to services who haven't considered the possibility of receiving large messages while trying to be large enough to not be hit in normal usage.

      • maxInboundMessageSize

        @CanIgnoreReturnValue
public NettyServerBuilder maxInboundMessageSize​(int bytes)
        Sets the maximum message size allowed to be received on the server. If not called, defaults to 4 MiB. The default provides protection to servers who haven't considered the possibility of receiving large messages while trying to be large enough to not be hit in normal usage.

        This method is advisory, and implementations may decide to not enforce this. Currently, the only known transport to not enforce this is InProcessServer.

        Overrides:
        maxInboundMessageSize in class ForwardingServerBuilder<NettyServerBuilder>
        Parameters:
        bytes - the maximum number of bytes a single message can be.
        Returns:
        this

      • maxHeaderListSize

        @CanIgnoreReturnValue
@Deprecated
@InlineMe(replacement="this.maxInboundMetadataSize(maxHeaderListSize)")
public NettyServerBuilder maxHeaderListSize​(int maxHeaderListSize)
        Deprecated.
        Use maxInboundMetadataSize(int) instead
        Sets the maximum size of header list allowed to be received. This is cumulative size of the headers with some overhead, as defined for HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE. The default is 8 KiB.

      • maxConnectionIdle

        @CanIgnoreReturnValue
public NettyServerBuilder maxConnectionIdle​(long maxConnectionIdle,
                                            java.util.concurrent.TimeUnit timeUnit)
        Sets a custom max connection idle time, connection being idle for longer than which will be gracefully terminated. Idleness duration is defined since the most recent time the number of outstanding RPCs became zero or the connection establishment. An unreasonably small value might be increased. Long.MAX_VALUE nano seconds or an unreasonably large value will disable max connection idle.
        Overrides:
        maxConnectionIdle in class ForwardingServerBuilder<NettyServerBuilder>
        Since:
        1.4.0
        See Also:
        gRFC A9 Server-side Connection Management

      • maxConnectionAge

        @CanIgnoreReturnValue
public NettyServerBuilder maxConnectionAge​(long maxConnectionAge,
                                           java.util.concurrent.TimeUnit timeUnit)
        Sets a custom max connection age, connection lasting longer than which will be gracefully terminated. An unreasonably small value might be increased. A random jitter of +/-10% will be added to it. Long.MAX_VALUE nano seconds or an unreasonably large value will disable max connection age.
        Overrides:
        maxConnectionAge in class ForwardingServerBuilder<NettyServerBuilder>
        Since:
        1.3.0
        See Also:
        gRFC A9 Server-side Connection Management

      • maxConnectionAgeGrace

        @CanIgnoreReturnValue
public NettyServerBuilder maxConnectionAgeGrace​(long maxConnectionAgeGrace,
                                                java.util.concurrent.TimeUnit timeUnit)
        Sets a custom grace time for the graceful connection termination. Once the max connection age is reached, RPCs have the grace time to complete. RPCs that do not complete in time will be cancelled, allowing the connection to terminate. Long.MAX_VALUE nano seconds or an unreasonably large value are considered infinite.
        Overrides:
        maxConnectionAgeGrace in class ForwardingServerBuilder<NettyServerBuilder>
        Since:
        1.3.0
        See Also:
        maxConnectionAge(long, TimeUnit)

      • permitKeepAliveTime

        @CanIgnoreReturnValue
public NettyServerBuilder permitKeepAliveTime​(long keepAliveTime,
                                              java.util.concurrent.TimeUnit timeUnit)
        Specify the most aggressive keep-alive time clients are permitted to configure. The server will try to detect clients exceeding this rate and when detected will forcefully close the connection. The default is 5 minutes.

        Even though a default is defined that allows some keep-alives, clients must not use keep-alive without approval from the service owner. Otherwise, they may experience failures in the future if the service becomes more restrictive. When unthrottled, keep-alives can cause a significant amount of traffic and CPU usage, so clients and servers should be conservative in what they use and accept.

        Overrides:
        permitKeepAliveTime in class ForwardingServerBuilder<NettyServerBuilder>
        Since:
        1.3.0
        See Also:
        permitKeepAliveWithoutCalls(boolean)

      • maxRstFramesPerWindow

        @CanIgnoreReturnValue
public NettyServerBuilder maxRstFramesPerWindow​(int maxRstStream,
                                                int secondsPerWindow)
        Limits the rate of incoming RST_STREAM frames per connection to maxRstStream per secondsPerWindow. When exceeded on a connection, the connection is closed. This can reduce the impact of an attacker continually resetting RPCs before they complete, when combined with TLS and maxConcurrentCallsPerConnection(int).

        gRPC clients send RST_STREAM when they cancel RPCs, so some RST_STREAMs are normal and setting this too low can cause errors for legimitate clients.

        By default there is no limit.

        Parameters:
        maxRstStream - the positive limit of RST_STREAM frames per connection per period, or Integer.MAX_VALUE for unlimited
        secondsPerWindow - the positive number of seconds per period

      • eagAttributes

        void eagAttributes​(Attributes eagAttributes)
        Sets the EAG attributes available to protocol negotiators. Not for general use.

      • assertEventLoopsAndChannelType

        void assertEventLoopsAndChannelType()

      • useTransportSecurity

        @CanIgnoreReturnValue
public NettyServerBuilder useTransportSecurity​(java.io.InputStream certChain,
                                               java.io.InputStream privateKey)
        Description copied from class: ServerBuilder
        Makes the server use TLS.
        Overrides:
        useTransportSecurity in class ForwardingServerBuilder<NettyServerBuilder>
        Parameters:
        certChain - InputStream containing the full certificate chain
        privateKey - InputStream containing the private key
        Returns:
        this