Package io.servicetalk.grpc.api

Class GrpcServerBuilder

  • public abstract class GrpcServerBuilder
extends java.lang.Object
    A builder for building a gRPC server.

    • Field Detail

      • GRPC_DEADLINE_KEY

        protected static final AsyncContextMap.Key<java.lang.Long> GRPC_DEADLINE_KEY
        gRPC timeout is stored in context as a deadline so that when propagated to a new client request the remaining time to be included in the request can be calculated.

    • Constructor Detail

      • GrpcServerBuilder

        public GrpcServerBuilder()

    • Method Detail

      • defaultTimeout

        public abstract GrpcServerBuilder defaultTimeout​(java.time.Duration defaultTimeout)
        Set a default timeout during which gRPC calls are expected to complete. This default will be used only if the request includes no timeout; any value specified in client request will supersede this default.
        Parameters:
        defaultTimeout - Duration of default timeout which must be positive non-zero.
        Returns:
        this.

      • backlog

        @Deprecated
public GrpcServerBuilder backlog​(int backlog)
        Deprecated.
        Use listenSocketOption(SocketOption, Object) with key ServiceTalkSocketOptions.SO_BACKLOG.
        The maximum queue length for incoming connection indications (a request to connect) is set to the backlog parameter. If a connection indication arrives when the queue is full, the connection may time out.
        Parameters:
        backlog - the backlog to use when accepting connections.
        Returns:
        this.

      • sslConfig

        public abstract GrpcServerBuilder sslConfig​(ServerSslConfig config)
        Set the SSL/TLS configuration.
        Parameters:
        config - The configuration to use.
        Returns:
        this.

      • sslConfig

        public abstract GrpcServerBuilder sslConfig​(ServerSslConfig defaultConfig,
                                            java.util.Map<java.lang.String,​ServerSslConfig> sniMap)
        Set the SSL/TLS and SNI configuration.
        Parameters:
        defaultConfig - The configuration to use is the client certificate's SNI extension isn't present or the SNI hostname doesn't match any values in sniMap.
        sniMap - A map where the keys are matched against the client certificate's SNI extension value in order to provide the corresponding ServerSslConfig.
        Returns:
        this.

      • socketOption

        public abstract <T> GrpcServerBuilder socketOption​(java.net.SocketOption<T> option,
                                                   T value)
        Add a SocketOption that is applied.
        Type Parameters:
        T - the type of the value.
        Parameters:
        option - the option to apply.
        value - the value.
        Returns:
        this.
        See Also:
        StandardSocketOptions, ServiceTalkSocketOptions

      • listenSocketOption

        public abstract <T> GrpcServerBuilder listenSocketOption​(java.net.SocketOption<T> option,
                                                         T value)
        Adds a SocketOption that is applied to the server socket channel which listens/accepts socket channels.
        Type Parameters:
        T - the type of the value.
        Parameters:
        option - the option to apply.
        value - the value.
        Returns:
        this.
        See Also:
        StandardSocketOptions, ServiceTalkSocketOptions

      • enableWireLogging

        public abstract GrpcServerBuilder enableWireLogging​(java.lang.String loggerName,
                                                    LogLevel logLevel,
                                                    java.util.function.BooleanSupplier logUserData)
        Enables wire-logging for connections created by this builder.
        Parameters:
        loggerName - The name of the logger to log wire events.
        logLevel - The level to log at.
        logUserData - true to include user data (e.g. data, headers, etc.). false to exclude user data and log only network events.
        Returns:
        this.

      • disableDrainingRequestPayloadBody

        public abstract GrpcServerBuilder disableDrainingRequestPayloadBody()
        Disables automatic consumption of request payload body when it is not consumed by the service.

        For persistent HTTP connections it is required to eventually consume the entire request payload to enable reading of the next request. This is required because requests are pipelined for HTTP/1.1, so if the previous request is not completely read, next request can not be read from the socket. For cases when there is a possibility that user may forget to consume request payload, ServiceTalk automatically consumes request payload body. This automatic consumption behavior may create some overhead and can be disabled using this method when it is guaranteed that all request paths consumes all request payloads eventually. An example of guaranteed consumption are non-streaming APIs.

        Returns:
        this.

      • appendConnectionAcceptorFilter

        public abstract GrpcServerBuilder appendConnectionAcceptorFilter​(ConnectionAcceptorFactory factory)
        Append the filter to the chain of filters used to decorate the ConnectionAcceptor used by this builder.

        The order of execution of these filters are in order of append. If 3 filters are added as follows: 

             builder.appendConnectionAcceptorFilter(filter1).appendConnectionAcceptorFilter(filter2).
     appendConnectionAcceptorFilter(filter3)
        accepting a connection by a filter wrapped by this filter chain, the order of invocation of these filters will be: 
             filter1 => filter2 => filter3
        Parameters:
        factory - ConnectionAcceptorFactory to append. Lifetime of this ConnectionAcceptorFactory is managed by this builder and the server started thereof.
        Returns:
        this.

      • appendHttpServiceFilter

        public final GrpcServerBuilder appendHttpServiceFilter​(StreamingHttpServiceFilterFactory factory)
        Append the filter to the chain of filters used to decorate the service used by this builder.

        The order of execution of these filters are in order of append. If 3 filters are added as follows: 

             builder.append(filter1).append(filter2).append(filter3)
        accepting a request by a service wrapped by this filter chain, the order of invocation of these filters will be: 
             filter1 => filter2 => filter3 => service
        Parameters:
        factory - StreamingHttpServiceFilterFactory to append.
        Returns:
        this.

      • appendHttpServiceFilter

        public final GrpcServerBuilder appendHttpServiceFilter​(java.util.function.Predicate<StreamingHttpRequest> predicate,
                                                       StreamingHttpServiceFilterFactory factory)
        Append the filter to the chain of filters used to decorate the service used by this builder, for every request that passes the provided Predicate.

        The order of execution of these filters are in order of append. If 3 filters are added as follows: 

             builder.append(filter1).append(filter2).append(filter3)
        accepting a request by a service wrapped by this filter chain, the order of invocation of these filters will be: 
             filter1 => filter2 => filter3 => service
        Parameters:
        predicate - the Predicate to test if the filter must be applied.
        factory - StreamingHttpServiceFilterFactory to append.
        Returns:
        this.

      • listen

        public final Single<ServerContext> listen​(GrpcBindableService<?,​?,​?>... services)
        Starts this server and returns the ServerContext after the server has been successfully started.

        If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

        Parameters:
        services - GrpcBindableService(s) to create a gRPC service.
        Returns:
        A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

      • listen

        public final Single<ServerContext> listen​(GrpcServiceFactory<?,​?,​?>... serviceFactories)
        Starts this server and returns the ServerContext after the server has been successfully started.

        If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

        Parameters:
        serviceFactories - GrpcServiceFactory(s) to create a gRPC service.
        Returns:
        A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

      • listenAndAwait

        public final ServerContext listenAndAwait​(GrpcServiceFactory<?,​?,​?>... serviceFactories)
                                   throws java.lang.Exception
        Starts this server and returns the ServerContext after the server has been successfully started.

        If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

        Parameters:
        serviceFactories - GrpcServiceFactory(s) to create a gRPC service.
        Returns:
        A ServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.
        Throws:
        java.lang.Exception - if the server could not be started.

      • listenAndAwait

        public final ServerContext listenAndAwait​(GrpcBindableService<?,​?,​?>... services)
                                   throws java.lang.Exception
        Starts this server and returns the ServerContext after the server has been successfully started.

        If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

        Parameters:
        services - GrpcBindableService(s) to create a gRPC service.
        Returns:
        A ServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.
        Throws:
        java.lang.Exception - if the server could not be started.

      • doListen

        protected abstract Single<ServerContext> doListen​(GrpcServiceFactory<?,​?,​?> serviceFactory)
        Starts this server and returns the ServerContext after the server has been successfully started.

        If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

        Parameters:
        serviceFactory - GrpcServiceFactory to create a gRPC service.
        Returns:
        A ServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

      • doAppendHttpServiceFilter

        protected abstract void doAppendHttpServiceFilter​(StreamingHttpServiceFilterFactory factory)
        Append the filter to the chain of filters used to decorate the service used by this builder.

        The order of execution of these filters are in order of append. If 3 filters are added as follows: 

             builder.append(filter1).append(filter2).append(filter3)
        accepting a request by a service wrapped by this filter chain, the order of invocation of these filters will be: 
             filter1 => filter2 => filter3 => service
        Parameters:
        factory - StreamingHttpServiceFilterFactory to append.

      • doAppendHttpServiceFilter

        protected abstract void doAppendHttpServiceFilter​(java.util.function.Predicate<StreamingHttpRequest> predicate,
                                                  StreamingHttpServiceFilterFactory factory)
        Append the filter to the chain of filters used to decorate the service used by this builder, for every request that passes the provided Predicate.

        The order of execution of these filters are in order of append. If 3 filters are added as follows: 

             builder.append(filter1).append(filter2).append(filter3)
        accepting a request by a service wrapped by this filter chain, the order of invocation of these filters will be: 
             filter1 => filter2 => filter3 => service
        Parameters:
        predicate - the Predicate to test if the filter must be applied.
        factory - StreamingHttpServiceFilterFactory to append.