Spring gRPC Documentation

By default, all BindableService beans are bound to all running gRPC servers. You can control this by registering a ServerServiceDefinitionFilter bean.

For InProcessGrpcServerFactory, the filter is applied automatically. For other factories (like NettyGrpcServerFactory), you must provide a GrpcServerFactoryCustomizer to register the filter.

// 1. Define the filter
@Bean
ServerServiceDefinitionFilter myServiceFilter() {
    return (serviceDefinition, __) ->
            !Set.of(HealthGrpc.SERVICE_NAME, ServerReflectionGrpc.SERVICE_NAME)
                    .contains(serviceDefinition.getServiceDescriptor().getName());
}

// 2. Apply it via a customizer (required for Netty)
@Bean
GrpcServerFactoryCustomizer myServerFactoryCustomizer(ServerServiceDefinitionFilter myServiceFilter) {
    return factory -> {
        if (factory instanceof NettyGrpcServerFactory nettyServerFactory) {
            nettyServerFactory.setServiceFilter(myServiceFilter);
        }
    };
}

Interceptors can be applied at three levels:

1. Global: Register a bean annotated with @GlobalClientInterceptor. These are applied to all channels in @Order sequence.
2. Per-Channel: Pass interceptors via ChannelBuilderOptions.withInterceptors(List.of(...)) when creating a channel. These are applied after global interceptors.
3. Blended: By default, global interceptors run first, then per-channel interceptors. If you set ChannelBuilderOptions.withInterceptorsMerge(true), all interceptors (global and per-channel) are combined and sorted together by their @Order.

Note: For proper merging, per-channel interceptors should be beans with @Order or implement Ordered.

// Global interceptor registration
@Bean
@Order(100)
@GlobalClientInterceptor
ClientInterceptor globalLoggingInterceptor() {
    return new LoggingInterceptor();
}

// Per-channel interceptor registration
@Bean
SimpleGrpc.SimpleBlockingStub stub(GrpcChannelFactory channelFactory) {
    ClientInterceptor interceptor1 = getChannelInterceptor1();
    ChannelBuilderOptions options = ChannelBuilderOptions.defaults()
            .withInterceptors(List.of(interceptor1));
    ManagedChannel channel = channelFactory.createChannel("localhost", options);
    return SimpleGrpc.newBlockingStub(channel);
}

To quickly set up a Spring gRPC service, follow these steps:

1. Initialize Project: Use Spring Initializr and select the gRPC dependency.
2. Define Proto: Create src/main/proto/hello.proto. Ensure the java_package matches your project's package name.
3. Generate Stubs: Run ./mvnw clean package (Maven) or ./gradlew build (Gradle) to generate Java source code from your .proto file.
4. Implement Service: Create a class annotated with @Service that extends the generated ImplBase class.
5. Run: Execute the application using ./mvnw spring-boot:run or ./gradlew bootRun.

Generated Source Locations:

• Maven: target/generated-sources/protobuf/grpc-java and target/generated-sources/protobuf/java
• Gradle: build/generated/source/proto/main/grpc and build/generated/source/proto/main/java

Note: You may need to manually mark these folders as 'Generated Source Roots' in your IDE (e.g., IntelliJ IDEA).

syntax = "proto3";

option java_multiple_files = true;
option java_package = "<your-package-name-goes-here>.proto";
option java_outer_classname = "HelloWorldProto";

service Simple {
  rpc SayHello(HelloRequest) returns (HelloReply) {}
  rpc StreamHello(HelloRequest) returns (stream HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

To quickly set up a working gRPC service with Spring gRPC:

1. Generate Project: Use Spring Initializr and select the gRPC dependency.
2. Define Proto: Create src/main/proto/hello.proto. Ensure the java_package matches your project's package name.
3. Generate Stubs: Run ./mvnw clean package (Maven) or ./gradlew build (Gradle).
   • Maven paths: target/generated-sources/protobuf/grpc-java and target/generated-sources/protobuf/java.
   • Gradle paths: build/generated/source/proto/main/grpc and build/generated/source/proto/main/java.
   • Note: You may need to mark these as 'Generated Source Roots' in your IDE.
4. Implement Service: Create a class annotated with @Service that extends the generated ImplBase class.
5. Run: Use ./mvnw spring-boot:run or ./gradlew bootRun.

syntax = "proto3";

option java_multiple_files = true;
option java_package = "<your-package-name-goes-here>.proto";
option java_outer_classname = "HelloWorldProto";

service Simple {
  rpc SayHello(HelloRequest) returns (HelloReply) {}
  rpc StreamHello(HelloRequest) returns (stream HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}