Spring gRPC

https://github.com/spring-projects/spring-grpc
Admin
Spring gRPC provides a Spring-friendly API and abstractions for developing gRPC applications with...
Tokens:87,194
Snippets:536
Trust Score:9.7
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run the gRPC client with Maven

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-client/README.md

Starts the Spring Boot gRPC client application. The output shows the Spring Boot banner and a log line indicating the application started, followed by a gRPC message 'Hello ==> Alien'.

```bash
$ ./mvnw spring-boot:run
...
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.5.5)

...
2025-02-27T09:21:19.515Z  INFO 1211091 --- [grpc-client] [           main] o.s.g.sample.GrpcClientApplication  : Started GrpcClientApplication in 0.909 seconds (process running for 1.172)
message: "Hello ==> Alien"
```

--------------------------------

### Build and run container image with bootBuildImage

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server/HELP-gradle.md

Builds a lightweight container image using Cloud Native Buildpacks and then runs it with Docker. Docker must be installed and configured before creating the image.

```bash
$ ./gradlew bootBuildImage
```

```bash
$ docker run --rm grpc-server:1.1.2-SNAPSHOT
```

--------------------------------

### Compile and run native image with Maven

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-tomcat/README.md

Run these commands to compile the application to a native image and then execute it. The output shows the Spring Boot startup logs, including the gRPC server starting on port 9090.

```bash
$ ./mvnw -Pnative native:compile
$ ./target/demo
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.5.5)

2022-12-08T05:36:54.365-08:00  INFO 554359 --- [           main] com.example.demo.DemoApplication         : Starting AOT-processed DemoApplication using Java 17.0.5 with PID 554359 (/home/dsyer/dev/scratch/demo/target/demo started by dsyer in /home/dsyer/dev/scratch/demo)
2022-12-08T05:36:54.366-08:00  INFO 554359 --- [           main] com.example.demo.DemoApplication         : No active profile set, falling back to 1 default profile: "default"
2022-12-08T05:36:54.377-08:00  INFO 554359 --- [           main] g.s.a.GrpcServerFactoryAutoConfiguration : Detected grpc-netty: Creating NettyGrpcServerFactory
2022-12-08T05:36:54.392-08:00  INFO 554359 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: Simple, bean: grpcServerService, class: com.example.demo.GrpcServerService
2022-12-08T05:36:54.392-08:00  INFO 554359 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.health.v1.Health, bean: grpcHealthService, class: io.grpc.protobuf.services.HealthServiceImpl
2022-12-08T05:36:54.392-08:00  INFO 554359 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.reflection.v1alpha.ServerReflection, bean: protoReflectionService, class: io.grpc.protobuf.services.ProtoReflectionService
2022-12-08T05:36:54.396-08:00  INFO 554359 --- [           main] n.d.b.g.s.s.GrpcServerLifecycle          : gRPC Server started, listening on address: *, port: 9090
2022-12-08T05:36:54.396-08:00  INFO 554359 --- [           main] com.example.demo.DemoApplication         : Started DemoApplication in 0.046 seconds (process running for 0.052)
```

--------------------------------

### Run Spring Boot application with Maven

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Starts the Spring Boot application using the Maven wrapper.

```shell
./mvnw spring-boot:run
```

--------------------------------

### Create OCI image with bootBuildImage

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-gradle.md

Creates a lightweight container image using Cloud Native Buildpacks. Docker must be installed and configured on your machine before running this command.

```bash
$ ./gradlew bootBuildImage
```

--------------------------------

### Run Spring Boot application with Gradle

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Starts the Spring Boot application using the Gradle wrapper.

```shell
./gradlew bootRun
```

--------------------------------

### Compile and run native executable with nativeCompile

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server/HELP-gradle.md

Compiles a native executable using GraalVM Native Build Tools and then runs it. GraalVM 22.3+ is required and the native-image compiler must be installed and configured.

```bash
$ ./gradlew nativeCompile
```

```bash
$ build/native/nativeCompile/grpc-server
```

--------------------------------

### Run Spring Boot gRPC server and test with gRPCurl

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-tomcat-secure/README.md

Run the Spring Boot gRPC server with Maven wrapper and then test it with gRPCurl. The server starts on port 9090 by default. The gRPCurl command sends a JSON request to the Simple.SayHello method and prints the response.

```bash
$ ./mvnw spring-boot:run
...
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.5.5)

2022-12-08T05:32:24.934-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : Starting DemoApplication using Java 17.0.5 with PID 551632 (/home/dsyer/dev/scratch/demo/target/classes started by dsyer in /home/dsyer/dev/scratch/demo)
2022-12-08T05:32:24.938-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : No active profile set, falling back to 1 default profile: "default"
2022-12-08T05:32:25.377-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcHealthServiceAutoConfiguration
2022-12-08T05:32:25.416-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcServerAutoConfiguration
2022-12-08T05:32:25.425-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcServerFactoryAutoConfiguration
2022-12-08T05:32:25.427-08:00  INFO 551632 --- [           main] g.s.a.GrpcServerFactoryAutoConfiguration : Detected grpc-netty: Creating NettyGrpcServerFactory
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: Simple, bean: grpcServerService, class: com.example.demo.GrpcServerService
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.health.v1.Health, bean: grpcHealthService, class: io.grpc.protobuf.services.HealthServiceImpl
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.reflection.v1alpha.ServerReflection, bean: protoReflectionService, class: io.grpc.protobuf.services.ProtoReflectionService
2022-12-08T05:32:25.820-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.GrpcServerLifecycle          : gRPC Server started, listening on address: *, port: 9090
2022-12-08T05:32:25.831-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : Started DemoApplication in 1.264 seconds (process running for 1.623)
```

```bash
$ grpcurl -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
{
  "message": "Hello ==\u003e Hi"
}
```

--------------------------------

### Build container image with spring-boot:build-image -Pnative

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-maven.md

Creates a lightweight container image using Cloud Native Buildpacks. Docker must be installed and configured before running this goal.

```bash
$ ./mvnw spring-boot:build-image -Pnative
```

--------------------------------

### Compile native executable with nativeCompile

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-gradle.md

Compiles the application into a native executable using GraalVM Native Build Tools. GraalVM 22.3+ is required and the native-image compiler must be installed and configured.

```bash
$ ./gradlew nativeCompile
```

--------------------------------

### Run Spring Boot gRPC sample with ./mvnw spring-boot:run

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-reactive/README.md

Run the Spring Boot gRPC sample with Maven wrapper. The server starts on port 9090 by default and logs show registered services: Simple, grpc.health.v1.Health, and grpc.reflection.v1alpha.ServerReflection.

```bash
$ ./mvnw spring-boot:run
...
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.5.5)

2022-12-08T05:32:24.934-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : Starting DemoApplication using Java 17.0.5 with PID 551632 (/home/dsyer/dev/scratch/demo/target/classes started by dsyer in /home/dsyer/dev/scratch/demo)
2022-12-08T05:32:24.938-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : No active profile set, falling back to 1 default profile: "default"
2022-12-08T05:32:25.377-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcHealthServiceAutoConfiguration
2022-12-08T05:32:25.416-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcServerAutoConfiguration
2022-12-08T05:32:25.425-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcServerFactoryAutoConfiguration
2022-12-08T05:32:25.427-08:00  INFO 551632 --- [           main] g.s.a.GrpcServerFactoryAutoConfiguration : Detected grpc-netty: Creating NettyGrpcServerFactory
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: Simple, bean: grpcServerService, class: com.example.demo.GrpcServerService
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.health.v1.Health, bean: grpcHealthService, class: io.grpc.protobuf.services.HealthServiceImpl
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.reflection.v1alpha.ServerReflection, bean: protoReflectionService, class: io.grpc.protobuf.services.ProtoReflectionService
2022-12-08T05:32:25.820-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.GrpcServerLifecycle          : gRPC Server started, listening on address: *, port: 9090
2022-12-08T05:32:25.831-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : Started DemoApplication in 1.264 seconds (process running for 1.623)
```

--------------------------------

### Run Spring Boot gRPC server with ./mvnw spring-boot:run

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/README.md

Run the Spring Boot gRPC server with Maven wrapper. The output shows the server starting on port 9090 and registering the Simple, Health, and Reflection services.

```bash
$ ./mvnw spring-boot:run
...
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.5.5)
2022-12-08T05:32:24.934-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : Starting DemoApplication using Java 17.0.5 with PID 551632 (/home/dsyer/dev/scratch/demo/target/classes started by dsyer in /home/dsyer/dev/scratch/demo)
2022-12-08T05:32:24.938-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : No active profile set, falling back to 1 default profile: "default"
2022-12-08T05:32:25.377-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcHealthServiceAutoConfiguration
2022-12-08T05:32:25.416-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcServerAutoConfiguration
2022-12-08T05:32:25.425-08:00  WARN 551632 --- [           main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcServerFactoryAutoConfiguration
2022-12-08T05:32:25.427-08:00  INFO 551632 --- [           main] g.s.a.GrpcServerFactoryAutoConfiguration : Detected grpc-netty: Creating NettyGrpcServerFactory
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: Simple, bean: grpcServerService, class: com.example.demo.GrpcServerService
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.health.v1.Health, bean: grpcHealthService, class: io.grpc.protobuf.services.HealthServiceImpl
2022-12-08T05:32:25.712-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.reflection.v1alpha.ServerReflection, bean: protoReflectionService, class: io.grpc.protobuf.services.ProtoReflectionService
2022-12-08T05:32:25.820-08:00  INFO 551632 --- [           main] n.d.b.g.s.s.GrpcServerLifecycle          : gRPC Server started, listening on address: *, port: 9090
2022-12-08T05:32:25.831-08:00  INFO 551632 --- [           main] com.example.demo.DemoApplication         : Started DemoApplication in 1.264 seconds (process running for 1.623)
```

--------------------------------

### Run Spring Boot gRPC server with ./mvnw spring-boot:test-run

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-oauth2/README.md

Run the Spring Boot gRPC server with the Maven wrapper. The server starts on port 9090 by default and logs show the registered gRPC services (Simple, ServerReflection, Health) and the startup time.

```bash
$ ./mvnw spring-boot:test-run
...
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.5.5)

...
2022-12-08T05:32:25.427-08:00  INFO 551632 --- [           main] g.s.a.GrpcServerFactoryAutoConfiguration : Detected grpc-netty: Creating NettyGrpcServerFactory
2025-01-28T07:10:35.363Z  INFO 1218185 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 44207 (http) with context path '/'
2025-01-28T07:10:35.394Z  INFO 1218185 --- [           main] o.s.e.b.s.e.m.SpringBootApplicationMain  : Started SpringBootApplicationMain in 2.802 seconds (process running for 3.291)
2025-01-28T07:10:35.749Z  INFO 1218050 --- [grpc-server] [           main] o.s.grpc.server.NettyGrpcServerFactory   : Registered gRPC service: Simple
2025-01-28T07:10:35.749Z  INFO 1218050 --- [grpc-server] [           main] o.s.grpc.server.NettyGrpcServerFactory   : Registered gRPC service: grpc.reflection.v1.ServerReflection
2025-01-28T07:10:35.749Z  INFO 1218050 --- [grpc-server] [           main] o.s.grpc.server.NettyGrpcServerFactory   : Registered gRPC service: grpc.health.v1.Health
2025-01-28T07:10:35.835Z  INFO 1218050 --- [grpc-server] [           main] o.s.g.s.lifecycle.GrpcServerLifecycle    : gRPC Server started, listening on address: [/[0:0:0:0:0:0:0:0]:9090]
2025-01-28T07:10:35.844Z  INFO 1218050 --- [grpc-server] [           main] o.s.grpc.sample.GrpcServerApplication    : Started GrpcServerApplication in 5.072 seconds (process running for 5.419)
```

--------------------------------

### Spring Boot application main class for gRPC server

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Standard Spring Boot application that starts the gRPC server on the default port 9090. Run it from your IDE or with ./mvnw spring-boot:run or ./gradlew bootRun.

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

--------------------------------

### Commit message with Signed-off-by line

Source: https://github.com/spring-projects/spring-grpc/blob/main/CONTRIBUTING.md

Example commit message format required by the Developer Certificate of Origin (DCO). Must include a Signed-off-by line, which can be appended automatically with git's -s option.

```text
This is my commit message

Signed-off-by: Random J Developer <random@developer.example.org>

[resolves #1234]

```

--------------------------------

### Implement gRPC service with Spring

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Implements the generated service stub as a Spring @Service. The sayHello method throws IllegalArgumentException for names starting with 'error' and RuntimeException for 'internal'. The streamHello method streams 10 replies with a 1-second delay.

```java
@Service
class GrpcServerService extends SimpleGrpc.SimpleImplBase {

    private static Log log = LogFactory.getLog(GrpcServerService.class);

    @Override
    public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
        log.info("Hello " + req.getName());
        if (req.getName().startsWith("error")) {
            throw new IllegalArgumentException("Bad name: " + req.getName());
        }
        if (req.getName().startsWith("internal")) {
            throw new RuntimeException();
        }
        HelloReply reply = HelloReply.newBuilder().setMessage("Hello ==> " + req.getName()).build();
        responseObserver.onNext(reply);
        responseObserver.onCompleted();
    }

    @Override
    public void streamHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
        log.info("Hello " + req.getName());
        int count = 0;
        while (count < 10) {
            HelloReply reply = HelloReply.newBuilder().setMessage("Hello(" + count + ") ==> " + req.getName()).build();
            responseObserver.onNext(reply);
            count++;
            try {
                Thread.sleep(1000L);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                responseObserver.onError(e);
                return;
            }
        }
        responseObserver.onCompleted();
    }
}
```

--------------------------------

### Replace Tomcat/Servlet web starter

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/migration.md

Replace the dedicated web starter with the standard gRPC server starter plus the servlet adapter and enable HTTP/2 in application.properties.

```xml
<dependency>
    <groupId>org.springframework.grpc</groupId>
    <artifactId>spring-grpc-server-web-spring-boot-starter</artifactId>
</dependency>
```

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-grpc-server</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-servlet-jakarta</artifactId>
</dependency>
```

```properties
server.http2.enabled=true
```

--------------------------------

### Build and run as native image with GraalVM

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-client/README.md

Compiles the application to a native executable using the Maven native profile, then runs the resulting binary.

```bash
$ ./mvnw -Pnative native:compile
$ ./target/grpc-client-sample
```

--------------------------------

### Generate stubs with Gradle

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Runs the Gradle wrapper to build the project, generating the gRPC stubs.

```shell
./gradlew build
```

--------------------------------

### Compile and run native image with Maven native profile

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-reactive/README.md

Compile the Spring Boot gRPC app to a native image using Maven with the native profile, then run the resulting binary. The output shows the Spring Boot banner and startup logs, including the gRPC server listening on port 9090 and registered services (Simple, health, reflection).

```bash
$ ./mvnw -Pnative native:compile
$ ./target/demo
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.0.0)

2022-12-08T05:36:54.365-08:00  INFO 554359 --- [           main] com.example.demo.DemoApplication         : Starting AOT-processed DemoApplication using Java 17.0.5 with PID 554359 (/home/dsyer/dev/scratch/demo/target/demo started by dsyer in /home/dsyer/dev/scratch/demo)
2022-12-08T05:36:54.366-08:00  INFO 554359 --- [           main] com.example.demo.DemoApplication         : No active profile set, falling back to 1 default profile: "default"
2022-12-08T05:36:54.377-08:00  INFO 554359 --- [           main] g.s.a.GrpcServerFactoryAutoConfiguration : Detected grpc-netty: Creating NettyGrpcServerFactory
2022-12-08T05:36:54.392-08:00  INFO 554359 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: Simple, bean: grpcServerService, class: com.example.demo.GrpcServerService
2022-12-08T05:36:54.392-08:00  INFO 554359 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.health.v1.Health, bean: grpcHealthService, class: io.grpc.protobuf.services.HealthServiceImpl
2022-12-08T05:36:54.392-08:00  INFO 554359 --- [           main] n.d.b.g.s.s.AbstractGrpcServerFactory    : Registered gRPC service: grpc.reflection.v1alpha.ServerReflection, bean: protoReflectionService, class: io.grpc.protobuf.services.ProtoReflectionService
2022-12-08T05:36:54.396-08:00  INFO 554359 --- [           main] n.d.b.g.s.s.GrpcServerLifecycle          : gRPC Server started, listening on address: *, port: 9090
2022-12-08T05:36:54.396-08:00  INFO 554359 --- [           main] com.example.demo.DemoApplication         : Started DemoApplication in 0.046 seconds (process running for 0.052)
```

--------------------------------

### Define hello.proto service definition

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Defines the gRPC service and messages in a .proto file. The java_package option must be changed to the package chosen in Spring Initializr.

```proto
syntax = "proto3";

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

// The greeting service definition.
service Simple {
  // Sends a greeting
  rpc SayHello(HelloRequest) returns (HelloReply) {}
  rpc StreamHello(HelloRequest) returns (stream HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}
```

--------------------------------

### Test gRPC server with grpcurl

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/README.md

Test the gRPC server using grpcurl. Sends a JSON request to the Simple.SayHello method and shows the response.

```bash
$ grpcurl -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
{
  "message": "Hello ==\u003e Hi"
}
```

--------------------------------

### Run container image with docker run

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-maven.md

Runs the generated container image as any other container.

```bash
$ docker run --rm grpc-server-sample:1.1.2-SNAPSHOT
```

--------------------------------

### Generate stubs with Maven

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Runs the Maven wrapper to clean and package the project, generating the gRPC stubs.

```shell
./mvnw clean package
```

--------------------------------

### Build Antora site with Maven

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/README.md

Builds the Antora site locally from the project root. The output can be viewed by opening spring-grpc-docs/target/antora/site/index.html.

```bash
./mvnw -pl spring-grpc-docs process-resources antora
```

--------------------------------

### Run container image with docker run

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-gradle.md

Runs the generated container image as any other container. The image name is grpc-server:1.1.2-SNAPSHOT.

```bash
$ docker run --rm grpc-server:1.1.2-SNAPSHOT
```

--------------------------------

### Test gRPC service with grpcurl

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Invokes the Simple.SayHello method on localhost:9090 with a JSON payload.

```shell
grpcurl -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
```

--------------------------------

### Generate stubs with Maven or Gradle

Source: https://github.com/spring-projects/spring-grpc/blob/main/README.md

Generate Java stubs from the .proto file using Maven or Gradle. The generated sources appear in target/generated-sources/protobuf for Maven and build/generated/source/proto/main for Gradle.

```shell
./mvnw clean package
```

```shell
./gradlew build
```

--------------------------------

### Maven protobuf-maven-plugin configuration before migration

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/migration.md

The original Maven plugin block with explicit version, configuration, and executions. Remove these when using spring-boot-starter-parent.

```xml
<plugin>
    <groupId>io.github.ascopes</groupId>
    <artifactId>protobuf-maven-plugin</artifactId>
    <version>4.0.3</version>
    <configuration>
        <protocVersion>${protobuf-java.version}</protocVersion>
        <binaryMavenPlugins>
            <binaryMavenPlugin>
                <groupId>io.grpc</groupId>
                <artifactId>protoc-gen-grpc-java</artifactId>
                <version>${grpc.version}</version>
                <options>@generated=omit</options>
            </binaryMavenPlugin>
        </binaryMavenPlugins>
    </configuration>
    <executions>
        <execution><goals><goal>generate</goal></goals></execution>
    </executions>
</plugin>
```

--------------------------------

### Test with grpcurl and expected response

Source: https://github.com/spring-projects/spring-grpc/blob/main/README.md

Test the gRPC service using grpcurl. The command sends a request to Simple.SayHello on localhost:9090 and the expected response is shown.

```shell
grpcurl -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
```

```shell
{
  "message": "Hello ==\u003e Hi"
}
```

--------------------------------

### Run the Spring Boot application

Source: https://github.com/spring-projects/spring-grpc/blob/main/README.md

Run the Spring Boot application using Maven or Gradle.

```shell
./mvnw spring-boot:run
```

```shell
./gradlew bootRun
```

--------------------------------

### Maven protobuf-maven-plugin configuration after migration for plain Java

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/migration.md

For plain Java, keep only the bare plugin declaration without version or configuration.

```xml
<plugin>
    <groupId>io.github.ascopes</groupId>
    <artifactId>protobuf-maven-plugin</artifactId>
</plugin>
```

--------------------------------

### Run native executable

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-maven.md

Runs the native executable produced by the native:compile goal.

```bash
$ target/grpc-server-sample
```

--------------------------------

### Run tests in native image with nativeTest

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-gradle.md

Runs the existing test suite in a native image to validate application compatibility.

```bash
$ ./gradlew nativeTest
```

--------------------------------

### Test HTTP Basic authentication with grpcurl

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-secure/README.md

Tests the HTTP Basic authentication channel. The password is the same as the username (user:user).

```bash
$ grpcurl -H "Authorization: Basic $(echo -n user:user | base64)" -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
{
  "message": "Hello ==\u003e Hi"
}
```

--------------------------------

### Gradle Protobuf plugin configuration after migration for plain Java Boot 4.1.1

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/migration.md

For plain Java with Spring Boot 4.1.1, keep an empty plugins declaration to ensure service stubs are generated.

```groovy
protobuf {
    plugins {
        grpc {}
    }
}
```

--------------------------------

### Test gRPC service with OAuth2 token and grpcurl

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-oauth2/README.md

Obtain an OAuth2 token using client credentials (spring:secret) and call the gRPC service Simple.SayHello with grpcurl. The auth server port is random and shown at startup; the response is a JSON message.

```bash
$ TOKEN=`curl -v spring:secret@localhost:43737/oauth2/token -d grant_type=client_credentials | jq -r .access_token`
$ grpcurl -H "Authorization: Bearer $TOKEN" -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
{
  "message": "Hello ==\u003e Hi"
}
```

--------------------------------

### Gradle Protobuf plugin configuration after migration for Kotlin

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/migration.md

For Kotlin, keep the plugin declarations but drop the protoc artifact. The grpckt plugin is also declared.

```groovy
protobuf {
    plugins {
        grpc {
            artifact = "io.grpc:protoc-gen-grpc-java:${dependencyManagement.importedProperties['grpc.version']}"
        }
        grpckt {
            artifact = "io.grpc:protoc-gen-grpc-kotlin:${dependencyManagement.importedProperties['grpc-kotlin.version']}:jdk8@jar"
        }
    }
    generateProtoTasks { ... }
}
```

--------------------------------

### gRPC server service implementation extending SimpleImplBase

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Create a @Bean of type BindableService by extending the generated SimpleImplBase class. The service is annotated with @Service and will be bound to the gRPC server automatically.

```java
@Service
public class GrpcServerService extends SimpleGrpc.SimpleImplBase {
...
}
```

--------------------------------

### Format code and process Javadoc with Maven wrapper

Source: https://github.com/spring-projects/spring-grpc/blob/main/CONTRIBUTING.md

Run this command before submitting a PR to apply Spring JavaFormat and process Javadoc. The -Pjavadoc profile enables Javadoc processing to avoid a long build time during development.

```shell
./mvnw spring-javaformat:apply javadoc:javadoc -Pjavadoc
```

--------------------------------

### Test insecure channel with grpcurl X-User header

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-secure/README.md

Tests the insecure channel by asserting the X-User header. The response echoes the message with the user name.

```bash
$ grpcurl -H "X-User: user" -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
{
  "message": "Hello ==\u003e Hi"
}
```

--------------------------------

### Create a gRPC stub with OAuth2 bearer token authentication

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/client.adoc

Creates a SimpleBlockingStub that uses a BearerTokenAuthenticationInterceptor with a token obtained from a ClientRegistrationRepository. The token method uses RestClientClientCredentialsTokenResponseClient to fetch an access token for the client registration.

```java
@Bean
@Lazy
SimpleGrpc.SimpleBlockingStub basic(GrpcChannelFactory channels, ClientRegistrationRepository registry) {
	ClientRegistration reg = registry.findByRegistrationId("spring");
	return SimpleGrpc.newBlockingStub(channels.createChannel("0.0.0.0:9090", ChannelBuilderOptions.defaults()
		.withInterceptors(List.of(new BearerTokenAuthenticationInterceptor(() -> token(reg))))));
}

private String token(ClientRegistration reg) {
	RestClientClientCredentialsTokenResponseClient creds = new RestClientClientCredentialsTokenResponseClient();
	String token = creds.getTokenResponse(new OAuth2ClientCredentialsGrantRequest(reg))
		.getAccessToken()
		.getTokenValue();
	return token;
}
```

--------------------------------

### Create a channel with Basic HTTP authentication

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/client.adoc

Creates a channel using BasicAuthenticationInterceptor with a username and password. The bean is marked @Lazy to defer creation until needed.

```java
@Bean
@Lazy
Channel basic(GrpcChannelFactory channels) {
	return channels.createChannel("my-channel", ChannelBuilderOptions.defaults()
		.withInterceptors(List.of(new BasicAuthenticationInterceptor("user", "password"))));
}
```

--------------------------------

### Compile native executable with native:compile -Pnative

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-maven.md

Compiles the project into a native executable using GraalVM native-image. GraalVM 22.3+ is required.

```bash
$ ./mvnw native:compile -Pnative
```

--------------------------------

### Run native executable

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-gradle.md

Runs the native executable produced by the nativeCompile task. The executable is located at build/native/nativeCompile/grpc-server.

```bash
$ build/native/nativeCompile/grpc-server
```

--------------------------------

### Apply service filter via GrpcServerFactoryCustomizer

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/server.adoc

Provides a GrpcServerFactoryCustomizer that applies the previously defined ServerServiceDefinitionFilter to a NettyGrpcServerFactory. This is required for server factories other than InProcessGrpcServerFactory, which picks up the filter automatically.

```java
@Bean
GrpcServerFactoryCustomizer myServerFactoryCustomizer(ServerServiceDefinitionFilter myServiceFilter) {
    return factory -> {
        if (factory instanceof NettyGrpcServerFactory nettyServerFactory) {
            nettyServerFactory.setServiceFilter(myServiceFilter);
        }
    };
}
```

--------------------------------

### Configure role-based authorization with AuthenticationProcessInterceptor

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/server.adoc

Configures a global server interceptor that enforces role-based authorization on gRPC methods. It allows only admin users for Simple/StreamHello, only users with ROLE_USER for Simple/SayHello, permits all gRPC services (e.g., reflection and health), and denies all other requests. Enables HTTP Basic and preauthentication (mTLS) using withDefaults() (static import from Customizer).

```java
@Bean
@GlobalServerInterceptor
AuthenticationProcessInterceptor jwtSecurityFilterChain(GrpcSecurity grpc) throws Exception {
	return grpc
			.authorizeRequests(requests -> requests
					.methods("Simple/StreamHello").hasAuthority("ROLE_ADMIN")
					.methods("Simple/SayHello").hasAuthority("ROLE_USER")
					.methods("grpc.*/*").permitAll()
					.allRequests().denyAll())
			.httpBasic(withDefaults())
			.preauth(withDefaults())
			.build();
}
```

--------------------------------

### Run tests in native image with test -PnativeTest

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-server-kotlin/HELP-maven.md

Runs the existing test suite in a native image to validate application compatibility.

```bash
$ ./mvnw test -PnativeTest
```

--------------------------------

### Create a gRPC channel with per-channel interceptors

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/client.adoc

Creates a SimpleBlockingStub with a channel that has two client interceptors applied in order. The ChannelBuilderOptions.withInterceptors method is used to set per-channel interceptors. Avoid calling intercept directly on the native channel builder to prevent interceptors being applied before global and per-channel interceptors.

```java
@Bean
SimpleGrpc.SimpleBlockingStub stub(GrpcChannelFactory channelFactory) {
    ClientInterceptor interceptor1 = getChannelInterceptor1();
    ClientInterceptor interceptor2 = getChannelInterceptor2();
    ChannelBuilderOptions options = ChannelBuilderOptions.defaults()
            .withInterceptors(List.of(interceptor1, interceptor2));
    ManagedChannel channel = channelFactory.createChannel("localhost", options);
    return SimpleGrpc.newBlockingStub(channel);
}
```

--------------------------------

### Default @ImportGrpcClients configuration on @SpringBootApplication

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/client.adoc

Shows the default behavior of @ImportGrpcClients with basePackageClasses pointing to the application class. This annotation is not necessary unless changing attributes.

```java
// This is the default behaviour, so not necessary to add this annotation unless you change its attributes
@ImportGrpcClients(basePackageClasses = MyApplication.class)
@SpringBootApplication
class MyApplication {
	// ...
}
```

--------------------------------

### Expected grpcurl response

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc

Shows the expected JSON response from the grpcurl invocation.

```shell
{
  "message": "Hello ==\u003e Hi"
}
```

--------------------------------

### Add @ImportGrpcClients in @TestConfiguration

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/migration.md

Typical pattern for tests: define an inner @TestConfiguration class annotated with @ImportGrpcClients to trigger stub registration.

```java
@TestConfiguration
@ImportGrpcClients(basePackageClasses = GrpcServerApplication.class)
static class ExtraConfiguration { }
```

--------------------------------

### Set gRPC server port via environment variable

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/grpc-client/README.md

Sets the 'launched.grpc.port' property to specify the port where the gRPC server is running. This is required if the server is not on the default port 9090.

```bash
export LAUNCHED_GRPC_PORT=9090
```

--------------------------------

### Customize stubs with GrpcChannelBuilderCustomizer

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/client.adoc

Registers a specific stub class SimpleBlockingStub with channel 'stub' and adds a security interceptor. The prefix 'secure' names the bean definition 'secureSimpleBlockingStub'.

```java
@ImportGrpcClients(target = "stub", prefix = "secure", types = SimpleBlockingStub.class)
@Configuration
class ExtraConfiguration {

	@Bean
	GrpcChannelBuilderCustomizer<?> stubs() {
		return GrpcChannelBuilderCustomizer.matches("stub", builder -> 
			builder.intercept(new BearerTokenAuthenticationInterceptor(() -> token(context))));
	}

}
```

--------------------------------

### Configure global gRPC security with custom authentication extractor

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/server.adoc

Configures a global gRPC interceptor that permits all gRPC methods, requires authentication for all other requests, and extracts a bearer token from the SESSION_KEY header. The returned Authentication must be supported by the AuthenticationManager, so pair it with a matching AuthenticationProvider. Extractors are applied in order and the first non-null Authentication wins.

```java
@Bean
@GlobalServerInterceptor
AuthenticationProcessInterceptor customSecurityFilterChain(GrpcSecurity grpc) throws Exception {
	return grpc
			.authorizeRequests(requests -> requests
					.methods("grpc.*/*").permitAll()
					.allRequests().authenticated())
			.authenticationExtractor((headers, attributes, method) -> {
				String token = headers.get(SESSION_KEY);
				return (token != null) ? new BearerTokenAuthenticationToken(token) : null;
			})
			.build();
}
```

--------------------------------

### Global channel builder customizers

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/client.adoc

Registers two GrpcChannelBuilderCustomizer beans with @Order to customize all channels. The first is applied only to NettyGrpcChannelFactory.

```java
@Bean
@Order(100)
GrpcChannelBuilderCustomizer<NettyChannelBuilder> flowControlCustomizer() {
    return (name, builder) -> builder.flowControlWindow(1024 * 1024);
}

@Bean
@Order(200)
<T extends ManagedChannelBuilder<T>> GrpcChannelBuilderCustomizer<T> retryChannelCustomizer() {
	return (name, builder) -> builder.enableRetry().maxRetryAttempts(5);
}
```

--------------------------------

### Gradle Protobuf plugin configuration before migration

Source: https://github.com/spring-projects/spring-grpc/blob/main/samples/migration.md

The original Gradle protobuf block with explicit protoc and grpc plugin artifacts. Remove this block for plain Java in Spring Boot 4.1.0.

```groovy
protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:${dependencyManagement.importedProperties['protobuf-java.version']}"
    }
    plugins {
        grpc {
            artifact = "io.grpc:protoc-gen-grpc-java:${dependencyManagement.importedProperties['grpc.version']}"
        }
    }
    generateProtoTasks {
        all()*.plugins {
            grpc { option '@generated=omit' }
        }
    }
}
```

--------------------------------

### Per-channel channel builder customizer

Source: https://github.com/spring-projects/spring-grpc/blob/main/spring-grpc-docs/src/main/antora/modules/ROOT/pages/client.adoc

Creates a channel with a per-channel customizer that disables retries, applied after global customizers.

```java
@Bean
SimpleGrpc.SimpleBlockingStub stub(GrpcChannelFactory channelFactory) {
    ChannelBuilderOptions options = ChannelBuilderOptions.defaults()
            .withCustomizer((__, b) -> b.disableRetry());
    ManagedChannel channel = channelFactory.createChannel("localhost", options);
    return SimpleGrpc.newBlockingStub(channel);
}
```
Tokens:
Raw