Class GrpcServiceBuilder
public final class GrpcServiceBuilder extends Object
GrpcService
to serve gRPC services from within Armeria.-
Method Summary
Modifier and Type Method Description GrpcServiceBuilder
addService(BindableService bindableService)
Adds a gRPCBindableService
to thisGrpcServiceBuilder
.GrpcServiceBuilder
addService(ServerServiceDefinition service)
Adds a gRPCServerServiceDefinition
to thisGrpcServiceBuilder
, such as what's returned byBindableService.bindService()
.GrpcServiceBuilder
addServices(BindableService... bindableServices)
Adds gRPCBindableService
s to thisGrpcServiceBuilder
.GrpcServiceBuilder
addServices(Iterable<BindableService> bindableServices)
Adds gRPCBindableService
s to thisGrpcServiceBuilder
.GrpcService
build()
Constructs a newGrpcService
that can be bound toServerBuilder
.GrpcServiceBuilder
compressorRegistry(CompressorRegistry registry)
Sets theCompressorRegistry
to use when compressing messages.GrpcServiceBuilder
decompressorRegistry(DecompressorRegistry registry)
Sets theDecompressorRegistry
to use when decompressing messages.GrpcServiceBuilder
enableUnframedRequests(boolean enableUnframedRequests)
Sets whether the service handles requests not framed using the gRPC wire protocol.GrpcServiceBuilder
jsonMarshallerFactory(Function<? super ServiceDescriptor,? extends GrpcJsonMarshaller> jsonMarshallerFactory)
Sets the factory that creates aGrpcJsonMarshaller
that serializes and deserializes request or response messages to and from JSON depending on theSerializationFormat
.GrpcServiceBuilder
setMaxInboundMessageSizeBytes(int maxInboundMessageSizeBytes)
Sets the maximum size in bytes of an individual incoming message.GrpcServiceBuilder
setMaxOutboundMessageSizeBytes(int maxOutboundMessageSizeBytes)
Sets the maximum size in bytes of an individual outgoing message.GrpcServiceBuilder
supportedSerializationFormats(SerializationFormat... formats)
Sets theSerializationFormat
s supported by this server.GrpcServiceBuilder
supportedSerializationFormats(Iterable<SerializationFormat> formats)
Sets theSerializationFormat
s supported by this server.GrpcServiceBuilder
unsafeWrapRequestBuffers(boolean unsafeWrapRequestBuffers)
Enables unsafe retention of request buffers.GrpcServiceBuilder
useBlockingTaskExecutor(boolean useBlockingTaskExecutor)
Sets whether the service executes service methods using the blocking executor.GrpcServiceBuilder
useClientTimeoutHeader(boolean useClientTimeoutHeader)
Sets whether to use agrpc-timeout
header sent by the client to control the timeout for request processing.
-
Method Details
-
addService
Adds a gRPCServerServiceDefinition
to thisGrpcServiceBuilder
, such as what's returned byBindableService.bindService()
. -
addService
Adds a gRPCBindableService
to thisGrpcServiceBuilder
. Most gRPC service implementations areBindableService
s. -
addServices
Adds gRPCBindableService
s to thisGrpcServiceBuilder
. Most gRPC service implementations areBindableService
s. -
addServices
Adds gRPCBindableService
s to thisGrpcServiceBuilder
. Most gRPC service implementations areBindableService
s. -
decompressorRegistry
Sets theDecompressorRegistry
to use when decompressing messages. If not set, will use the default, which supports gzip only. -
compressorRegistry
Sets theCompressorRegistry
to use when compressing messages. If not set, will use the default, which supports gzip only. -
supportedSerializationFormats
Sets theSerializationFormat
s supported by this server. If not set, defaults to support allGrpcSerializationFormats.values()
. -
supportedSerializationFormats
Sets theSerializationFormat
s supported by this server. If not set, defaults to support allGrpcSerializationFormats.values()
. -
setMaxInboundMessageSizeBytes
Sets the maximum size in bytes of an individual incoming message. If not set, will useVirtualHost.maxRequestLength()
. To support long-running RPC streams, it is recommended to setServerBuilder.maxRequestLength(long)
(orVirtualHostBuilder.maxRequestLength(long)
) andServerBuilder.requestTimeoutMillis(long)
(orVirtualHostBuilder.requestTimeoutMillis(long)
) to very high values and set this to the expected limit of individual messages in the stream. -
setMaxOutboundMessageSizeBytes
Sets the maximum size in bytes of an individual outgoing message. If not set, all messages will be sent. This can be a safety valve to prevent overflowing network connections with large messages due to business logic bugs. -
enableUnframedRequests
Sets whether the service handles requests not framed using the gRPC wire protocol. Such requests should only have the serialized message as the request content, and the response content will only have the serialized response message. Supporting unframed requests can be useful, for example, when migrating an existing service to gRPC.Limitations:
- Only unary methods (single request, single response) are supported.
-
Message compression is not supported.
EncodingService
should be used instead for transport level encoding.
-
useBlockingTaskExecutor
Sets whether the service executes service methods using the blocking executor. By default, service methods are executed directly on the event loop for implementing fully asynchronous services. If your service uses blocking logic, you should either execute such logic in a separate thread using something likeExecutors.newCachedThreadPool()
or enable this setting. -
unsafeWrapRequestBuffers
Enables unsafe retention of request buffers. Can improve performance when working with very large (i.e., several megabytes) payloads.DISCLAIMER: Do not use this if you don't know what you are doing. It is very easy to introduce memory leaks when using this method. You will probably spend much time debugging memory leaks during development if this is enabled. You will probably spend much time debugging memory leaks in production if this is enabled. You probably don't want to do this and should turn back now.
When enabled, the reference-counted buffer received from the client will be stored into
RequestContext
instead of being released. AllByteString
in a protobuf message will reference sections of this buffer instead of having their own copies. When done with a request message, callGrpcUnsafeBufferUtil.releaseBuffer(Object, RequestContext)
with the message and the request's context to release the buffer. The message must be the same reference as what was passed to the service stub - a message with the same contents will not work. IfGrpcUnsafeBufferUtil.releaseBuffer(Object, RequestContext)
is not called, the memory will be leaked.Note that this isn't working if the payloads are compressed or the
SerializationFormat
isGrpcSerializationFormats.PROTO_WEB_TEXT
. -
jsonMarshallerFactory
public GrpcServiceBuilder jsonMarshallerFactory(Function<? super ServiceDescriptor,? extends GrpcJsonMarshaller> jsonMarshallerFactory)Sets the factory that creates aGrpcJsonMarshaller
that serializes and deserializes request or response messages to and from JSON depending on theSerializationFormat
. The returnedGrpcJsonMarshaller
from the factory replaces the built-inGrpcJsonMarshaller
.This is commonly used to:
- Switch from the default of using lowerCamelCase for field names to using the field name from
the proto definition, by setting
MessageMarshaller.Builder.preservingProtoFieldNames(boolean)
viaGrpcJsonMarshallerBuilder.jsonMarshallerCustomizer(Consumer)
.GrpcService.builder() .jsonMarshallerFactory(serviceDescriptor -> { return GrpcJsonMarshaller.builder() .jsonMarshallerCustomizer(builder -> { builder.preservingProtoFieldNames(true); }) .build(serviceDescriptor); }) .build();
- Set a customer marshaller for non-
Message
types such asscalapb.GeneratedMessage
for Scala andpbandk.Message
for Kotlin.
- Switch from the default of using lowerCamelCase for field names to using the field name from
the proto definition, by setting
-
useClientTimeoutHeader
Sets whether to use agrpc-timeout
header sent by the client to control the timeout for request processing. If disabled, the request timeout will be the one configured for the Armeria server, e.g., usingServerBuilder.requestTimeout(Duration)
.It is recommended to disable this when clients are not trusted code, e.g., for gRPC-Web clients that can come from arbitrary browsers.
-
build
Constructs a newGrpcService
that can be bound toServerBuilder
. It is recommended to bind the service to a server using ServerBuilder.service(HttpServiceWithRoutes) to mount all service paths without interfering with other services.
-