Ankur
cd82ab9275
Companion code for the ankurm.com guide. Verified on Spring Boot 4.1.0, spring-grpc 1.1.0,
grpc-java 1.80.0, protobuf-java 4.34.2, JDK 25.0.3. results-full.txt is unedited mvn test
output: 8 tests, 0 failures. No installs needed - protoc and the gRPC codegen plugin resolve
as Maven artifacts, and every test uses the in-process transport.
_01_basics all four call types, and how their failure modes differ: iterator semantics on
server streaming, the half-close that client streaming hangs without, and the
independence of the two streams in bidi.
_02_troubleshooting
four failures reproduced then fixed - the 4 MB message limit and which side
enforces it, the absent default deadline, cancellation that never interrupts a
thread, and errors that arrive as UNKNOWN with no description.
Findings worth the commit message
- The in-process transport CANNOT enforce message size limits: it passes messages by
reference and never serialises them. A 4 MB + 1 KB message goes through cleanly in tests
and fails in production with RESOURCE_EXHAUSTED. The test asserts this rather than
pretending otherwise. Same blind spot covers compression, TLS, keepalive and LB.
- Two property names cost real time while writing this:
spring.grpc.server.inprocess.name (not in-process) and
spring.grpc.client.channel.<n>.target (singular channel, and target not address).
The second failure surfaces as UnknownHostException on the channel NAME.
- gRPC still has no default deadline, and cancellation only sets a Context flag.
Spring gRPC with Spring Boot 4
Companion repository for Spring gRPC with Spring Boot 4 on ankurm.com.
The post covers the concepts. This repository adds the part that is hard to find written down: a symptom-first troubleshooting guide, with the failures reproduced as tests wherever a test can honestly reproduce them.
Verified against Spring Boot 4.1.0, spring-grpc 1.1.0, grpc-java 1.80.0,
protobuf-java 4.34.2, JDK 25.0.3. Full output in results-full.txt.
Quick start
Nothing to install — protoc and the gRPC codegen plugin are resolved as Maven artifacts, and every
test runs over the in-process transport, so no port is bound.
git clone https://ankurm.com/git.app/asmhatre/spring-grpc-boot4.git
cd spring-grpc-boot4
mvn test
8 tests, a few seconds.
What is here
| Test | Covers |
|---|---|
FourCallTypesTest |
Unary, server streaming, client streaming, bidirectional — and how their failure modes differ |
HardToDiagnoseTest |
Four failures reproduced and fixed: message size limits, missing deadlines, unobserved cancellation, useless error statuses |
| Document | Covers |
|---|---|
| Troubleshooting | Symptom-first index: every entry starts from the error message you actually see |
The service itself (OrderServiceImpl)
is heavily commented and is where the correct patterns live — cancellation checks, half-close
handling, StreamObserver thread-safety, structured errors.
Five findings
- gRPC is a first-class Boot starter now.
spring-boot-starter-grpc-serverand-grpc-client, version-managed by the Boot BOM. A@Serviceextending the generatedImplBaseis registered automatically — no@GrpcService, no registration code. - The in-process transport cannot enforce message size limits. It passes messages by reference
and never serialises them, so a 4 MB + 1 KB message sails through — and fails in production with
RESOURCE_EXHAUSTED. Asserted in the test suite. The same blind spot covers compression, TLS, keepalive and load balancing. - Two property names that cost real time.
spring.grpc.server.inprocess.name(notin-process) andspring.grpc.client.channel.<n>.target(singularchannel, andtargetnotaddress). Getting the second wrong yieldsUnknownHostExceptionon the channel name, which sends you to look at DNS. - gRPC has no default deadline. A call without one waits forever. This is the single most common cause of a gRPC service that silently stops responding.
- Cancellation does not interrupt your thread. It sets a
Contextflag. A server that never checks it keeps working for a client that left ten minutes ago.
Reference machine
AMD Ryzen 5 5600U, Windows 11, java 25.0.3+9-LTS-195, Maven 3.9.9.
Licence
MIT. See LICENSE.