Interface HttpServerBuilder
- All Known Implementing Classes:
DelegatingHttpServerBuilder
-
Method Summary
Modifier and TypeMethodDescriptionallowDropRequestTrailers
(boolean allowDrop) Provide a hint if request trailers are allowed to be dropped.default HttpServerBuilder
Deprecated.default HttpServerBuilder
Appends theEarlyConnectionAcceptor
to be called when a new connection has been created.default HttpServerBuilder
Appends theLateConnectionAcceptor
to be called when a new connection has been created.Appends a non-offloading filter to the chain of filters used to decorate theStreamingHttpService
used by this builder.appendNonOffloadingServiceFilter
(Predicate<StreamingHttpRequest> predicate, StreamingHttpServiceFilterFactory factory) Appends a non-offloading filter to the chain of filters used to decorate theStreamingHttpService
used by this builder, for every request that passes the providedPredicate
.Appends the filter to the chain of filters used to decorate theStreamingHttpService
used by this builder.appendServiceFilter
(Predicate<StreamingHttpRequest> predicate, StreamingHttpServiceFilterFactory factory) Appends the filter to the chain of filters used to decorate theStreamingHttpService
used by this builder, for every request that passes the providedPredicate
.bufferAllocator
(BufferAllocator allocator) Sets theBufferAllocator
to be used by this server.drainRequestPayloadBody
(boolean enable) Configure automatic consumption of requestpayload body
when it is not consumed by the service.enableWireLogging
(String loggerName, LogLevel logLevel, BooleanSupplier logUserData) Enables wire-logging for this server.executionStrategy
(HttpExecutionStrategy strategy) Sets theHttpExecutionStrategy
to be used by this server.Sets theExecutor
to be used by this server.ioExecutor
(IoExecutor ioExecutor) Sets theIoExecutor
to be used by this server.lifecycleObserver
(HttpLifecycleObserver lifecycleObserver) Sets aHttpLifecycleObserver
that provides visibility into HTTP lifecycle events.listen
(HttpService service) Starts this server and returns theHttpServerContext
after the server has been successfully started.default HttpServerContext
listenAndAwait
(HttpService service) Starts this server and returns theHttpServerContext
after the server has been successfully started.listenBlocking
(BlockingHttpService service) Starts this server and returns theHttpServerContext
after the server has been successfully started.default HttpServerContext
Starts this server and returns theHttpServerContext
after the server has been successfully started.Starts this server and returns theHttpServerContext
after the server has been successfully started.default HttpServerContext
Starts this server and returns theHttpServerContext
after the server has been successfully started.default Single<HttpServerContext>
listenService
(HttpServiceBase service) Starts this server and returns theHttpServerContext
after the server has been successfully started.default HttpServerContext
listenServiceAndAwait
(HttpServiceBase service) Starts this server and returns theHttpServerContext
after the server has been successfully started.listenSocketOption
(SocketOption<T> option, T value) Adds aSocketOption
that is applied to the server socket channel which listens/accepts socket channels.listenStreaming
(StreamingHttpService service) Starts this server and returns theHttpServerContext
after the server has been successfully started.default HttpServerContext
Starts this server and returns theHttpServerContext
after the server has been successfully started.protocols
(HttpProtocolConfig... protocols) Configurations of various HTTP protocol versions.socketOption
(SocketOption<T> option, T value) Adds aSocketOption
that is applied to connected/accepted socket channels.sslConfig
(ServerSslConfig config) Set the SSL/TLS configuration.default HttpServerBuilder
sslConfig
(ServerSslConfig config, boolean acceptInsecureConnections) Set the SSL/TLS configuration and allows to specify if insecure connections should also be allowed.sslConfig
(ServerSslConfig defaultConfig, Map<String, ServerSslConfig> sniMap) Set the SSL/TLS and SNI configuration.default HttpServerBuilder
sslConfig
(ServerSslConfig defaultConfig, Map<String, ServerSslConfig> sniMap, int maxClientHelloLength, Duration clientHelloTimeout) Set the SSL/TLS and SNI configuration.default HttpServerBuilder
transportConfig
(TransportConfig transportConfig) Set the transport configuration.transportObserver
(TransportObserver transportObserver) Sets aTransportObserver
that provides visibility into transport events.
-
Method Details
-
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
Set the SSL/TLS configuration.- Parameters:
config
- The configuration to use.- Returns:
this
.
-
sslConfig
Set the SSL/TLS configuration and allows to specify if insecure connections should also be allowed.- Parameters:
config
- The configuration to use.acceptInsecureConnections
- if non-TLS connections are accepted on the same socket.- Returns:
this
.
-
sslConfig
Set the SSL/TLS and SNI configuration.- Parameters:
defaultConfig
- The configuration to use if the client certificate's SNI extension isn't present or the SNI hostname doesn't match any values insniMap
.sniMap
- A map where the keys are matched against the client certificate's SNI extension value in order to provide the correspondingServerSslConfig
.- Returns:
this
.
-
sslConfig
default HttpServerBuilder sslConfig(ServerSslConfig defaultConfig, Map<String, ServerSslConfig> sniMap, int maxClientHelloLength, Duration clientHelloTimeout) Set the SSL/TLS and SNI configuration.- Parameters:
defaultConfig
- The configuration to use if the client certificate's SNI extension isn't present or the SNI hostname doesn't match any values insniMap
.sniMap
- A map where the keys are matched against the client certificate's SNI extension value in order to provide the correspondingServerSslConfig
.maxClientHelloLength
- The maximum length of a ClientHello message in bytes, up to2^24 - 1
bytes. Zero (0
) disables validation.clientHelloTimeout
- The timeout for waiting until ClientHello message is received. Implementations can round the specifiedDuration
to full time units, depending on their time granularity.Zero (0)
disables timeout.- Returns:
this
.
-
transportConfig
Set the transport configuration.- Parameters:
transportConfig
-TransportConfig
to use.- Returns:
this
.- See Also:
-
socketOption
Adds aSocketOption
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:
-
listenSocketOption
Adds aSocketOption
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:
-
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. This method is invoked for each data object allowing for dynamic behavior.- Returns:
this
.
-
transportObserver
Sets aTransportObserver
that provides visibility into transport events.- Parameters:
transportObserver
- ATransportObserver
that provides visibility into transport events.- Returns:
this
.
-
lifecycleObserver
Sets aHttpLifecycleObserver
that provides visibility into HTTP lifecycle events.This method allows setting a
HttpLifecycleObserver
in a position that captures entire state of the execution chain, including all filters and internal post-processing. If it's necessary to observe an exchange after other filters or apply it conditionally, consider usingio.servicetalk.http.netty.HttpLifecycleObserverServiceFilter
instead.- Parameters:
lifecycleObserver
- AHttpLifecycleObserver
that provides visibility into HTTP lifecycle events.- Returns:
this
.
-
drainRequestPayloadBody
Configure automatic consumption of requestpayload 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
- Whenfalse
it will disable the automatic consumption of requestStreamingHttpRequest.payloadBody()
.- Returns:
this
.
-
allowDropRequestTrailers
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
@Deprecated default HttpServerBuilder appendConnectionAcceptorFilter(ConnectionAcceptorFactory factory) Deprecated.useappendLateConnectionAcceptor(LateConnectionAcceptor)
instead.Appends the filter to the chain of filters used to decorate theConnectionAcceptor
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 yourConnectionAcceptorFactory
will need to returnConnectExecutionStrategy.offloadAll()
from theExecutionStrategyInfluencer.requiredOffloads()
.- Parameters:
factory
-ConnectionAcceptorFactory
to append. Lifetime of thisConnectionAcceptorFactory
is managed by this builder and the server started thereof.- Returns:
this
-
appendEarlyConnectionAcceptor
Appends theEarlyConnectionAcceptor
to be called when a new connection has been created.The difference between the
EarlyConnectionAcceptor
and theLateConnectionAcceptor
is that the early one is called right after the connection has been accepted - and most importantly - before any TLS handshake has been performed. This allows to terminate connections quickly and spend less CPU resources if the amount of information provided to make such a decision is sufficient.The order of execution of these acceptors are in order of append. If 3 acceptors are added as follows:
builder .appendEarlyConnectionAcceptor(acceptor1) .appendEarlyConnectionAcceptor(acceptor2) .appendEarlyConnectionAcceptor(acceptor3)
the order of invocation of these filters will be:acceptor1 ⇒ acceptor2 ⇒ acceptor3
The acceptor is offloaded by default. If an acceptor in the chain fails the
Completable
, the later ones will not be called.- Parameters:
acceptor
- the acceptor to append to the chain of acceptors.- Returns:
- this
HttpServerBuilder
for chaining purposes. - See Also:
-
appendLateConnectionAcceptor
Appends theLateConnectionAcceptor
to be called when a new connection has been created.The
LateConnectionAcceptor
(compared to theEarlyConnectionAcceptor
) gets called later in the connection establishment process. Instead of being invoked right after the connection has been accepted, this acceptor gets called after the connection is fully initialized, the TLS handshake has been completed and as a result has more contextual information available in theConnectionInfo
.The order of execution of these acceptors are in order of append. If 3 acceptors are added as follows:
builder .appendLateConnectionAcceptor(acceptor1) .appendLateConnectionAcceptor(acceptor2) .appendLateConnectionAcceptor(acceptor3)
the order of invocation of these filters will be:acceptor1 ⇒ acceptor2 ⇒ acceptor3
The acceptor is offloaded by default. If an acceptor in the chain fails the
Completable
, the later ones will not be called.- Parameters:
acceptor
- the acceptor to append to the chain of acceptors.- Returns:
- this
HttpServerBuilder
for chaining purposes. - See Also:
-
appendNonOffloadingServiceFilter
Appends a non-offloading filter to the chain of filters used to decorate theStreamingHttpService
used by this builder.Note this method will be used to decorate the
StreamingHttpService
passed tolistenStreaming(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 theStreamingHttpService
used by this builder, for every request that passes the providedPredicate
. Filters added via this method will be executed before offloading occurs and before filters appended viaappendServiceFilter(StreamingHttpServiceFilterFactory)
.Note this method will be used to decorate the
StreamingHttpService
passed tolistenStreaming(StreamingHttpService)
before it is used by the server. The order of execution of these filters are in order of append, before the filters added withappendServiceFilter(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
- thePredicate
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
Appends the filter to the chain of filters used to decorate theStreamingHttpService
used by this builder.Note this method will be used to decorate the
StreamingHttpService
passed tolistenStreaming(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 theStreamingHttpService
used by this builder, for every request that passes the providedPredicate
.Note this method will be used to decorate the
StreamingHttpService
passed tolistenStreaming(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
- thePredicate
to test if the filter must be applied. This must not block.factory
-StreamingHttpServiceFilterFactory
to append.- Returns:
this
-
ioExecutor
Sets theIoExecutor
to be used by this server.- Parameters:
ioExecutor
-IoExecutor
to use.- Returns:
this
.
-
executor
Sets theExecutor
to be used by this server.- Parameters:
executor
-Executor
to use.- Returns:
this
.
-
bufferAllocator
Sets theBufferAllocator
to be used by this server.- Parameters:
allocator
-BufferAllocator
to use.- Returns:
this
.
-
executionStrategy
Sets theHttpExecutionStrategy
to be used by this server.- Parameters:
strategy
-HttpExecutionStrategy
to use by this server.- Returns:
this
.
-
listenServiceAndAwait
Starts this server and returns theHttpServerContext
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
.Note that this method is generic in the sense that it accepts all HTTP
HttpServiceBase
implementations to be passed in, namelyStreamingHttpService
,HttpService
,BlockingStreamingHttpService
andBlockingHttpService
. It is especially useful when Dependency Injection is used and the type of service is not known at compile time.- Parameters:
service
- Service invoked for every request received by this server. The returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
is closed.- Returns:
- A
HttpServerContext
by blocking the calling thread until the server is successfully started or throws anException
if the server could not be started. - Throws:
IllegalArgumentException
- if an unsupportedHttpServiceBase
type is being provided.Exception
- if the server could not be started.
-
listenAndAwait
Starts this server and returns theHttpServerContext
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 returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
is closed.- Returns:
- A
HttpServerContext
by blocking the calling thread until the server is successfully started or throws anException
if the server could not be started. - Throws:
Exception
- if the server could not be started.
-
listenStreamingAndAwait
Starts this server and returns theHttpServerContext
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 returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
is closed.- Returns:
- A
HttpServerContext
by blocking the calling thread until the server is successfully started or throws anException
if the server could not be started. - Throws:
Exception
- if the server could not be started.
-
listenBlockingAndAwait
Starts this server and returns theHttpServerContext
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 returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
is closed.- Returns:
- A
HttpServerContext
by blocking the calling thread until the server is successfully started or throws anException
if the server could not be started. - Throws:
Exception
- if the server could not be started.
-
listenBlockingStreamingAndAwait
default HttpServerContext listenBlockingStreamingAndAwait(BlockingStreamingHttpService service) throws Exception Starts this server and returns theHttpServerContext
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 returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
is closed.- Returns:
- A
HttpServerContext
by blocking the calling thread until the server is successfully started or throws anException
if the server could not be started. - Throws:
Exception
- if the server could not be started.
-
listenService
Starts this server and returns theHttpServerContext
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
.Note that this method is generic in the sense that it accepts all HTTP
HttpServiceBase
implementations to be passed in, namelyStreamingHttpService
,HttpService
,BlockingStreamingHttpService
andBlockingHttpService
. It is especially useful when Dependency Injection is used and the type of service is not known at compile time.- Parameters:
service
- Service invoked for every request received by this server. The returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
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. - Throws:
IllegalArgumentException
- if an unsupportedHttpServiceBase
type is being provided.
-
listen
Starts this server and returns theHttpServerContext
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 returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
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
Starts this server and returns theHttpServerContext
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 returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
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
Starts this server and returns theHttpServerContext
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 returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
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
Starts this server and returns theHttpServerContext
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 returnedHttpServerContext
manages the lifecycle of theservice
, ensuring it is closed when theHttpServerContext
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.
-
appendLateConnectionAcceptor(LateConnectionAcceptor)
instead.