io.servicetalk.http.api

Interface HttpServerBuilder

public interface HttpServerBuilder

A builder for building HTTP Servers.

Method Summary

Modifier and Type	Method and Description
HttpServerBuilder	allowDropRequestTrailers(boolean allowDrop) Provide a hint if request trailers are allowed to be dropped.
HttpServerBuilder	appendConnectionAcceptorFilter(ConnectionAcceptorFactory factory) Appends the filter to the chain of filters used to decorate the ConnectionAcceptor used by this builder.
HttpServerBuilder	appendNonOffloadingServiceFilter(Predicate<StreamingHttpRequest> predicate, StreamingHttpServiceFilterFactory factory) Appends a non-offloading filter to the chain of filters used to decorate the StreamingHttpService used by this builder, for every request that passes the provided Predicate.
HttpServerBuilder	appendNonOffloadingServiceFilter(StreamingHttpServiceFilterFactory factory) Appends a non-offloading filter to the chain of filters used to decorate the StreamingHttpService used by this builder.
HttpServerBuilder	appendServiceFilter(Predicate<StreamingHttpRequest> predicate, StreamingHttpServiceFilterFactory factory) Appends the filter to the chain of filters used to decorate the StreamingHttpService used by this builder, for every request that passes the provided Predicate.
HttpServerBuilder	appendServiceFilter(StreamingHttpServiceFilterFactory factory) Appends the filter to the chain of filters used to decorate the StreamingHttpService used by this builder.
HttpServerBuilder	bufferAllocator(BufferAllocator allocator) Sets the BufferAllocator to be used by this server.
HttpServerBuilder	drainRequestPayloadBody(boolean enable) Configure automatic consumption of request payload body when it is not consumed by the service.
HttpServerBuilder	enableWireLogging(String loggerName, LogLevel logLevel, BooleanSupplier logUserData) Enables wire-logging for this server.
HttpServerBuilder	executionStrategy(HttpExecutionStrategy strategy) Sets the HttpExecutionStrategy to be used by this server.
HttpServerBuilder	executor(Executor executor) Sets the Executor to be used by this server.
HttpServerBuilder	ioExecutor(IoExecutor ioExecutor) Sets the IoExecutor to be used by this server.
HttpServerBuilder	lifecycleObserver(HttpLifecycleObserver lifecycleObserver) Sets a HttpLifecycleObserver that provides visibility into HTTP lifecycle events.
Single<HttpServerContext>	listen(HttpService service) Starts this server and returns the HttpServerContext after the server has been successfully started.
default HttpServerContext	listenAndAwait(HttpService service) Starts this server and returns the HttpServerContext after the server has been successfully started.
Single<HttpServerContext>	listenBlocking(BlockingHttpService service) Starts this server and returns the HttpServerContext after the server has been successfully started.
default HttpServerContext	listenBlockingAndAwait(BlockingHttpService service) Starts this server and returns the HttpServerContext after the server has been successfully started.
Single<HttpServerContext>	listenBlockingStreaming(BlockingStreamingHttpService service) Starts this server and returns the HttpServerContext after the server has been successfully started.
default HttpServerContext	listenBlockingStreamingAndAwait(BlockingStreamingHttpService handler) Starts this server and returns the HttpServerContext after the server has been successfully started.
<T> HttpServerBuilder	listenSocketOption(SocketOption<T> option, T value) Adds a SocketOption that is applied to the server socket channel which listens/accepts socket channels.
Single<HttpServerContext>	listenStreaming(StreamingHttpService service) Starts this server and returns the HttpServerContext after the server has been successfully started.
default HttpServerContext	listenStreamingAndAwait(StreamingHttpService handler) Starts this server and returns the HttpServerContext after the server has been successfully started.
HttpServerBuilder	protocols(HttpProtocolConfig... protocols) Configurations of various HTTP protocol versions.
<T> HttpServerBuilder	socketOption(SocketOption<T> option, T value) Adds a SocketOption that is applied to connected/accepted socket channels.
HttpServerBuilder	sslConfig(ServerSslConfig config) Set the SSL/TLS configuration.
HttpServerBuilder	sslConfig(ServerSslConfig defaultConfig, Map<String,ServerSslConfig> sniMap) Set the SSL/TLS and SNI configuration.
HttpServerBuilder	transportObserver(TransportObserver transportObserver) Sets a TransportObserver that provides visibility into transport events.

Method Detail

protocols

HttpServerBuilder protocols(HttpProtocolConfig... protocols)

Configurations of various HTTP protocol versions.

Note: the order of specified protocols will reflect on priorities for ALPN in case the connections use sslConfig(ServerSslConfig).

Parameters:

protocols - HttpProtocolConfig for each protocol that should be supported.

Returns:

this.

sslConfig

HttpServerBuilder sslConfig(ServerSslConfig config)

Set the SSL/TLS configuration.

Parameters:

config - The configuration to use.

Returns:

this.

sslConfig

HttpServerBuilder sslConfig(ServerSslConfig defaultConfig,
                            Map<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

<T> HttpServerBuilder socketOption(SocketOption<T> option,
                                   T value)

Adds a SocketOption that is applied to connected/accepted 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

listenSocketOption

<T> HttpServerBuilder listenSocketOption(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

HttpServerBuilder enableWireLogging(String loggerName,
                                    LogLevel logLevel,
                                    BooleanSupplier logUserData)

Enables wire-logging for this server.

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.

transportObserver

HttpServerBuilder transportObserver(TransportObserver transportObserver)

Sets a TransportObserver that provides visibility into transport events.

Parameters:

transportObserver - A TransportObserver that provides visibility into transport events.

Returns:

this.

lifecycleObserver

HttpServerBuilder lifecycleObserver(HttpLifecycleObserver lifecycleObserver)

Sets a HttpLifecycleObserver that provides visibility into HTTP lifecycle events.

Parameters:

lifecycleObserver - A HttpLifecycleObserver that provides visibility into HTTP lifecycle events.

Returns:

this.

drainRequestPayloadBody

HttpServerBuilder drainRequestPayloadBody(boolean enable)

Configure 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.

Parameters:

enable - When false it will disable the automatic consumption of request StreamingHttpRequest.payloadBody().

Returns:

this.

allowDropRequestTrailers

HttpServerBuilder allowDropRequestTrailers(boolean allowDrop)

Provide a hint if request trailers are allowed to be dropped. This hint maybe ignored if the transport can otherwise infer that the trailers should be preserved. For example, if the request headers contain Trailer then this hint maybe ignored.

Parameters:

allowDrop - true if request trailers are allowed to be dropped.

Returns:

this

appendConnectionAcceptorFilter

HttpServerBuilder appendConnectionAcceptorFilter(ConnectionAcceptorFactory factory)

Appends 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
 

The connection acceptor will, by default, not be offloaded. If your filter requires the ConnectionAcceptor.accept(ConnectionContext) to be offloaded then your ConnectionAcceptorFactory will need to return ConnectExecutionStrategy.offloadAll() from the ExecutionStrategyInfluencer.requiredOffloads().

Parameters:

factory - ConnectionAcceptorFactory to append. Lifetime of this ConnectionAcceptorFactory is managed by this builder and the server started thereof.

Returns:

this

appendNonOffloadingServiceFilter

HttpServerBuilder appendNonOffloadingServiceFilter(StreamingHttpServiceFilterFactory factory)

Appends a non-offloading filter to the chain of filters used to decorate the StreamingHttpService used by this builder.

Note this method will be used to decorate the StreamingHttpService passed to listenStreaming(StreamingHttpService) before it is used by the server.

The order of execution of these filters are in order of append, before the filters added with appendServiceFilter(StreamingHttpServiceFilterFactory). If 3 filters are added as follows:

     builder
         .appendServiceFilter(filter1)
         .appendNonOffloadingServiceFilter(filter2)
         .appendServiceFilter(filter3)
 

accepting a request by a service wrapped by this filter chain, the order of invocation of these filters will be:

     filter2 ⇒ [offloading] ⇒ filter1 ⇒ filter3 ⇒ service
 

Parameters:

factory - StreamingHttpServiceFilterFactory to append.

Returns:

this

Throws:

IllegalArgumentException - if the provided filter requires offloading.

appendNonOffloadingServiceFilter

HttpServerBuilder appendNonOffloadingServiceFilter(Predicate<StreamingHttpRequest> predicate,
                                                   StreamingHttpServiceFilterFactory factory)

Appends a non-offloading filter to the chain of filters used to decorate the StreamingHttpService used by this builder, for every request that passes the provided Predicate. Filters added via this method will be executed before offloading occurs and before filters appended via appendServiceFilter(StreamingHttpServiceFilterFactory).

Note this method will be used to decorate the StreamingHttpService passed to listenStreaming(StreamingHttpService) before it is used by the server. The order of execution of these filters are in order of append, before the filters added with appendServiceFilter(StreamingHttpServiceFilterFactory). If 3 filters are added as follows:

     builder
         .appendServiceFilter(filter1)
         .appendNonOffloadingServiceFilter(filter2)
         .appendServiceFilter(filter3)
 

accepting a request by a service wrapped by this filter chain, the order of invocation of these filters will be:

     filter2 ⇒ [offloading] ⇒ filter1 ⇒ filter3 ⇒ service
 

Parameters:

predicate - the Predicate to test if the filter must be applied. This must not block.

factory - StreamingHttpServiceFilterFactory to append.

Returns:

this

Throws:

IllegalArgumentException - if the provided filter or predicate requires offloading.

appendServiceFilter

HttpServerBuilder appendServiceFilter(StreamingHttpServiceFilterFactory factory)

Appends the filter to the chain of filters used to decorate the StreamingHttpService used by this builder.

Note this method will be used to decorate the StreamingHttpService passed to listenStreaming(StreamingHttpService) before it is used by the server.

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

     builder.appendServiceFilter(filter1).appendServiceFilter(filter2).appendServiceFilter(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

appendServiceFilter

HttpServerBuilder appendServiceFilter(Predicate<StreamingHttpRequest> predicate,
                                      StreamingHttpServiceFilterFactory factory)

Appends the filter to the chain of filters used to decorate the StreamingHttpService used by this builder, for every request that passes the provided Predicate.

Note this method will be used to decorate the StreamingHttpService passed to listenStreaming(StreamingHttpService) before it is used by the server.

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

     builder.appendServiceFilter(filter1).appendServiceFilter(filter2).appendServiceFilter(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. This must not block.

factory - StreamingHttpServiceFilterFactory to append.

Returns:

this

ioExecutor

HttpServerBuilder ioExecutor(IoExecutor ioExecutor)

Sets the IoExecutor to be used by this server.

Parameters:

ioExecutor - IoExecutor to use.

Returns:

this.

executor

HttpServerBuilder executor(Executor executor)

Sets the Executor to be used by this server.

Parameters:

executor - Executor to use.

Returns:

this.

bufferAllocator

HttpServerBuilder bufferAllocator(BufferAllocator allocator)

Sets the BufferAllocator to be used by this server.

Parameters:

allocator - BufferAllocator to use.

Returns:

this.

executionStrategy

HttpServerBuilder executionStrategy(HttpExecutionStrategy strategy)

Sets the HttpExecutionStrategy to be used by this server.

Parameters:

strategy - HttpExecutionStrategy to use by this server.

Returns:

this.

listenAndAwait

default HttpServerContext listenAndAwait(HttpService service)
                                  throws Exception

Starts this server and returns the HttpServerContext after the server has been successfully started.

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

Parameters:

service - Service invoked for every request received by this server. The returned HttpServerContext manages the lifecycle of the service, ensuring it is closed when the HttpServerContext is closed.

Returns:

A HttpServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

Throws:

Exception - if the server could not be started.

listenStreamingAndAwait

default HttpServerContext listenStreamingAndAwait(StreamingHttpService handler)
                                           throws Exception

Starts this server and returns the HttpServerContext after the server has been successfully started.

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

Parameters:

handler - Service invoked for every request received by this server. The returned HttpServerContext manages the lifecycle of the service, ensuring it is closed when the HttpServerContext is closed.

Returns:

A HttpServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

Throws:

Exception - if the server could not be started.

listenBlockingAndAwait

default HttpServerContext listenBlockingAndAwait(BlockingHttpService service)
                                          throws Exception

Starts this server and returns the HttpServerContext after the server has been successfully started.

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

Parameters:

service - Service invoked for every request received by this server. The returned HttpServerContext manages the lifecycle of the service, ensuring it is closed when the HttpServerContext is closed.

Returns:

A HttpServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

Throws:

Exception - if the server could not be started.

listenBlockingStreamingAndAwait

default HttpServerContext listenBlockingStreamingAndAwait(BlockingStreamingHttpService handler)
                                                   throws Exception

Starts this server and returns the HttpServerContext after the server has been successfully started.

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

Parameters:

handler - Service invoked for every request received by this server. The returned HttpServerContext manages the lifecycle of the service, ensuring it is closed when the HttpServerContext is closed.

Returns:

A HttpServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

Throws:

Exception - if the server could not be started.

listen

Single<HttpServerContext> listen(HttpService service)

Starts this server and returns the HttpServerContext after the server has been successfully started.

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

Parameters:

service - Service invoked for every request received by this server. The returned HttpServerContext manages the lifecycle of the service, ensuring it is closed when the HttpServerContext is closed.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

listenStreaming

Single<HttpServerContext> listenStreaming(StreamingHttpService service)

Starts this server and returns the HttpServerContext after the server has been successfully started.

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

Parameters:

service - Service invoked for every request received by this server. The returned HttpServerContext manages the lifecycle of the service, ensuring it is closed when the HttpServerContext is closed.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

listenBlocking

Single<HttpServerContext> listenBlocking(BlockingHttpService service)

Starts this server and returns the HttpServerContext after the server has been successfully started.

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

Parameters:

service - Service invoked for every request received by this server. The returned HttpServerContext manages the lifecycle of the service, ensuring it is closed when the HttpServerContext is closed.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

listenBlockingStreaming

Single<HttpServerContext> listenBlockingStreaming(BlockingStreamingHttpService service)

Starts this server and returns the HttpServerContext after the server has been successfully started.

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

Parameters:

service - Service invoked for every request received by this server. The returned HttpServerContext manages the lifecycle of the service, ensuring it is closed when the HttpServerContext is closed.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.