Best viewed with

Autoconfigures and runs the embedded gRPC server with @GRpcService-enabled beans as part of spring-boot application (short video)

By default, starter pulls io.grpc:grpc-netty-shaded as transitive dependency, if you are forced to use pure grpc-netty dependency:

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 ):

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

• Optionally enable server reflection (see https://github.com/grpc/grpc-java/blob/master/documentation/server-reflection-tutorial.md)

• Optionally set the startup phase order (defaults to Integer.MAX_VALUE).

• 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).

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

1. Duration type properties can be configured with string value format described here.

2. DataSize type properties can be configured with string value described here

3. 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 )

4. Exposed on internal network IP as well with predefined port 6767.

5. 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 :

1. Disables the default server (NettyServer).

2. Enables the in-process server.

In the grpc-spring-boot-starter-demo project you can find fully functional examples with integration tests.

4.1. Service implementation

service Greeter {
    rpc SayHello ( HelloRequest) returns (  HelloReply) {}
}

    @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();
        }
    }

4.2. Interceptors support

@GRpcService(interceptors = { LogInterceptor.class })
public  class GreeterService extends  GreeterGrpc.GreeterImplBase{
    // ommited
}

@GRpcGlobalInterceptor
public  class MyInterceptor implements ServerInterceptor{
    // ommited
}

 @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);
             }
         };
     }
 }

@GRpcService(applyGlobalInterceptors = false)
public  class GreeterService extends  GreeterGrpc.GreeterImplBase{
    // ommited
}

@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
}

4.3. Distributed tracing support (Spring Cloud Sleuth integration)

4.4. GRPC server metrics (Micrometer.io integration)

implementation "org.springframework.boot:spring-boot-starter-actuator"
implementation "io.micrometer:micrometer-registry-prometheus"
implementation 'org.springframework.boot:spring-boot-starter-web'

management:
  metrics:
    export:
      prometheus:
        enabled: true
  endpoints:
    web:
      exposure:
        include: "*"

4.5. Spring Boot Validation support

4.6. Spring cloud stream support

4.7. Spring security support

4.8. Transport Security (TLS)

 grpc:
    security:
      cert-chain: classpath:cert/server-cert.pem
      private-key: file:../grpc-spring-boot-starter-demo/src/test/resources/cert/server-key.pem

((NettyChannelBuilder)channelBuilder)
 .useTransportSecurity()
 .sslContext(GrpcSslContexts.forClient().trustManager(certChain).build());

4.9. Custom gRPC Server Configuration

@Component
public class MyGRpcServerBuilderConfigurer extends GRpcServerBuilderConfigurer{
        @Override
        public void configure(ServerBuilder<?> serverBuilder){
            serverBuilder
                .executor(YOUR EXECUTOR INSTANCE)
                .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(...);

        }
    };
}
@Component
public class MyCustomCompressionGRpcServerBuilderConfigurer extends GRpcServerBuilderConfigurer{
        @Override
        public void configure(ServerBuilder<?> serverBuilder){
            serverBuilder
                .compressorRegistry(YOUR COMPRESSION REGISTRY)
                .decompressorRegistry(YOUR DECOMPRESSION REGISTRY) ;

        }
    };
}

GRpcServerInitializedEvent is published upon server startup, you can consume it using regular spring API.

Starting from version 5.1.0, spring-boot-starter-gradle-plugin integrates SalesForce’s reactive-grpc protoc plugin :

Here are the tests and reactive grpc sample service.

The starter registers the GRpcExceptionHandlerInterceptor which is responsible to propagate the service-thrown exception to the error handlers.
The error handling method could be registered by having @GRpcServiceAdvice annotated bean with methods annotated with @GRpcExceptionHandler annotations.
These are considered as global error handlers and the method with exception type parameter the nearest by the type hierarchy to the thrown exception is invoked.
The signature of the error handler has to follow the below pattern:

You can have as many advice beans and handler methods as you want as long as they don’t interfere with each other and don’t create handled exception type ambiguity.

The grpc service bean is also discovered for error handlers, having the higher precedence than global error handling methods discovered in @GRpcServiceAdvice beans. The service-level error handling methods are considered private and invoked only when the exception is thrown by this service:

1. Because the nature of grpc service API that doesn’t allow throwing checked exception, the special runtime exception type is provided to wrap the checked exception. It’s then getting unwrapped when looking for the handler method.

2. When throwing the GRpcRuntimeExceptionWrapper exception, you can also pass the hint object which is then accessible from the scope object in handler method.

3. Runtime exception can be thrown as-is and doesn’t need to be wrapped.

4. Obtain the hint object.

5. Send custom headers to the client.

Authentication failure is propagated via AuthenticationException and authorization failure - via AccessDeniedException.

Validation failure is propagated via ConstraintViolationException: for failed request - with Status.INVALID_ARGUMENT as a hint , and for failed response - with Status.FAILED_PRECONDITION as a hint.

The demo is here

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.

1. Add org.springframework.boot:spring-boot-starter-validation dependency to your project.

2. 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 :

1. Apply this constraint only for request message

2. Apply this constraint only for response message

Note also custom cross-field constraint and its usage :

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. Demo is here

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 :

1. The method is annotated as @Transactional, Spring will commit the transaction at some time after methods returns

2. Response is returned to the caller

3. 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 :

1. Service method is transactional

2. Transaction is eventually committed.

3. Reply after transaction is committed.

By following this approach you also decouple the transport layer and business logic that now can be tested separately.

10.1. Setup

10.2. Server side configuration

 @Configuration
   class MySecurityCfg extends GrpcSecurityConfigurerAdapter {
        @Override
        public void configure(GrpcSecurity builder) throws Exception {
            MethodsDescriptor<?,?> adminMethods = MyServiceGrpc.getSomeMethod();
            builder
                    .authorizeRequests()
                    .methods(adminMethods).hasAnyRole("admin")
                    .anyMethodExcluding(adminMethods).hasAnyRole("user")
                    .withSecuredAnnotation();(1)
        }
    }

    @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)
        }
    }

@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);
                        }
                    });
 }
 }

@Bean
public AuthenticationSchemeSelector myCustomSchemeSelector(){
     return authHeader->{
         // your logic here
     };
}

10.3. @PreAuthorize() and @PostAuthorize() support

@Override
@PreAuthorize("#person.age<12")
@PostAuthorize("returnObject.description.length()>0")
public void unary(Person person, StreamObserver<Assignment> responseObserver) {
    }

@Override
@PreAuthorize("#p0.getAge()<12")
@PostAuthorize("returnObject.description.length()>0")
public StreamObserver<Person> inStream(StreamObserver<Assignment> responseObserver) {
    }

@Override
@PreAuthorize("#person.age<12")
@PostAuthorize("returnObject.description.length()>0")
public void outStream(Person person, StreamObserver<Assignment> responseObserver) {
}

@Override
@PreAuthorize("#p0.age<12")
@PostAuthorize("returnObject.description.length()>0")
public StreamObserver<Person> bidiStream(StreamObserver<Assignment> responseObserver) {
}

10.4. Obtaining Authentication details

final Authentication auth = GrpcSecurity.AUTHENTICATION_CONTEXT_KEY.get();

final Authentication auth = SecurityContextHolder.getContext().getAuthentication();

10.5. Client side configuration support

The starter registers the default implementation of HealthServiceImpl.
You can provide you own by registering ManagedHealthStatusService bean in your application context.

If you have org.springframework.boot:spring-boot-starter-actuator and org.springframework.boot:spring-boot-starter-web in the classpath, the starter will expose:

• grpc health indicator under /actuator/health endpoint.

• /actuator/grpc endpoint.

This can be controlled by standard endpoints and health configuration.

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.

ConsulDiscoveryProperties are bound from configuration properties prefixed by spring.cloud.consul.discovery and then the values are overwritten by grpc.consul.discovery prefixed properties (if set). This allows you to have separate consul discovery configuration for rest and grpc services if you choose to expose both from your application.

1. Both rest and grpc services are registered with metadata myKey=myValue

2. Rest services are registered with myWebTag

3. Grpc services are registered with myGrpcTag

Setting spring.cloud.consul.discovery.register-health-check (or grpc.consul.discovery.register-health-check) to true will register GRPC health check service with Consul.

There are 4 supported registration modes :

1. SINGLE_SERVER_WITH_GLOBAL_CHECK (default)
   In this mode the running grpc server is registered as single service with single grpc check with empty serviceId.
   Please note that default implementation does nothing and simply returns SERVING status. You might want to provide your custom Health check implementation for this mode.

2. SINGLE_SERVER_WITH_CHECK_PER_SERVICE
   In this mode the running grpc server is registered as single service with check per each discovered grpc service.

3. STANDALONE_SERVICES
   In this mode each discovered grpc service is registered as single service with single check. Each registered service is tagged by its own service name.

4. NOOP - no grpc services registered. This mode is useful if you serve both rest and grpc services in your application, but for some reason, only rest services should be registered with Consul.

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.

14.1. gRPC Server Project

 dependencies {
     compile('org.springframework.cloud:spring-cloud-starter-eureka')
     compile project(":yourProject-api")
 }

14.2. gRPC Client Project

 dependencies {
     compile('org.springframework.cloud:spring-cloud-starter-eureka')
     compile project(":yourProject-api")
 }

eureka:
  client:
    register-with-eureka: false (1)
    service-url:
      defaultZone: http://${eureka.host:localhost}:${eureka.port:8761}/eureka/ (2)

@EnableEurekaClient
@SpringBootApplication
public class GreeterServiceConsumerApplication {
 public static void main(String[] args) {
   SpringApplication.run(GreeterServiceConsumerApplication.class, args);
 }
}

@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)

    }
}

Apache 2.0