代码拉取完成，页面将自动刷新
Best viewed with
Auto-configures and runs the embedded gRPC server with @GRpcService-enabled beans as part of spring-boot application.
repositories {
mavenCentral()
//maven { url "https://oss.sonatype.org/content/repositories/snapshots" } //for snapshot builds
}
dependencies {
compile 'io.github.lognet:grpc-spring-boot-starter:4.5.3'
}
By default, starter pulls io.grpc:grpc-netty-shaded as transitive dependency, if you are forced to use pure grpc-netty dependency:
compile ('io.github.lognet:grpc-spring-boot-starter:4.4.7') {
exclude group: 'io.grpc', module: 'grpc-netty-shaded'
}
compile 'io.grpc:grpc-netty:1.37.0' // (1)
Make sure to pull the version that matches the release.
Both libraries' presence on classpath is also supported with grpc.netty-server.on-collision-prefer-shaded-netty property.
If you are using Spring Boot Dependency Management plugin, it might pull not the same version as the version this started was compiled against, causing binary incompatibility issue.
In this case you’ll need to forcibly and explicitly set the grpc version to use (see version matrix here ):
configurations.all {
resolutionStrategy.eachDependency { details ->
if ("io.grpc".equalsIgnoreCase(details.requested.group)) {
details.useVersion "1.37.0"
}
}
}
|
|
The release notes with compatibility matrix can be found here |
Start by generating stub and server interface(s) from your .proto file(s).
Annotate your server interface implementation(s) with @org.lognet.springboot.grpc.GRpcService
Optionally configure the server port in your application.yml/properties.
Default port is 6565.
grpc:
port: 6565
|
|
A random port can be defined by setting the port to 0.The actual port being used can then be retrieved by using @LocalRunningGrpcPort annotation on int field which will inject the running port (explicitly configured or randomly selected)
|
Optionally enable server reflection (see https://github.com/grpc/grpc-java/blob/master/documentation/server-reflection-tutorial.md)
grpc:
enableReflection: true
Optionally set the startup phase order (defaults to Integer.MAX_VALUE).
grpc:
start-up-phase: XXX
Optionally set the number of seconds to wait for preexisting calls to finish during graceful server shutdown.
New calls will be rejected during this time.
A negative value is equivalent to an infinite grace period.
Default value is 0 (means don’t wait).
grpc:
shutdownGrace: 30
Netty-specific server properties can be specified under grpc.netty-server prefix.
By configuring one of the grpc.netty-server.xxxx values you are implicitly setting transport to be Netty-based.
grpc:
netty-server:
keep-alive-time: 30s (1)
max-inbound-message-size: 10MB (2)
primary-listen-address: 10.10.15.23:0 (3)
additional-listen-addresses:
- 192.168.0.100:6767 (4)
on-collision-prefer-shaded-netty: false (5)
Duration type properties can be configured with string value format described here.
DataSize type properties can be configured with string value described here
Exposed on external network IP with custom port.
SocketAddress type properties string value format:
host:port (if port value is less than 1, uses random value)
host: (uses default grpc port, 6565 )
Exposed on internal network IP as well with predefined port 6767.
In case you have both shaded and pure netty libraries in dependencies, pick the NettyServerBuilder type that should be created. This is the type that will be passed to GRpcServerBuilderConfigurer (see Custom gRPC Server Configuration), defaults to true(i.e. io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder; io.grpc.netty.NettyServerBuilder if false)
The starter supports also the in-process server, which should be used for testing purposes :
grpc:
enabled: false (1)
inProcessServerName: myTestServer (2)
Disables the default server (NettyServer).
Enables the in-process server.
|
|
If you enable both the NettyServer and in-process server, they will both share the same instance of HealthStatusManager and GRpcServerBuilderConfigurer (see Custom gRPC Server Configuration).
|
In the grpc-spring-boot-starter-demo project you can find fully functional examples with integration tests.
The service definition from .proto file looks like this :
service Greeter {
rpc SayHello ( HelloRequest) returns ( HelloReply) {}
}
Note the generated io.grpc.examples.GreeterGrpc.GreeterImplBase class that extends io.grpc.BindableService.(The generated classes were intentionally committed for demo purposes).
All you need to do is to annotate your service implementation with @org.lognet.springboot.grpc.GRpcService
@GRpcService
public static class GreeterService extends GreeterGrpc.GreeterImplBase{
@Override
public void sayHello(GreeterOuterClass.HelloRequest request, StreamObserver<GreeterOuterClass.HelloReply> responseObserver) {
final GreeterOuterClass.HelloReply.Builder replyBuilder = GreeterOuterClass.HelloReply.newBuilder().setMessage("Hello " + request.getName());
responseObserver.onNext(replyBuilder.build());
responseObserver.onCompleted();
}
}
The starter supports the registration of two kinds of interceptors: Global and Per Service.
In both cases the interceptor has to implement io.grpc.ServerInterceptor interface.
Per service
@GRpcService(interceptors = { LogInterceptor.class })
public class GreeterService extends GreeterGrpc.GreeterImplBase{
// ommited
}
LogInterceptor will be instantiated via spring factory if there is bean of type LogInterceptor, or via no-args constructor otherwise.
Global
@GRpcGlobalInterceptor
public class MyInterceptor implements ServerInterceptor{
// ommited
}
The annotation on java config factory method is also supported :
@Configuration
public class MyConfig{
@Bean
@GRpcGlobalInterceptor
public ServerInterceptor globalInterceptor(){
return new ServerInterceptor(){
@Override
public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
// your logic here
return next.startCall(call, headers);
}
};
}
}
The particular service also has the opportunity to disable the global interceptors :
@GRpcService(applyGlobalInterceptors = false)
public class GreeterService extends GreeterGrpc.GreeterImplBase{
// ommited
}
Global interceptors can be ordered using Spring’s @Ordered or @Priority annotations.
Following Spring’s ordering semantics, lower order values have higher priority and will be executed first in the interceptor chain.
@GRpcGlobalInterceptor
@Order(10)
public class A implements ServerInterceptor{
// will be called before B
}
@GRpcGlobalInterceptor
@Order(20)
public class B implements ServerInterceptor{
// will be called after A
}
The starter uses built-in interceptors to implement Spring Security, Validation and Metrics integration.
Their order can also be controlled by below properties :
grpc.security.auth.interceptor-order ( defaults to Ordered.HIGHEST_PRECEDENCE)
grpc.validation.interceptor-order ( defaults to Ordered.HIGHEST_PRECEDENCE+10)
grpc.metrics.interceptor-order ( defaults to Ordered.HIGHEST_PRECEDENCE+20)
This gives you the ability to setup the desired order of built-in and your custom interceptors.
Keep on reading !!! There is more
The way grpc interceptor works is that it intercepts the call and returns the server call listener, which in turn can intercept the request message as well, before forwarding it to the actual service call handler :
interceptor_1(interceptCall) → interceptor_2(interceptCall) → interceptor_3(interceptCall) →
interceptor_1(On_Message)→ interceptor_2(On_Message)→ interceptor_3(On_Message)→
actual service call
By setting grpc.security.auth.fail-fast property to false all downstream interceptors as well as all upstream interceptors (On_Message) will still be executed in case of authentication/authorization failure
Assuming interceptor_2 is securityInterceptor :
For failed authentication/authorization with grpc.security.auth.fail-fast=true(default):
interceptor_1(interceptCall) → securityInterceptor(interceptCall) - Call is Closed → interceptor_3(interceptCall) →
interceptor_1(On_Message)→ securityInterceptor(On_Message)→`interceptor_3(On_Message)→
`actual service call
For failed authentication/authorization with grpc.security.auth.fail-fast=false:
interceptor_1(interceptCall) → securityInterceptor(interceptCall) → interceptor_3(interceptCall) →
interceptor_1(On_Message)→ securityInterceptor(On_Message) - Call is Closed → interceptor_3(On_Message)→
actual service call
This started is natively supported by spring-cloud-sleuth project.
Please continue to sleuth grpc integration.
By including org.springframework.boot:spring-boot-starter-actuator dependency,
the starter will collect gRPC server metrics , broken down by
method - gRPC service method FQN (Fully Qualified Name)
result - Response status code
address - server local address (if you exposed additional listen addresses, with grpc.netty-server.additional-listen-addresses property)
After configuring the exporter of your choice,
you should see the timer named grpc.server.calls.
By defining GRpcMetricsTagsContributor bean in your application context, you can add custom tags to the grpc.server.calls timer.
You can also use RequestAwareGRpcMetricsTagsContributor bean to tag unary calls.
Demo is here
|
|
Keep the dispersion low not to blow up the cardinality of the metric. |
RequestAwareGRpcMetricsTagsContributor can be still executed for failed authentication if metric interceptor has higher precedence than security interceptor and grpc.security.auth.fail-fast set to false.
This case is covered by this test.
|
|
Make sure to read Interceptors ordering chapter. |
Make sure to include below dependencies :
implementation "org.springframework.boot:spring-boot-starter-actuator"
implementation "io.micrometer:micrometer-registry-prometheus"
implementation 'org.springframework.boot:spring-boot-starter-web'
Configuration :
management:
metrics:
export:
prometheus:
enabled: true
endpoints:
web:
exposure:
include: "*"
Standard /actuator/metrics and /actuator/prometheus endpoints will render grpc.server.calls metrics (see demo here).
|
|
GRPC scrapping proposal |
The starter can be auto-configured to validate request/response gRPC service messages. Please continue to Implementing message validation for configuration details.
The starter provides built-in support for authenticating and authorizing users leveraging integration with Spring Security framework.
Please refer to the sections on Spring Security Integration for details on supported authentication providers and configuration options.
The transport security can be configured using root certificate together with its private key path:
grpc:
security:
cert-chain: classpath:cert/server-cert.pem
private-key: file:../grpc-spring-boot-starter-demo/src/test/resources/cert/server-key.pem
The value of both properties is in form supported by ResourceEditor.
The client side should be configured accordingly :
((NettyChannelBuilder)channelBuilder)
.useTransportSecurity()
.sslContext(GrpcSslContexts.forClient().trustManager(certChain).build());
This starter will pull the io.netty:netty-tcnative-boringssl-static dependency by default to support SSL.
If you need another SSL/TLS support, please exclude this dependency and follow Security Guide.
|
|
If the more detailed tuning is needed for security setup, please use custom configurer described in Custom gRPC Server Configuration |
To intercept the io.grpc.ServerBuilder instance used to build the io.grpc.Server, you can add bean that inherits from org.lognet.springboot.grpc.GRpcServerBuilderConfigurer to your context and override the configure method.
By the time of invocation of configure method, all discovered services, including theirs interceptors, had been added to the passed builder.
In your implementation of configure method, you can add your custom configuration:
@Component
public class MyGRpcServerBuilderConfigurer extends GRpcServerBuilderConfigurer{
@Override
public void configure(ServerBuilder<?> serverBuilder){
serverBuilder
.executor(YOUR EXECUTOR INSTANCE)
.compressorRegistry(YOUR COMPRESSION REGISTRY)
.decompressorRegistry(YOUR DECOMPRESSION REGISTRY)
.useTransportSecurity(YOUR TRANSPORT SECURITY SETTINGS);
((NettyServerBuilder)serverBuilder)// cast to NettyServerBuilder (which is the default server) for further customization
.sslContext(GrpcSslContexts // security fine tuning
.forServer(...)
.trustManager(...)
.build())
.maxConnectionAge(...)
.maxConnectionAgeGrace(...);
}
};
}
|
|
If you enable both NettyServer and in-process servers, the configure method will be invoked on the same instance of configurer.If you need to differentiate between the passed serverBuilder s, you can check the type.This is the current limitation. |
Thanks to Bean Validation configuration support via XML deployment descriptor , it’s possible to
provide the constraints for generated classes via XML instead of instrumenting the generated messages with custom protoc compiler.
Add org.springframework.boot:spring-boot-starter-validation dependency to your project.
Create META-INF/validation.xml and constraints declarations file(s). (IntelliJ IDEA has great auto-complete support for authorizing bean validation constraints xml files )
See also samples from Hibernate validator documentation
You can find demo configuration and corresponding tests here
Note, that both request and response messages are being validated.
If your gRPC method uses the same request and response message type, you can use org.lognet.springboot.grpc.validation.group.RequestMessage and
org.lognet.springboot.grpc.validation.group.ResponseMessage validation groups to apply different validation logic :
...
<getter name="someField">
<!--should be empty for request message-->
<constraint annotation="javax.validation.constraints.Size">
<groups>
<value>org.lognet.springboot.grpc.validation.group.RequestMessage</value> (1)
</groups>
<element name="min">0</element>
<element name="max">0</element>
</constraint>
<!--should NOT be empty for response message-->
<constraint annotation="javax.validation.constraints.NotEmpty">
<groups>
<value>org.lognet.springboot.grpc.validation.group.ResponseMessage</value> (2)
</groups>
</constraint>
</getter>
...
Apply this constraint only for request message
Apply this constraint only for response message
Note also custom cross-field constraint and its usage :
<bean class="io.grpc.examples.GreeterOuterClass$Person">
<class>
<constraint annotation="org.lognet.springboot.grpc.demo.PersonConstraint"/>
</class>
...
</bean>
As described in Interceptors ordering chapter, you can give validation interceptor the higher precedence than security interceptor and set grpc.security.auth.fail-fast property to false.
In this scenario, if call is both unauthenticated and invalid, the client will get Status.INVALID_ARGUMENT instead of Status.PERMISSION_DENIED/Status.UNAUTHENTICATED response status.
By adding GRpcErrorHandler bean to your application, you get a chance to send your custom response headers. The error handler will be called with Status.INVALID_ARGUMENT and incoming request message that is failed.
While it’s still possible to have your rpc methods annotated with @Transactional (with spring.aop.proxy-target-class=true if it’s not enabled by default), chances are to get unpredictable behaviour. Consider below grpc method implementation :
class MyGrpcService extends ...{
@Autowired
private MyJpaRepository repo;
@Transactional //(1)
public void rpcCall(Req request, StreamOvserver<Res> observer) {
Res response = // Database operations via repo
observer.onNext(response); //(2)
observer.onCompleted();
}//(3)
}
The method is annotated as @Transactional, Spring will commit the transaction at some time after methods returns
Response is returned to the caller
Methods returns, transaction eventually committed.
Theoretically, and as you can see - practically, there is small time-span when client (if the network latency is minimal, and your grpc server encouraged context switch right after <2>) can try to access the database via another grpc call before the transaction is committed.
The solution to overcome this situation is to externalize the transactional logic into separate service class :
@Service
class MyService{
@Autowired
private MyJpaRepository repo;
@Transactional //(1)
public Res doTransactionalWork(){
// Database operations via repo
return result;
}//(2)
}
class MyGrpcService extends ...{
@Autowired
private MyService myService;
public void rpcCall(Req request, StreamOvserver<Res> observer) {
Res response = myService.doTransactionalWork();
observer.onNext(response); //(3)
observer.onCompleted();
}
}
Service method is transactional
Transaction is eventually committed.
Reply after transaction is committed.
By following this approach you also decouple the transport layer and business logic that now can be tested separately.
| Scheme | Dependencies |
|---|---|
Basic |
|
Bearer |
|
Custom |
|
GRPC security configuration follows the same principals and APIs as Spring WEB security configuration.
GRPC security is enabled by default if you have org.springframework.security:spring-security-config dependency in your classpath.
This default configuration secures GRPC methods/services annotated with org.springframework.security.access.annotation.@Secured annotation.
Leaving value of the annotation empty (@Secured({})) means : authenticate only, no authorization will be performed.
If JwtDecoder bean exists in your context, it will also register JwtAuthenticationProvider to handle the validation of authentication claim.
BasicAuthSchemeSelector and BearerTokenAuthSchemeSelector are also automatically registered to support authentication with username/password and bearer token.
By setting grpc.security.auth.enabled to false, GRPC security can be turned-off.
Customization of GRPC security configuration is done by extending GrpcSecurityConfigurerAdapter (Various configuration examples and test scenarios are here.)
@Configuration
public class GrpcSecurityConfiguration extends GrpcSecurityConfigurerAdapter {
@Autowired
private JwtDecoder jwtDecoder;
@Override
public void configure(GrpcSecurity builder) throws Exception {
builder.authorizeRequests()(1)
.methods(GreeterGrpc.getSayHelloMethod()).hasAnyAuthority("SCOPE_profile")(2)
.and()
.authenticationProvider(JwtAuthProviderFactory.withAuthorities(jwtDecoder));(3)
}
}
Get hold of authorization configuration object
MethodDefinition of sayHello method is allowed for authenticated users with SCOPE_profile authority.
Use JwtAuthenticationProvider to validate user claim (BEARER token) against resource server configured with spring.security.oauth2.resourceserver.jwt.issuer-uri property.
One is possible to plug in your own bespoke authentication provider by implementing AuthenticationSchemeSelector interface.
@Configuration
public class GrpcSecurityConfiguration extends GrpcSecurityConfigurerAdapter {
@Override
public void configure(GrpcSecurity builder) throws Exception {
builder.authorizeRequests()
.anyMethod().authenticated()(1)
.and()
.authenticationSchemeSelector(new AuthenticationSchemeSelector() { (2)
@Override
public Optional<Authentication> getAuthScheme(CharSequence authorization) {
return new MyAuthenticationObject(); (3)
}
})
.authenticationProvider(new AuthenticationProvider() { (4)
@Override
public Authentication authenticate(Authentication authentication) throws AuthenticationException {
MyAuthenticationObject myAuth= (MyAuthenticationObject)authentication;
//validate myAuth
return MyValidatedAuthenticationObject(withAuthorities);(5)
}
@Override
public boolean supports(Class<?> authentication) {
return MyAuthenticationObject.class.isInstance(authentication);
}
});
}
}
Secure all services methods.
Register your own AuthenticationSchemeSelector.
Based on provided authorization header - return Authentication object as a claim (not authenticated yet)
Register your own AuthenticationProvider that supports validation of MyAuthenticationObject
Validate provided authentication and return validated and authenticated Authentication object
AuthenticationSchemeSelector can also be registered by defining Spring bean in your application context:
@Bean
public AuthenticationSchemeSelector myCustomSchemeSelector(){
return authHeader->{
// your logic here
};
}
Client side configuration support section explains how to pass custom authorization scheme and claim from GRPC client.
To obtain Authentication object in the implementation of secured method, please use below snippet
final Authentication auth = GrpcSecurity.AUTHENTICATION_CONTEXT_KEY.get();
By adding GRpcErrorHandler bean to your application, you get a chance to provide your custom response headers. The error handler will be called with Status.PERMISSION_DENIED/Status.UNAUTHENTICATED (and incoming request message , if you set grpc.security.auth.fail-fast property to false).
The demo is here
By adding io.github.lognet:grpc-client-spring-boot-starter dependency to your java grpc client application you can easily configure per-channel or per-call credentials :
class MyClient{
public void doWork(){
final AuthClientInterceptor clientInterceptor = new AuthClientInterceptor((1)
AuthHeader.builder()
.bearer()
.binaryFormat(true)(3)
.tokenSupplier(this::generateToken)(4)
);
Channel authenticatedChannel = ClientInterceptors.intercept(
ManagedChannelBuilder.forAddress("host", 6565), clientInterceptor (2)
);
// use authenticatedChannel to invoke GRPC service
}
private ByteBuffer generateToken(){ (4)
// generate bearer token against your resource server
}
}
Create client interceptor
Intercept channel
Turn the binary format on/off:
When true, the authentication header is sent with Authentication-bin key using binary marshaller.
When false, the authentication header is sent with Authentication key using ASCII marshaller.
Provide token generator function (Please refer to for example.)
class MyClient{
public void doWork(){
AuthCallCredentials callCredentials = new AuthCallCredentials( (1)
AuthHeader.builder().basic("user","pwd".getBytes())
);
final SecuredGreeterGrpc.SecuredGreeterBlockingStub securedFutureStub = SecuredGreeterGrpc.newBlockingStub(ManagedChannelBuilder.forAddress("host", 6565));(2)
final String reply = securedFutureStub
.withCallCredentials(callCredentials)(3)
.sayAuthHello(Empty.getDefaultInstance()).getMessage();
}
}
Create call credentials with basic scheme
Create service stub
Attach call credentials to the call
AuthHeader could also be built with bespoke authorization scheme :
AuthHeader
.builder()
.authScheme("myCustomAuthScheme")
.tokenSupplier(()->generateMyCustomToken())
Starting from version 3.3.0, the starter will auto-register the running grpc server in Consul registry if org.springframework.cloud:spring-cloud-starter-consul-discovery is in classpath and
spring.cloud.service-registry.auto-registration.enabled is NOT set to false.
The registered service name will be prefixed with grpc- ,i.e. grpc-${spring.application.name} to not interfere with standard registered web-service name if you choose to run both embedded Grpc and Web servers.
Setting spring.cloud.consul.discovery.register-health-check to true will register GRPC health check service in Consul.
Tags could be set by defining spring.cloud.consul.discovery.tags property.
You can find the test that demonstrates the feature here.
When building production-ready services, the advise is to have separate project for your service(s) gRPC API that holds only proto-generated classes both for server and client side usage.
You will then add this project as compile dependency to your gRPC client and gRPC server projects.
To integrate Eureka simply follow the great guide from Spring.
Below are the essential parts of configurations for both server and client projects.
Add eureka starter as dependency of your server project together with generated classes from proto files:
dependencies {
compile('org.springframework.cloud:spring-cloud-starter-eureka')
compile project(":yourProject-api")
}
Configure gRPC server to register itself with Eureka.
spring:
application:
name: my-service-name (1)
Eureka’s ServiceId by default is the spring application name, provide it before the service registers itself with Eureka.
grpc:
port: 6565 (1)
eureka:
instance:
nonSecurePort: ${grpc.port} (2)
client:
serviceUrl:
defaultZone: http://${eureka.host:localhost}:${eureka.port:8761}/eureka/ (3)
Specify the port number the gRPC is listening on.
Register the eureka service port to be the same as grpc.port so client will know where to send the requests to.
Specify the registry URL, so the service will register itself with.
Expose the gRPC service as part of Spring Boot Application.
@SpringBootApplication
@EnableEurekaClient
public class EurekaGrpcServiceApp {
@GRpcService
public static class GreeterService extends GreeterGrpc.GreeterImplBase {
@Override
public void sayHello(GreeterOuterClass.HelloRequest request, StreamObserver<GreeterOuterClass.HelloReply> responseObserver) {
}
}
public static void main(String[] args) {
SpringApplication.run(DemoApp.class,args);
}
}
Add eureka starter as dependency of your client project together with generated classes from proto files:
dependencies {
compile('org.springframework.cloud:spring-cloud-starter-eureka')
compile project(":yourProject-api")
}
Configure client to find the eureka service registry:
eureka:
client:
register-with-eureka: false (1)
service-url:
defaultZone: http://${eureka.host:localhost}:${eureka.port:8761}/eureka/ (2)
false if this project is not meant to act as a service to another client.
Specify the registry URL, so this client will know where to look up the required service.
@EnableEurekaClient
@SpringBootApplication
public class GreeterServiceConsumerApplication {
public static void main(String[] args) {
SpringApplication.run(GreeterServiceConsumerApplication.class, args);
}
}
Use EurekaClient to get the coordinates of gRPC service instance from Eureka and consume the service :
@EnableEurekaClient
@Component
public class GreeterServiceConsumer {
@Autowired
private EurekaClient client;
public void greet(String name) {
final InstanceInfo instanceInfo = client.getNextServerFromEureka("my-service-name", false);(1)
final ManagedChannel channel = ManagedChannelBuilder.forAddress(instanceInfo.getIPAddr(), instanceInfo.getPort())
.usePlaintext()
.build(); (2)
final GreeterServiceGrpc.GreeterServiceFutureStub stub = GreeterServiceGrpc.newFutureStub(channel); (3)
stub.greet(name); (4)
}
}
Get the information about the my-service-name instance.
Build channel accordingly.
Create stub using the channel.
Invoke the service.
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。
马建仓 AI 助手